Breaking change:
This change renames the `modules` field in `modules.lua` to `features`.
Previous API:
`doom.modules.whichkey.settings.leader = ","`
New API:
`doom.features.whichkey.settings.leader = ","`
or
`doom.modules.features.whichkey.settings.leader = ","`
This has been made because that module also handles C source code support since C and C++ shares toolstack (e.g. lsp and formatters). Also to keep consistency with doom emacs layout.
These changes have been discussed in #233.
As a side note, I ran stylua and luacheck over the repo.
* From everyone's perpective
- The module structure has been flattened out, removing the category
grouping. Beyond less iteration scopes, this may help with, in the
future, allowing the user to write and enable custom modules in
$DOOMDIR.
* From the user's perpective
- `doom_config.lua` works via overrides now, it can change defaults
on the global `doom` before everything gets actually configured.
- `doom_modules.lua` just returns the actual thing it's supposed to,
without {return value}.source. More on that next.
- Instead of each config file returning a source key with its file
location, the handlers for each config file actively search for them.
This is described in the respective files inside `lua/doom/core/config`,
but it's basicaly a check for two special paths falling back to
runtimepath.
- `doom_userplugins.lua` is removed in favor of having its
functionality in `doom_config.lua`. To add a standalone package, add
its packer spec to `doom.packages` (this is a map-like table of
package names to packer specs).
- To override the spec of a module package, change the keys in
`doom.packages[package_name_without_author]`.
Special attrs: `config` is run after the built-in config.
- To change settings and behavior, override keys in
`doom[module]`, or just `doom.*` for some core features.
- To add standalone bindings, add them to `doom.binds`. This is
passed to nest along with the modules' binds. `doom.binds` overrides
anything you don't like in modules, you can safely replace the bind.
- To add standalone autocmds, add them to `doom.autocmds[augroup_name]`. The
structure is as passed to `utils.create_augroups`, so:
```lua
doom.autocmds[group_name] = {
{ event1, pattern1, cmd1 },
...
}
```
- You shouldn't override any tables, like `doom.autocmds` or `doom.packages`,
only the leaves, else you remove all that is already there. We could
use metatables to avoid this in the future.
- The `config.nvim` table is no longer used, most of its functionality is spread
elsewhere, like autocmds. For variables and options, just use
vim.opt.*, vim.g.* etc. in `doom_config.lua`
- Settings can also be appended to in `doom_config.lua`, because
defaults are prepopulated.
* From a maintainer's perpective
- Most things are grouped under the `doom` global, which is populated
and overriden early in `init.lua`. The exception is enabled modules,
which you still need to require `doom.core.config.modules` to get.
However, do so sparingly, and only if you truly mean to iterate over
enabled modules disregarding user overrides (they may have removed a
particular package or reset binds).
- Modules are defined in the following folder structure inside
`lua/doom/modules`:
`<module>/{init.lua,packages.lua,binds.lua,autocmds.lua}`.
init.lua and packages.lua are required, even if empty.
- `init.lua` returns: defaults under a `defaults` key; config functions
under `packer_config[package_name]`. It can access the doom global
only inside the configs.
- `packages.lua` returns: a map of package names to package specs, with no
`config` or `disable` keys present. Most things should be lazy-loaded,
preferably with the `cmd` and `module` keys. It cannot access the doom global.
- `autocmds.lua` returns: a list of autocmds to be applied under the group
`doom_{module}`. It can use the `doom` global to add things
conditionally.
- `binds.lua` returns: the keyconfig to be passed to nest. It can use the
`doom` global to add things conditionally.
What's left:
- Implement lsp wrapping.
- Document the individual modules.
- Write a migration script.
connorgmeean
NTBBloodbath
Luigi Sartor Piucco