diff options
Diffstat (limited to 'src/nvim/README.md')
| -rw-r--r-- | src/nvim/README.md | 50 |
1 files changed, 40 insertions, 10 deletions
diff --git a/src/nvim/README.md b/src/nvim/README.md index 6876227e48..b484d59cb3 100644 --- a/src/nvim/README.md +++ b/src/nvim/README.md @@ -1,8 +1,7 @@ Nvim core ========= -Module-specific details are documented at the top of each module (`terminal.c`, -`screen.c`, …). +Module-specific details are documented at the top of each module (`terminal.c`, `undo.c`, …). See `:help dev` for guidelines. @@ -29,17 +28,17 @@ Logs Low-level log messages sink to `$NVIM_LOG_FILE`. -UI events are logged at DEBUG level (`LOGLVL_DBG`). +UI events are logged at DEBUG level. rm -rf build/ - make CMAKE_EXTRA_FLAGS="-DMIN_LOG_LEVEL=0" + make CMAKE_EXTRA_FLAGS="-DLOG_DEBUG" Use `LOG_CALLSTACK()` (Linux only) to log the current stacktrace. To log to an alternate file (e.g. stderr) use `LOG_CALLSTACK_TO_FILE(FILE*)`. Requires `-no-pie` ([ref](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=860394#15)): rm -rf build/ - make CMAKE_EXTRA_FLAGS="-DMIN_LOG_LEVEL=0 -DCMAKE_C_FLAGS=-no-pie" + make CMAKE_EXTRA_FLAGS="-DLOG_DEBUG -DCMAKE_C_FLAGS=-no-pie" Many log messages have a shared prefix, such as "UI" or "RPC". Use the shell to filter the log, e.g. at DEBUG level you might want to exclude UI messages: @@ -60,9 +59,9 @@ Requires clang 3.4 or later, and `llvm-symbolizer` must be in `$PATH`: Build Nvim with sanitizer instrumentation (choose one): - CC=clang make CMAKE_EXTRA_FLAGS="-DCLANG_ASAN_UBSAN=ON" - CC=clang make CMAKE_EXTRA_FLAGS="-DCLANG_MSAN=ON" - CC=clang make CMAKE_EXTRA_FLAGS="-DCLANG_TSAN=ON" + CC=clang make CMAKE_EXTRA_FLAGS="-DENABLE_ASAN_UBSAN=ON" + CC=clang make CMAKE_EXTRA_FLAGS="-DENABLE_MSAN=ON" + CC=clang make CMAKE_EXTRA_FLAGS="-DENABLE_TSAN=ON" Create a directory to store logs: @@ -70,10 +69,9 @@ Create a directory to store logs: Configure the sanitizer(s) via these environment variables: - # Change to detect_leaks=1 to detect memory leaks (slower). + # Change to detect_leaks=1 to detect memory leaks (slower, noisier). export ASAN_OPTIONS="detect_leaks=0:log_path=$HOME/logs/asan" # Show backtraces in the logs. - export UBSAN_OPTIONS=print_stacktrace=1 export MSAN_OPTIONS="log_path=${HOME}/logs/msan" export TSAN_OPTIONS="log_path=${HOME}/logs/tsan" @@ -81,6 +79,13 @@ Logs will be written to `${HOME}/logs/*san.PID` then. For more information: https://github.com/google/sanitizers/wiki/SanitizerCommonFlags +Reproducible build +------------------ + +To make a reproducible build of Nvim, set cmake variable `LUA_GEN_PRG` to +a LuaJIT binary built with `LUAJIT_SECURITY_PRN=0`. See commit +cb757f2663e6950e655c6306d713338dfa66b18d. + Debug: Performance ------------------ @@ -191,6 +196,31 @@ possible to see exactly what terminfo values Nvim is using on any system. nvim -V3log +### TUI Debugging with gdb/lldb + +Launching the nvim TUI involves two processes, one for main editor state and one +for rendering the TUI. Both of these processes use the nvim binary, so somewhat +confusingly setting a breakpoint in either will generally succeed but may not be +hit depending on which process the breakpoints were set in. + +To debug the main process, you can debug the nvim binary with the `--headless` +flag which does not launch the TUI and will allow you to set breakpoints in code +not related to TUI rendering like so: + + lldb -- ./build/bin/nvim --headless --listen ~/.cache/nvim/debug-server.pipe + +While in lldb, enter `run`. You can then attach to the headless process in a +new terminal window to interact with the editor like so: + + ./build/bin/nvim --remote-ui --server ~/.cache/nvim/debug-server.pipe + +Conversely for debugging TUI rendering, you can start a headless process and +debug the remote-ui process multiple times without losing editor state. + +For details on using nvim-dap and automatically debugging the child (main) +process, see +[here](https://zignar.net/2023/02/17/debugging-neovim-with-neovim-and-nvim-dap/) + ### TUI trace The ancient `script` command is still the "state of the art" for tracing |