mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-06 03:18:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: vim.pack

Browse Source
This commit is contained in:
Justin M. Keyes
2025-07-28 15:57:21 -04:00
parent 56a4ef3c21
commit c81dc320b0
2 changed files with 55 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
runtime/doc/pack.txt
View File

@@ -8,7 +8,7 @@
Type |gO| to see the table of contents. Type |gO| to see the table of contents.
============================================================================== ==============================================================================
Using Vim packages *packages* Using Vim packages *packages*
A Vim "package" is a directory that contains |plugin|s. Compared to normal A Vim "package" is a directory that contains |plugin|s. Compared to normal
plugins, a package can... plugins, a package can...
@@ -20,34 +20,34 @@ plugins, a package can...
located in "pack/*/start/*") and ones that are only loaded when needed with located in "pack/*/start/*") and ones that are only loaded when needed with
|:packadd| ("opt" packages, located in "pack/*/opt/*"). |:packadd| ("opt" packages, located in "pack/*/opt/*").
*runtime-search-path* *runtime-search-path*
Nvim searches for |:runtime| files in: Nvim searches for |:runtime| files in:
1. all paths in 'runtimepath' - 1. all paths in 'runtimepath'
2. all "pack/*/start/*" dirs - 2. all "pack/*/start/*" dirs
Note that the "pack/*/start/*" paths are not explicitly included in Note that the "pack/*/start/*" paths are not explicitly included in
'runtimepath', so they will not be reported by ":set rtp" or "echo &rtp". 'runtimepath', so they will not be reported by ":set rtp" or "echo &rtp".
Scripts can use |nvim_list_runtime_paths()| to list all used directories, and Scripts can use |nvim_list_runtime_paths()| to list all used directories, and
|nvim_get_runtime_file()| to query for specific files or sub-folders within |nvim_get_runtime_file()| to query for specific files or sub-folders within
the runtime path. Example: > the runtime path. Example: >
" List all runtime dirs and packages with Lua paths. " List all runtime dirs and packages with Lua paths.
:echo nvim_get_runtime_file("lua/", v:true) :echo nvim_get_runtime_file("lua/", v:true)
Using a package and loading automatically ~ Using a package and loading automatically ~
Let's assume your Nvim files are in "~/.local/share/nvim/site" and you want to Let's assume your Nvim files are in "~/.local/share/nvim/site" and you want to
add a package from a zip archive "/tmp/foopack.zip": > add a package from a zip archive "/tmp/foopack.zip": >
% mkdir -p ~/.local/share/nvim/site/pack/foo % mkdir -p ~/.local/share/nvim/site/pack/foo
% cd ~/.local/share/nvim/site/pack/foo % cd ~/.local/share/nvim/site/pack/foo
% unzip /tmp/foopack.zip % unzip /tmp/foopack.zip
The directory name "foo" is arbitrary, you can pick anything you like. The directory name "foo" is arbitrary, you can pick anything you like.
You would now have these files under ~/.local/share/nvim/site: You would now have these files under ~/.local/share/nvim/site: >
pack/foo/README.txt pack/foo/README.txt
pack/foo/start/foobar/plugin/foo.vim pack/foo/start/foobar/plugin/foo.vim
pack/foo/start/foobar/syntax/some.vim pack/foo/start/foobar/syntax/some.vim
pack/foo/opt/foodebug/plugin/debugger.vim pack/foo/opt/foodebug/plugin/debugger.vim
On startup after processing your |config|, Nvim scans all directories in On startup after processing your |config|, Nvim scans all directories in
'packpath' for plugins in "pack/*/start/*", then loads the plugins. 'packpath' for plugins in "pack/*/start/*", then loads the plugins.
@@ -74,7 +74,7 @@ Loading packages automatically will not happen if loading plugins is disabled,
see |load-plugins|. see |load-plugins|.
To load packages earlier, so that plugin/ files are sourced: To load packages earlier, so that plugin/ files are sourced:
:packloadall :packloadall
This also works when loading plugins is disabled. The automatic loading will This also works when loading plugins is disabled. The automatic loading will
only happen once. only happen once.
@@ -86,21 +86,21 @@ Using a single plugin and loading it automatically ~
If you don't have a package but a single plugin, you need to create the extra If you don't have a package but a single plugin, you need to create the extra
directory level: > directory level: >
% mkdir -p ~/.local/share/nvim/site/pack/foo/start/foobar % mkdir -p ~/.local/share/nvim/site/pack/foo/start/foobar
% cd ~/.local/share/nvim/site/pack/foo/start/foobar % cd ~/.local/share/nvim/site/pack/foo/start/foobar
% unzip /tmp/someplugin.zip % unzip /tmp/someplugin.zip
You would now have these files: You would now have these files: >
pack/foo/start/foobar/plugin/foo.vim pack/foo/start/foobar/plugin/foo.vim
pack/foo/start/foobar/syntax/some.vim pack/foo/start/foobar/syntax/some.vim
From here it works like above. From here it works like above.
Optional plugins ~ Optional plugins ~
*pack-add* *pack-add*
To load an optional plugin from a pack use the `:packadd` command: > To load an optional plugin from a pack use the `:packadd` command: >
:packadd foodebug :packadd foodebug
This searches for "pack/*/opt/foodebug" in 'packpath' and will find This searches for "pack/*/opt/foodebug" in 'packpath' and will find
~/.local/share/nvim/site/pack/foo/opt/foodebug/plugin/debugger.vim and source ~/.local/share/nvim/site/pack/foo/opt/foodebug/plugin/debugger.vim and source
it. it.
@@ -110,7 +110,7 @@ whether Nvim supports a feature or a dependency is missing.
You can also load an optional plugin at startup, by putting this command in You can also load an optional plugin at startup, by putting this command in
your |config|: > your |config|: >
:packadd! foodebug :packadd! foodebug
The extra "!" is so that the plugin isn't loaded if Nvim was started with The extra "!" is so that the plugin isn't loaded if Nvim was started with
|--noplugin|. |--noplugin|.
@@ -129,17 +129,17 @@ Filetype plugins should go under "pack/*/start", so that they are always
found. Unless you have more than one plugin for a file type and want to found. Unless you have more than one plugin for a file type and want to
select which one to load with `:packadd`. E.g. depending on the compiler select which one to load with `:packadd`. E.g. depending on the compiler
version: > version: >
if foo_compiler_version > 34 if foo_compiler_version > 34
packadd foo_new packadd foo_new
else else
packadd foo_old packadd foo_old
endif endif
The "after" directory is most likely not useful in a package. It's not The "after" directory is most likely not useful in a package. It's not
disallowed though. disallowed though.
============================================================================== ==============================================================================
Creating Vim packages *package-create* Creating Vim packages *package-create*
This assumes you write one or more plugins that you distribute as a package. This assumes you write one or more plugins that you distribute as a package.
@@ -154,28 +154,28 @@ bit harder to update to a new version. A repository can usually be kept
up-to-date easily, but it requires a program like "git" to be available. up-to-date easily, but it requires a program like "git" to be available.
You can do both, github can automatically create an archive for a release. You can do both, github can automatically create an archive for a release.
Your directory layout would be like this: Your directory layout would be like this: >
start/foobar/plugin/foo.vim " always loaded, defines commands start/foobar/plugin/foo.vim " always loaded, defines commands
start/foobar/plugin/bar.vim " always loaded, defines commands start/foobar/plugin/bar.vim " always loaded, defines commands
start/foobar/autoload/foo.vim " loaded when foo command used start/foobar/autoload/foo.vim " loaded when foo command used
start/foobar/doc/foo.txt " help for foo.vim start/foobar/doc/foo.txt " help for foo.vim
start/foobar/doc/tags " help tags start/foobar/doc/tags " help tags
opt/fooextra/plugin/extra.vim " optional plugin, defines commands opt/fooextra/plugin/extra.vim " optional plugin, defines commands
opt/fooextra/autoload/extra.vim " loaded when extra command used opt/fooextra/autoload/extra.vim " loaded when extra command used
opt/fooextra/doc/extra.txt " help for extra.vim opt/fooextra/doc/extra.txt " help for extra.vim
opt/fooextra/doc/tags " help tags opt/fooextra/doc/tags " help tags
<
This allows for the user to do: > This allows for the user to do: >
mkdir ~/.local/share/nvim/site/pack mkdir ~/.local/share/nvim/site/pack
cd ~/.local/share/nvim/site/pack cd ~/.local/share/nvim/site/pack
git clone https://github.com/you/foobar.git myfoobar git clone https://github.com/you/foobar.git myfoobar
Here "myfoobar" is a name that the user can choose, the only condition is that Here "myfoobar" is a name that the user can choose, the only condition is that
it differs from other packages. it differs from other packages.
In your documentation you explain what the plugins do, and tell the user how In your documentation you explain what the plugins do, and tell the user how
to load the optional plugin: > to load the optional plugin: >
:packadd! fooextra :packadd! fooextra
You could add this packadd command in one of your plugins, to be executed when You could add this packadd command in one of your plugins, to be executed when
the optional plugin is needed. the optional plugin is needed.
@@ -184,22 +184,22 @@ Run the `:helptags` command to generate the doc/tags file. Including this
generated file in the package means that the user can drop the package in the generated file in the package means that the user can drop the package in the
pack directory and the help command works right away. Don't forget to re-run pack directory and the help command works right away. Don't forget to re-run
the command after changing the plugin help: > the command after changing the plugin help: >
:helptags path/start/foobar/doc :helptags path/start/foobar/doc
:helptags path/opt/fooextra/doc :helptags path/opt/fooextra/doc
Dependencies between plugins ~ Dependencies between plugins ~
*packload-two-steps* *packload-two-steps*
Suppose you have two plugins that depend on the same functionality. You can Suppose you have two plugins that depend on the same functionality. You can
put the common functionality in an autoload directory, so that it will be put the common functionality in an autoload directory, so that it will be
found automatically. Your package would have these files: found automatically. Your package would have these files:
pack/foo/start/one/plugin/one.vim > pack/foo/start/one/plugin/one.vim >
call foolib#getit() call foolib#getit()
< pack/foo/start/two/plugin/two.vim > pack/foo/start/two/plugin/two.vim >
call foolib#getit() call foolib#getit()
< pack/foo/start/lib/autoload/foolib.vim > pack/foo/start/lib/autoload/foolib.vim >
func foolib#getit() func foolib#getit()
This works, because start packages will be searched for autoload files, when This works, because start packages will be searched for autoload files, when
sourcing the plugins. sourcing the plugins.

1
src/gen/gen_help_html.lua
View File

@@ -79,6 +79,7 @@ local new_layout = {
['news-0.10.txt'] = true, ['news-0.10.txt'] = true,
['news-0.11.txt'] = true, ['news-0.11.txt'] = true,
['nvim.txt'] = true, ['nvim.txt'] = true,
['pack.txt'] = true,
['provider.txt'] = true, ['provider.txt'] = true,
['tui.txt'] = true, ['tui.txt'] = true,
['ui.txt'] = true, ['ui.txt'] = true,