Hacking

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

$ git clone https://git.lix.systems/lix-project/lix
$ cd lix

The following instructions assume you already have some version of Nix or Lix 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 Lix in a development shell

Setting up the development shell

If you are using Lix or Nix with the flakes and nix-command experimental features enabled, the following command will build all dependencies and start a shell in which all environment variables are setup for those dependencies to be found:

$ nix develop

That will use the default stdenv for your system. To get a shell with one of the other supported compilation environments, specify its attribute name after a hash (which you may need to quote, depending on your shell):

$ nix develop ".#native-clangStdenvPackages"

For classic Nix, use:

$ nix-shell -A native-clangStdenvPackages

Building from the development shell

As always you may run stdenv's phases by name, e.g.:

$ configurePhase
$ buildPhase
$ checkPhase
$ installPhase
$ installCheckPhase

To build manually, however, use the following:

$ meson setup ./build "--prefix=$out" $mesonFlags

(A simple meson setup ./build will also build, but will do a different thing, not having the settings from package.nix applied).

$ meson compile -C build
$ meson test -C build --suite=check
$ meson install -C build
$ meson test -C build --suite=installcheck

(Check and installcheck may both be done after install, allowing you to omit the --suite argument entirely, but this is the order package.nix runs them in.)

This will install Lix to $PWD/outputs, the /bin of which is prepended to PATH in the development shells.

If the tests fail and Meson helpfully has no output for why, use the --print-error-logs option to meson test.

If you change a setting in the buildsystem (i.e., any of the meson.build files), most cases will automatically regenerate the Meson configuration just before compiling. Some cases, however, like trying to build a specific target whose name is new to the buildsystem (e.g. meson compile -C build src/libmelt/libmelt.dylib, when libmelt.dylib did not exist as a target the last time the buildsystem was generated), then you can reconfigure using new settings but existing options, and only recompiling stuff affected by the changes:

$ meson setup --reconfigure build

Note that changes to the default values in meson.options or in the default_options : argument to project() are not propagated with --reconfigure.

If you want a totally clean build, you can use:

$ meson setup --wipe build

That will work regardless of if ./build exists or not.

Specific, named targets may be addressed in meson build -C build <target>, with the "target ID", if there is one, which is the first string argument passed to target functions that have one, and unrelated to the variable name, e.g.:

libexpr_dylib = library('nixexpr', …)

can be addressed with:

$ meson compile -C build nixexpr

All targets may be addressed as their output, relative to the build directory, e.g.:

$ meson compile -C build src/libexpr/liblixexpr.so

But Meson does not consider intermediate files like object files targets. To build a specific object file, use Ninja directly and specify the output file relative to the build directory:

$ ninja -C build src/libexpr/liblixexpr.so.p/nixexpr.cc.o

To inspect the canonical source of truth on what the state of the buildsystem configuration is, use:

$ meson introspect

Building Lix outside of development shells

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

$ nix build

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

Note

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

Platforms

Lix can be built for various platforms, as specified in flake.nix:

• x86_64-linux
• x86_64-darwin
• i686-linux
• aarch64-linux
• aarch64-darwin
• armv6l-linux
• armv7l-linux

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

Given such a setup, executing the build only requires selecting the respective attribute. For example, to compile for aarch64-linux:

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

or for Nix with the flakes and nix-command experimental features enabled:

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

Cross-compiled builds are available for ARMv6 (armv6l-linux) and ARMv7 (armv7l-linux). Add more system types to crossSystems in flake.nix to bootstrap Nix on unsupported platforms.

Building for multiple platforms at once

It is useful to perform multiple cross and native builds on the same source tree, for example to ensure that better support for one platform doesn't break the build for another. As Lix now uses Meson, out-of-tree builds are supported first class. In the invocation

$ meson setup build

the argument after setup specifies the directory for this build, conventionally simply called "build", but it may be called anything, and you may run meson setup <somedir> for as many different directories as you want. To compile the configuration for a given build directory, pass that build directory to the -C argument of meson compile:

$ meson setup some-custom-build
$ meson compile -C some-custom-build

System type

Lix uses a string with the following format to identify the system type or platform it runs on:

<cpu>-<os>[-<abi>]

It is set when Lix is compiled for the given system, and determined by Meson's host_machine.cpu_family() and host_machine.system() values.

For historic reasons and backward-compatibility, some CPU and OS identifiers are translated from the GNU Autotools naming convention in meson.build as follows:

Compilation environments

Lix 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 in each development shell. See supported compilation environments and instructions how to set up a shell with flakes or in classic Nix.

Clangd requires a compilation database, which Meson generates by default. After running meson setup, there will already be a compile_commands.json file in the build directory. Some editor configurations may prefer that file to be in the root directory, which you can accomplish with a simple:

$ ln -sf ./build/compile_commands.json ./compile_commands.json

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:

meson compile -C build manual

mdbook-linkcheck does not implement checking URI fragments yet.

.. variable

.. 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 .. to reference the doc/manual/src directory.

If the .. literal appears in an error message from the mdbook-linkcheck tool, the .. replacement needs to be applied to the generated source file that mentions it. See existing .. 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 ...

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:

$ meson compile -C build internal-api-docs
$ 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.

Add a release note

doc/manual/rl-next contains release notes entries for all unreleased changes.

User-visible changes should come with a release note.

Add an entry

Here's what a complete entry looks like. The file name is not incorporated in the document.

---
synopsis: Basically a title
# 1234 or gh#1234 will refer to CppNix GitHub, fj#1234 will refer to a Lix forgejo issue.
issues: [1234, fj#1234]
# Use this *only* if there is a CppNix pull request associated with this change
prs: 1238
# List of Lix Gerrit changelist numbers; if there is an associated Lix GitHub
# PR, just put in the Gerrit CL number.
cls: [123]
---

Here's one or more paragraphs that describe the change.

- It's markdown
- Add references to the manual using ..

Significant changes should add the following header, which moves them to the top.

significance: significant

Build process

Releases have a precomputed rl-MAJOR.MINOR.md, and no rl-next.md. Set buildUnreleasedNotes = true; in flake.nix to build the release notes on the fly.