neovim

Neovim text editor
git clone https://git.dasho.dev/neovim.git
Log | Files | Refs | README

BUILD.md (23477B)

Quick start

  1. IMPORTANT: Before upgrading to a new version, always check for [breaking changes](https://neovim.io/doc/user/news.html#news-breaking).
  2. IMPORTANT: Before upgrading to a new version, always check for [breaking changes](https://neovim.io/doc/user/news.html#news-breaking).
  3. IMPORTANT: Before upgrading to a new version, always check for [breaking changes](https://neovim.io/doc/user/news.html#news-breaking).

- If you want the stable release, also run git checkout stable.

  1. IMPORTANT: Before upgrading to a new version, always check for [breaking changes](https://neovim.io/doc/user/news.html#news-breaking).

- If you want to install to a custom location, set CMAKE_INSTALL_PREFIX. See also INSTALL.md. - On BSD, use gmake instead of make. - To build on Windows, see the Building on Windows section. MSVC (Visual Studio) is recommended.

  1. IMPORTANT: Before upgrading to a new version, always check for [breaking changes](https://neovim.io/doc/user/news.html#news-breaking).

- Default install location is /usr/local - On Debian/Ubuntu, instead of sudo make install, you can try cd build && cpack -G DEB && sudo dpkg -i nvim-linux-<arch>.deb (with <arch> either x86_64 or arm64) to build DEB-package and install it. This helps ensure clean removal of installed files. Note: This is an unsupported, "best-effort" feature of the Nvim build.

Notes:

Running tests

See test/README.md.

Building

First make sure you installed the build prerequisites. Now that you have the dependencies, you can try other build targets explained below.

The build type determines the level of used compiler optimizations and debug information:

So, for a release build, just use:

make CMAKE_BUILD_TYPE=Release

(Do not add a -j flag if ninja is installed! The build will be in parallel automatically.)

Afterwards, the nvim executable can be found in build/bin. To verify the build type after compilation, run:

./build/bin/nvim --version | grep ^Build

To install the executable to a certain location, use:

make CMAKE_INSTALL_PREFIX=$HOME/local/nvim install

CMake, our main build system, caches a lot of things in build/CMakeCache.txt. If you ever want to change CMAKE_BUILD_TYPE or CMAKE_INSTALL_PREFIX, run rm -rf build first. This is also required when rebuilding after a Git commit adds or removes files (including from runtime) — when in doubt, run make distclean (which is basically a shortcut for rm -rf build .deps).

By default (USE_BUNDLED=1), Neovim downloads and statically links its needed dependencies. In order to be able to use a debugger on these libraries, you might want to compile them with debug information as well:

<!-- THIS CAUSES SCREEN INTERFERENCE

make distclean
VERBOSE=1 DEBUG=1 make deps

-->

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

MSVC (Visual Studio) is the recommended way to build on Windows. These steps were confirmed as of 2023.

  1. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.

- On 32-bit Windows, you will need this workaround.

  1. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.

- Visual Studio should detect the cmake files and automatically start building...

  1. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.

- If the build fails, it may be because Visual Studio started the build with x64-{Debug,Release} before you switched the configuration to x86-Release. - Right-click CMakeLists.txt → Delete Cache. - Right-click CMakeLists.txt → Generate Cache. - If you see an "access violation" from ntdll, you can ignore it and continue.

  1. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.

Windows / MSVC PowerShell

To build from the command line (i.e. invoke the cmake commands yourself),

  1. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.

- Using the Visual Studio Developer Command Prompt or Visual Studio Developer PowerShell - Invoking Import-VisualStudioVars in PowerShell from this PowerShell module - Invoking VsDevCmd.bat in Command Prompt ` VsDevCmd.bat -arch=x64 ` This is to make sure that luarocks finds the Visual Studio installation, and doesn't fall back to MinGW with errors like: ` 'mingw32-gcc' is not recognized as an internal or external command `

  1. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.

`bash cmake -S cmake.deps -B .deps -G Ninja -D CMAKEBUILDTYPE=Release cmake --build .deps --config Release cmake -B build -G Ninja -D CMAKEBUILDTYPE=Release cmake --build build --config Release ` - Omit --config Release if you want a debug build. - Omit -G Ninja to use the "Visual Studio" generator.

Windows / CLion

  1. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.
  2. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.
  3. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.

Windows / Cygwin

Since https://github.com/neovim/neovim/pull/36417 , building on Cygwin may be as easy as:

make && make install

If that fails, an alternative is:

  1. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.

- The cygport repo contains Cygport files (e.g. APKBUILD, PKGBUILD) for all the dependencies not available in the Cygwin distribution, and describes any special commands or arguments needed to build. The Cygport definitions also try to describe the required dependencies for each one. Unless custom commands are provided, Cygport just calls autogen/cmake, make, make install, etc. in a clean and consistent way. - https://github.com/cascent/neovim-cygwin was built on Cygwin 2.9.0. Newer libuv should require slightly less patching. Some SSP stuff changed in Cygwin 2.10.0, so that might change things too when building Neovim.

  1. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.

`bash cmake -S cmake.deps -B .deps -G Ninja -D CMAKEBUILDTYPE=RelWithDebInfo -DUSEBUNDLED=OFF -DUSEBUNDLED_TS=ON cmake --build .deps cmake -B build -G Ninja -D CMAKEBUILDTYPE=RelWithDebInfo cmake --build build `

Windows / MSYS2 / MinGW

  1. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.

`bash pacman -S \ mingw-w64-ucrt-x86_64-gcc \ mingw-w64-x86_64-{cmake,make,ninja,diffutils} `

  1. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.

`cmd set PATH=c:\msys64\ucrt64\bin;c:\msys64\usr\bin;%PATH% `

  1. RelWithDebInfo ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace.

- Build using cmake and Ninja generator: `cmd cmake -S cmake.deps -B .deps -G Ninja -D CMAKEBUILDTYPE=RelWithDebInfo cmake --build .deps cmake -B build -G Ninja -D CMAKEBUILDTYPE=RelWithDebInfo cmake --build build ` If you cannot install neovim with ninja install due to permission restriction, you can install neovim in a directory you have write access to. `cmd cmake -S cmake.deps -B .deps -G Ninja -D CMAKEBUILDTYPE=RelWithDebInfo cmake --build .deps cmake -B build -G Ninja -D CMAKEINSTALLPREFIX=C:\nvim -D CMAKEBUILDTYPE=RelWithDebInfo cmake --build build ` - Or, alternatively, you can use mingw32-make: `cmd mingw32-make deps mingw32-make CMAKEBUILDTYPE=RelWithDebInfo :: Or you can do the previous command specifying a custom prefix :: (Default is C:\Program Files (x86)\nvim) :: mingw32-make CMAKEBUILDTYPE=RelWithDebInfo CMAKEINSTALLPREFIX=C:\nvim mingw32-make install `

Windows WSL

Build Ubuntu/Debian linux binary on WSL (Windows Subsystem for Linux).

# Install build prerequisites
sudo apt-get install ninja-build gettext cmake build-essential

# Build the linux binary in WSL
make CMAKE_BUILD_TYPE=RelWithDebInfo

# Install the linux binary in WSL (with `<arch>` either `x86_64` or `arm64`)
cd build && cpack -G DEB && sudo dpkg -i nvim-linux-<arch>.deb

# Verify the installation
nvim --version && which nvim # should be debug build in /usr/bin/nvim

Note: If you encounter linker errors or segfaults during the build, Windows libraries in your PATH may be interfering. Use a clean PATH to avoid conflicts:

PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" make CMAKE_BUILD_TYPE=RelWithDebInfo

Localization

Localization build

Translations are turned off by default. Enable by building Nvim with the CMake flag ENABLE_TRANSLATIONS=ON. Doing this will create .mo files in build/src/nvim/po. Example:

make CMAKE_EXTRA_FLAGS="-DENABLE_TRANSLATIONS=ON"

Localization check

To check the translations for $LANG, run make -C build check-po-$LANG. Examples:

cmake --build build --target check-po-de
cmake --build build --target check-po-pt_BR

Localization update

To update the src/nvim/po/$LANG.po file with the latest strings, run the following:

cmake --build build --target update-po-$LANG

Compiler options

To see the chain of includes, use the -H option (#918):

echo '#include "./src/nvim/buffer.h"' | \
> clang -I.deps/usr/include -Isrc -std=c99 -P -E -H - 2>&1 >/dev/null | \
> grep -v /usr/

Custom Makefile

You can customize the build process locally by creating a local.mk, which is referenced at the top of the main Makefile. It's listed in .gitignore, so it can be used across branches. A new target in `local.mk` overrides the default make-target.

Here's a sample local.mk which adds a target to force a rebuild but does not override the default-target:

all:

rebuild:
	rm -rf build
	make

Third-party dependencies

Reference the Debian package (or alternatively, the Homebrew formula) for the precise list of dependencies/versions.

To build the bundled dependencies using CMake:

cmake -S cmake.deps -B .deps -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build .deps

By default the libraries and headers are placed in .deps/usr. Now you can build Neovim:

cmake -B build -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build

Build without "bundled" dependencies

  1. -save-temps can be added as well to see expanded macros or commented assembly.

- libuv libluv libutf8proc luajit lua-lpeg tree-sitter tree-sitter-c tree-sitter-lua tree-sitter-markdown tree-sitter-query tree-sitter-vim tree-sitter-vimdoc unibilium

  1. -save-temps can be added as well to see expanded macros or commented assembly.

`bash cmake -B build -G Ninja -D CMAKEBUILDTYPE=RelWithDebInfo cmake --build build ` If all the dependencies are not available in the package, you can use only some of the bundled dependencies as follows (example of using ninja): `bash cmake -S cmake.deps -B .deps -G Ninja -D CMAKEBUILDTYPE=RelWithDebInfo -DUSEBUNDLED=OFF -DUSEBUNDLED_TS=ON cmake --build .deps cmake -B build -G Ninja -D CMAKEBUILDTYPE=RelWithDebInfo cmake --build build `

  1. -save-temps can be added as well to see expanded macros or commented assembly.

- Using ninja is strongly recommended.

  1. -save-temps can be added as well to see expanded macros or commented assembly.

Build offline

On systems with old or missing libraries, without network access, you may want to build with bundled dependencies. This is supported as follows.

  1. -save-temps can be added as well to see expanded macros or commented assembly.

dependency sources in .deps in a form that the build will work with: - Fetch https://github.com/neovim/deps/tree/master/src into .deps/build/src/. (https://github.com/neovim/deps/tree/master/src is an auto-updated, "cleaned up", snapshot of .deps/build/src/). - Run make deps to generate .deps/, then clean it up using these commands.

  1. -save-temps can be added as well to see expanded macros or commented assembly.
  2. -save-temps can be added as well to see expanded macros or commented assembly.

`bash make deps DEPSCMAKEFLAGS=-DUSEEXISTINGSRC_DIR=ON make `

Build without unibilium

Unibilium is the only dependency which is licensed under LGPLv3 (there are no GPLv3-only dependencies). This library is used for loading the terminfo database at runtime, and can be disabled if the internal definitions for common terminals are good enough. To avoid this dependency, build with support for loading custom terminfo at runtime, use

make CMAKE_EXTRA_FLAGS="-DENABLE_UNIBILIUM=0" DEPS_CMAKE_FLAGS="-DUSE_BUNDLED_UNIBILIUM=0"

To confirm at runtime that unibilium was not included, check has('terminfo') == 1.

Build with specific "bundled" dependencies

Example of building with specific bundled and non-bundled dependencies:

make DEPS_CMAKE_FLAGS="-DUSE_BUNDLED=OFF -DUSE_BUNDLED_LUV=ON -DUSE_BUNDLED_TS=ON -DUSE_BUNDLED_LIBUV=ON"

Build static binary (Linux)

  1. -save-temps can be added as well to see expanded macros or commented assembly.
  2. -save-temps can be added as well to see expanded macros or commented assembly.

In case you are not using Alpine Linux you can use a container to do the build the binary:

podman run \
  --rm \
  -it \
  -v "$PWD:/workdir" \
  -w /workdir \
  alpine:latest \
  sh -c 'apk add build-base cmake coreutils curl gettext-tiny-dev git && make CMAKE_EXTRA_FLAGS="-DSTATIC_BUILD=1"'

The resulting binary in build/bin/nvim will have all the dependencies statically linked:

build/bin/nvim: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), statically linked, BuildID[sha1]=b93fa8e678d508ac0a76a2e3da20b119105f1b2d, with debug_info, not stripped

Build prerequisites

General requirements (see #1469):

- Optional: Get the latest CMake from https://cmake.org/download/ - Provides a shell script which works on most Linux systems. After running it, ensure the resulting cmake binary is in your $PATH so the the Nvim build will find it.

Platform-specific requirements are listed below.

Ubuntu / Debian

sudo apt-get install ninja-build gettext cmake curl build-essential git

RHEL / Fedora

sudo dnf -y install ninja-build cmake gcc make gettext curl glibc-gconv-extra git

openSUSE

sudo zypper install ninja cmake gcc-c++ gettext-tools curl git

Arch Linux

sudo pacman -S base-devel cmake ninja curl git

Alpine Linux

apk add build-base cmake coreutils curl gettext-tiny-dev git

Void Linux

xbps-install base-devel cmake curl git

NixOS / Nix

Starting from NixOS 18.03, the Neovim binary resides in the neovim-unwrapped Nix package (the neovim package being just a wrapper to setup runtime options like Ruby/Python support):

cd path/to/neovim/src

Drop into nix-shell to pull in the Neovim dependencies:

nix-shell '<nixpkgs>' -A neovim-unwrapped

Configure and build:

rm -rf build && cmakeConfigurePhase
buildPhase

Tests are not available by default, because of some unfixed failures. You can enable them via adding this package in your overlay:

  neovim-dev = (super.pkgs.neovim-unwrapped.override  {
    doCheck=true;
  }).overrideAttrs(oa:{
    cmakeBuildType="debug";

    nativeBuildInputs = oa.nativeBuildInputs ++ [ self.pkgs.valgrind ];
    shellHook = ''
      export NVIM_PYTHON_LOG_LEVEL=DEBUG
      export NVIM_LOG_FILE=/tmp/log
      export VALGRIND_LOG="$PWD/valgrind.log"
    '';
  });

and replacing neovim-unwrapped with neovim-dev:

nix-shell '<nixpkgs>' -A neovim-dev

A flake for Neovim is hosted at nix-community/neovim-nightly-overlay, with 3 packages:

Thus you can run Neovim nightly with nix run github:nix-community/neovim-nightly-overlay. Similarly to develop on Neovim: nix run github:nix-community/neovim-nightly-overlay#neovim-developer.

To use a specific version of Neovim, you can pass --override-input neovim-src . to use your current directory, or a specific SHA1 like --override-input neovim-src github:neovim/neovim/89dc8f8f4e754e70cbe1624f030fb61bded41bc2.

Haiku

Some deps can be pulled from haiku repos, the rest need "bundled" deps:

cmake -DUSE_BUNDLED_LIBUV=OFF -DUSE_BUNDLED_UNIBILIUM=OFF -DUSE_BUNDLED_LUAJIT=OFF -B .deps ./cmake.deps
make -C .deps

FreeBSD

sudo pkg install cmake gmake sha wget gettext curl git

If you get an error regarding a sha256sum mismatch, where the actual SHA-256 hash is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, then this is your issue (that's the sha256sum of an empty file).

OpenBSD

doas pkg_add gmake cmake curl gettext-tools git ninja

While ninja is technically optional, the build is likely to fail without it. This is because cmake will use make in that case, and the bundled LuaJIT requires gmake. Instead of installing ninja, you could work around this by installing luajit and disabling the bundled LuaJIT:

gmake DEPS_CMAKE_FLAGS="-DUSE_BUNDLED_LUAJIT=0"

Another workaround is to edit cmake/Deps.cmake and comment out the line set(MAKE_PRG "$(MAKE)"). This will leave MAKE_PRG set to gmake, so LuaJIT will be built with gmake.

macOS

macOS / Homebrew

  1. neovim-developer to get all the tools to develop on neovim
  2. neovim-developer to get all the tools to develop on neovim
  3. neovim-developer to get all the tools to develop on neovim

`bash brew install ninja cmake gettext curl git ` - Note: If you see Wget certificate errors (for older macOS versions less than 10.10): `bash brew install curl-ca-bundle echo CA_CERTIFICATE=$(brew --prefix curl-ca-bundle)/share/ca-bundle.crt >> ~/.wgetrc ` - Note: If you see 'stdio.h' file not found, try the following: `bash open /Library/Developer/CommandLineTools/Packages/macOSSDKheadersformacOS_10.14.pkg `

macOS / MacPorts

  1. neovim-developer to get all the tools to develop on neovim
  2. neovim-developer to get all the tools to develop on neovim
  3. neovim-developer to get all the tools to develop on neovim

`bash sudo port install ninja cmake gettext git ` - Note: If you see Wget certificate errors (for older macOS versions less than 10.10): `bash sudo port install curl-ca-bundle echo CA_CERTIFICATE=/opt/local/share/curl/curl-ca-bundle.crt >> ~/.wgetrc ` - Note: If you see 'stdio.h' file not found, try the following: `bash open /Library/Developer/CommandLineTools/Packages/macOSSDKheadersformacOS_10.14.pkg `

Building for older macOS versions

From a newer macOS version, to build for older macOS versions, you will have to set the macOS deployment target:

make CMAKE_BUILD_TYPE=Release MACOSX_DEPLOYMENT_TARGET=10.13 DEPS_CMAKE_FLAGS="-DCMAKE_CXX_COMPILER=$(xcrun -find c++)"

Note that the C++ compiler is explicitly set so that it can be found when the deployment target is set.

Building with zig

Prerequisites

- zig 0.15.2

Instructions

- Build the editor: zig build, run it with ./zig-out/bin/nvim - Complete installation with runtime: zig build install --prefix ~/.local - Tests: + zig build functionaltest to run all functionaltests + zig build functionaltest -- test/functional/autocmd/bufenter_spec.lua to run the tests in one file + zig build unittest to run all unittests

Using system dependencies

See "Available System Integrations" in zig build -h to see available system integrations. Enabling an integration, e.g. zig build -fsys=utf8proc will use the system's installation of utf8proc.

zig build --system deps_dir will enable all integrations and turn off dependency fetching. This requires you to pre-download the dependencies which don't have a system integration into deps_dir (at the time of writing these are ziglua, `lua_dev_deps`, and the built-in tree-sitter parsers). You have to create subdirectories whose names are the respective package's hash under deps_dir and unpack the dependencies inside that directory - ziglua should go under deps_dir/zlua-0.1.0-hGRpC1dCBQDf-IqqUifYvyr8B9-4FlYXqY8cl7HIetrC and so on. Hashes should be taken from build.zig.zon.

See the prepare function of this `PKGBUILD` for an example.