1 files changed, 44 insertions, 13 deletions
diff --git a/src/nvim/README.md b/src/nvim/README.md
index da87a0208e..1ece92e44d 100644
--- a/src/nvim/README.md
+++ b/src/nvim/README.md
@@ -1,10 +1,22 @@
-Nvim core source
-================
+Nvim core
+=========
 
 Module-specific details are documented at the top of each module (`terminal.c`,
-`screen.c`, ...).
+`screen.c`, …).
 
-See `:help development` for more guidelines.
+See `:help dev` for guidelines.
+
+Filename conventions
+--------------------
+
+The source files use extensions to hint about their purpose.
+
+- `*.c`, `*.generated.c` - full C files, with all includes, etc.
+- `*.c.h` - parametrized C files, contain all necessary includes, but require
+  defining macros before actually using. Example: `typval_encode.c.h`
+- `*.h` - full headers, with all includes. Does *not* apply to `*.generated.h`.
+- `*.h.generated.h` - exported functions’ declarations.
+- `*.c.generated.h` - static functions’ declarations.
 
 Logs
 ----
@@ -20,17 +32,36 @@ UI events are logged at level 0 (`DEBUG_LOG_LEVEL`).
     rm -rf build/
     make CMAKE_EXTRA_FLAGS="-DMIN_LOG_LEVEL=0"
 
-Filename conventions
---------------------
+Build with ASAN
+---------------
 
-The source files use extensions to hint about their purpose.
+Building Nvim with Clang sanitizers (Address Sanitizer: ASan, Undefined
+Behavior Sanitizer: UBSan, Memory Sanitizer: MSan, Thread Sanitizer: TSan) is
+a good way to catch undefined behavior, leaks and other errors as soon as they
+happen.  It's significantly faster than Valgrind.
 
-- `*.c`, `*.generated.c` - full C files, with all includes, etc.
-- `*.c.h` - parametrized C files, contain all necessary includes, but require
-  defining macros before actually using. Example: `typval_encode.c.h`
-- `*.h` - full headers, with all includes. Does *not* apply to `*.generated.h`.
-- `*.h.generated.h` - exported functions’ declarations.
-- `*.c.generated.h` - static functions’ declarations.
+Requires clang 3.4 or later:
+
+    clang --version
+
+Build Nvim with sanitizer instrumentation:
+
+    CC=clang make CMAKE_EXTRA_FLAGS="-DCLANG_ASAN_UBSAN=ON"
+
+Create a directory to store logs:
+
+    mkdir -p "$HOME/logs"
+
+Enable the sanitizer(s) via these environment variables:
+
+    # Change to detect_leaks=1 to detect memory leaks (slower).
+    export ASAN_OPTIONS="detect_leaks=0:log_path=$HOME/logs/asan"
+    export ASAN_SYMBOLIZER_PATH=/usr/lib/llvm-5.0/bin/llvm-symbolizer
+
+    export MSAN_SYMBOLIZER_PATH=/usr/lib/llvm-5.0/bin/llvm-symbolizer
+    export TSAN_OPTIONS="external_symbolizer_path=/usr/lib/llvm-5.0/bin/llvm-symbolizer log_path=${HOME}/logs/tsan"
+
+Logs will be written to `${HOME}/logs/*san.PID`.
 
 TUI debugging
 -------------