Building Neovim

Before upgrading to a new version, ALWAYS check the Following HEAD page.

Quick start

1. Verify that you have the build prerequisites installed.
2. Clone neovim/neovim.
3. Build Neovim by running make. (On BSD systems use gmake / GNU Make.)

make pulls third-party dependencies (libuv, LuaJIT, etc.) into .deps/, and builds them. If you have issues while attempting to build Neovim, see FAQ.

To generate the Makefile without building: make cmake

If you plan on building Neovim frequently, install ninja for faster builds, it will be used by the top-level Makefile automatically.

Now that you have the dependencies, you can try other build targets and options, explained below.

Running tests

To run all non-legacy (unit + functional) tests:

LC_ALL=C make test

To run only unit tests:

LC_ALL=C make unittest

To run only functional tests:

LC_ALL=C make functionaltest

---

To run a specific unit test:

TEST_FILE=test/unit/foo.lua make unittest

To run a specific functional test:

TEST_FILE=test/functional/foo.lua make functionaltest

---

To run all legacy (Vim) integration tests:

make oldtest

Functional tests

$GDB can be set to run tests under gdbserver. If $VALGRIND is also set, it will add the --vgdb=yes option to valgrind instead of starting gdbserver directly.

Optimized builds

rm -r build
make clean
make CMAKE_BUILD_TYPE=Release

For developers and "edge" users, RelWithDebInfo is recommended over Release as the latter doesn't generate debug info.

To verify the build type after compilation, run ./build/bin/nvim --version | grep ^Build

Localization build

A normal build will create all the .mo files in build/src/nvim/po.

• If you see msgfmt: command not found, you need to install gettext. On most systems the package is just called gettext.

Localization check

• Change into the build directory and run make check-po-$LANG where $LANG is the language you want to check. For instance, make check-po-de or make check-po-pt_BR.
• check-po-$LANG generates a detailed report in ./build/src/nvim/po/check-${LANG}.log. Note: this report is generated by Vim to help identify errors in the translations, not by msgfmt.

Localization update

To update the src/nvim/po/$LANG.po file with the latest strings from sources, run make update-po-$LANG.

GNU-like (GCC, Clang) 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/

• grep -v /usr/ is used to filter out system header files
• -save-temps can be added as well to see expanded macros or commented assembly

Xcode and MSVC project files

CMake has a -G option for exporting to multiple project file formats, such as Xcode and Visual Studio.

For example, to use Xcode's static analysis GUI (#167), you need to generate an Xcode project file from the Neovim makefile (where neovim/ is the top-level Neovim source code directory containing the main Makefile):

cmake -G Xcode neovim

then open the resulting project file in Xcode.

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

Controlling the build for third-party dependencies (#1588)

To build the bundled dependencies using CMake:

mkdir .deps
cd .deps
cmake ../third-party
make

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

mkdir build
cd build
cmake ..
make

You can build the dependencies in a different location:

mkdir deps2
cd deps2
cmake ../third-party/
make
cd ..

And then build Neovim:

mkdir build
cd build
cmake -DDEPS_PREFIX=../deps2/usr ..

When changing DEPS_PREFIX, you may need to clear the CMake cache in order for the changes to take effect.

General notes on CMake

• cmake -LAH prints all variable definitions.
• build/CMakeCache.txt contains the resolved values of all variables used by CMake.
• build/compile_commands.json shows the full compiler invocations for each translation unit.

Build Prerequisites

General requirements (see #1469):

• A recent version of Clang, or GCC version 4.4 and above
• CMake version 2.8.7 and above, built with TLS/SSL support

Platform-specific requirements are listed below.

Ubuntu / Debian

sudo apt-get install libtool libtool-bin autoconf automake cmake g++ pkg-config unzip 

CentOS / RHEL / Fedora

If you're using CentOS/RHEL 6 you need at least autoconf version 2.69 for compiling the libuv dependency. See https://github.com/joyent/libuv/issues/1158.

sudo yum -y install libtool autoconf automake cmake gcc gcc-c++ make pkgconfig unzip

openSUSE

sudo zypper install libtool autoconf automake cmake gcc-c++

Arch Linux

sudo pacman -S base-devel cmake unzip

FreeBSD 10

sudo pkg install cmake gmake libtool sha automake pkgconf unzip wget

If you get an error regarding a sha256sum mismatch, where the actual sha256sum is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, then this is your issue (that's the sha256sum of an empty file). Also, make sure you have wget installed. LuaRocks has bad interactions with cURL, at least under FreeBSD, and will die with a PANIC in LuaJIT when trying to install a rock.

OpenBSD -current

doas pkg_add gmake cmake libtool unzip autoconf-2.69p1 automake-1.15
export AUTOCONF_VERSION=2.69
export AUTOMAKE_VERSION=1.15

The build sometimes fails when using the top level Makefile, apparently due to some third-party component #2445-comment. The following instructions use CMake

mkdir .deps
cd .deps
cmake ../third-party/
gmake
cd ..
mkdir build
cmake ..
gmake

OS X

• Install Xcode and Homebrew or MacPorts

• Install Xcode commandline tools xcode-select --install

• Install other dependencies:

  Via MacPorts:

  sudo port install libtool autoconf automake cmake pkgconfig gettext
  

  Via Homebrew:

  brew install libtool automake cmake pkg-config gettext
  

• After this you may need to run make distclean && make before the tests will run.

• If you see wget certificate errors (for OS X before version 10.10/Yosemite):

  Via MacPorts:

  sudo port install curl-ca-bundle
  echo CA_CERTIFICATE=/opt/local/share/curl/curl-ca-bundle.crt >> ~/.wgetrc
  

  Via Homebrew:

  brew install curl-ca-bundle
  echo CA_CERTIFICATE=$(brew --prefix curl-ca-bundle)/share/ca-bundle.crt >> ~/.wgetrc
  

Windows/MSYS2

From the MSYS2 shell install these packages

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-libtool mingw-w64-x86_64-cmake \
mingw-w64-x86_64-make mingw-w64-x86_64-perl mingw-w64-x86_64-python2 gperf

Now from the windows console (cmd.exe) setup the PATH and build

set PATH=%PATH%;c:\msys64\mingw64\bin
set CC=gcc

Build using the MinGW Makefiles generator

mkdir .deps
cd .deps
cmake  -G "MinGW Makefiles" ..\third-party\
mingw32-make
cd ..
mkdir build
cd build
cmake -G "MinGW Makefiles" -DGPERF_PRG="C:\msys64\usr\bin\gperf.exe" ..
mingw32-make

For 32bit builds adjust the package names and paths accordingly.