commit c3f8fef67e3a946edce62ef29cccd8c910ca13ac
parent 36cd13eaae5cc864fe98f0759c37d89b0fbb73e8
Author: Özgür Kesim <oec@codeblau.de>
Date: Mon, 12 Oct 2026 14:40:36 +0200
[doc] add README.meson.md, link it from INSTALL.md
Diffstat:
2 files changed, 185 insertions(+), 0 deletions(-)
diff --git a/INSTALL.md b/INSTALL.md
@@ -31,6 +31,10 @@ Quick summary:
$ make check
```
+The build system is meson; `./configure` and `make` are a thin wrapper
+around it. See [README.meson.md](README.meson.md) for using meson
+directly, the test suites and setups, and the nix development shell.
+
General Installation Instructions (autoconf)
--------------------------------------------
diff --git a/README.meson.md b/README.meson.md
@@ -0,0 +1,181 @@
+# Meson build system
+
+The exchange is built with meson and ninja. `./configure` and `make` are
+only a thin GNU-style wrapper around them (see below), so everything here
+can also be done with plain meson commands.
+
+## Use
+
+After every `git pull`, first run
+
+```
+$ ./bootstrap
+```
+
+It initializes the `contrib/gana` and `doc/prebuilt` submodules, installs
+the pre-commit hook and makes the already shipped SQL patches read-only.
+
+To compile run:
+
+```
+$ meson setup $builddir --prefix=$PFX -Dlibdir=lib
+$ meson compile -C $builddir
+```
+
+Pass `-Dlibdir=lib`: depending on the distribution, meson otherwise picks
+`lib64` or `lib/<multiarch>`. If `doc/prebuilt` is empty (the submodule
+needs ssh access to git.taler.net), add `-Ddisable-doc=true`.
+
+To change options of an existing build directory:
+
+```
+$ meson configure $builddir -Dlogging=verbose
+```
+
+to install:
+
+```
+$ meson install -C $builddir
+```
+
+to uninstall:
+
+```
+$ ninja -C $builddir uninstall
+```
+
+to make a tarball (runs the tests unless `--no-tests` is given):
+
+```
+$ meson dist -C $builddir
+```
+
+to generate the doxygen documentation:
+
+```
+$ ninja -C $builddir doxygen
+```
+
+### Options
+
+| Option | Default | Meaning |
+|------------------|---------|------------------------------------------------------|
+| `logging` | `yes` | `no`, `yes`, `verbose` or `veryverbose` |
+| `expensivetests` | `false` | also run expensive tests |
+| `enable-epoll` | `auto` | epoll support: `yes`, `no`, `auto` |
+| `disable-doc` | `false` | do not build/install man pages and info files |
+| `only-doc` | `false` | build the documentation only |
+| `install-rpath` | `false` | add `$prefix/$libdir` to the RUNPATH of installed targets that opt in (mostly libraries, not the executables) |
+
+Run `meson configure $builddir` for the full list, including meson's
+built-in options.
+
+### The configure/make wrapper
+
+`./configure` runs `meson setup build` (deleting an existing `build/`
+first) and generates a `Makefile` that forwards to meson:
+
+| make | meson |
+|--------------------------|--------------------------------------------------------|
+| `make` | `ninja -C build` |
+| `make install` | `meson install -C build` |
+| `make uninstall` | `ninja -C build uninstall` |
+| `make check` | `meson test -C build` |
+| `make allcheck` | `meson test -C build --setup=all` |
+| `make installcheck` | `meson test -C build --suite=installcheck` |
+| `make integrationtests` | `meson test -C build --suite=integrationtests` |
+| `make dist` | `meson dist -C build --no-tests --formats gztar` |
+| `make doxygen` | `ninja -C build doxygen` |
+
+The `make` test targets add `--maxfail 999 --timeout-multiplier 4`.
+`./configure` only knows the features `--enable-logging=...`,
+`--enable-coverage`, `--enable-epoll`, `--enable-expensivetests`,
+`--enable-only-doc` and `--enable-install-rpath`; others, such as
+`--disable-doc`, are silently ignored.
+
+## Test
+
+You can run the unit tests as:
+
+```
+$ meson test -C $builddir
+```
+
+The default test setup excludes the `installcheck` and `integrationtests`
+suites. Those use the installed binaries, so run `meson install` first.
+The test setups take `TALER_EXCHANGE_PREFIX`, `TALER_AUDITOR_PREFIX` and
+`PATH` from the configured prefix, so there is no need to export them
+when going through `meson test`.
+
+You can list the tests and run individual ones as:
+
+```
+$ meson test -C $builddir --list
+$ meson test -C $builddir test_amount
+```
+
+You can run the test suites for components as:
+
+```
+$ meson test -C $builddir --suite exchangedb
+```
+
+The suites are `util`, `json`, `pq`, `mhd`, `templating`, `kyclogic`,
+`exchangedb`, `auditordb`, `exchange`, `auditor`, `lib`, `bank-api`,
+`testing`, `installcheck` and `integrationtests`.
+
+Besides `default`, there are two more test setups:
+
+```
+$ meson test -C $builddir --setup all # everything, incl. installcheck and integrationtests
+$ meson test -C $builddir --setup valgrind # unit tests, DB table tests under valgrind
+```
+
+You can use `--setup` also when running suites or individual tests.
+
+The tests need a running PostgreSQL that the current user can reach
+without a password (`PGHOST` etc. are honoured). The `exchangedb` tests
+create and drop a scratch database per run and are skipped (exit status
+77) rather than failed when they cannot create it. The integration
+tests use the `talercheck` database, start the whole system through
+`src/testing/taler-unified-setup.sh` and also need `curl` and `jq`.
+Tests needing `libeufin-bank` or `taler-harness` are skipped when those
+are not installed.
+
+The test log is `$builddir/meson-logs/testlog.txt`. For integration
+tests, the logs of the started processes (`taler-exchange-httpd.log`,
+`taler-exchange-secmod-*.log`, ...) are in `$builddir/src/testing/`;
+they are overwritten by the next test, so rerun a single failing test
+to inspect them.
+
+## Nix development shell
+
+`nix develop` provides all build dependencies and, in addition:
+
+ - links with `-rpath $ORIGIN/../lib/:$ORIGIN/../`, so that the
+ installed binaries and plugins find the exchange libraries for any
+ `--prefix` (the nix linker wrapper would not add the prefix). This
+ is read at `meson setup` time: set up build directories from inside
+ the shell, and with `-Dlibdir=lib`.
+ - a private PostgreSQL in `default/.pg`, reachable only via the Unix
+ socket there (`PGHOST` points to it, `PGDATABASE=talercheck`). It
+ is started if not already running, logs to `default/postgres.log`,
+ and keeps running after the shell exits; stop it with `pg_ctl stop`
+ from within the shell. Unix socket paths are limited to 107 bytes,
+ so the checkout path must not be too long.
+
+A complete run thus is:
+
+```
+$ nix develop
+$ meson setup build --prefix=$HOME/taler -Dlibdir=lib
+$ meson compile -C build
+$ meson install -C build
+$ meson test -C build
+$ meson test -C build --suite integrationtests
+```
+
+The installed binaries refer to their dependencies (GNUnet, jansson, ...)
+in `/nix/store`. `nix develop` does not register a GC root, so a
+`nix-collect-garbage` can remove them; use `nix develop --profile <path>`
+to keep the shell's dependencies alive.