mirror of
https://github.com/neovim/neovim.git
synced 2025-09-05 19:08:15 +00:00
docs: move *packages* and *package-create* into 'pack.txt'
This commit is contained in:
Evgeni Chasnovski
@@ -7,6 +7,203 @@
|
|||||||
|
|
||||||
Type |gO| to see the table of contents.
|
Type |gO| to see the table of contents.
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
Using Vim packages *packages*
|
||||||
|
|
||||||
|
A Vim "package" is a directory that contains |plugin|s. Compared to normal
|
||||||
|
plugins, a package can...
|
||||||
|
- be downloaded as an archive and unpacked in its own directory, so the files
|
||||||
|
are not mixed with files of other plugins.
|
||||||
|
- be a git, mercurial, etc. repository, thus easy to update.
|
||||||
|
- contain multiple plugins that depend on each other.
|
||||||
|
- contain plugins that are automatically loaded on startup ("start" packages,
|
||||||
|
located in "pack/*/start/*") and ones that are only loaded when needed with
|
||||||
|
|:packadd| ("opt" packages, located in "pack/*/opt/*").
|
||||||
|
|
||||||
|
*runtime-search-path*
|
||||||
|
Nvim searches for |:runtime| files in:
|
||||||
|
1. all paths in 'runtimepath'
|
||||||
|
2. all "pack/*/start/*" dirs
|
||||||
|
|
||||||
|
Note that the "pack/*/start/*" paths are not explicitly included in
|
||||||
|
'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
|
||||||
|
|nvim_get_runtime_file()| to query for specific files or sub-folders within
|
||||||
|
the runtime path. Example: >
|
||||||
|
" List all runtime dirs and packages with Lua paths.
|
||||||
|
:echo nvim_get_runtime_file("lua/", v:true)
|
||||||
|
|
||||||
|
Using a package and loading automatically ~
|
||||||
|
|
||||||
|
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": >
|
||||||
|
% mkdir -p ~/.local/share/nvim/site/pack/foo
|
||||||
|
% cd ~/.local/share/nvim/site/pack/foo
|
||||||
|
% unzip /tmp/foopack.zip
|
||||||
|
|
||||||
|
The directory name "foo" is arbitrary, you can pick anything you like.
|
||||||
|
|
||||||
|
You would now have these files under ~/.local/share/nvim/site:
|
||||||
|
pack/foo/README.txt
|
||||||
|
pack/foo/start/foobar/plugin/foo.vim
|
||||||
|
pack/foo/start/foobar/syntax/some.vim
|
||||||
|
pack/foo/opt/foodebug/plugin/debugger.vim
|
||||||
|
|
||||||
|
On startup after processing your |config|, Nvim scans all directories in
|
||||||
|
'packpath' for plugins in "pack/*/start/*", then loads the plugins.
|
||||||
|
|
||||||
|
To allow for calling into package functionality while parsing your |vimrc|,
|
||||||
|
|:colorscheme| and |autoload| will both automatically search under 'packpath'
|
||||||
|
as well in addition to 'runtimepath'. See the documentation for each for
|
||||||
|
details.
|
||||||
|
|
||||||
|
In the example Nvim will find "pack/foo/start/foobar/plugin/foo.vim" and load
|
||||||
|
it.
|
||||||
|
|
||||||
|
If the "foobar" plugin kicks in and sets the 'filetype' to "some", Nvim will
|
||||||
|
find the syntax/some.vim file, because its directory is in the runtime search
|
||||||
|
path.
|
||||||
|
|
||||||
|
Nvim will also load ftdetect files, if there are any.
|
||||||
|
|
||||||
|
Note that the files under "pack/foo/opt" are not loaded automatically, only the
|
||||||
|
ones under "pack/foo/start". See |pack-add| below for how the "opt" directory
|
||||||
|
is used.
|
||||||
|
|
||||||
|
Loading packages automatically will not happen if loading plugins is disabled,
|
||||||
|
see |load-plugins|.
|
||||||
|
|
||||||
|
To load packages earlier, so that plugin/ files are sourced:
|
||||||
|
:packloadall
|
||||||
|
This also works when loading plugins is disabled. The automatic loading will
|
||||||
|
only happen once.
|
||||||
|
|
||||||
|
If the package has an "after" directory, that directory is added to the end of
|
||||||
|
'runtimepath', so that anything there will be loaded later.
|
||||||
|
|
||||||
|
|
||||||
|
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
|
||||||
|
directory level: >
|
||||||
|
% mkdir -p ~/.local/share/nvim/site/pack/foo/start/foobar
|
||||||
|
% cd ~/.local/share/nvim/site/pack/foo/start/foobar
|
||||||
|
% unzip /tmp/someplugin.zip
|
||||||
|
|
||||||
|
You would now have these files:
|
||||||
|
pack/foo/start/foobar/plugin/foo.vim
|
||||||
|
pack/foo/start/foobar/syntax/some.vim
|
||||||
|
|
||||||
|
From here it works like above.
|
||||||
|
|
||||||
|
|
||||||
|
Optional plugins ~
|
||||||
|
*pack-add*
|
||||||
|
To load an optional plugin from a pack use the `:packadd` command: >
|
||||||
|
:packadd foodebug
|
||||||
|
This searches for "pack/*/opt/foodebug" in 'packpath' and will find
|
||||||
|
~/.local/share/nvim/site/pack/foo/opt/foodebug/plugin/debugger.vim and source
|
||||||
|
it.
|
||||||
|
|
||||||
|
This could be done if some conditions are met. For example, depending on
|
||||||
|
whether Nvim supports a feature or a dependency is missing.
|
||||||
|
|
||||||
|
You can also load an optional plugin at startup, by putting this command in
|
||||||
|
your |config|: >
|
||||||
|
:packadd! foodebug
|
||||||
|
The extra "!" is so that the plugin isn't loaded if Nvim was started with
|
||||||
|
|--noplugin|.
|
||||||
|
|
||||||
|
It is perfectly normal for a package to only have files in the "opt"
|
||||||
|
directory. You then need to load each plugin when you want to use it.
|
||||||
|
|
||||||
|
|
||||||
|
Where to put what ~
|
||||||
|
|
||||||
|
Since color schemes, loaded with `:colorscheme`, are found below
|
||||||
|
"pack/*/start" and "pack/*/opt", you could put them anywhere. We recommend
|
||||||
|
you put them below "pack/*/opt", for example
|
||||||
|
"~/.config/nvim/pack/mycolors/opt/dark/colors/very_dark.vim".
|
||||||
|
|
||||||
|
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
|
||||||
|
select which one to load with `:packadd`. E.g. depending on the compiler
|
||||||
|
version: >
|
||||||
|
if foo_compiler_version > 34
|
||||||
|
packadd foo_new
|
||||||
|
else
|
||||||
|
packadd foo_old
|
||||||
|
endif
|
||||||
|
|
||||||
|
The "after" directory is most likely not useful in a package. It's not
|
||||||
|
disallowed though.
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
Creating Vim packages *package-create*
|
||||||
|
|
||||||
|
This assumes you write one or more plugins that you distribute as a package.
|
||||||
|
|
||||||
|
If you have two unrelated plugins you would use two packages, so that Vim
|
||||||
|
users can choose what they include or not. Or you can decide to use one
|
||||||
|
package with optional plugins, and tell the user to add the preferred ones with
|
||||||
|
`:packadd`.
|
||||||
|
|
||||||
|
Decide how you want to distribute the package. You can create an archive or
|
||||||
|
you could use a repository. An archive can be used by more users, but is a
|
||||||
|
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.
|
||||||
|
You can do both, github can automatically create an archive for a release.
|
||||||
|
|
||||||
|
Your directory layout would be like this:
|
||||||
|
start/foobar/plugin/foo.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/doc/foo.txt " help for foo.vim
|
||||||
|
start/foobar/doc/tags " help tags
|
||||||
|
opt/fooextra/plugin/extra.vim " optional plugin, defines commands
|
||||||
|
opt/fooextra/autoload/extra.vim " loaded when extra command used
|
||||||
|
opt/fooextra/doc/extra.txt " help for extra.vim
|
||||||
|
opt/fooextra/doc/tags " help tags
|
||||||
|
|
||||||
|
This allows for the user to do: >
|
||||||
|
mkdir ~/.local/share/nvim/site/pack
|
||||||
|
cd ~/.local/share/nvim/site/pack
|
||||||
|
git clone https://github.com/you/foobar.git myfoobar
|
||||||
|
|
||||||
|
Here "myfoobar" is a name that the user can choose, the only condition is that
|
||||||
|
it differs from other packages.
|
||||||
|
|
||||||
|
In your documentation you explain what the plugins do, and tell the user how
|
||||||
|
to load the optional plugin: >
|
||||||
|
:packadd! fooextra
|
||||||
|
|
||||||
|
You could add this packadd command in one of your plugins, to be executed when
|
||||||
|
the optional plugin is needed.
|
||||||
|
|
||||||
|
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
|
||||||
|
pack directory and the help command works right away. Don't forget to re-run
|
||||||
|
the command after changing the plugin help: >
|
||||||
|
:helptags path/start/foobar/doc
|
||||||
|
:helptags path/opt/fooextra/doc
|
||||||
|
|
||||||
|
|
||||||
|
Dependencies between plugins ~
|
||||||
|
*packload-two-steps*
|
||||||
|
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
|
||||||
|
found automatically. Your package would have these files:
|
||||||
|
|
||||||
|
pack/foo/start/one/plugin/one.vim >
|
||||||
|
call foolib#getit()
|
||||||
|
< pack/foo/start/two/plugin/two.vim >
|
||||||
|
call foolib#getit()
|
||||||
|
< pack/foo/start/lib/autoload/foolib.vim >
|
||||||
|
func foolib#getit()
|
||||||
|
|
||||||
|
This works, because start packages will be searched for autoload files, when
|
||||||
|
sourcing the plugins.
|
||||||
|
|
||||||
==============================================================================
|
==============================================================================
|
||||||
Plugin manager *vim.pack*
|
Plugin manager *vim.pack*
|
||||||
|
|
||||||
|
|||||||
@@ -520,203 +520,6 @@ Rationale:
|
|||||||
though it may look a bit weird. Requiring the space after the
|
though it may look a bit weird. Requiring the space after the
|
||||||
backslash is to make it very unlikely this is a normal comment line.
|
backslash is to make it very unlikely this is a normal comment line.
|
||||||
|
|
||||||
==============================================================================
|
|
||||||
Using Vim packages *packages*
|
|
||||||
|
|
||||||
A Vim "package" is a directory that contains |plugin|s. Compared to normal
|
|
||||||
plugins, a package can...
|
|
||||||
- be downloaded as an archive and unpacked in its own directory, so the files
|
|
||||||
are not mixed with files of other plugins.
|
|
||||||
- be a git, mercurial, etc. repository, thus easy to update.
|
|
||||||
- contain multiple plugins that depend on each other.
|
|
||||||
- contain plugins that are automatically loaded on startup ("start" packages,
|
|
||||||
located in "pack/*/start/*") and ones that are only loaded when needed with
|
|
||||||
|:packadd| ("opt" packages, located in "pack/*/opt/*").
|
|
||||||
|
|
||||||
*runtime-search-path*
|
|
||||||
Nvim searches for |:runtime| files in:
|
|
||||||
1. all paths in 'runtimepath'
|
|
||||||
2. all "pack/*/start/*" dirs
|
|
||||||
|
|
||||||
Note that the "pack/*/start/*" paths are not explicitly included in
|
|
||||||
'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
|
|
||||||
|nvim_get_runtime_file()| to query for specific files or sub-folders within
|
|
||||||
the runtime path. Example: >
|
|
||||||
" List all runtime dirs and packages with Lua paths.
|
|
||||||
:echo nvim_get_runtime_file("lua/", v:true)
|
|
||||||
|
|
||||||
Using a package and loading automatically ~
|
|
||||||
|
|
||||||
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": >
|
|
||||||
% mkdir -p ~/.local/share/nvim/site/pack/foo
|
|
||||||
% cd ~/.local/share/nvim/site/pack/foo
|
|
||||||
% unzip /tmp/foopack.zip
|
|
||||||
|
|
||||||
The directory name "foo" is arbitrary, you can pick anything you like.
|
|
||||||
|
|
||||||
You would now have these files under ~/.local/share/nvim/site:
|
|
||||||
pack/foo/README.txt
|
|
||||||
pack/foo/start/foobar/plugin/foo.vim
|
|
||||||
pack/foo/start/foobar/syntax/some.vim
|
|
||||||
pack/foo/opt/foodebug/plugin/debugger.vim
|
|
||||||
|
|
||||||
On startup after processing your |config|, Nvim scans all directories in
|
|
||||||
'packpath' for plugins in "pack/*/start/*", then loads the plugins.
|
|
||||||
|
|
||||||
To allow for calling into package functionality while parsing your |vimrc|,
|
|
||||||
|:colorscheme| and |autoload| will both automatically search under 'packpath'
|
|
||||||
as well in addition to 'runtimepath'. See the documentation for each for
|
|
||||||
details.
|
|
||||||
|
|
||||||
In the example Nvim will find "pack/foo/start/foobar/plugin/foo.vim" and load
|
|
||||||
it.
|
|
||||||
|
|
||||||
If the "foobar" plugin kicks in and sets the 'filetype' to "some", Nvim will
|
|
||||||
find the syntax/some.vim file, because its directory is in the runtime search
|
|
||||||
path.
|
|
||||||
|
|
||||||
Nvim will also load ftdetect files, if there are any.
|
|
||||||
|
|
||||||
Note that the files under "pack/foo/opt" are not loaded automatically, only the
|
|
||||||
ones under "pack/foo/start". See |pack-add| below for how the "opt" directory
|
|
||||||
is used.
|
|
||||||
|
|
||||||
Loading packages automatically will not happen if loading plugins is disabled,
|
|
||||||
see |load-plugins|.
|
|
||||||
|
|
||||||
To load packages earlier, so that plugin/ files are sourced:
|
|
||||||
:packloadall
|
|
||||||
This also works when loading plugins is disabled. The automatic loading will
|
|
||||||
only happen once.
|
|
||||||
|
|
||||||
If the package has an "after" directory, that directory is added to the end of
|
|
||||||
'runtimepath', so that anything there will be loaded later.
|
|
||||||
|
|
||||||
|
|
||||||
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
|
|
||||||
directory level: >
|
|
||||||
% mkdir -p ~/.local/share/nvim/site/pack/foo/start/foobar
|
|
||||||
% cd ~/.local/share/nvim/site/pack/foo/start/foobar
|
|
||||||
% unzip /tmp/someplugin.zip
|
|
||||||
|
|
||||||
You would now have these files:
|
|
||||||
pack/foo/start/foobar/plugin/foo.vim
|
|
||||||
pack/foo/start/foobar/syntax/some.vim
|
|
||||||
|
|
||||||
From here it works like above.
|
|
||||||
|
|
||||||
|
|
||||||
Optional plugins ~
|
|
||||||
*pack-add*
|
|
||||||
To load an optional plugin from a pack use the `:packadd` command: >
|
|
||||||
:packadd foodebug
|
|
||||||
This searches for "pack/*/opt/foodebug" in 'packpath' and will find
|
|
||||||
~/.local/share/nvim/site/pack/foo/opt/foodebug/plugin/debugger.vim and source
|
|
||||||
it.
|
|
||||||
|
|
||||||
This could be done if some conditions are met. For example, depending on
|
|
||||||
whether Nvim supports a feature or a dependency is missing.
|
|
||||||
|
|
||||||
You can also load an optional plugin at startup, by putting this command in
|
|
||||||
your |config|: >
|
|
||||||
:packadd! foodebug
|
|
||||||
The extra "!" is so that the plugin isn't loaded if Nvim was started with
|
|
||||||
|--noplugin|.
|
|
||||||
|
|
||||||
It is perfectly normal for a package to only have files in the "opt"
|
|
||||||
directory. You then need to load each plugin when you want to use it.
|
|
||||||
|
|
||||||
|
|
||||||
Where to put what ~
|
|
||||||
|
|
||||||
Since color schemes, loaded with `:colorscheme`, are found below
|
|
||||||
"pack/*/start" and "pack/*/opt", you could put them anywhere. We recommend
|
|
||||||
you put them below "pack/*/opt", for example
|
|
||||||
"~/.config/nvim/pack/mycolors/opt/dark/colors/very_dark.vim".
|
|
||||||
|
|
||||||
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
|
|
||||||
select which one to load with `:packadd`. E.g. depending on the compiler
|
|
||||||
version: >
|
|
||||||
if foo_compiler_version > 34
|
|
||||||
packadd foo_new
|
|
||||||
else
|
|
||||||
packadd foo_old
|
|
||||||
endif
|
|
||||||
|
|
||||||
The "after" directory is most likely not useful in a package. It's not
|
|
||||||
disallowed though.
|
|
||||||
|
|
||||||
==============================================================================
|
|
||||||
Creating Vim packages *package-create*
|
|
||||||
|
|
||||||
This assumes you write one or more plugins that you distribute as a package.
|
|
||||||
|
|
||||||
If you have two unrelated plugins you would use two packages, so that Vim
|
|
||||||
users can choose what they include or not. Or you can decide to use one
|
|
||||||
package with optional plugins, and tell the user to add the preferred ones with
|
|
||||||
`:packadd`.
|
|
||||||
|
|
||||||
Decide how you want to distribute the package. You can create an archive or
|
|
||||||
you could use a repository. An archive can be used by more users, but is a
|
|
||||||
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.
|
|
||||||
You can do both, github can automatically create an archive for a release.
|
|
||||||
|
|
||||||
Your directory layout would be like this:
|
|
||||||
start/foobar/plugin/foo.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/doc/foo.txt " help for foo.vim
|
|
||||||
start/foobar/doc/tags " help tags
|
|
||||||
opt/fooextra/plugin/extra.vim " optional plugin, defines commands
|
|
||||||
opt/fooextra/autoload/extra.vim " loaded when extra command used
|
|
||||||
opt/fooextra/doc/extra.txt " help for extra.vim
|
|
||||||
opt/fooextra/doc/tags " help tags
|
|
||||||
|
|
||||||
This allows for the user to do: >
|
|
||||||
mkdir ~/.local/share/nvim/site/pack
|
|
||||||
cd ~/.local/share/nvim/site/pack
|
|
||||||
git clone https://github.com/you/foobar.git myfoobar
|
|
||||||
|
|
||||||
Here "myfoobar" is a name that the user can choose, the only condition is that
|
|
||||||
it differs from other packages.
|
|
||||||
|
|
||||||
In your documentation you explain what the plugins do, and tell the user how
|
|
||||||
to load the optional plugin: >
|
|
||||||
:packadd! fooextra
|
|
||||||
|
|
||||||
You could add this packadd command in one of your plugins, to be executed when
|
|
||||||
the optional plugin is needed.
|
|
||||||
|
|
||||||
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
|
|
||||||
pack directory and the help command works right away. Don't forget to re-run
|
|
||||||
the command after changing the plugin help: >
|
|
||||||
:helptags path/start/foobar/doc
|
|
||||||
:helptags path/opt/fooextra/doc
|
|
||||||
|
|
||||||
|
|
||||||
Dependencies between plugins ~
|
|
||||||
*packload-two-steps*
|
|
||||||
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
|
|
||||||
found automatically. Your package would have these files:
|
|
||||||
|
|
||||||
pack/foo/start/one/plugin/one.vim >
|
|
||||||
call foolib#getit()
|
|
||||||
< pack/foo/start/two/plugin/two.vim >
|
|
||||||
call foolib#getit()
|
|
||||||
< pack/foo/start/lib/autoload/foolib.vim >
|
|
||||||
func foolib#getit()
|
|
||||||
|
|
||||||
This works, because start packages will be searched for autoload files, when
|
|
||||||
sourcing the plugins.
|
|
||||||
|
|
||||||
==============================================================================
|
==============================================================================
|
||||||
Debugging scripts *debug-scripts*
|
Debugging scripts *debug-scripts*
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user