diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index e1b429ea89..aa76f55662 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -2535,192 +2535,6 @@ vim.loader.reset({path}) *vim.loader.reset()* • {path} (`string?`) path to reset -============================================================================== -Lua module: vim.pack *vim.pack* - -WORK IN PROGRESS built-in plugin manager! Early testing of existing features -is appreciated, but expect breaking changes without notice. - -Manages plugins only in a dedicated *vim.pack-directory* (see |packages|): -`$XDG_DATA_HOME/nvim/site/pack/core/opt`. Plugin's subdirectory name matches -plugin's name in specification. It is assumed that all plugins in the -directory are managed exclusively by `vim.pack`. - -Uses Git to manage plugins and requires present `git` executable of at least -version 2.36. Target plugins should be Git repositories with versions as named -tags following semver convention `v..`. - -Example workflows ~ - -Basic install and management: -• Add |vim.pack.add()| call(s) to 'init.lua': >lua - - vim.pack.add({ - -- Install "plugin1" and use default branch (usually `main` or `master`) - 'https://github.com/user/plugin1', - - -- Same as above, but using a table (allows setting other options) - { src = 'https://github.com/user/plugin1' }, - - -- Specify plugin's name (here the plugin will be called "plugin2" - -- instead of "generic-name") - { src = 'https://github.com/user/generic-name', name = 'plugin2' }, - - -- Specify version to follow during install and update - { - src = 'https://github.com/user/plugin3', - -- Version constraint, see |vim.version.range()| - version = vim.version.range('1.0'), - }, - { - src = 'https://github.com/user/plugin4', - -- Git branch, tag, or commit hash - version = 'main', - }, - }) - - -- Plugin's code can be used directly after `add()` - plugin1 = require('plugin1') -< -• Restart Nvim (for example, with |:restart|). Plugins that were not yet - installed will be available on disk in target state after `add()` call. -• To update all plugins with new changes: - • Execute |vim.pack.update()|. This will download updates from source and - show confirmation buffer in a separate tabpage. - • Review changes. To confirm all updates execute |:write|. To discard - updates execute |:quit|. - -Switch plugin's version: -• Update 'init.lua' for plugin to have desired `version`. Let's say, plugin - named 'plugin1' has changed to `vim.version.range('*')`. -• |:restart|. The plugin's actual state on disk is not yet changed. -• Execute `vim.pack.update({ 'plugin1' })`. -• Review changes and either confirm or discard them. If discarded, revert any - changes in 'init.lua' as well or you will be prompted again next time you - run |vim.pack.update()|. - -Freeze plugin from being updated: -• Update 'init.lua' for plugin to have `version` set to current commit hash. - You can get it by running `vim.pack.update({ 'plugin-name' })` and yanking - the word describing current state (looks like `abc12345`). -• |:restart|. - -Unfreeze plugin to start receiving updates: -• Update 'init.lua' for plugin to have `version` set to whichever version you - want it to be updated. -• |:restart|. - -Remove plugins from disk: -• Use |vim.pack.del()| with a list of plugin names to remove. Make sure their - specs are not included in |vim.pack.add()| call in 'init.lua' or they will - be reinstalled. - -Available events to hook into ~ -• *PackChangedPre* - before trying to change plugin's state. -• *PackChanged* - after plugin's state has changed. - -Each event populates the following |event-data| fields: -• `kind` - one of "install" (install on disk), "update" (update existing - plugin), "delete" (delete from disk). -• `spec` - plugin's specification. -• `path` - full path to plugin's directory. - - -*vim.pack.Spec* - - Fields: ~ - • {src} (`string`) URI from which to install and pull updates. Any - format supported by `git clone` is allowed. - • {name}? (`string`) Name of plugin. Will be used as directory name. - Default: `src` repository name. - • {version}? (`string|vim.VersionRange`) Version to use for install and - updates. Can be: - • `nil` (no value, default) to use repository's default - branch (usually `main` or `master`). - • String to use specific branch, tag, or commit hash. - • Output of |vim.version.range()| to install the - greatest/last semver tag inside the version constraint. - - -vim.pack.add({specs}, {opts}) *vim.pack.add()* - Add plugin to current session - • For each specification check that plugin exists on disk in - |vim.pack-directory|: - • If exists, do nothin in this step. - • If doesn't exist, install it by downloading from `src` into `name` - subdirectory (via `git clone`) and update state to match `version` - (via `git checkout`). - • For each plugin execute |:packadd| making them reachable by Nvim. - - Notes: - • Installation is done in parallel, but waits for all to finish before - continuing next code execution. - • If plugin is already present on disk, there are no checks about its - present state. The specified `version` can be not the one actually - present on disk. Execute |vim.pack.update()| to synchronize. - • Adding plugin second and more times during single session does nothing: - only the data from the first adding is registered. - - Parameters: ~ - • {specs} (`(string|vim.pack.Spec)[]`) List of plugin specifications. - String item is treated as `src`. - • {opts} (`table?`) A table with the following fields: - • {load}? (`boolean`) Load `plugin/` files and `ftdetect/` - scripts. If `false`, works like `:packadd!`. Default - `true`. - -vim.pack.del({names}) *vim.pack.del()* - Remove plugins from disk - - Parameters: ~ - • {names} (`string[]`) List of plugin names to remove from disk. Must - be managed by |vim.pack|, not necessarily already added to - current session. - -vim.pack.get() *vim.pack.get()* - Get data about all plugins managed by |vim.pack| - - Return: ~ - (`table[]`) A list of objects with the following fields: - • {spec} (`vim.pack.SpecResolved`) A |vim.pack.Spec| with defaults - made explicit. - • {path} (`string`) Plugin's path on disk. - • {active} (`boolean`) Whether plugin was added via |vim.pack.add()| - to current session. - -vim.pack.update({names}, {opts}) *vim.pack.update()* - Update plugins - • Download new changes from source. - • Infer update info (current/target state, changelog, etc.). - • Depending on `force`: - • If `false`, show confirmation buffer. It lists data about all set to - update plugins. Pending changes starting with `>` will be applied - while the ones starting with `<` will be reverted. It has special - in-process LSP server attached to provide more interactive features. - Currently supported methods: - • 'textDocument/documentSymbol' (`gO` via |lsp-defaults| or - |vim.lsp.buf.document_symbol()|) - show structure of the buffer. - • 'textDocument/hover' (`K` via |lsp-defaults| or - |vim.lsp.buf.hover()|) - show more information at cursor. Like - details of particular pending change or newer tag. - Execute |:write| to confirm update, execute |:quit| to discard the - update. - • If `true`, make updates right away. - - Notes: - • Every actual update is logged in "nvim-pack.log" file inside "log" - |stdpath()|. - - Parameters: ~ - • {names} (`string[]?`) List of plugin names to update. Must be managed - by |vim.pack|, not necessarily already added to current - session. Default: names of all plugins added to current - session via |vim.pack.add()|. - • {opts} (`table?`) A table with the following fields: - • {force}? (`boolean`) Whether to skip confirmation and make - updates immediately. Default `false`. - - ============================================================================== Lua module: vim.uri *vim.uri* diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt new file mode 100644 index 0000000000..5a2f99757a --- /dev/null +++ b/runtime/doc/pack.txt @@ -0,0 +1,393 @@ +*pack.txt* Nvim + + NVIM REFERENCE MANUAL + + Extending Nvim + + + 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* + +WORK IN PROGRESS built-in plugin manager! Early testing of existing features +is appreciated, but expect breaking changes without notice. + +Manages plugins only in a dedicated *vim.pack-directory* (see |packages|): +`$XDG_DATA_HOME/nvim/site/pack/core/opt`. Plugin's subdirectory name matches +plugin's name in specification. It is assumed that all plugins in the +directory are managed exclusively by `vim.pack`. + +Uses Git to manage plugins and requires present `git` executable of at least +version 2.36. Target plugins should be Git repositories with versions as named +tags following semver convention `v..`. + +Example workflows ~ + +Basic install and management: +• Add |vim.pack.add()| call(s) to 'init.lua': >lua + + vim.pack.add({ + -- Install "plugin1" and use default branch (usually `main` or `master`) + 'https://github.com/user/plugin1', + + -- Same as above, but using a table (allows setting other options) + { src = 'https://github.com/user/plugin1' }, + + -- Specify plugin's name (here the plugin will be called "plugin2" + -- instead of "generic-name") + { src = 'https://github.com/user/generic-name', name = 'plugin2' }, + + -- Specify version to follow during install and update + { + src = 'https://github.com/user/plugin3', + -- Version constraint, see |vim.version.range()| + version = vim.version.range('1.0'), + }, + { + src = 'https://github.com/user/plugin4', + -- Git branch, tag, or commit hash + version = 'main', + }, + }) + + -- Plugin's code can be used directly after `add()` + plugin1 = require('plugin1') +< +• Restart Nvim (for example, with |:restart|). Plugins that were not yet + installed will be available on disk in target state after `add()` call. +• To update all plugins with new changes: + • Execute |vim.pack.update()|. This will download updates from source and + show confirmation buffer in a separate tabpage. + • Review changes. To confirm all updates execute |:write|. To discard + updates execute |:quit|. + +Switch plugin's version: +• Update 'init.lua' for plugin to have desired `version`. Let's say, plugin + named 'plugin1' has changed to `vim.version.range('*')`. +• |:restart|. The plugin's actual state on disk is not yet changed. +• Execute `vim.pack.update({ 'plugin1' })`. +• Review changes and either confirm or discard them. If discarded, revert any + changes in 'init.lua' as well or you will be prompted again next time you + run |vim.pack.update()|. + +Freeze plugin from being updated: +• Update 'init.lua' for plugin to have `version` set to current commit hash. + You can get it by running `vim.pack.update({ 'plugin-name' })` and yanking + the word describing current state (looks like `abc12345`). +• |:restart|. + +Unfreeze plugin to start receiving updates: +• Update 'init.lua' for plugin to have `version` set to whichever version you + want it to be updated. +• |:restart|. + +Remove plugins from disk: +• Use |vim.pack.del()| with a list of plugin names to remove. Make sure their + specs are not included in |vim.pack.add()| call in 'init.lua' or they will + be reinstalled. + +Available events to hook into ~ +• *PackChangedPre* - before trying to change plugin's state. +• *PackChanged* - after plugin's state has changed. + +Each event populates the following |event-data| fields: +• `kind` - one of "install" (install on disk), "update" (update existing + plugin), "delete" (delete from disk). +• `spec` - plugin's specification. +• `path` - full path to plugin's directory. + + +*vim.pack.Spec* + + Fields: ~ + • {src} (`string`) URI from which to install and pull updates. Any + format supported by `git clone` is allowed. + • {name}? (`string`) Name of plugin. Will be used as directory name. + Default: `src` repository name. + • {version}? (`string|vim.VersionRange`) Version to use for install and + updates. Can be: + • `nil` (no value, default) to use repository's default + branch (usually `main` or `master`). + • String to use specific branch, tag, or commit hash. + • Output of |vim.version.range()| to install the + greatest/last semver tag inside the version constraint. + + +add({specs}, {opts}) *vim.pack.add()* + Add plugin to current session + • For each specification check that plugin exists on disk in + |vim.pack-directory|: + • If exists, do nothin in this step. + • If doesn't exist, install it by downloading from `src` into `name` + subdirectory (via `git clone`) and update state to match `version` + (via `git checkout`). + • For each plugin execute |:packadd| making them reachable by Nvim. + + Notes: + • Installation is done in parallel, but waits for all to finish before + continuing next code execution. + • If plugin is already present on disk, there are no checks about its + present state. The specified `version` can be not the one actually + present on disk. Execute |vim.pack.update()| to synchronize. + • Adding plugin second and more times during single session does nothing: + only the data from the first adding is registered. + + Parameters: ~ + • {specs} (`(string|vim.pack.Spec)[]`) List of plugin specifications. + String item is treated as `src`. + • {opts} (`table?`) A table with the following fields: + • {load}? (`boolean`) Load `plugin/` files and `ftdetect/` + scripts. If `false`, works like `:packadd!`. Default + `true`. + +del({names}) *vim.pack.del()* + Remove plugins from disk + + Parameters: ~ + • {names} (`string[]`) List of plugin names to remove from disk. Must + be managed by |vim.pack|, not necessarily already added to + current session. + +get() *vim.pack.get()* + Get data about all plugins managed by |vim.pack| + + Return: ~ + (`table[]`) A list of objects with the following fields: + • {spec} (`vim.pack.SpecResolved`) A |vim.pack.Spec| with defaults + made explicit. + • {path} (`string`) Plugin's path on disk. + • {active} (`boolean`) Whether plugin was added via |vim.pack.add()| + to current session. + +update({names}, {opts}) *vim.pack.update()* + Update plugins + • Download new changes from source. + • Infer update info (current/target state, changelog, etc.). + • Depending on `force`: + • If `false`, show confirmation buffer. It lists data about all set to + update plugins. Pending changes starting with `>` will be applied + while the ones starting with `<` will be reverted. It has special + in-process LSP server attached to provide more interactive features. + Currently supported methods: + • 'textDocument/documentSymbol' (`gO` via |lsp-defaults| or + |vim.lsp.buf.document_symbol()|) - show structure of the buffer. + • 'textDocument/hover' (`K` via |lsp-defaults| or + |vim.lsp.buf.hover()|) - show more information at cursor. Like + details of particular pending change or newer tag. + Execute |:write| to confirm update, execute |:quit| to discard the + update. + • If `true`, make updates right away. + + Notes: + • Every actual update is logged in "nvim-pack.log" file inside "log" + |stdpath()|. + + Parameters: ~ + • {names} (`string[]?`) List of plugin names to update. Must be managed + by |vim.pack|, not necessarily already added to current + session. Default: names of all plugins added to current + session via |vim.pack.add()|. + • {opts} (`table?`) A table with the following fields: + • {force}? (`boolean`) Whether to skip confirmation and make + updates immediately. Default `false`. + + + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index 3f7504bb93..fe6a8be443 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* diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua index d712e41b7a..7568cc3788 100755 --- a/src/gen/gen_vimdoc.lua +++ b/src/gen/gen_vimdoc.lua @@ -144,7 +144,6 @@ local config = { '_inspector.lua', 'shared.lua', 'loader.lua', - 'pack.lua', 'uri.lua', 'ui.lua', '_extui.lua', @@ -169,7 +168,6 @@ local config = { 'runtime/lua/vim/_options.lua', 'runtime/lua/vim/shared.lua', 'runtime/lua/vim/loader.lua', - 'runtime/lua/vim/pack.lua', 'runtime/lua/vim/uri.lua', 'runtime/lua/vim/ui.lua', 'runtime/lua/vim/_extui.lua', @@ -403,6 +401,17 @@ local config = { return { 'vim.health', 'health' } end, }, + pack = { + filename = 'pack.txt', + files = { 'runtime/lua/vim/pack.lua' }, + section_order = { 'pack.lua' }, + section_fmt = function(_name) + return 'Plugin manager' + end, + helptag_fmt = function() + return { 'vim.pack' } + end, + }, } --- @param ty string