lix/doc/manual/src/contributing/hacking.md

Hacking

This section provides some notes on how to hack on Nix. To get the latest version of Nix from GitHub:

$ git clone https://github.com/NixOS/nix.git
$ cd nix

The following instructions assume you already have some version of Nix installed locally, so that you can use it to set up the development environment. If you don't have it installed, follow the installation instructions.

Building Nix with flakes

This section assumes you are using Nix with the flakes and nix-command experimental features enabled. See the Building Nix section for equivalent instructions using stable Nix interfaces.

To build all dependencies and start a shell in which all environment variables are set up so that those dependencies can be found:

$ nix develop

This shell also adds ./outputs/bin/nix to your $PATH so you can run nix immediately after building it.

To get a shell with one of the other supported compilation environments:

$ nix develop .#native-clang11StdenvPackages

Note

Use ccacheStdenv to drastically improve rebuild time. By default, ccache keeps artifacts in ~/.cache/ccache/.

To build Nix itself in this shell:

[nix-shell]$ ./bootstrap.sh
[nix-shell]$ ./configure $configureFlags --prefix=$(pwd)/outputs/out
[nix-shell]$ make -j $NIX_BUILD_CORES

To install it in $(pwd)/outputs and test it:

[nix-shell]$ make install
[nix-shell]$ make installcheck -j $NIX_BUILD_CORES
[nix-shell]$ nix --version
nix (Nix) 2.12

To build a release version of Nix for the current operating system and CPU architecture:

$ nix build

You can also build Nix for one of the supported platforms.

Building Nix

To build all dependencies and start a shell in which all environment variables are set up so that those dependencies can be found:

$ nix-shell

To get a shell with one of the other supported compilation environments:

$ nix-shell --attr devShells.x86_64-linux.native-clang11StdenvPackages

Note

You can use native-ccacheStdenvPackages to drastically improve rebuild time. By default, ccache keeps artifacts in ~/.cache/ccache/.

To build Nix itself in this shell:

[nix-shell]$ ./bootstrap.sh
[nix-shell]$ ./configure $configureFlags --prefix=$(pwd)/outputs/out
[nix-shell]$ make -j $NIX_BUILD_CORES

To install it in $(pwd)/outputs and test it:

[nix-shell]$ make install
[nix-shell]$ make installcheck -j $NIX_BUILD_CORES
[nix-shell]$ ./outputs/out/bin/nix --version
nix (Nix) 2.12

To build a release version of Nix for the current operating system and CPU architecture:

$ nix-build

You can also build Nix for one of the supported platforms.

Platforms

As specified in flake.nix, Nix can be built for various platforms:

• aarch64-linux
• i686-linux
• x86_64-darwin
• x86_64-linux

In order to build Nix for a different platform than the one you're currently on, you need to have some way for your system Nix to build code for that platform. Common solutions include remote builders and binfmt emulation (only supported on NixOS).

These solutions let Nix perform builds as if you're on the native platform, so executing the build is as simple as

$ nix build .#packages.aarch64-linux.default

for flake-enabled Nix, or

$ nix-build --attr packages.aarch64-linux.default

for classic Nix.

You can use any of the other supported platforms in place of aarch64-linux.

Cross-compiled builds are available for ARMv6 and ARMv7, and Nix on unsupported platforms can be bootstrapped by adding more crossSystems in flake.nix.

Compilation environments

Nix can be compiled using multiple environments:

• stdenv: default;
• gccStdenv: force the use of gcc compiler;
• clangStdenv: force the use of clang compiler;
• ccacheStdenv: enable [ccache], a compiler cache to speed up compilation.

To build with one of those environments, you can use

$ nix build .#nix-ccacheStdenv

for flake-enabled Nix, or

$ nix-build --attr nix-ccacheStdenv

for classic Nix.

You can use any of the other supported environments in place of nix-ccacheStdenv.

Editor integration

The clangd LSP server is installed by default on the clang-based devShells. See supported compilation environments and instructions how to set up a shell with flakes or in classic Nix.

To use the LSP with your editor, you first need to set up clangd by running:

make clean && bear -- make -j$NIX_BUILD_CORES install

Configure your editor to use the clangd from the shell, either by running it inside the development shell, or by using nix-direnv and the appropriate editor plugin.

Note

For some editors (e.g. Visual Studio Code), you may need to install a special extension for the editor to interact with clangd. Some other editors (e.g. Emacs, Vim) need a plugin to support LSP servers in general (e.g. lsp-mode for Emacs and vim-lsp for vim). Editor-specific setup is typically opinionated, so we will not cover it here in more detail.

Checking links in the manual

The build checks for broken internal links. This happens late in the process, so nix build is not suitable for iterating. To build the manual incrementally, run:

make html -j $NIX_BUILD_CORES

In order to reflect changes to the Makefile, clear all generated files before re-building:

rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/command-ref/new-cli && make html -j $NIX_BUILD_CORES

mdbook-linkcheck does not implement checking URI fragments yet.

@docroot@ variable

@docroot@ provides a base path for links that occur in reusable snippets or other documentation that doesn't have a base path of its own.

If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use @docroot@ to reference the doc/manual/src directory.

If the @docroot@ literal appears in an error message from the mdbook-linkcheck tool, the @docroot@ replacement needs to be applied to the generated source file that mentions it. See existing @docroot@ logic in the Makefile. Regular markdown files used for the manual have a base path of their own and they can use relative paths instead of @docroot@.

API documentation

Doxygen API documentation is available online. You can also build and view it yourself:

# nix build .#hydraJobs.internal-api-docs
# xdg-open ./result/share/doc/nix/internal-api/html/index.html

or inside a nix develop shell by running:

# make internal-api-html
# xdg-open ./outputs/doc/share/doc/nix/internal-api/html/index.html

Coverage analysis

A coverage analysis report is available online. You can build it yourself:

# nix build .#hydraJobs.coverage
# xdg-open ./result/coverage/index.html

Metrics about the change in line/function coverage over time are also available.