Skip to content

Ninja build system targets

This document describes how the CMake/Ninja build system works and how to use it.

You will find some information on how to set up a Ninja build, and what are the build targets and their effects.

Generally understanding the Ninja build system

CMake is used to generate Ninja build files.

Please briefly acquaint yourself with the Ninja documentation at

Setting up an out-of-tree Ninja build of Bitcoin Cash Node

An out-of-tree build creates build products in a separate folder where they do not interfere with the source code working area.

An in-tree build is not recommended and therefore not described further, but it is noted that in-tree builds are possible.

To set up an out-of-tree Ninja build:

  1. create a build directory within your source tree:

    mkdir build/
  2. enter the build folder:

    cd build/
  3. configure the build:

    cmake -GNinja ..

    The command above will configure your build to build the application according to the feature dependencies you have installed. For more configuration options, see the final section in this document.

  4. once step 3 has completed without errors, you are ready to call ninja to build various targets.

In the next sections, there is a description of the ninja build targets. They are grouped according to their function.

For all these targets, run them by appending them to the ninja command.


When used without further arguments, cleans up the build area by removing all build products.

See also the description of the clean target at:

If you need to 'clean up hardest' then the right way is to change to the source folder of your checked out working area, and remove the entire build/ folder. (rm -rf build)

(running ninja without arguments)

Running ninja without additional arguments will call the default target "all".

This builds the entire application based on the Cmake configuration settings selected previously.

There are some test-related targets which are not automatically built in this way.

Calling ninja all is equivalent to just running ninja.


ninja check runs only basic unit tests on the daemon, the Qt wallet (if built), and other utilities.


Builds and runs only the core application's C++ unit tests.


Similar to check-bitcoin, but runs the tests in a mode simulating that the next upgrade has activated.


Builds and runs application utility unit tests.


Runs devtools/chainparams/

This tests utilities to generate chainparams constants that are compiled into the client. See contrib/devtools/chainparams/ for more information on these tools.


Runs checking of our source code for programmatic and stylistic errors.

See linting documentation for details.


Runs a series of security tests for ELF binaries against the following executables:

  • bitcoin-cli
  • bitcoin-tx
  • bitcoind
  • bitcoin-qt
  • bitcoin-seeder

If the checks are successful, the exit status of the script script will be 0 and its output will be silent, otherwise there will be a log which executables failed which checks.


Build and run LevelDB test suite.


Build and run Bitcoin RPC authentication tests.


Build and run all secp256k1 tests.


Build and run only the 'non-exhaustive' secp256k1 tests (this is a subset of check-secp256k1 target).


Build and run only the 'exhaustive' secp256k1 tests (this is a subset of check-secp256k1 target).


ninja check-all runs basic unit tests and the Python functional regression tests, but not all (excludes so-called "extended" tests).


Runs unit tests and extended Python functional regression tests.


Runs seeder and application unit and Python functional regression tests in a mode where it simulates that the next planned upgrade (already built into the code) has been activated.


Similar to check-upgrade-activated but with more extensive Python functional regression tests (the --extended suite).


Builds the application (daemon and command line RPC client) and runs the Python-based regression test suite, but only the basic (short/fast) regression tests, not the extended ones.


Runs only the longer-running Python tests by running the with a --startfrom=40 option (i.e. only run tests that have been timed previously to take longer than 40 seconds).


Runs the Python regression tests with an option to simulate that thhe next upgrade has been activated (currently --with-phonon-activation option).


Similar to check-functional-upgrade-activated target, but runs with the --extended option as well, so executing the full set of Python regression tests while simulating that the next upgrade has been activated.


Same as above but running long Python regression tests only (--startfrom=40).


Generate coverage report for <target>. See generate coverage report.


Build the core application's C++ unit test runner (executable produced at src/test/test_bitcoin)


Build the GUI wallet's C++ unit test runner (executable produced at src/qt/test/test_bitcoin-qt)


Build the DNS seeder's C++ unit test runner (executable produced at src/seeder/test/test_bitcoin-seeder)


Build the HTML documentation in the doc-html folder.


Build the Markdown documentation in the doc-md folder and generate mkdocs.yml. The HTML documentation depends on this.


Builds and installs the project.

You can override the installation root (which defaults to /usr/local) by defining the CMAKE_INSTALL_PREFIX when you configure your build, like this:

cmake -DCMAKE_INSTALL_PREFIX=${your_install_root_path} -GNinja ..

where you can use $HOME or $(pwd) (if you want to install into your build folder) or whatever you prefer for ${your_install_root_path}.


Creates a versioned tarball package containing the executables, include header files, libraries and manual pages.


Creates a versioned tar.gz archive containing the project source code already configured by cmake and ready to be built.

Benchmarking targets


Builds and executes all application benchmarks. Excludes some library dependency benchmarks (eg. secp256k1).

This target results in a comma separated output listing all benchmark names, the number of iterations and timings associated with those (these will be machine-specific).


Build and run the secp256k1 benchmarks. Outputs the benchmark information (names, timings). Again, timings will be machine-specific.

Fuzzing targets


Builds application fuzz testing executables.

See the fuzzing instructions for more information.

Other targets


Creates test vectors for ASERT difficulty adjustment algorithms. Requires define BUILD_ASERT_TEST_VECTORS=ON

Ninja build configuration options

Below are some of the cmake build options with example values.

All these options are passed via -D (defines) to the cmake command.

  • -DBUILD_BITCOIN_SEEDER=OFF # to disable build of the seeder (it is not supported in Windows yet)

  • -DCMAKE_INSTALL_PREFIX=/home/user # set install prefix to user home directory

  • -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/Win64.cmake # select 64-bit Windows toolchain

  • -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/LinuxARM.cmake # select ARM Linux toolchain

  • -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/LinuxAArch64.cmake # select AArch64 Linux toolchain

  • -DCCACHE=OFF # disable ccache

  • -DCMAKE_C_COMPILER=clang # select clang as C compiler

  • -DCMAKE_CXX_COMPILER=clang++ # select clang++ as C++ compiler

  • -DCMAKE_C_COMPILER=afl-gcc # select afl-gcc as C compiler

  • -DCMAKE_CXX_COMPILER=afl-g++ # select afl-g++ as C++ compiler



  • -DEXCLUDE_FUNCTIONAL_TESTS # Skip specified functional tests for check-functional targets.

  • -DENABLE_MAN=OFF # Disable manpage generation/installation

  • -DDOC_ONLINE=ON # Adapt Markdown and HTML documentation for publication on