`GIT_REPOSITORY` will cause cmake to rebuild if local dependency
changes, which isn't the case for `URL`.
Also document how to test a different commits of a dependency.
Problem:
The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.
Solution:
Re-implement the flow using Lua, LPEG and treesitter.
- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
- LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
- LPEG for C parsing (see `scripts/cdoc_parser.lua`)
- Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
- Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
- `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).
Github Issue template:
- Add pointers to |dev-tools-backtrace|.
- Add pointers to CONTRIBUTING.md (Reporting Problems), which includes
additional helpful instructions for issue reporting.
- Search existing issues: include label `bug-crash` as well as `bug`.
CONTRIBUTING.md:
- Fix broken link on "stacktrace" after moving to help from wiki.
Summary: Separate the lint job (`make lintdoc`) to validate runtime/doc,
it is no longer as a part of functionaltest (help_spec).
Build (cmake) and CI:
- `make lintdoc`: validate vimdoc files and test-generate HTML docs.
CI will run this as a part of the "docs" workflow.
- `scripts/lintdoc.lua` is added as an entry point (executable script)
for validating vimdoc files.
scripts/gen_help_html.lua:
- Move the tests for validating docs and generating HTMLs from
`help_spec.lua` to `gen_help_html`. Added:
- `gen_help_html.run_validate()`.
- `gen_help_html.test_gen()`.
- Do not hard-code `help_dir` to `build/runtime/doc`, but resolve from
`$VIMRUNTIME`. Therefore, the `make lintdoc` job will check doc files
on `./runtime/doc`, not on `./build/runtime/doc`.
- Add type annotations for gen_help_html.
Problem: Wiki contents are not discoverable and hard to maintain.
Solution: Move FAQ to runtime docs.
Co-authored-by: Christian Clason <c.clason@uni-graz.at>
We already have an extensive suite of static analysis tools we use,
which causes a fair bit of redundancy as we get duplicate warnings. PVS
is also prone to give false warnings which creates a lot of work to
identify and disable.
It is enabled with ENABLE_ASAN_UBSAN like other compilers. Technically
it only enables ASAN as UBSAN is not available, meaning to make the
variable names fully correct we'd need to separate it into two checks:
ENABLE_ASAN and ENABLE_UBSAN, but the convenience of combining them into
the same flag outweighs the theoretical correctness.
Also note in CONTRIBUTING.md that debug builds in ASAN is not supported.
Technically it is the debug runtime that is not supported, which cmake
automatically enables when using the debug build type. However, neovim
can't be built with debug builds without linking to the debug runtime
since the third party libraries has likely been linked to the debug
runtime if it was built with debug build type. This technicality is
likely uninteresting to the potential developer and it's easier to just
say to use a release build type.
Recommend adding a space after i.e. `--- @see`.
The "space" variant is common for the vast majority of docstring formats
such as doxygen, javadoc and typescript.
Co-authored by: zeertzjq <zeertzjq@outlook.com>
Co-authored by: Steven Todd McIntyre II <114119064+stmii@users.noreply.github.com>
Co-authored by: nobe4 <nobe4@users.noreply.github.com>
- docs: mention --luadev-mod to run with lua runtime files
When changing a lua file in the ./runtime folder, a new contributor
might expect changes to be applied to the built Neovim binary.
`cmake --preset ci`
is equivalent to
`cmake -B build -G Ninja -D CI_BUILD=ON`
Also remove build presets as they're not very useful without workflow
presets, which are only available in schema versions 6 and above.
Having a workflow that only builds neovim without running all of the
tests is a cheap way to test the build still works without burning too
much CI time.
- Suggest reading CONTRIBUTING.md once, not for each commit failure
- Suggest using "fix" type if none of the provided types are appropriate
- Remove "dist" type. It's rarely used and can be replaced by using the
"build" type
Initial benchmarks show that this gives a nice 50% compile time
reduction for neovim. This shouldn't affect users or CI, but it's a nice
speedup for local development. The C_COMPILER_LAUNCHER target property
is only supported by Makefiles and Ninja generators only, so this won't
give a speedup when using the Xcode and Visual Studio generators even if
ccache is available.
Workflow presets allows combining configure, build, test and packaging
steps and makes it possible to run everything in a single command. So
cmake --preset iwyu
cmake --build --preset iwyu
instead becomes
cmake --workflow --preset iwyu
Workflow presets requires at least cmake version 3.25 to use.
Problem:
Nvim has Lua but the "nvim" CLI can't easily be used to execute Lua
scripts, especially scripts that take arguments or produce output.
Solution:
- support "nvim -l [args...]" for running scripts. closes#15749
- exit without +q
- remove lua2dox_filter
- remove Doxyfile. This wasn't used anyway, because the doxygen config
is inlined in gen_vimdoc.py (`Doxyfile` variable).
- use "nvim -l" in docs-gen CI job
Examples:
$ nvim -l scripts/lua2dox.lua --help
Lua2DoX (0.2 20130128)
...
$ echo "print(vim.inspect(_G.arg))" | nvim -l - --arg1 --arg2
$ echo 'print(vim.inspect(vim.api.nvim_buf_get_text(1,0,0,-1,-1,{})))' | nvim +"put ='text'" -l -
TODO?
-e executes Lua code
-l loads a module
-i enters REPL _after running the other arguments_.
Allow Include What You Use to remove unnecessary includes and only
include what is necessary. This helps with reducing compilation times
and makes it easier to visualise which dependencies are actually
required.
Work on https://github.com/neovim/neovim/issues/549, but doesn't close
it since this only works fully for .c files and not headers.
dispatch.sr.ht is being deprecated, meaning that using sourcehut CI
won't be possible (see https://github.com/neovim/neovim/issues/19609).
Since Github Actions doesn't provide any BSD runners an external service
is required and Cirrus CI seems like a good replacement for sourcehut.
Initially experimented with using FreeBSD and OpenBSD virtual machines
in GitHub Actions, but Cirrus has been a much better fit with better
performance, logs and overall experience.
Failing tests are automatically skipped on FreeBSD regardless if it's on
CI or not. Ideally these tests should only be skipped in CI with the
help of `isCI` helper function. Unfortunately, the tests don't recognize
the environment variable CIRRUS_CI even if it's set manually. This
workaround is good enough for the time being, but we might want to only
skip tests when using the CI (or even better, fix the failing tests).
Closes: https://github.com/neovim/neovim/issues/19609
The targets will only format files that have been changed in current
branch compared to the master branch. This includes unstaged, staged and
committed files.
Add following make and cmake targets:
formatc - format changed c files
formatlua - format changed lua files
format - run formatc and formatlua
Remove scripts/uncrustify.sh as this deprecates it.
The Sumneko Lua language server has matured quite a bit and many
Neovim developers use it while working on Neovim. Having a default
configuration for Neovim development is a nice convenience (and
dovetails well with the auto-generated compile_command.json for C
development).
The file is shipped under `contrib` and users can make use of it by
symlinking to `.luarc.json` in the project root.
dundargoc