diff --git a/README.vim.md b/README.vim.md
index 25c49a7..4b163f0 100644
--- a/README.vim.md
+++ b/README.vim.md
@@ -3,20 +3,32 @@
## 11.x
- **New Website**: There's a whole new website with a fresh look and improved documentation.
- Check it out at [lazy.nvim](https://lazy.folke.io/).
+ Check it out at [https://lazy.folke.io](https://lazy.folke.io/).
The GitHub `README.md` has been updated to point to the new website.
The `vimdoc` contains all the information that is available on the website.
- **Spec Resolution & Merging**: the code that resolves a final spec from a plugin's fragments has been rewritten.
This should be a tiny bit faster, but more importantly, fixes some issues and is easier to maintain.
-- `rocks`: specs can now specify a list of rocks ([luarocks](https://luarocks.org/)) that should be installed.
-
- [Packages](https://lazy.folke.io/packages) can now specify their dependencies and configuration using one of:
+
- **Lazy**: `lazy.lua` file
- **Rockspec**: [luarocks](https://luarocks.org/) `*-scm-1.rockspec` [file](https://github.com/luarocks/luarocks/wiki/Rockspec-format)
- **Packspec**: `pkg.json` (experimental, since the [format](https://github.com/neovim/packspec/issues/41) is not quite there yet)
+- Packages are not limited to just Neovim plugins. You can install any **luarocks** package, like:
+
+ ```lua
+ { "https://github.com/lubyk/yaml" }
+ ```
+
+ Luarocks packages without a `/lua` directory are never lazy-loaded, since it's just a library.
+
+- `build` functions or `*.lua` build files (like `build.lua`) now run asynchronously.
+ You can use `coroutine.yield(status_msg)` to show progress.
+ Yielding will also schedule the next `resume` to run in the next tick,
+ so you can do long-running tasks without blocking Neovim.
+
# π Getting Started
**lazy.nvim** is a modern plugin manager for Neovim.
@@ -182,14 +194,13 @@ A valid spec should define one of `[1]`, `dir` or `url`.
## Spec Setup
-| Property | Type | Description |
-| ---------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **init** | `fun(LazyPlugin)` | `init` functions are always executed during startup |
-| **opts** | `table` or `fun(LazyPlugin, opts:table)` | `opts` should be a table (will be merged with parent specs), return a table (replaces parent specs) or should change a table. The table will be passed to the `Plugin.config()` function. Setting this value will imply `Plugin.config()` |
-| **config** | `fun(LazyPlugin, opts:table)` or `true` | `config` is executed when the plugin loads. The default implementation will automatically run `require(MAIN).setup(opts)` if `opts` or `config = true` is set. Lazy uses several heuristics to determine the plugin's `MAIN` module automatically based on the plugin's **name**. See also `opts`. To use the default implementation without `opts` set `config` to `true`. |
-| **main** | `string?` | You can specify the `main` module to use for `config()` and `opts()`, in case it can not be determined automatically. See `config()` |
-| **build** | `fun(LazyPlugin)` or `string` or a list of build commands | `build` is executed when a plugin is installed or updated. Before running `build`, a plugin is first loaded. If it's a string it will be run as a shell command. When prefixed with `:` it is a Neovim command. You can also specify a list to executed multiple build commands. Some plugins provide their own `build.lua` which is automatically used by lazy. So no need to specify a build step for those plugins. |
-| **rocks** | `string[]?` | Add any [luarocks](https://luarocks.org/) dependencies. |
+| Property | Type | Description |
+| ---------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **init** | `fun(LazyPlugin)` | `init` functions are always executed during startup |
+| **opts** | `table` or `fun(LazyPlugin, opts:table)` | `opts` should be a table (will be merged with parent specs), return a table (replaces parent specs) or should change a table. The table will be passed to the `Plugin.config()` function. Setting this value will imply `Plugin.config()` |
+| **config** | `fun(LazyPlugin, opts:table)` or `true` | `config` is executed when the plugin loads. The default implementation will automatically run `require(MAIN).setup(opts)` if `opts` or `config = true` is set. Lazy uses several heuristics to determine the plugin's `MAIN` module automatically based on the plugin's **name**. See also `opts`. To use the default implementation without `opts` set `config` to `true`. |
+| **main** | `string?` | You can specify the `main` module to use for `config()` and `opts()`, in case it can not be determined automatically. See `config()` |
+| **build** | `fun(LazyPlugin)` or `string` or a list of build commands | `build` is executed when a plugin is installed or updated. See [Building](/developers#building) for more information. |
## Spec Lazy Loading
@@ -431,7 +442,7 @@ Syntax is the same as any plugin spec.
## Rockspec
-When a plugin contains a `*-scm-1.rockspec` file, **lazy.nvim** will automatically load its [`rocks`](/spec#setup) dependencies.
+When a plugin contains a `*-1.rockspec` file, **lazy.nvim** will automatically build the rock and its dependencies.
## Packspec
@@ -976,12 +987,78 @@ specs, adding any keys you want to override / merge.
`opts`, `dependencies`, `cmd`, `event`, `ft` and `keys` are always merged with the parent spec.
Any other property will override the property from the parent spec.
-# π Plugin Developers
+# π₯ Developers
To make it easier for users to install your plugin, you can include a [package spec](/packages) in your repo.
-If your plugin needs a build step, you can specify this in your **package file**,
-or create a file `build.lua` or `build/init.lua` in the root of your repo.
-This file will be loaded when the plugin is installed or updated.
+## Best Practices
-This makes it easier for users, as they no longer need to specify a `build` command.
\ No newline at end of file
+- If your plugin needs `setup()`, then create a simple `lazy.lua` file like this:
+
+ ```lua
+ return { "me/my-plugin", opts = {} }
+ ```
+
+- Plugins that are pure lua libraries should be lazy-loaded with `lazy = true`.
+
+ ```lua
+ { "nvim-lua/plenary.nvim", lazy = true }
+ ```
+
+- Only use `dependencies` if a plugin needs the dep to be installed **AND** loaded.
+ Lua plugins/libraries are automatically loaded when they are `require()`d,
+ so they don't need to be in `dependencies`.
+
+ :::tip[GOOD]
+
+ ```lua
+ { "folke/todo-comments.nvim", opts = {} },
+ { "nvim-lua/plenary.nvim", lazy = true },
+ ```
+
+ :::
+
+ :::danger[BAD]
+
+ ```lua
+ {
+ "folke/todo-comments.nvim",
+ opts = {},
+ -- This will always load plenary as soon as todo-comments loads,
+ -- even when todo-comments doesn't use it.
+ dependencies = { "nvim-lua/plenary.nvim", lazy = true },
+ },
+ ```
+
+ :::
+
+- Inside a `build` function or `*.lua` build file, use `coroutine.yield(status_msg)` to show progress.
+
+- Don't change the `cwd` in your build function, since builds run in parallel and changing the `cwd` will affect other builds.
+
+## Building
+
+The spec **build** property can be one of the following:
+
+- `fun(plugin: LazyPlugin)`: a function that builds the plugin.
+- `*.lua`: a Lua file that builds the plugin (like `build.lua`)
+- `":Command"`: a Neovim command
+- `"rockspec"`: this will run `luarocks make` in the plugin's directory
+ This is automatically set by the `rockspec` [package](/packages) source.
+- any other **string** will be run as a shell command
+- a `list` of any of the above to run multiple build steps
+- if no `build` is specified, but a `build.lua` file exists, that will be used instead.
+
+Build functions and `*.lua` files run asynchronously in a coroutine.
+Use `coroutine.yield(status_msg)` to show progress.
+Yielding will also schedule the next `coroutine.resume()` to run in the next tick, so you can do long-running tasks without blocking Neovim.
+
+:::tip
+
+If you need to know the directory of your build lua file, you can use:
+
+```lua
+local dir = vim.fn.fnamemodify(debug.getinfo(1, "S").source:sub(2), ":p:h")
+```
+
+:::
\ No newline at end of file
diff --git a/doc/lazy.nvim.txt b/doc/lazy.nvim.txt
index ed9bcad..b31fb4e 100644
--- a/doc/lazy.nvim.txt
+++ b/doc/lazy.nvim.txt
@@ -36,7 +36,9 @@ Table of Contents *lazy.nvim-table-of-contents*
- π¦ Migration Guide |lazy.nvim-π-usage-π¦-migration-guide|
- β‘ Profiling & Debug |lazy.nvim-π-usage-β‘-profiling-&-debug|
- π Structuring Your Plugins|lazy.nvim-π-usage-π-structuring-your-plugins|
-8. π Plugin Developers |lazy.nvim-π-plugin-developers|
+8. π₯ Developers |lazy.nvim-π₯-developers|
+ - Best Practices |lazy.nvim-π₯-developers-best-practices|
+ - Building |lazy.nvim-π₯-developers-building|
9. Links |lazy.nvim-links|
==============================================================================
@@ -46,19 +48,28 @@ Table of Contents *lazy.nvim-table-of-contents*
11.X *lazy.nvim-π°-whatβs-new?-11.x*
- **New Website**: Thereβs a whole new website with a fresh look and improved
- documentation. Check it out at lazy.nvim . The GitHub
- `README.md` has been updated to point to the new website. The `vimdoc` contains
- all the information that is available on the website.
+ documentation. Check it out at . The GitHub `README.md`
+ has been updated to point to the new website. The `vimdoc` contains all the
+ information that is available on the website.
- **Spec Resolution & Merging**: the code that resolves a final spec from a
pluginβs fragments has been rewritten. This should be a tiny bit faster, but
more importantly, fixes some issues and is easier to maintain.
-- `rocks`: specs can now specify a list of rocks (luarocks
- ) that should be installed.
- Packages can now specify their dependencies
and configuration using one of:
- **Lazy**: `lazy.lua` file
- **Rockspec**: luarocks `*-scm-1.rockspec` file
- **Packspec**: `pkg.json` (experimental, since the format is not quite there yet)
+- Packages are not limited to just Neovim plugins. You can install any
+ **luarocks** package, like:
+ >lua
+ { "https://github.com/lubyk/yaml" }
+ <
+ Luarocks packages without a `/lua` directory are never lazy-loaded, since
+ itβs just a library.
+- `build` functions or `*.lua` build files (like `build.lua`) now run
+ asynchronously. You can use `coroutine.yield(status_msg)` to show progress.
+ Yielding will also schedule the next `resume` to run in the next tick, so you
+ can do long-running tasks without blocking Neovim.
==============================================================================
@@ -235,9 +246,9 @@ SPEC LOADING *lazy.nvim-π-plugin-spec-spec-loading*
SPEC SETUP *lazy.nvim-π-plugin-spec-spec-setup*
- -----------------------------------------------------------------------------------------------------
+ ----------------------------------------------------------------------------------------------------
Property Type Description
- ---------- ----------------------------- ------------------------------------------------------------
+ ---------- ----------------------------- -----------------------------------------------------------
init fun(LazyPlugin) init functions are always executed during startup
opts table or opts should be a table (will be merged with parent specs),
@@ -258,15 +269,8 @@ SPEC SETUP *lazy.nvim-π-plugin-spec-spec-setup*
config()
build fun(LazyPlugin) or string or build is executed when a plugin is installed or updated.
- a list of build commands Before running build, a plugin is first loaded. If itβs a
- string it will be run as a shell command. When prefixed with
- : it is a Neovim command. You can also specify a list to
- executed multiple build commands. Some plugins provide their
- own build.lua which is automatically used by lazy. So no
- need to specify a build step for those plugins.
-
- rocks string[]? Add any luarocks dependencies.
- -----------------------------------------------------------------------------------------------------
+ a list of build commands See Building for more information.
+ ----------------------------------------------------------------------------------------------------
SPEC LAZY LOADING *lazy.nvim-π-plugin-spec-spec-lazy-loading*
@@ -535,8 +539,8 @@ dependencies and configuration. Syntax is the same as any plugin spec.
ROCKSPEC *lazy.nvim-π¦-packages-rockspec*
-When a plugin contains a `*-scm-1.rockspec` file, **lazy.nvim** will
-automatically load its `rocks` dependencies.
+When a plugin contains a `*-1.rockspec` file, **lazy.nvim** will automatically
+build the rock and its dependencies.
PACKSPEC *lazy.nvim-π¦-packages-packspec*
@@ -1175,17 +1179,49 @@ spec.
==============================================================================
-8. π Plugin Developers *lazy.nvim-π-plugin-developers*
+8. π₯ Developers *lazy.nvim-π₯-developers*
To make it easier for users to install your plugin, you can include a package
spec in your repo.
-If your plugin needs a build step, you can specify this in your **package
-file**, or create a file `build.lua` or `build/init.lua` in the root of your
-repo. This file will be loaded when the plugin is installed or updated.
-This makes it easier for users, as they no longer need to specify a `build`
-command.
+BEST PRACTICES *lazy.nvim-π₯-developers-best-practices*
+
+- If your plugin needs `setup()`, then create a simple `lazy.lua` file like this:
+ >lua
+ return { "me/my-plugin", opts = {} }
+ <
+- Plugins that are pure lua libraries should be lazy-loaded with `lazy = true`.
+ >lua
+ { "nvim-lua/plenary.nvim", lazy = true }
+ <
+- Only use `dependencies` if a plugin needs the dep to be installed **AND**
+ loaded. Lua plugins/libraries are automatically loaded when they are
+ `require()`d, so they donβt need to be in `dependencies`.
+- Inside a `build` function or `*.lua` build file, use
+ `coroutine.yield(status_msg)` to show progress.
+- Donβt change the `cwd` in your build function, since builds run in parallel
+ and changing the `cwd` will affect other builds.
+
+
+BUILDING *lazy.nvim-π₯-developers-building*
+
+The spec **build** property can be one of the following:
+
+- `fun(plugin: LazyPlugin)`: a function that builds the plugin.
+- `*.lua`: a Lua file that builds the plugin (like `build.lua`)
+- `":Command"`: a Neovim command
+- `"rockspec"`: this will run `luarocks make` in the pluginβs directory
+ This is automatically set by the `rockspec` package source.
+- any other **string** will be run as a shell command
+- a `list` of any of the above to run multiple build steps
+- if no `build` is specified, but a `build.lua` file exists, that will be used instead.
+
+Build functions and `*.lua` files run asynchronously in a coroutine. Use
+`coroutine.yield(status_msg)` to show progress. Yielding will also schedule the
+next `coroutine.resume()` to run in the next tick, so you can do long-running
+tasks without blocking Neovim.
+
==============================================================================
9. Links *lazy.nvim-links*
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index c35bdef..d80bb58 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -187,12 +187,6 @@ sidebar_position: 5
skip_if_doc_exists = true,
},
state = vim.fn.stdpath("state") .. "/lazy/state.json", -- state info for checker and other things
- build = {
- -- Plugins can provide a `build.lua` file that will be executed when the plugin is installed
- -- or updated. When the plugin spec also has a `build` command, the plugin's `build.lua` not be
- -- executed. In this case, a warning message will be shown.
- warn_on_override = true,
- },
-- Enable profiling of lazy.nvim. This will add some overhead,
-- so only enable this when you are debugging lazy.nvim
profiling = {