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

Update documentation to refer to Meson not Make in most places

Browse source 
This is necessary to make the Meson one the default and preferred one.

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
This commit is contained in:
John Ericson 2024-08-19 10:24:38 -04:00
parent aeabe68291
commit ceae25825f
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:
```console
[nix-shell]$ autoreconfPhase
[nix-shell]$ ./configure $configureFlags --prefix=$(pwd)/outputs/out
[nix-shell]$ make -j $NIX_BUILD_CORES
[nix-shell]$ mesonFlags+=" --prefix=$(pwd)/outputs/out"
[nix-shell]$ dontAddPrefix=1 mesonConfigurePhase
[nix-shell]$ ninjaBuildPhase
```
To install it in `$(pwd)/outputs` and test it:
To test it:
```console
[nix-shell]$ make install
[nix-shell]$ make installcheck -j $NIX_BUILD_CORES
[nix-shell]$ mesonCheckPhase
```
To install it in `$(pwd)/outputs`:
```console
[nix-shell]$ ninjaInstallPhase
[nix-shell]$ ./outputs/out/bin/nix --version
nix (Nix) 2.12
```
@ -85,16 +90,20 @@ $ nix develop .#native-clangStdenvPackages
To build Nix itself in this shell:
```console
[nix-shell]$ autoreconfPhase
[nix-shell]$ configurePhase
[nix-shell]$ make -j $NIX_BUILD_CORES OPTIMIZE=0
[nix-shell]$ mesonConfigurePhase
[nix-shell]$ ninjaBuildPhase
```
To install it in `$(pwd)/outputs` and test it:
To test it:
```console
[nix-shell]$ make install OPTIMIZE=0
[nix-shell]$ make installcheck check -j $NIX_BUILD_CORES
[nix-shell]$ mesonCheckPhase
```
To install it in `$(pwd)/outputs`:
```console
[nix-shell]$ ninjaInstallPhase
[nix-shell]$ nix --version
nix (Nix) 2.12
```
@ -110,25 +119,6 @@ $ nix build
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
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,
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
mkdir build
mesonConfigurePhase
```
2. Run the configure script from that directory, e.g.
2. Rename the build directory
```bash
cd build
../configure <configure flags>
cd .. # since `mesonConfigurePhase` cd'd inside
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
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
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.
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:
```console
make compile_commands.json
```
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.
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:
```console
make format
./maintainers/format.sh
```
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
The whole test suite can be run with:
The whole test suite (functional and unit tests) can be run with:
```shell-session
$ make install && make installcheck
ran test tests/functional/foo.sh... [PASS]
ran test tests/functional/bar.sh... [PASS]
...
$ mesonCheckPhase
```
### Grouping tests
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`.
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:
```shell-session
$ make ca.test-group -j50
ran test tests/functional/ca/nix-run.sh... [PASS]
ran test tests/functional/ca/import-derivation.sh... [PASS]
...
```
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)
$ meson test --suite ca
ninja: Entering directory `/home/jcericson/src/nix/master/build'
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
```
### Running individual tests
Individual tests can be run with `make`:
Individual tests can be run with `meson`:
```shell-session
$ make tests/functional/${testName}.sh.test
ran test tests/functional/${testName}.sh... [PASS]
$ meson test ${testName}
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
$ ./mk/run-test.sh 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
$ TEST_NAME=${testName} NIX_REMOTE='' PS4='+(${BASH_SOURCE[0]-$0}:$LINENO) tests/functional/${testName}.sh
+(${testName}.sh:1) foo
output from foo
+(${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`.
For example:
```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.

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

@ -1,24 +1,19 @@
# 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
$ autoreconf -vfi
$ ./configure options...
$ make
$ make install
```
There are no mandatory extra steps to the building process:
generic Meson installation instructions like [this](https://mesonbuild.com/Quick-guide.html#using-meson-as-a-distro-packager) should work.
Nix requires GNU Make so you may need to invoke `gmake` instead.
The installation path can be specified by passing the `--prefix=prefix`
The installation path can be specified by passing the `-Dprefix=prefix`
to `configure`. The default installation directory is `/usr/local`. You
can change this to any location you like. You must have write permission
to the *prefix* path.
Nix keeps its *store* (the place where packages are stored) in
`/nix/store` by default. This can be changed using
`--with-store-dir=path`.
`-Dstore-dir=path`.
> **Warning**
>
@ -28,4 +23,4 @@ Nix keeps its *store* (the place where packages are stored) in
> source.
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'
# This uses the cached .pre-commit-hooks.yaml file
fmt_script := $(d)/format.sh
format:
@if ! type -p pre-commit &>/dev/null; then \
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
@$(fmt_script)