exchange

Base system with REST service to issue digital coins, run by the payment service provider
Log | Files | Refs | Submodules | README | LICENSE

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:
MINSTALL.md | 4++++
AREADME.meson.md | 181+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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.