mirror of
https://github.com/neovim/neovim.git
synced 2024-09-17 20:58:20 -04:00
docs: add wiki FAQ to the runtime documentation (#26539)
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>
This commit is contained in:
parent
8122470f83
commit
ef58ee48f4
@ -24,7 +24,7 @@ Reporting problems
|
||||
- If a specific configuration or plugin is necessary to recreate the problem, use the minimal template in `contrib/minimal.lua` with `nvim --clean -u contrib/minimal.lua` after making the necessary changes.
|
||||
- [Bisect](https://neovim.io/doc/user/starting.html#bisect) your config: disable plugins incrementally, to narrow down the cause of the issue.
|
||||
- [Bisect][git-bisect] Neovim's source code to find the cause of a regression, if you can. This is _extremely_ helpful.
|
||||
- When reporting a crash, [include a stacktrace](https://github.com/neovim/neovim/wiki/FAQ#backtrace-linux).
|
||||
- When reporting a crash, [include a stacktrace](https://neovim.io/doc/user/faq.html#backtrace-linux).
|
||||
- Use [ASAN/UBSAN](#clang-sanitizers-asan-and-ubsan) to get detailed errors for segfaults and undefined behavior.
|
||||
- Check the logs. `:edit $NVIM_LOG_FILE`
|
||||
- Include `cmake --system-information` for build-related issues.
|
||||
@ -347,4 +347,4 @@ as context, use the `-W` argument as well.
|
||||
[pr-ready]: https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request
|
||||
[run-tests]: https://github.com/neovim/neovim/blob/master/test/README.md#running-tests
|
||||
[style-guide]: https://neovim.io/doc/user/dev_style.html#dev-style
|
||||
[wiki-faq]: https://github.com/neovim/neovim/wiki/FAQ
|
||||
[wiki-faq]: https://neovim.io/doc/user/faq.html
|
||||
|
192
runtime/doc/dev_tools.txt
Normal file
192
runtime/doc/dev_tools.txt
Normal file
@ -0,0 +1,192 @@
|
||||
*dev_tools.txt* Nvim
|
||||
|
||||
|
||||
NVIM REFERENCE MANUAL
|
||||
|
||||
|
||||
Tools and techniques for developing Nvim *dev-tools*
|
||||
|
||||
The following advice is helpful when working on or debugging issues with Nvim
|
||||
itself. See also |debug.txt| for advice that applies to Vim.
|
||||
|
||||
Type |gO| to see the table of contents.
|
||||
|
||||
==============================================================================
|
||||
Backtraces *dev-tools-backtrace*
|
||||
|
||||
LINUX ~
|
||||
|
||||
Core dumps are disabled by default on Ubuntu
|
||||
https://stackoverflow.com/a/18368068, CentOS and others. To enable core dumps:
|
||||
>bash
|
||||
ulimit -c unlimited
|
||||
<
|
||||
On systemd-based systems getting a backtrace is as easy as:
|
||||
>bash
|
||||
coredumpctl -1 gdb
|
||||
<
|
||||
It's an optional tool, so you may need to install it:
|
||||
>bash
|
||||
sudo apt install systemd-coredump
|
||||
<
|
||||
|
||||
The full backtrace is most useful, send us the `bt.txt` file:
|
||||
>bash
|
||||
2>&1 coredumpctl -1 gdb | tee -a bt.txt
|
||||
thread apply all bt full
|
||||
<
|
||||
On older systems a `core` file will appear in the current directory. To get
|
||||
a backtrace from the `core` file:
|
||||
>bash
|
||||
gdb build/bin/nvim core 2>&1 | tee backtrace.txt
|
||||
thread apply all bt full
|
||||
<
|
||||
|
||||
MACOS
|
||||
|
||||
If `nvim` crashes, you can see the backtrace in `Console.app` (under "Crash
|
||||
Reports" or "User Diagnostic Reports" for older macOS versions).
|
||||
>bash
|
||||
open -a Console
|
||||
<
|
||||
You may also want to enable core dumps on macOS. To do this, first make sure
|
||||
the `/cores/` directory exists and is writable:
|
||||
>bash
|
||||
sudo mkdir /cores
|
||||
sudo chown root:admin /cores
|
||||
sudo chmod 1775 /cores
|
||||
<
|
||||
Then set the core size limit to `unlimited`:
|
||||
>bash
|
||||
ulimit -c unlimited
|
||||
<
|
||||
Note that this is done per shell process. If you want to make this the default
|
||||
for all shells, add the above line to your shell's init file (e.g. `~/.bashrc`
|
||||
or similar).
|
||||
|
||||
You can then open the core file in `lldb`:
|
||||
>bash
|
||||
lldb -c /cores/core.12345
|
||||
<
|
||||
Apple's documentation archive has some other useful information
|
||||
https://developer.apple.com/library/archive/technotes/tn2124/_index.html#//apple_ref/doc/uid/DTS10003391-CH1-SECCOREDUMPS,
|
||||
but note that some of the things on this page are out of date (such as enabling
|
||||
core dumps with `/etc/launchd.conf`).
|
||||
|
||||
==============================================================================
|
||||
Gdb *dev-tools-gdb*
|
||||
|
||||
USING GDB TO STEP THROUGH FUNCTIONAL TESTS ~
|
||||
|
||||
Use `TEST_TAG` to run tests matching busted tags (of the form `#foo` e.g.
|
||||
`it("test #foo ...", ...)`):
|
||||
>bash
|
||||
GDB=1 TEST_TAG=foo make functionaltest
|
||||
<
|
||||
Then, in another terminal:
|
||||
>bash
|
||||
gdb build/bin/nvim
|
||||
target remote localhost:7777
|
||||
<
|
||||
- See also test/functional/helpers.lua https://github.com/neovim/neovim/blob/3098b18a2b63a841351f6d5e3697cb69db3035ef/test/functional/helpers.lua#L38-L44.
|
||||
|
||||
|
||||
USING LLDB TO STEP THROUGH UNIT TESTS ~
|
||||
|
||||
>bash
|
||||
lldb .deps/usr/bin/luajit -- .deps/usr/bin/busted --lpath="./build/?.lua" test/unit/
|
||||
<
|
||||
|
||||
USING GDB ~
|
||||
|
||||
To attach to a running `nvim` process with a pid of 1234:
|
||||
>bash
|
||||
gdb -tui -p 1234 build/bin/nvim
|
||||
<
|
||||
The `gdb` interactive prompt will appear. At any time you can:
|
||||
|
||||
- `break foo` to set a breakpoint on the `foo()` function
|
||||
- `n` to step over the next statement
|
||||
- `<Enter>` to repeat the last command
|
||||
- `s` to step into the next statement
|
||||
- `c` to continue
|
||||
- `finish` to step out of the current function
|
||||
- `p zub` to print the value of `zub`
|
||||
- `bt` to see a backtrace (callstack) from the current location
|
||||
- `CTRL-x CTRL-a` or `tui enable` to show a TUI view of the source file in the
|
||||
current debugging context. This can be extremely useful as it avoids the
|
||||
need for a gdb "frontend".
|
||||
- `<up>` and `<down>` to scroll the source file view
|
||||
|
||||
|
||||
GDB "REVERSE DEBUGGING" ~
|
||||
|
||||
- `set record full insn-number-max unlimited`
|
||||
- `continue` for a bit (at least until `main()` is executed
|
||||
- `record`
|
||||
- provoke the bug, then use `revert-next`, `reverse-step`, etc. to rewind the
|
||||
debugger
|
||||
|
||||
|
||||
USING GDBSERVER ~
|
||||
|
||||
You may want to connect multiple `gdb` clients to the same running `nvim`
|
||||
process, or you may want to connect to a remote `nvim` process with a local
|
||||
`gdb`. Using `gdbserver`, you can attach to a single process and control it
|
||||
from multiple `gdb` clients.
|
||||
|
||||
Open a terminal and start `gdbserver` attached to `nvim` like this:
|
||||
>bash
|
||||
gdbserver :6666 build/bin/nvim 2> gdbserver.log
|
||||
<
|
||||
`gdbserver` is now listening on port 6666. You then need to attach to this
|
||||
debugging session in another terminal:
|
||||
>bash
|
||||
gdb build/bin/nvim
|
||||
<
|
||||
Once you've entered `gdb`, you need to attach to the remote session:
|
||||
>
|
||||
target remote localhost:6666
|
||||
<
|
||||
In case gdbserver puts the TUI as a background process, the TUI can become
|
||||
unable to read input from pty (and receives SIGTTIN signal) and/or output data
|
||||
(SIGTTOU signal). To force the TUI as the foreground process, you can add
|
||||
>
|
||||
signal (SIGTTOU, SIG_IGN);
|
||||
if (!tcsetpgrp(data->input.in_fd, getpid())) {
|
||||
perror("tcsetpgrp failed");
|
||||
}
|
||||
<
|
||||
to `tui.c:terminfo_start`.
|
||||
|
||||
|
||||
USING GDBSERVER IN TMUX ~
|
||||
|
||||
Consider using a custom makefile
|
||||
https://github.com/neovim/neovim/wiki/Building-Neovim#custom-makefile to
|
||||
quickly start debugging sessions using the `gdbserver` method mentioned above.
|
||||
This example `local.mk` will create the debugging session when you type
|
||||
`make debug`.
|
||||
>make
|
||||
.PHONY: dbg-start dbg-attach debug build
|
||||
|
||||
build:
|
||||
@$(MAKE) nvim
|
||||
|
||||
dbg-start: build
|
||||
@tmux new-window -n 'dbg-neovim' 'gdbserver :6666 ./build/bin/nvim -D'
|
||||
|
||||
dbg-attach:
|
||||
@tmux new-window -n 'dbg-cgdb' 'cgdb -x gdb_start.sh ./build/bin/nvim'
|
||||
|
||||
debug: dbg-start dbg-attach
|
||||
<
|
||||
Here `gdb_start.sh` includes `gdb` commands to be called when the debugger
|
||||
starts. It needs to attach to the server started by the `dbg-start` rule. For
|
||||
example:
|
||||
>
|
||||
target remote localhost:6666
|
||||
br main
|
||||
<
|
||||
|
||||
vim:tw=78:ts=8:et:ft=help:norl:
|
485
runtime/doc/faq.txt
Normal file
485
runtime/doc/faq.txt
Normal file
@ -0,0 +1,485 @@
|
||||
*faq.txt* Nvim
|
||||
|
||||
NVIM REFERENCE MANUAL
|
||||
|
||||
|
||||
Frequently asked Questions *faq*
|
||||
|
||||
Type |gO| to see the table of contents.
|
||||
|
||||
==============================================================================
|
||||
General Questions *faq-general*
|
||||
|
||||
|
||||
WHERE SHOULD I PUT MY CONFIG (VIMRC)? ~
|
||||
|
||||
See |config|; you can copy (or symlink) your existing vimrc. |nvim-from-vim|
|
||||
|
||||
|
||||
HOW STABLE IS THE DEVELOPMENT (PRE-RELEASE) VERSION? ~
|
||||
|
||||
The unstable (pre-release)
|
||||
https://github.com/neovim/neovim/releases/tag/nightly version of Nvim
|
||||
("HEAD", i.e. the `master` branch) is used to aggressively stage new features
|
||||
and changes. It's usually stable, but will occasionally break your workflow.
|
||||
We depend on HEAD users to report "blind spots" that were not caught by
|
||||
automated tests.
|
||||
|
||||
Use the stable (release) https://github.com/neovim/neovim/releases/latest
|
||||
version for a more predictable experience.
|
||||
|
||||
|
||||
CAN I USE RUBY-BASED VIM PLUGINS (E.G. LUSTYEXPLORER)? ~
|
||||
|
||||
Yes, starting with Nvim 0.1.5 PR #4980
|
||||
https://github.com/neovim/neovim/pull/4980 the legacy Vim `if_ruby` interface
|
||||
is supported.
|
||||
|
||||
|
||||
CAN I USE LUA-BASED VIM PLUGINS (E.G. NEOCOMPLETE)? ~
|
||||
|
||||
No. Starting with Nvim 0.2 PR #4411
|
||||
https://github.com/neovim/neovim/pull/4411 Lua is built-in, but the legacy
|
||||
Vim `if_lua` interface is not supported.
|
||||
|
||||
|
||||
HOW CAN I USE "TRUE COLOR" IN THE TERMINAL? ~
|
||||
|
||||
Truecolor (24bit colors) are enabled by default if a supporting terminal is
|
||||
detected. If your terminal is not detected but you are sure it supports
|
||||
truecolor, add this to your |init.vim|:
|
||||
>vim
|
||||
set termguicolors
|
||||
<
|
||||
|
||||
NVIM SHOWS WEIRD SYMBOLS (`<60>[2 q`) WHEN CHANGING MODES ~
|
||||
|
||||
This is a bug in your terminal emulator. It happens because Nvim sends
|
||||
cursor-shape termcodes by default, if the terminal appears to be
|
||||
xterm-compatible (`TERM=xterm-256color`).
|
||||
|
||||
To workaround the issue, you can:
|
||||
|
||||
- Use a different terminal emulator
|
||||
- Disable 'guicursor' in your Nvim config: >vim
|
||||
|
||||
:set guicursor=
|
||||
" Workaround some broken plugins which set guicursor indiscriminately.
|
||||
:autocmd OptionSet guicursor noautocmd set guicursor=
|
||||
<
|
||||
See also |$TERM| for recommended values of `$TERM`.
|
||||
|
||||
|
||||
HOW TO CHANGE CURSOR SHAPE IN THE TERMINAL? ~
|
||||
|
||||
- For Nvim 0.1.7 or older: see the note about `NVIM_TUI_ENABLE_CURSOR_SHAPE` in `man nvim`.
|
||||
- For Nvim 0.2 or newer: cursor styling is controlled by the 'guicursor' option.
|
||||
- To _disable_ cursor-styling, set 'guicursor' to empty: >vim
|
||||
|
||||
:set guicursor=
|
||||
" Workaround some broken plugins which set guicursor indiscriminately.
|
||||
:autocmd OptionSet guicursor noautocmd set guicursor=
|
||||
<
|
||||
- If you want a non-blinking cursor, use `blinkon0`. See 'guicursor'.
|
||||
- 'guicursor' is enabled by default, unless Nvim thinks your terminal doesn't
|
||||
support it. If you're sure that your terminal supports cursor-shaping, set
|
||||
'guicursor' in your |init.vim|, as described in 'guicursor'.
|
||||
- The Vim terminal options |t_SI| and `t_EI` are ignored, like all other |t_xx| options.
|
||||
- Old versions of libvte (gnome-terminal, roxterm, terminator, ...) do not
|
||||
support cursor style control codes. #2537
|
||||
https://github.com/neovim/neovim/issues/2537
|
||||
|
||||
|
||||
HOW TO CHANGE CURSOR COLOR IN THE TERMINAL? ~
|
||||
|
||||
Cursor styling (shape, color, behavior) is controlled by 'guicursor', even in
|
||||
the terminal. Cursor color (as opposed to shape) only works if
|
||||
'termguicolors' is set.
|
||||
|
||||
'guicursor' gives an example, but here's a more complicated example
|
||||
which sets different colors in insert-mode and normal-mode:
|
||||
>vim
|
||||
:set termguicolors
|
||||
:hi Cursor guifg=green guibg=green
|
||||
:hi Cursor2 guifg=red guibg=red
|
||||
:set guicursor=n-v-c:block-Cursor/lCursor,i-ci-ve:ver25-Cursor2/lCursor2,r-cr:hor20,o:hor50
|
||||
<
|
||||
|
||||
CURSOR STYLE ISN'T RESTORED AFTER EXITING OR SUSPENDING AND RESUMING NVIM ~
|
||||
|
||||
Terminals do not provide a way to query the cursor style. Use autocommands to
|
||||
manage the cursor style:
|
||||
>vim
|
||||
au VimEnter,VimResume * set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50
|
||||
\,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor
|
||||
\,sm:block-blinkwait175-blinkoff150-blinkon175
|
||||
|
||||
au VimLeave,VimSuspend * set guicursor=a:block-blinkon0
|
||||
<
|
||||
|
||||
CURSOR SHAPE DOESN'T CHANGE IN TMUX ~
|
||||
|
||||
tmux decides that, not Nvim. See |tui-cursor-shape| for a fix.
|
||||
|
||||
See #3165 https://github.com/neovim/neovim/pull/3165 for discussion.
|
||||
|
||||
|
||||
CURSOR FLICKER IN TMUX? ~
|
||||
|
||||
If cursor `_` appears and disappears very quickly when opening nvim without a
|
||||
document under tmux, and you set |ctermbg| in `EndOfBuffer` and `Normal`, try
|
||||
setting these to `NONE`:
|
||||
>vim
|
||||
hi EndOfBuffer ctermbg=NONE ctermfg=200 cterm=NONE
|
||||
hi Normal ctermbg=NONE ctermfg=200 cterm=NONE
|
||||
<
|
||||
|
||||
WHAT HAPPENED TO --remote AND FRIENDS? ~
|
||||
|
||||
|--remote| is partly supported. |clientserver|
|
||||
|
||||
If you require flags from Vim that are missing in Nvim, you can use
|
||||
https://github.com/mhinz/neovim-remote instead.
|
||||
|
||||
==============================================================================
|
||||
Runtime issues *faq-runtime*
|
||||
|
||||
|
||||
COPYING TO X11 PRIMARY SELECTION WITH THE MOUSE DOESN'T WORK ~
|
||||
|
||||
`clipboard=autoselect` is not implemented yet
|
||||
https://github.com/neovim/neovim/issues/2325. You may find this workaround to
|
||||
be useful:
|
||||
>vim
|
||||
vnoremap <LeftRelease> "*ygv
|
||||
vnoremap <2-LeftRelease> "*ygv
|
||||
<
|
||||
|
||||
MY CTRL-H MAPPING DOESN'T WORK ~
|
||||
|
||||
This was fixed in Nvim 0.2. If you are running Nvim 0.1.7 or older,
|
||||
adjust your terminal's "kbs" (key_backspace) terminfo entry:
|
||||
>vim
|
||||
infocmp $TERM | sed 's/kbs=^[hH]/kbs=\\177/' > $TERM.ti
|
||||
tic $TERM.ti
|
||||
<
|
||||
(Feel free to delete the temporary `*.ti` file created after running the above
|
||||
commands).
|
||||
|
||||
|
||||
<HOME> OR SOME OTHER "SPECIAL" KEY DOESN'T WORK ~
|
||||
|
||||
Make sure |$TERM| is set correctly.
|
||||
|
||||
- For screen or tmux, `$TERM` should be `screen-256color` (not `xterm-256color`!)
|
||||
- In other cases if "256" does not appear in the string it's probably wrong.
|
||||
Try `TERM=xterm-256color`.
|
||||
|
||||
|
||||
:! AND SYSTEM() DO WEIRD THINGS WITH INTERACTIVE PROCESSES ~
|
||||
|
||||
Interactive commands are supported by |:terminal| in Nvim. But |:!| and
|
||||
|system()| do not support interactive commands, primarily because Nvim UIs use
|
||||
stdio for msgpack communication, but also for performance, reliability, and
|
||||
consistency across platforms (see
|
||||
https://vimhelp.org/gui_x11.txt.html#gui-pty).
|
||||
|
||||
See also #1496 https://github.com/neovim/neovim/issues/1496 and #8217
|
||||
https://github.com/neovim/neovim/issues/8217#issuecomment-402152307.
|
||||
|
||||
|
||||
PYTHON SUPPORT ISN'T WORKING ~
|
||||
|
||||
Run |:checkhealth| in Nvim for automatic diagnosis.
|
||||
|
||||
Other hints:
|
||||
|
||||
- The python `neovim` module was renamed to `pynvim` (long ago).
|
||||
- If you're using pyenv or virtualenv for the `pynvim` module
|
||||
https://pypi.python.org/pypi/pynvim/, you must set `g:python3_host_prog` to
|
||||
the virtualenv's interpreter path.
|
||||
- Read |provider-python|.
|
||||
- Be sure you have the latest version of the `pynvim` Python module: >bash
|
||||
|
||||
python -m pip install setuptools
|
||||
python -m pip install --upgrade pynvim
|
||||
python3 -m pip install --upgrade pynvim
|
||||
<
|
||||
- Try with `nvim -u NORC` to make sure your config (|init.vim|) isn't causing a
|
||||
problem. If you get `E117: Unknown function`, that means there's a runtime
|
||||
issue: |faq-runtime|.
|
||||
|
||||
|
||||
:CHECKHEALTH REPORTS E5009: INVALID $VIMRUNTIME ~
|
||||
|
||||
This means `health#check()` couldn't load, which suggests that |$VIMRUNTIME|
|
||||
or 'runtimepath' is broken.
|
||||
|
||||
- |$VIMRUNTIME| must point to Nvim's runtime files, not Vim's.
|
||||
- The |$VIMRUNTIME| directory contents should be readable by the current user.
|
||||
- Verify that `:echo &runtimepath` contains the $VIMRUNTIME path.
|
||||
- Check the output of: >vim
|
||||
|
||||
:call health#check()
|
||||
:verbose func health#check
|
||||
<
|
||||
|
||||
NEOVIM CAN'T FIND ITS RUNTIME ~
|
||||
|
||||
This is the case if `:help nvim` shows `E149: Sorry, no help for nvim`.
|
||||
|
||||
Make sure that |$VIM| and |$VIMRUNTIME| point to Nvim's (as opposed to
|
||||
Vim's) runtime by checking `:echo $VIM` and `:echo $VIMRUNTIME`. This should
|
||||
give something like `/usr/share/nvim` resp. `/usr/share/nvim/runtime`.
|
||||
|
||||
Also make sure that you don't accidentally overwrite your runtimepath
|
||||
(`:set runtimepath?`), which includes the above |$VIMRUNTIME| by default (see
|
||||
'runtimepath').
|
||||
|
||||
|
||||
NEOVIM IS SLOW ~
|
||||
|
||||
|
||||
Use a fast terminal emulator:
|
||||
|
||||
- kitty https://github.com/kovidgoyal/kitty
|
||||
- alacritty https://github.com/jwilm/alacritty
|
||||
|
||||
|
||||
Use an optimized build:
|
||||
|
||||
`:checkhealth nvim` should report one of these "build types":
|
||||
>
|
||||
Build type: RelWithDebInfo
|
||||
Build type: MinSizeRel
|
||||
Build type: Release
|
||||
<
|
||||
If it reports `Build type: Debug` and you're building Nvim from source, see
|
||||
https://github.com/neovim/neovim/wiki/Building-Neovim.
|
||||
|
||||
|
||||
COLORS AREN'T DISPLAYED CORRECTLY ~
|
||||
|
||||
Ensure that |$TERM| is set correctly.
|
||||
|
||||
From a shell, run `TERM=xterm-256color nvim`. If colors are displayed
|
||||
correctly, then export that value of `TERM` in your user profile (usually
|
||||
`~/.profile`):
|
||||
>bash
|
||||
export TERM=xterm-256color
|
||||
<
|
||||
If you're using `tmux`, instead add this to your `tmux.conf`:
|
||||
>bash
|
||||
set -g default-terminal "tmux-256color"
|
||||
<
|
||||
|
||||
For GNU `screen`, configure your `.screenrc`
|
||||
<https://wiki.archlinux.org/index.php/GNU_Screen#Use_256_colors>:
|
||||
>
|
||||
term screen-256color
|
||||
<
|
||||
|
||||
NOTE: Nvim ignores `t_Co` and other |t_xx| terminal codes.
|
||||
|
||||
|
||||
NEOVIM CAN'T READ UTF-8 CHARACTERS ~
|
||||
|
||||
Run the following from the command line:
|
||||
>bash
|
||||
locale | grep -E '(LANG|LC_CTYPE|LC_ALL)=(.*\.)?(UTF|utf)-?8'
|
||||
<
|
||||
If there's no results, then you might not be using a UTF-8 locale. See the
|
||||
following issues:
|
||||
#1601 https://github.com/neovim/neovim/issues/1601
|
||||
#1858 https://github.com/neovim/neovim/issues/1858
|
||||
#2386 https://github.com/neovim/neovim/issues/2386
|
||||
|
||||
|
||||
ESC IN TMUX OR GNU SCREEN IS DELAYED ~
|
||||
|
||||
This is a common problem
|
||||
https://www.google.com/?q=tmux%20vim%20escape%20delay in `tmux` / `screen`
|
||||
(see also tmux/#131
|
||||
https://github.com/tmux/tmux/issues/131#issuecomment-145853211). The
|
||||
corresponding timeout needs to be tweaked to a low value (10-20ms).
|
||||
|
||||
`.tmux.conf`:
|
||||
>
|
||||
set -g escape-time 10
|
||||
# Or for tmux >= 2.6
|
||||
set -sg escape-time 10
|
||||
<
|
||||
`.screenrc`:
|
||||
>
|
||||
maptimeout 10
|
||||
<
|
||||
|
||||
"WHY DOESN'T THIS HAPPEN IN VIM?"
|
||||
|
||||
It does happen (try `vim -N -u NONE`), but if you hit a key quickly after
|
||||
ESC_ then Vim interprets the ESC as ESC instead of ALT (META). You won't
|
||||
notice the delay unless you closely observe the cursor. The tradeoff is that
|
||||
Vim won't understand ALT (META) key-chords, so for example `nnoremap <M-a>`
|
||||
won't work. ALT (META) key-chords always work in Nvim. See also `:help
|
||||
xterm-cursor-keys` in Vim.
|
||||
|
||||
Nvim 0.3 mimics the Vim behavior while still fully supporting ALT mappings. See
|
||||
|i_ALT|.
|
||||
|
||||
|
||||
ESC IN GNU SCREEN IS LOST WHEN MOUSE MODE IS ENABLED ~
|
||||
|
||||
This happens because of a bug in screen https://savannah.gnu.org/bugs/?60196:
|
||||
in mouse mode, screen assumes that `ESC` is part of a mouse sequence and will
|
||||
wait an unlimited time for the rest of the sequence, regardless of
|
||||
`maptimeout`. Until it's fixed in screen, there's no known workaround for
|
||||
this other than double-pressing escape, which causes a single escape to be
|
||||
passed through to Nvim.
|
||||
|
||||
|
||||
CALLING INPUTLIST(), ECHOMSG, ... IN FILETYPE PLUGINS AND AUTOCMD DOES NOT WORK ~
|
||||
|
||||
#10008 https://github.com/neovim/neovim/issues/10008,
|
||||
#10116 https://github.com/neovim/neovim/issues/10116,
|
||||
#12288 https://github.com/neovim/neovim/issues/12288,
|
||||
# vim/vim#4379 https://github.com/vim/vim/issues/4379.
|
||||
This is because Nvim sets `shortmess+=F` by default. Vim behaves the same way
|
||||
with `set shortmes+=F`. There are plans to improve this, but meanwhile as a
|
||||
workaround, use `set shortmess-=F` or use `unsilent` as follows.
|
||||
>vim
|
||||
unsilent let var = inputlist(['1. item1', '2. item2'])
|
||||
autocmd BufNewFile * unsilent echomsg 'The autocmd has been fired.'
|
||||
<
|
||||
|
||||
G:CLIPBOARD SETTINGS ARE NOT USED. ~
|
||||
|
||||
If the clipboard provider is already loaded, you will need to reload it after
|
||||
configuration. Use the following configuration.
|
||||
>vim
|
||||
let g:clipboard = { 'name' : ... }
|
||||
if exists('g:loaded_clipboard_provider')
|
||||
unlet g:loaded_clipboard_provider
|
||||
runtime autoload/provider/clipboard.vim
|
||||
endif
|
||||
<
|
||||
|
||||
Or, if you want automatic reloading when assigning to |g:clipboard|, set
|
||||
|init.vim| as follows.
|
||||
>vim
|
||||
function! s:clipboard_changed(...) abort
|
||||
if exists('g:loaded_clipboard_provider')
|
||||
unlet g:loaded_clipboard_provider
|
||||
endif
|
||||
runtime autoload/provider/clipboard.vim
|
||||
endfunction
|
||||
|
||||
if !exists('s:loaded")
|
||||
call dictwatcheradd(g:, 'clipboard', function('s:clipboard_changed'))
|
||||
endif
|
||||
let s:loaded = v:true
|
||||
<
|
||||
|
||||
==============================================================================
|
||||
Build issues *faq-build*
|
||||
|
||||
|
||||
GENERAL BUILD ISSUES ~
|
||||
|
||||
Run `make distclean && make` to rule out a stale build environment causing the
|
||||
failure.
|
||||
|
||||
|
||||
SETTINGS IN LOCAL.MK DON'T TAKE EFFECT ~
|
||||
|
||||
CMake caches build settings, so you might need to run `rm -r build && make`
|
||||
after modifying `local.mk`.
|
||||
|
||||
|
||||
CMAKE ERRORS ~
|
||||
|
||||
`configure_file Problem configuring file`
|
||||
|
||||
This is probably a permissions issue, which can happen if you run `make` as the
|
||||
root user, then later run an unprivileged `make`. To fix this, run `rm -rf
|
||||
build` and try again.
|
||||
|
||||
|
||||
GENERATING HELPTAGS FAILED ~
|
||||
|
||||
If re-installation fails with "Generating helptags failed", try removing the
|
||||
previously installed runtime directory (if `CMAKE_INSTALL_PREFIX` is not set
|
||||
during building, the default is `/usr/local/share/nvim`):
|
||||
>bash
|
||||
rm -r /usr/local/share/nvim
|
||||
<
|
||||
|
||||
==============================================================================
|
||||
Design *faq-design*
|
||||
|
||||
|
||||
WHY NOT USE JSON FOR RPC? ~
|
||||
|
||||
- JSON cannot easily/efficiently handle binary data
|
||||
- JSON specification is ambiguous: https://seriot.ch/parsing_json.php
|
||||
|
||||
|
||||
WHY EMBED LUA INSTEAD OF X? ~
|
||||
|
||||
- Lua is a very small language, ideal for embedding. The biggest advantage of
|
||||
Python/Ruby/etc is their huge collection of libraries, but that isn't
|
||||
relevant for Nvim, where Nvim is the "batteries included" library:
|
||||
introducing another stdlib would be redundant.
|
||||
- Lua 5.1 is a complete language: the syntax is frozen. This is great for
|
||||
backwards compatibility.
|
||||
- Nvim also uses Lua internally as an alternative to C. Extra performance is
|
||||
useful there, as opposed to a slow language like Python or Vim9script.
|
||||
- LuaJIT is one of the fastest runtimes on the planet, 10x faster than Python
|
||||
and "Vim9script" https://vimhelp.org/vim9.txt.html, 100x faster than
|
||||
Vimscript.
|
||||
- Python/JS cost more than Lua in terms of size and portability, and there are
|
||||
already numerous Python/JS-based editors. So Python/JS would make Nvim
|
||||
bigger and less portable, in exchange for a non-differentiating feature.
|
||||
|
||||
See also:
|
||||
|
||||
- Why Lua https://web.archive.org/web/20150219224654/https://blog.datamules.com/blog/2012/01/30/why-lua/
|
||||
- The Design of Lua https://cacm.acm.org/magazines/2018/11/232214-a-look-at-the-design-of-lua/fulltext
|
||||
- Scripting architecture considerations http://oldblog.antirez.com/post/redis-and-scripting.html
|
||||
- LuaJIT performance https://julialang.org/benchmarks/
|
||||
- Discussion of JavaScript vs Lua https://github.com/vim/vim/pull/5198#issuecomment-554693754
|
||||
- Discussion Python embedding https://lobste.rs/s/pnuak4/mercurial_s_journey_reflections_on#c_zshdwy
|
||||
|
||||
|
||||
WHY LUA 5.1 INSTEAD OF LUA 5.3+? ~
|
||||
|
||||
Lua 5.1 is a different language than 5.3. The Lua org makes breaking changes
|
||||
with every new version, so even if we switched (not upgraded, but switched) to
|
||||
5.3 we gain nothing when they create the next new language in 5.4, 5.5, etc.
|
||||
And we would lose LuaJIT, which is far more valuable than Lua 5.3+.
|
||||
|
||||
Lua 5.1 is a complete language. To "upgrade" it, add libraries, not syntax.
|
||||
Nvim itself already is a pretty good "stdlib" for Lua, and we will continue to
|
||||
grow and enhance it. Changing the rules of Lua gains nothing in this context.
|
||||
|
||||
|
||||
WILL NEOVIM TRANSLATE VIMSCRIPT TO LUA, INSTEAD OF EXECUTING VIMSCRIPT DIRECTLY? ~
|
||||
|
||||
- We are experimenting with vim9jit https://github.com/tjdevries/vim9jit to
|
||||
transpile Vim9script (Vim9's Vimscript variant) to Lua and have used this to
|
||||
port Vim9 plugins https://github.com/neovim/neovim/pull/21662 to Nvim Lua.
|
||||
- We have no plans for transpiling legacy Vimscript.
|
||||
|
||||
|
||||
ARE PLUGIN AUTHORS ENCOURAGED TO PORT THEIR PLUGINS FROM VIMSCRIPT TO LUA? DO YOU PLAN ON SUPPORTING VIMSCRIPT INDEFINITELY? (#1152) ~
|
||||
|
||||
We don't anticipate any reason to deprecate Vimscript, which is a valuable DSL
|
||||
https://en.wikipedia.org/wiki/Domain-specific_language for text-editing tasks.
|
||||
Maintaining Vimscript compatibility is less costly than a mass migration of
|
||||
existing Vim plugins.
|
||||
|
||||
Porting from Vimscript to Lua just for the heck of it gains nothing. Nvim is
|
||||
emphatically a fork of Vim in order to leverage the work already spent on
|
||||
thousands of Vim plugins, while enabling new types of plugins and
|
||||
integrations.
|
||||
|
||||
vim:tw=78:ts=8:noet:ft=help:norl:
|
@ -47,6 +47,7 @@ ABOUT NVIM *reference_toc* *doc-file-list* *Q_ct*
|
||||
|news| News since the previous release
|
||||
|nvim| Transitioning from Vim
|
||||
|vim-differences| Nvim compared to Vim
|
||||
|faq| Frequently Asked Questions
|
||||
|user-manual| User manual: How to accomplish editing tasks.
|
||||
|quickref| Overview of common commands
|
||||
|tutor| 30-minute interactive course for beginners
|
||||
@ -167,7 +168,8 @@ DEVELOPING NVIM
|
||||
|
||||
|dev| Development of Nvim
|
||||
|dev-style| Development style guidelines
|
||||
|debug.txt| Debugging Vim itself
|
||||
|dev-theme| Design guidelines (colorschemes etc.)
|
||||
|dev-tools| Tools and techniques for developing Nvim
|
||||
|
||||
Standard plugins ~
|
||||
*standard-plugin-list*
|
||||
|
@ -49,10 +49,9 @@ For more information try one of these:
|
||||
==============================================================================
|
||||
Nvim on the interwebs *internet*
|
||||
|
||||
*www* *faq* *distribution* *download*
|
||||
*www* *distribution* *download*
|
||||
|
||||
Nvim home page: https://neovim.io/
|
||||
Nvim FAQ: https://github.com/neovim/neovim/wiki/FAQ
|
||||
Downloads: https://github.com/neovim/neovim/releases
|
||||
Vim FAQ: https://vimhelp.org/vim_faq.txt.html
|
||||
|
||||
|
@ -30,6 +30,7 @@ achieve special effects. These options come in three forms:
|
||||
|
||||
*E518* *E519*
|
||||
:se[t] {option}? Show value of {option}.
|
||||
NOTE: some legacy options were removed. |nvim-removed|
|
||||
|
||||
:se[t] {option} Toggle option: set, switch it on.
|
||||
Number option: show value.
|
||||
|
@ -56,7 +56,7 @@
|
||||
<launchable type="desktop-id">nvim.desktop</launchable>
|
||||
<url type="homepage">https://neovim.io/</url>
|
||||
<url type="bugtracker">https://github.com/neovim/neovim/issues</url>
|
||||
<url type="faq">https://github.com/neovim/neovim/wiki/FAQ</url>
|
||||
<url type="faq">https://neovim.io/doc/user/faq.html</url>
|
||||
<url type="help">https://neovim.io/doc/</url>
|
||||
<url type="donation">https://neovim.io/#sponsor</url>
|
||||
<url type="translate">https://github.com/neovim/neovim/tree/master/src/nvim/po</url>
|
||||
|
@ -80,6 +80,7 @@ local exclude_invalid_urls = {
|
||||
['http://wiki.services.openoffice.org/wiki/Dictionaries'] = 'spell.txt',
|
||||
['http://www.adapower.com'] = 'ft_ada.txt',
|
||||
['http://www.jclark.com/'] = 'quickfix.txt',
|
||||
['http://oldblog.antirez.com/post/redis-and-scripting.html'] = 'faq.txt',
|
||||
}
|
||||
|
||||
-- Deprecated, brain-damaged files that I don't care about.
|
||||
|
Loading…
Reference in New Issue
Block a user