From 858576777eb3d5227c6450c327ea87e40a59fda1 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 25 Dec 2025 04:02:12 -0500 Subject: [PATCH] docs: lsp, options, promptbuf Close #37630 Close #37682 Close #37762 Close #37785 Co-authored-by: Daniel Schmitt Co-authored-by: Duane Hilton Co-authored-by: NeOzay Co-authored-by: Yi Ming Co-authored-by: "Justin M. Keyes" --- BUILD.md | 12 +++++++++++ CONTRIBUTING.md | 2 +- MAINTAIN.md | 12 ++++------- runtime/doc/channel.txt | 2 +- runtime/doc/dev.txt | 2 +- runtime/doc/dev_arch.txt | 4 ++-- runtime/doc/dev_style.txt | 2 +- runtime/doc/dev_test.txt | 27 ++++++++++++++++-------- runtime/doc/lsp.txt | 29 +++++++++++++++----------- runtime/doc/lua-plugin.txt | 3 ++- runtime/doc/map.txt | 4 ++-- runtime/doc/news.txt | 11 +++++----- runtime/lua/vim/health/health.lua | 2 ++ runtime/lua/vim/lsp.lua | 2 +- runtime/scripts/optwin.lua | 2 -- src/nvim/message.h | 2 +- test/functional/lua/fs_spec.lua | 2 +- test/functional/lua/ui_spec.lua | 2 +- test/functional/plugin/optwin_spec.lua | 2 ++ 19 files changed, 75 insertions(+), 49 deletions(-) diff --git a/BUILD.md b/BUILD.md index 7ff4680ed0..e49afa1456 100644 --- a/BUILD.md +++ b/BUILD.md @@ -70,6 +70,18 @@ make distclean make deps ``` +### PUC Lua + +To build with "PUC Lua" instead of LuaJit: + + make CMAKE_EXTRA_FLAGS="-DPREFER_LUA=ON" DEPS_CMAKE_FLAGS="-DUSE_BUNDLED_LUAJIT=OFF -DUSE_BUNDLED_LUA=ON" + +### Build options + +View the full list of CMake options defined in this project: + + cmake -B build -LH + ## Building on Windows ### Windows / MSVC diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 761e730c8a..4d6fc52c2a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -235,7 +235,7 @@ See [#549][549] for more details. The Lua [`runtime/lua/vim/_core/`](./runtime/lua/vim/_core/) modules are precompiled to bytecode, so changes won't be usable unless you (1) rebuild Nvim or (2) start Nvim with `--luamod-dev` and `$VIMRUNTIME`. For example try adding -a function to `runtime/lua/vim/editor.lua`, then: +a function to `runtime/lua/vim/_core/editor.lua`, then: ```bash VIMRUNTIME=./runtime ./build/bin/nvim --luamod-dev diff --git a/MAINTAIN.md b/MAINTAIN.md index 44a51bc875..3df2a808b8 100644 --- a/MAINTAIN.md +++ b/MAINTAIN.md @@ -116,12 +116,7 @@ should be stated explicitly and publicly. Third-party dependencies ------------------------ -For some dependencies we maintain temporary "forks", which are simply private -branches with a few extra patches, while we wait for the upstream project to -merge the patches. This is done instead of maintaining the patches as (fragile) -CMake `PATCH_COMMAND` steps. - -These "bundled" dependencies can be updated by bumping their versions in `cmake.deps/deps.txt`. +"Bundled" dependencies can be updated by bumping their versions in `cmake.deps/deps.txt`. Some can be auto-bumped by `scripts/bump_deps.lua`. * [LuaJIT](https://github.com/LuaJIT/LuaJIT) @@ -136,9 +131,10 @@ Some can be auto-bumped by `scripts/bump_deps.lua`. * [libiconv](https://ftp.gnu.org/pub/gnu/libiconv) * [lua-compat](https://github.com/keplerproject/lua-compat-5.3) * [tree-sitter](https://github.com/tree-sitter/tree-sitter) -* [unibilium](https://github.com/neovim/unibilium) - * The original project [was abandoned](https://github.com/neovim/neovim/issues/10302), so the [neovim/unibilium](https://github.com/neovim/unibilium) fork is considered "upstream" and is maintained on the `master` branch. * [treesitter parsers](https://github.com/neovim/neovim/blob/7e97c773e3ba78fcddbb2a0b9b0d572c8210c83e/cmake.deps/deps.txt#L47-L62) +* (Deprecated) [unibilium](https://github.com/neovim/unibilium) + * The original project [was abandoned](https://github.com/neovim/neovim/issues/10302), so the [neovim/unibilium](https://github.com/neovim/unibilium) fork is considered "upstream" and is maintained on the `master` branch. + * **Note:** unibilium is NOT required. See [BUILD.md](./BUILD.md#build-without-unibilium) to build Nvim without unibilium. ### Vendored dependencies diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt index ca09f4e542..494854d781 100644 --- a/runtime/doc/channel.txt +++ b/runtime/doc/channel.txt @@ -189,7 +189,7 @@ normally only do that in a newly created buffer: >vim The user can edit and input text at the end of the buffer. Pressing Enter in the input section invokes the |prompt_setcallback()| callback, which is typically expected to process the prompt and show results by appending to the -buffer. To input multiline text, use Shift- to add a new line without +buffer. To input multiline text, use *Shift-* to add a new line without submitting the prompt, or just |put| or |paste| multiline text. Only the section starting with the mark |':| of the buffer (after the prompt) diff --git a/runtime/doc/dev.txt b/runtime/doc/dev.txt index fae7a535a2..f5b4950c6d 100644 --- a/runtime/doc/dev.txt +++ b/runtime/doc/dev.txt @@ -365,7 +365,7 @@ Where possible, these patterns apply to _both_ Lua and the API: If `opts` is omitted (or `nil`) it returns the current configuration. - Example: See |vim.diagnostic.config()|. - "Enable" ("toggle") interface and behavior: - - `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control the + - `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control the "global" enablement of a feature. - `is_enabled(nil)` and `is_enabled({buf=nil})`, likewise, query the global state of the feature. diff --git a/runtime/doc/dev_arch.txt b/runtime/doc/dev_arch.txt index c6c5fc418f..e8aee5e7bb 100644 --- a/runtime/doc/dev_arch.txt +++ b/runtime/doc/dev_arch.txt @@ -154,8 +154,8 @@ API *dev-api-fast* API functions and Vimscript "eval" functions may be marked as |api-fast| which -means they are safe to call in Lua callbacks and other scenarios. A functions -CANNOT be marked as "fast" if could trigger `os_breakcheck()`, which may +means they are safe to call in Lua callbacks and other scenarios. A function +CANNOT be marked as "fast" if it could trigger `os_breakcheck()`, which may "yield" the current execution and start a new execution of code not expecting this: - accidentally recursing into a function not expecting this. diff --git a/runtime/doc/dev_style.txt b/runtime/doc/dev_style.txt index 8634a6d65b..9d8b0fd8ac 100644 --- a/runtime/doc/dev_style.txt +++ b/runtime/doc/dev_style.txt @@ -6,7 +6,7 @@ Nvim style guide *dev-style* -Style guidelines for developers working Nvim's source code. +Style guidelines for developers working on Nvim's source code. License: CC-By 3.0 https://creativecommons.org/licenses/by/3.0/ diff --git a/runtime/doc/dev_test.txt b/runtime/doc/dev_test.txt index e0523fb937..7bcfdbcc05 100644 --- a/runtime/doc/dev_test.txt +++ b/runtime/doc/dev_test.txt @@ -349,17 +349,26 @@ GUIDELINES files. - `#define` constants must be rewritten `const` or `enum` so they can be "visible" to the tests. -- Use `pending()` to skip tests - ([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)). - Do not silently skip the test with `if-else`. If a functional test depends on - some external factor (e.g. the existence of `md5sum` on `$PATH`), _and_ you - can't mock or fake the dependency, then skip the test via `pending()` if the - external factor is missing. This ensures that the _total_ test-count - (success + fail + error + pending) is the same in all environments. +- Use `pending()` or `t.skip()` to skip tests. + - Example: https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18 + - Note: If a test is skipped because of a non-actionable reason, we don't + want it to appear in the "pending" list. Include "N/A" in the skip + description, then it won't be added to the "pending" list. For example, if + a test is skipped because it's running on a non-LuaJit system, including + it in the "pending" list is just noise. Thus, its pending reason should + say "N/A": > + pending('N/A: missing LuaJIT FFI') +< + - Do not silently skip the test with `if-else`. If a functional test depends + on some external factor (e.g. the existence of `md5sum` on `$PATH`), _and_ + you can't mock or fake the dependency, then skip the test via `pending()` + if the external factor is missing. This ensures that the _total_ + test-count (success + fail + error + pending) is the same in all + environments. - Note: `pending()` is ignored if it is missing an argument, unless it is [contained in an `it()` block](https://github.com/neovim/neovim/blob/d21690a66e7eb5ebef18046c7a79ef898966d786/test/functional/ex_cmds/grep_spec.lua#L11). Provide empty function argument if the `pending()` call is outside `it()` - ([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)). + Example: https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18 WHERE TESTS GO @@ -502,7 +511,7 @@ Number; !must be defined to function properly): - `NVIM_TEST_TRACE_LEVEL` (U) (N): specifies unit tests tracing level: - `0` disables tracing (the fastest, but you get no data if tests crash and - there no core dump was generated), + no core dump was generated), - `1` leaves only C function calls and returns in the trace (faster than recording everything), - `2` records all function calls, returns and executed Lua source lines. diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 7cda4a5c9f..7bb3603f6a 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -56,7 +56,14 @@ Follow these steps to get LSP features: a |lsp-root_markers| file so the workspace can be recognized. 5. Check that LSP is active ("attached") for the buffer: >vim :checkhealth vim.lsp -6. (Optional) Configure keymaps and autocommands to use LSP features. +6. Please note that certain LSP features are disabled by default, + you may choose to enable them manually. See: + - |lsp-codelens| + - |lsp-document_color| + - |lsp-linked_editing_range| + - |lsp-inlay_hint| + - |lsp-inline_completion| +7. (Optional) Configure keymaps and autocommands to use LSP features. |lsp-attach| ============================================================================== @@ -657,18 +664,16 @@ LspProgress *LspProgress* Redraw the statusline whenever an LSP progress message arrives: >vim autocmd LspProgress * redrawstatus < - Tell the parent terminal to indicate progress using a native progress - indicator (requires a supporting terminal): >lua - vim.api.nvim_create_autocmd('LspProgress', { - callback = function(ev) + Emit a |progress-message| on LSP progress events: >lua + vim.api.nvim_create_autocmd('LspProgress', { buffer = buf, callback = function(ev) local value = ev.data.params.value - if value.kind == 'begin' then - vim.api.nvim_ui_send('\027]9;4;1;0\027\\') - elseif value.kind == 'end' then - vim.api.nvim_ui_send('\027]9;4;0\027\\') - elseif value.kind == 'report' then - vim.api.nvim_ui_send(string.format('\027]9;4;1;%d\027\\', value.percentage or 0)) - end + vim.api.nvim_echo({ { value.message or 'done' } }, false, { + id = 'lsp', + kind = 'progress', + title = value.title, + status = value.kind ~= 'end' and 'running' or 'success', + percent = value.percentage, + }) end, }) < diff --git a/runtime/doc/lua-plugin.txt b/runtime/doc/lua-plugin.txt index d1ec2c7dc7..390384513d 100644 --- a/runtime/doc/lua-plugin.txt +++ b/runtime/doc/lua-plugin.txt @@ -142,7 +142,8 @@ initialization may be useful in specific cases: Keep in mind that this approach requires users to call `setup` in order to use your plugin, even if the default configuration is enough for them. Consider carefully whether your plugin benefits from combined `setup()` pattern -before adopting it. +before adopting it. This article chronicles the history and tradeoffs of +`setup()`: https://mrcjkb.dev/posts/2023-08-22-setup.html NOTE: A well designed plugin has minimal impact on startup time. See also |lua-plugin-lazy|. diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 0d12438680..b588ffc05f 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -1581,7 +1581,7 @@ supports incremental command preview: preview_ns, 'Substitute', {line1 + i - 2, start_idx - 1}, - {line1 + i - 2, end_idx}, + {line1 + i - 2, end_idx} ) -- Add lines and set highlights in the preview buffer @@ -1601,7 +1601,7 @@ supports incremental command preview: preview_ns, 'Substitute', {preview_buf_line, #prefix + start_idx - 1}, - {preview_buf_line, #prefix + end_idx}, + {preview_buf_line, #prefix + end_idx} ) preview_buf_line = preview_buf_line + 1 end diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 6784a236ec..39f2eaa3a4 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -41,7 +41,7 @@ TREESITTER UI -• `progress` attribute removed form |ui-messages| msg_show event +• `progress` attribute removed from |ui-messages| msg_show event VIMSCRIPT @@ -255,7 +255,7 @@ LSP https://microsoft.github.io/language-server-protocol/specification/#textDocument_colorPresentation • The `textDocument/diagnostic` request now includes the previous id in its parameters. -• |vim.lsp.enable()| start/stops clients as necessary. And detaches +• |vim.lsp.enable()| start/stops clients as necessary and detaches non-applicable LSP clients. • |vim.lsp.is_enabled()| checks if a LSP config is enabled (without "resolving" it). @@ -314,7 +314,7 @@ LUA • |vim.hl.range()| now allows multiple timed highlights. • |vim.tbl_extend()| and |vim.tbl_deep_extend()| now accept a function behavior argument. • |vim.fs.root()| can define "equal priority" via nested lists. -• |vim.version.range()| output can be converted to human-readable string with |tostring()|. +• |vim.version.range()| output can be converted to a human-readable string with |tostring()|. • |vim.version.intersect()| computes intersection of two version ranges. • |Iter:take()| and |Iter:skip()| now optionally accept predicates. • Built-in plugin manager |vim.pack| @@ -359,17 +359,17 @@ PERFORMANCE additional constraints for improved correctness and resistance to backtracking edge cases. • |i_CTRL-R| inserts named/clipboard registers literally, 10x speedup. +• LSP `textDocument/semanticTokens/range` is supported, which requests tokens + for the viewport (visible screen) only. PLUGINS • Customize :checkhealth by handling a `FileType checkhealth` event. |health-usage| - • Simplify Python provider setup to a single step: `uv tool install pynvim` Nvim will detect the plugin's location without user configuration, even if unrelated Python virtual environments are activated. |provider-python| - • |:checkhealth| now checks for an available |vim.ui.open()| handler. STARTUP @@ -407,6 +407,7 @@ UI • "Error detected while processing:" changed to "Error in:". • "Error executing Lua:" changed to "Lua:". • 'busy' status is shown in default statusline with symbol ◐ +• Cursor shape indicates when it is behind an unfocused floating window. • Improved LSP signature help rendering. • Multigrid UIs can call nvim_input_mouse with grid 0 to let Nvim decide the grid. diff --git a/runtime/lua/vim/health/health.lua b/runtime/lua/vim/health/health.lua index da49d39afb..465f4a1528 100644 --- a/runtime/lua/vim/health/health.lua +++ b/runtime/lua/vim/health/health.lua @@ -621,6 +621,8 @@ local function check_sysinfo() [[ ## Problem + Describe the problem (concisely). + ## Steps to reproduce ``` diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index cfa3d04461..682f222e6c 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -198,7 +198,7 @@ end --- provide the root dir, or LSP will not be activated for the buffer. Thus a `root_dir()` function --- can dynamically decide per-buffer whether to activate (or skip) LSP. --- See example at |vim.lsp.enable()|. ---- @field root_dir? string|fun(bufnr: integer, on_dir:fun(root_dir?:string)) +--- @field root_dir? string|fun(bufnr: integer, on_dir:fun(root_dir?:string)) # --- --- [lsp-root_markers]() --- Filename(s) (".git/", "package.json", …) used to decide the workspace root. Unused if `root_dir` diff --git a/runtime/scripts/optwin.lua b/runtime/scripts/optwin.lua index ca3c48e775..572698e6aa 100644 --- a/runtime/scripts/optwin.lua +++ b/runtime/scripts/optwin.lua @@ -29,7 +29,6 @@ local options_list = { { 'autochdir', N_ 'change to directory of file in buffer' }, { 'wrapscan', N_ 'search commands wrap around the end of the buffer' }, { 'incsearch', N_ 'show match for partly typed search command' }, - { 'magic', N_ 'change the way backslashes are used in search patterns' }, { 'regexpengine', N_ 'select the default regexp engine used' }, { 'ignorecase', N_ 'ignore case when using a search pattern' }, { 'smartcase', N_ "override 'ignorecase' when pattern has upper case characters" }, @@ -438,7 +437,6 @@ local options_list = { { 'eventignorewin', N_ 'list of autocommand events which are to be ignored in a window' }, { 'loadplugins', N_ 'load plugin scripts when starting up' }, { 'exrc', N_ 'enable reading .vimrc/.exrc/.gvimrc in the current directory' }, - { 'gdefault', N_ 'use the \'g\' flag for ":substitute"' }, { 'maxfuncdepth', N_ 'maximum depth of function calls' }, { 'sessionoptions', N_ 'list of words that specifies what to put in a session file' }, { 'viewoptions', N_ 'list of words that specifies what to save for :mkview' }, diff --git a/src/nvim/message.h b/src/nvim/message.h index 938c0f245a..f34d79b767 100644 --- a/src/nvim/message.h +++ b/src/nvim/message.h @@ -37,7 +37,7 @@ EXTERN bool msg_ext_skip_flush INIT( = false); EXTERN bool msg_ext_append INIT( = false); /// Set to true when previous message should be overwritten. EXTERN bool msg_ext_overwrite INIT( = false); -/// Set to true to avoid setting "verbose" kind for last set messages. +/// Set to true to avoid setting "verbose" kind for "last set" messages. EXTERN bool msg_ext_skip_verbose INIT( = false); /// allocated grid for messages. Used unless ext_messages is active. diff --git a/test/functional/lua/fs_spec.lua b/test/functional/lua/fs_spec.lua index 8c826a211d..017d158584 100644 --- a/test/functional/lua/fs_spec.lua +++ b/test/functional/lua/fs_spec.lua @@ -731,7 +731,7 @@ describe('vim.fs', function() vim.uv.fs_rmdir('Xtest_fs-rm') end) - it('works with symlink', function() + it('symlink', function() -- File vim.uv.fs_symlink('Xtest_fs-rm/file-to-link', 'Xtest_fs-rm/file-as-link') vim.fs.rm('Xtest_fs-rm/file-as-link') diff --git a/test/functional/lua/ui_spec.lua b/test/functional/lua/ui_spec.lua index 5fe4257a3d..244082fdf2 100644 --- a/test/functional/lua/ui_spec.lua +++ b/test/functional/lua/ui_spec.lua @@ -109,7 +109,7 @@ describe('vim.ui', function() eq(true, exec_lua('return (nil == result)')) end) - it('can return opts.cacelreturn when aborted with ESC with cancelreturn opt #18144', function() + it('can return opts.cancelreturn when aborted with ESC with cancelreturn opt #18144', function() feed(':lua result = "on_confirm not called"') feed(':lua vim.ui.input({ cancelreturn = "CANCEL" }, function(input) result = input end)') feed('Inputted Text') diff --git a/test/functional/plugin/optwin_spec.lua b/test/functional/plugin/optwin_spec.lua index 143ffdd693..2cfed64588 100644 --- a/test/functional/plugin/optwin_spec.lua +++ b/test/functional/plugin/optwin_spec.lua @@ -68,10 +68,12 @@ describe('optwin.lua', function() 'secure', 'prompt', 'edcompatible', + 'gdefault', 'guioptions', 'guitablabel', 'guitabtooltip', 'insertmode', + 'magic', 'mouseshape', 'imcmdline', 'imdisable',