diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt index cba99e192f..5a2f99757a 100644 --- a/runtime/doc/pack.txt +++ b/runtime/doc/pack.txt @@ -7,6 +7,203 @@ 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* diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index 7e8569f745..1c5cbd4c8d 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -520,203 +520,6 @@ Rationale: 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. -============================================================================== -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*