exchange

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

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.