From d0190cff6f2314cc1c727ff113aea20e086f4bcc Mon Sep 17 00:00:00 2001 From: Qyriad Date: Fri, 20 Mar 2026 10:59:43 +0100 Subject: [PATCH] improve justfile, and add more docs about it Change-Id: I00286276dc0ce17a5877a7bd13bb254d6a6a6964 --- doc/manual/src/contributing/hacking.md | 60 ++++++++++++++++++++------ justfile | 42 +++++++++--------- 2 files changed, 68 insertions(+), 34 deletions(-) diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index d682d532a..3b5b63a29 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -51,28 +51,64 @@ $ nix-shell -A native-clangStdenvPackages ### Building from the development shell -Run a clean build and test with `just clean setup build install test`. +We have a [justfile](just.systems) for extra convenient building. +It defaults to using `./build` as the build directory, and `$out` (`./outputs/out`) as the install directory. +For most cases, you can clean-build, install, and run the tests with: + +```bash +$ just setup --wipe && just test +``` + +> **Note** +> +> The `--wipe` argument to `meson setup` conveniently works whether you have an existing build directory or not. +> +> However, it is *mostly*, but not *exactly* equivalent to deleting the build directory first. +> In particular, previously specified `-D` build options are **preserved** with `--wipe` (for some reason). +> For example, if you fetch and checkout a new version of Lix, and that new version *removes* a Meson build option from `./meson.options`, *and* a previous invocation in that build directory explicitly set that option, then `meson setup --wipe build` will error, complaining about the unknown option. +> For these cases, `just clean` will give you a well-and-truly-this-time-for-real clean build. + +Because the integration tests require installation to work, `just test` automatically also calls `just install`, and Meson helpfully will automatically build any targets that need building when trying to install them. + +You can override the build directory or install directory by setting the justfile [variables](https://just.systems/man/en/setting-variables-from-the-command-line.html) `outdir` and `builddir` on the command-line: + +```bash +$ just builddir=build-before-bisect outdir=out-before-bisect setup +$ just builddir=build-before-bisect test +``` + +You'll have to set `builddir` for every target, but `outdir` only needs to be set for `setup`. You can also run the unit tests and integration tests separately: ```bash -$ just setup build test-unit -$ just install test-integration +$ just setup +$ just test-unit +$ just test-integration ``` -Many justfile aliases have a `-custom` variant which pass extra arguments to `meson`. +Most justfile targets forward all further arguments to the underlying Meson invocation. For example, to work on both Lix and nix-eval-jobs you can run: -``` -$ just setup-custom -Dnix-eval-jobs=enabled -$ # or -$ mesonFlags=-Dnix-eval-jobs=enabled just setup +```bash +$ just setup -Dnix-eval-jobs=enabled ``` -Note that only targets which don't accept extra arguments can be used when -running multiple targets at once; `just setup build` is fine, but `just -setup-custom build` is an error. The `test` target is usually the last one to -run, so it always accepts extra arguments. +Note that only targets which *don't* accept extra arguments can have other targets following them. +`just clean setup` is equivalent to `just clean && just setup`, but `just build test` runs the `build` target with the argument `test`. +This means that if you want to, for example, build with lower parallelism, and then test, you will have to do something like this: + +```bash +$ just build -j4 +$ just test +``` + +Finally, the rewrite of the integration test suite, functional2, also has its own justfile target which allows passing extra arguments to pytest. +For example, to collect and list all functional2 tests without running them, you can pass pytest's `--collect-only` argument: + +```bash +$ just test-functional2 --collect-only +``` You can also build Lix manually: diff --git a/justfile b/justfile index d8247dfc6..d67a5588a 100644 --- a/justfile +++ b/justfile @@ -1,4 +1,10 @@ # https://just.systems/man/en/ +# +# Take a look at ./doc/manual/src/contributing/hacking.md for a detailed +# explanation on how to use this file! + +outdir := x"${out:-$PWD/outputs/out}" +builddir := "build" # List all available targets list: @@ -6,40 +12,32 @@ list: # Clean build artifacts clean: - rm -rf build + rm -rf {{ builddir }} -# Prepare meson for building with extra options -setup-custom *OPTIONS: - meson setup build --prefix="$PWD/outputs/out" $mesonFlags {{ OPTIONS }} - -# Prepare meson for building -setup: (setup-custom) +# Prepare meson for building. +setup *OPTIONS: + meson setup {{ builddir }} --reconfigure --prefix="{{outdir}}" $mesonFlags {{ OPTIONS }} # Build lix with extra options -build-custom *OPTIONS: - meson compile -C build {{ OPTIONS }} - -# Build lix -build: (build-custom) +build *OPTIONS: + meson compile -C {{ builddir }} {{ OPTIONS }} alias compile := build -# Install lix for local development with extra options -install-custom *OPTIONS: (build-custom OPTIONS) - meson install -C build +# `meson install` will automatically build anything that needs to be built to install it. +[doc("Install Lix for local development")] +install *OPTIONS: + meson install --quiet -C {{ builddir }} {{ OPTIONS }} -# Install lix for local development -install: (install-custom) - -# Run tests (usually requires `install`) with extra options -test *OPTIONS: - meson test -C build --print-errorlogs --max-lines 10000 {{ OPTIONS }} +# Run all tests tests (installs first). +test *OPTIONS: (install) + meson test -C {{ builddir }} --print-errorlogs --max-lines 10000 {{ OPTIONS }} # Run unit tests only test-unit *OPTIONS: (test "--suite" "check") # Run integration tests only -test-integration *OPTIONS: install (test "--suite" "installcheck") +test-integration *OPTIONS: (test "--suite" "installcheck" OPTIONS) # Run functional2 tests using pytest directly, allowing for additional arguments to be passed to pytest e.g. for more granular test selection test-functional2 *OPTIONS: