README.meson.md (6631B)
1 # Meson build system 2 3 The exchange is built with meson and ninja. `./configure` and `make` are 4 only a thin GNU-style wrapper around them (see below), so everything here 5 can also be done with plain meson commands. 6 7 ## Use 8 9 After every `git pull`, first run 10 11 ``` 12 $ ./bootstrap 13 ``` 14 15 It initializes the `contrib/gana` and `doc/prebuilt` submodules, installs 16 the pre-commit hook and makes the already shipped SQL patches read-only. 17 18 To compile run: 19 20 ``` 21 $ meson setup $builddir --prefix=$PFX -Dlibdir=lib 22 $ meson compile -C $builddir 23 ``` 24 25 Pass `-Dlibdir=lib`: depending on the distribution, meson otherwise picks 26 `lib64` or `lib/<multiarch>`. If `doc/prebuilt` is empty (the submodule 27 needs ssh access to git.taler.net), add `-Ddisable-doc=true`. 28 29 To change options of an existing build directory: 30 31 ``` 32 $ meson configure $builddir -Dlogging=verbose 33 ``` 34 35 to install: 36 37 ``` 38 $ meson install -C $builddir 39 ``` 40 41 to uninstall: 42 43 ``` 44 $ ninja -C $builddir uninstall 45 ``` 46 47 to make a tarball (runs the tests unless `--no-tests` is given): 48 49 ``` 50 $ meson dist -C $builddir 51 ``` 52 53 to generate the doxygen documentation: 54 55 ``` 56 $ ninja -C $builddir doxygen 57 ``` 58 59 ### Options 60 61 | Option | Default | Meaning | 62 |------------------|---------|------------------------------------------------------| 63 | `logging` | `yes` | `no`, `yes`, `verbose` or `veryverbose` | 64 | `expensivetests` | `false` | also run expensive tests | 65 | `enable-epoll` | `auto` | epoll support: `yes`, `no`, `auto` | 66 | `disable-doc` | `false` | do not build/install man pages and info files | 67 | `only-doc` | `false` | build the documentation only | 68 | `install-rpath` | `false` | add `$prefix/$libdir` to the RUNPATH of installed targets that opt in (mostly libraries, not the executables) | 69 70 Run `meson configure $builddir` for the full list, including meson's 71 built-in options. 72 73 ### The configure/make wrapper 74 75 `./configure` runs `meson setup build` (deleting an existing `build/` 76 first) and generates a `Makefile` that forwards to meson: 77 78 | make | meson | 79 |--------------------------|--------------------------------------------------------| 80 | `make` | `ninja -C build` | 81 | `make install` | `meson install -C build` | 82 | `make uninstall` | `ninja -C build uninstall` | 83 | `make check` | `meson test -C build` | 84 | `make allcheck` | `meson test -C build --setup=all` | 85 | `make installcheck` | `meson test -C build --suite=installcheck` | 86 | `make integrationtests` | `meson test -C build --suite=integrationtests` | 87 | `make dist` | `meson dist -C build --no-tests --formats gztar` | 88 | `make doxygen` | `ninja -C build doxygen` | 89 90 The `make` test targets add `--maxfail 999 --timeout-multiplier 4`. 91 `./configure` only knows the features `--enable-logging=...`, 92 `--enable-coverage`, `--enable-epoll`, `--enable-expensivetests`, 93 `--enable-only-doc` and `--enable-install-rpath`; others, such as 94 `--disable-doc`, are silently ignored. 95 96 ## Test 97 98 You can run the unit tests as: 99 100 ``` 101 $ meson test -C $builddir 102 ``` 103 104 The default test setup excludes the `installcheck` and `integrationtests` 105 suites. Those use the installed binaries, so run `meson install` first. 106 The test setups take `TALER_EXCHANGE_PREFIX`, `TALER_AUDITOR_PREFIX` and 107 `PATH` from the configured prefix, so there is no need to export them 108 when going through `meson test`. 109 110 You can list the tests and run individual ones as: 111 112 ``` 113 $ meson test -C $builddir --list 114 $ meson test -C $builddir test_amount 115 ``` 116 117 You can run the test suites for components as: 118 119 ``` 120 $ meson test -C $builddir --suite exchangedb 121 ``` 122 123 The suites are `util`, `json`, `pq`, `mhd`, `templating`, `kyclogic`, 124 `exchangedb`, `auditordb`, `exchange`, `auditor`, `lib`, `bank-api`, 125 `testing`, `installcheck` and `integrationtests`. 126 127 Besides `default`, there are two more test setups: 128 129 ``` 130 $ meson test -C $builddir --setup all # everything, incl. installcheck and integrationtests 131 $ meson test -C $builddir --setup valgrind # unit tests, DB table tests under valgrind 132 ``` 133 134 You can use `--setup` also when running suites or individual tests. 135 136 The tests need a running PostgreSQL that the current user can reach 137 without a password (`PGHOST` etc. are honoured). The `exchangedb` tests 138 create and drop a scratch database per run and are skipped (exit status 139 77) rather than failed when they cannot create it. The integration 140 tests use the `talercheck` database, start the whole system through 141 `src/testing/taler-unified-setup.sh` and also need `curl` and `jq`. 142 Tests needing `libeufin-bank` or `taler-harness` are skipped when those 143 are not installed. 144 145 The test log is `$builddir/meson-logs/testlog.txt`. For integration 146 tests, the logs of the started processes (`taler-exchange-httpd.log`, 147 `taler-exchange-secmod-*.log`, ...) are in `$builddir/src/testing/`; 148 they are overwritten by the next test, so rerun a single failing test 149 to inspect them. 150 151 ## Nix development shell 152 153 `nix develop` provides all build dependencies and, in addition: 154 155 - links with `-rpath $ORIGIN/../lib/:$ORIGIN/../`, so that the 156 installed binaries and plugins find the exchange libraries for any 157 `--prefix` (the nix linker wrapper would not add the prefix). This 158 is read at `meson setup` time: set up build directories from inside 159 the shell, and with `-Dlibdir=lib`. 160 - a private PostgreSQL in `default/.pg`, reachable only via the Unix 161 socket there (`PGHOST` points to it, `PGDATABASE=talercheck`). It 162 is started if not already running, logs to `default/postgres.log`, 163 and keeps running after the shell exits; stop it with `pg_ctl stop` 164 from within the shell. Unix socket paths are limited to 107 bytes, 165 so the checkout path must not be too long. 166 167 A complete run thus is: 168 169 ``` 170 $ nix develop 171 $ meson setup build --prefix=$HOME/taler -Dlibdir=lib 172 $ meson compile -C build 173 $ meson install -C build 174 $ meson test -C build 175 $ meson test -C build --suite integrationtests 176 ``` 177 178 The installed binaries refer to their dependencies (GNUnet, jansson, ...) 179 in `/nix/store`. `nix develop` does not register a GC root, so a 180 `nix-collect-garbage` can remove them; use `nix develop --profile <path>` 181 to keep the shell's dependencies alive.