mirror of
https://github.com/NixOS/nix.git
synced 2024-11-22 06:42:28 +00:00
Merge pull request #11335 from obsidiansystems/meson-doc
Update documentation to refer to Meson not Make in most places
This commit is contained in:
John Ericson
GitHub
commit
d34a89afc3
@ -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:
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -1,31 +1,26 @@
|
||||
# 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**
|
||||
>
|
||||
>
|
||||
> 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
|
||||
> Nixpkgs channels — that is, all packages will need to be built from
|
||||
> 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
11
maintainers/format.sh
Executable 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
|
||||
@ -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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user