max/nix-super
1
0
Fork 0
mirror of https://github.com/privatevoid-net/nix-super.git synced 2024-11-15 02:36:16 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #11335 from obsidiansystems/meson-doc

Browse source 
Update documentation to refer to Meson not Make in most places
This commit is contained in:
John Ericson 2024-08-20 11:49:19 -04:00 committed by GitHub
commit d34a89afc3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 89 additions and 100 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

88
doc/manual/src/development/building.md
View file

@ -34,16 +34,21 @@ $ nix-shell --attr devShells.x86_64-linux.native-clangStdenvPackages
To build Nix itself in this shell: To build Nix itself in this shell:
```console ```console
[nix-shell]$ autoreconfPhase [nix-shell]$ mesonFlags+=" --prefix=$(pwd)/outputs/out"
[nix-shell]$ ./configure $configureFlags --prefix=$(pwd)/outputs/out [nix-shell]$ dontAddPrefix=1 mesonConfigurePhase
[nix-shell]$ make -j $NIX_BUILD_CORES [nix-shell]$ ninjaBuildPhase
``` ```
To install it in `$(pwd)/outputs` and test it: To test it:
```console ```console
[nix-shell]$ make install [nix-shell]$ mesonCheckPhase
[nix-shell]$ make installcheck -j $NIX_BUILD_CORES ```
To install it in `$(pwd)/outputs`:
```console
[nix-shell]$ ninjaInstallPhase
[nix-shell]$ ./outputs/out/bin/nix --version [nix-shell]$ ./outputs/out/bin/nix --version
nix (Nix) 2.12 nix (Nix) 2.12
``` ```
@ -85,16 +90,20 @@ $ nix develop .#native-clangStdenvPackages
To build Nix itself in this shell: To build Nix itself in this shell:
```console ```console
[nix-shell]$ autoreconfPhase [nix-shell]$ mesonConfigurePhase
[nix-shell]$ configurePhase [nix-shell]$ ninjaBuildPhase
[nix-shell]$ make -j $NIX_BUILD_CORES OPTIMIZE=0
``` ```
To install it in `$(pwd)/outputs` and test it: To test it:
```console ```console
[nix-shell]$ make install OPTIMIZE=0 [nix-shell]$ mesonCheckPhase
[nix-shell]$ make installcheck check -j $NIX_BUILD_CORES ```
To install it in `$(pwd)/outputs`:
```console
[nix-shell]$ ninjaInstallPhase
[nix-shell]$ nix --version [nix-shell]$ nix --version
nix (Nix) 2.12 nix (Nix) 2.12
``` ```
@ -110,25 +119,6 @@ $ nix build
You can also build Nix for one of the [supported platforms](#platforms). You can also build Nix for one of the [supported platforms](#platforms).
## Makefile variables
You may need `profiledir=$out/etc/profile.d` and `sysconfdir=$out/etc` to run `make install`.
Run `make` with [`-e` / `--environment-overrides`](https://www.gnu.org/software/make/manual/make.html#index-_002de) to allow environment variables to override `Makefile` variables:
- `ENABLE_BUILD=yes` to enable building the C++ code.
- `ENABLE_DOC_GEN=yes` to enable building the documentation (manual, man pages, etc.).
The docs can take a while to build, so you may want to disable this for local development.
- `ENABLE_FUNCTIONAL_TESTS=yes` to enable building the functional tests.
- `OPTIMIZE=1` to enable optimizations.
- `libraries=libutil programs=` to only build a specific library.
This will fail in the linking phase if the other libraries haven't been built, but is useful for checking types.
- `libraries= programs=nix` to only build a specific program.
This will not work in general, because the programs need the libraries.
## Platforms ## Platforms
Nix can be built for various platforms, as specified in [`flake.nix`]: Nix can be built for various platforms, as specified in [`flake.nix`]:
@ -175,27 +165,38 @@ Add more [system types](#system-type) to `crossSystems` in `flake.nix` to bootst
It is useful to perform multiple cross and native builds on the same source tree, 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. for example to ensure that better support for one platform doesn't break the build for another.
In order to facilitate this, Nix has some support for being built out of tree – that is, placing build artefacts in a different directory than the source code: Meson thankfully makes this very easy by confining all build products to the build directory --- one simple shares the source directory between multiple build directories, each of which contains the build for Nix to a different platform.
1. Create a directory for the build, e.g. Nixpkgs's `mesonConfigurePhase` always chooses `build` in the current directory as the name and location of the build.
This makes having multiple build directories slightly more inconvenient.
The good news is that Meson/Ninja seem to cope well with relocating the build directory after it is created.
Here's how to do that
1. Configure as usual
```bash ```bash
mkdir build mesonConfigurePhase
``` ```
2. Run the configure script from that directory, e.g. 2. Rename the build directory
```bash ```bash
cd build cd .. # since `mesonConfigurePhase` cd'd inside
../configure <configure flags> mv build build-linux # or whatever name we want
cd build-linux
``` ```
3. Run make from the source directory, but with the build directory specified, e.g. 3. Build as usual
```bash ```bash
make builddir=build <make flags> ninjaBuildPhase
``` ```
> **N.B.**
> [`nixpkgs#335818`](https://github.com/NixOS/nixpkgs/issues/335818) tracks giving `mesonConfigurePhase` proper support for custom build directories.
> When it is fixed, we can simplify these instructions and then remove this notice.
## System type ## System type
Nix uses a string with the following format to identify the *system type* or *platform* it runs on: Nix uses a string with the following format to identify the *system type* or *platform* it runs on:
@ -257,11 +258,8 @@ You can use any of the other supported environments in place of `nix-ccacheStden
The `clangd` LSP server is installed by default on the `clang`-based `devShell`s. The `clangd` LSP server is installed by default on the `clang`-based `devShell`s.
See [supported compilation environments](#compilation-environments) and instructions how to set up a shell [with flakes](#nix-with-flakes) or in [classic Nix](#classic-nix). See [supported compilation environments](#compilation-environments) and instructions how to set up a shell [with flakes](#nix-with-flakes) or in [classic Nix](#classic-nix).
To use the LSP with your editor, you first need to [set up `clangd`](https://clangd.llvm.org/installation#project-setup) by running: To use the LSP with your editor, you will want a `compile_commands.json` file telling `clangd` how we are compiling the code.
Meson's configure always produces this inside the build directory.
```console
make compile_commands.json
```
Configure your editor to use the `clangd` from the `.#native-clangStdenvPackages` shell. You can do that either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration). Configure your editor to use the `clangd` from the `.#native-clangStdenvPackages` shell. You can do that either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration).
@ -276,7 +274,7 @@ Configure your editor to use the `clangd` from the `.#native-clangStdenvPackages
You may run the formatters as a one-off using: You may run the formatters as a one-off using:
```console ```console
make format ./maintainers/format.sh
``` ```
If you'd like to run the formatters before every commit, install the hooks: If you'd like to run the formatters before every commit, install the hooks:

58
doc/manual/src/development/testing.md
View file

@ -135,60 +135,52 @@ Functional tests are run during `installCheck` in the `nix` package build, as we
### Running the whole test suite ### Running the whole test suite
The whole test suite can be run with: The whole test suite (functional and unit tests) can be run with:
```shell-session ```shell-session
$ make install && make installcheck $ mesonCheckPhase
ran test tests/functional/foo.sh... [PASS]
ran test tests/functional/bar.sh... [PASS]
...
``` ```
### Grouping tests ### Grouping tests
Sometimes it is useful to group related tests so they can be easily run together without running the entire test suite. Sometimes it is useful to group related tests so they can be easily run together without running the entire test suite.
Each test group is in a subdirectory of `tests`. Each test group is in a subdirectory of `tests`.
For example, `tests/functional/ca/local.mk` defines a `ca` test group for content-addressed derivation outputs. For example, `tests/functional/ca/meson.build` defines a `ca` test group for content-addressed derivation outputs.
That test group can be run like this: That test group can be run like this:
```shell-session ```shell-session
$ make ca.test-group -j50 $ meson test --suite ca
ran test tests/functional/ca/nix-run.sh... [PASS] ninja: Entering directory `/home/jcericson/src/nix/master/build'
ran test tests/functional/ca/import-derivation.sh... [PASS] ninja: no work to do.
... [1-20/20] 🌑 nix-functional-tests:ca / ca/why-depends 1/20 nix-functional-tests:ca / ca/nix-run OK 0.16s
``` [2-20/20] 🌒 nix-functional-tests:ca / ca/why-depends 2/20 nix-functional-tests:ca / ca/import-derivation OK 0.17s
The test group is defined in Make like this:
```makefile
$(test-group-name)-tests := \
$(d)/test0.sh \
$(d)/test1.sh \
...
install-tests-groups += $(test-group-name)
``` ```
### Running individual tests ### Running individual tests
Individual tests can be run with `make`: Individual tests can be run with `meson`:
```shell-session ```shell-session
$ make tests/functional/${testName}.sh.test $ meson test ${testName}
ran test tests/functional/${testName}.sh... [PASS] ninja: Entering directory `/home/jcericson/src/nix/master/build'
ninja: no work to do.
1/1 nix-functional-tests:main / ${testName} OK 0.41s
Ok: 1
Expected Fail: 0
Fail: 0
Unexpected Pass: 0
Skipped: 0
Timeout: 0
Full log written to /home/jcericson/src/nix/master/build/meson-logs/testlog.txt
``` ```
or without `make`: or without `meson`, showing the output:
```shell-session ```shell-session
$ ./mk/run-test.sh tests/functional/${testName}.sh $ TEST_NAME=${testName} NIX_REMOTE='' PS4='+(${BASH_SOURCE[0]-$0}:$LINENO) tests/functional/${testName}.sh
ran test tests/functional/${testName}.sh... [PASS]
```
To see the complete output, one can also run:
```shell-session
$ ./mk/debug-test.sh tests/functional/${testName}.sh
+(${testName}.sh:1) foo +(${testName}.sh:1) foo
output from foo output from foo
+(${testName}.sh:2) bar +(${testName}.sh:2) bar
@ -254,7 +246,7 @@ It is frequently useful to regenerate the expected output.
To do that, rerun the failed test(s) with `_NIX_TEST_ACCEPT=1`. To do that, rerun the failed test(s) with `_NIX_TEST_ACCEPT=1`.
For example: For example:
```bash ```bash
_NIX_TEST_ACCEPT=1 make tests/functional/lang.sh.test _NIX_TEST_ACCEPT=1 meson test lang
``` ```
This convention is shared with the [characterisation unit tests](#characterisation-testing-unit) too. This convention is shared with the [characterisation unit tests](#characterisation-testing-unit) too.

21
doc/manual/src/installation/building-source.md
View file

@ -1,31 +1,26 @@
# Building Nix from Source # Building Nix from Source
After cloning Nix's Git repository, issue the following commands: Nix is built with [Meson](https://mesonbuild.com/).
It is broken up into multiple Meson packages, which are optionally combined in a single project using Meson's [subprojects](https://mesonbuild.com/Subprojects.html) feature.
```console There are no mandatory extra steps to the building process:
$ autoreconf -vfi generic Meson installation instructions like [this](https://mesonbuild.com/Quick-guide.html#using-meson-as-a-distro-packager) should work.
$ ./configure options...
$ make
$ make install
```
Nix requires GNU Make so you may need to invoke `gmake` instead. The installation path can be specified by passing the `-Dprefix=prefix`
The installation path can be specified by passing the `--prefix=prefix`
to `configure`. The default installation directory is `/usr/local`. You to `configure`. The default installation directory is `/usr/local`. You
can change this to any location you like. You must have write permission can change this to any location you like. You must have write permission
to the *prefix* path. to the *prefix* path.
Nix keeps its *store* (the place where packages are stored) in Nix keeps its *store* (the place where packages are stored) in
`/nix/store` by default. This can be changed using `/nix/store` by default. This can be changed using
`--with-store-dir=path`. `-Dstore-dir=path`.
> **Warning** > **Warning**
> >
> It is best *not* to change the Nix store from its default, since doing > It is best *not* to change the Nix store from its default, since doing
> so makes it impossible to use pre-built binaries from the standard > so makes it impossible to use pre-built binaries from the standard
> Nixpkgs channels — that is, all packages will need to be built from > Nixpkgs channels — that is, all packages will need to be built from
> source. > source.
Nix keeps state (such as its database and log files) in `/nix/var` by Nix keeps state (such as its database and log files) in `/nix/var` by
default. This can be changed using `--localstatedir=path`. default. This can be changed using `-Dlocalstatedir=path`.

11
maintainers/format.sh Executable file
View file

@ -0,0 +1,11 @@
#!/usr/bin/env bash
if ! type -p pre-commit &>/dev/null; then
echo "format.sh: pre-commit not found. Please use \`nix develop\`.";
exit 1;
fi;
if test -z "$_NIX_PRE_COMMIT_HOOKS_CONFIG"; then
echo "format.sh: _NIX_PRE_COMMIT_HOOKS_CONFIG not set. Please use \`nix develop\`.";
exit 1;
fi;
pre-commit run --config "$_NIX_PRE_COMMIT_HOOKS_CONFIG" --all-files

11
maintainers/local.mk
View file

@ -3,13 +3,6 @@
print-top-help += echo ' format: Format source code' print-top-help += echo ' format: Format source code'
# This uses the cached .pre-commit-hooks.yaml file # This uses the cached .pre-commit-hooks.yaml file
fmt_script := $(d)/format.sh
format: format:
@if ! type -p pre-commit &>/dev/null; then \ @$(fmt_script)
echo "make format: pre-commit not found. Please use \`nix develop\`."; \
exit 1; \
fi; \
if test -z "$$_NIX_PRE_COMMIT_HOOKS_CONFIG"; then \
echo "make format: _NIX_PRE_COMMIT_HOOKS_CONFIG not set. Please use \`nix develop\`."; \
exit 1; \
fi; \
pre-commit run --config $$_NIX_PRE_COMMIT_HOOKS_CONFIG --all-files