Installation Instructions
*************************

GNU Anastasis is built with Meson and Ninja.  The ‘configure’ script in
this directory is *not* generated by Autoconf: it is a small hand-written
wrapper around ‘meson setup’.  It therefore supports only the options
documented below — any other option is silently ignored.


Basic Installation
==================

   When building from a git checkout, first run:

     ./bootstrap

This initialises the git submodules (notably ‘contrib/gana’, which
supplies the generated error codes) and installs the uncrustify
pre-commit hook.  It is not needed when building from a distribution
tarball.

   Then the usual three commands:

     ./configure
     make
     make install

‘configure’ runs ‘meson setup build’ and writes a ‘Makefile’ that
forwards to ‘ninja -C build’.  Using it is optional; you can drive Meson
directly instead:

     meson setup build
     ninja -C build
     meson install -C build

   Note that ‘configure’ deletes and re-creates the build directory.  Run
it for the initial setup or when changing options; for ordinary rebuilds
just run ‘make’.

   ‘configure’ records its arguments in ‘config.status’, and running that
script repeats the same configuration.


Running the Test Suite
======================

   The package must be installed before the tests can run, because the
test harness locates the installed binaries through the ANASTASIS_PREFIX
environment variable:

     make install
     make check

A PostgreSQL server (see README for the required version) must be
running and reachable for the database and integration tests.

   Two groups of tests are excluded from ‘make check’ and have their own
targets:

     make installcheck
     make integrationtests

   Tests are grouped into Meson suites, so a subset can be run directly:

     meson test -C build --suite stasis
     meson test -C build test_anastasis_crypto


Installation Names
==================

   By default ‘make install’ installs under ‘/usr/local’.  Use ‘--prefix’
to change this:

     ./configure --prefix=$HOME/anastasis

   The following directory options are accepted and forwarded to Meson.
Each takes the form ‘--NAME=DIRECTORY’:

     prefix          exec_prefix     bindir          sbindir
     libexecdir      sysconfdir      sharedstatedir  localstatedir
     runstatedir     libdir          includedir      oldincludedir
     datarootdir     datadir         infodir         localedir
     mandir          docdir          htmldir         dvidir
     pdfdir          psdir

   Two further options control the build layout rather than the
installation layout:

     --srcdir=DIR         the source directory (default: ‘.’ or ‘..’)
     --mesonbuilddir=DIR  the build directory (default: ‘build’)


Optional Features
=================

   ‘configure’ accepts the following ‘--enable-’ options.  All of them
default to disabled.

     --enable-coverage
          Build with coverage instrumentation (Meson’s ‘b_coverage’).

     --enable-logging=LEVEL
          Set the logging level.  LEVEL is one of ‘yes’, ‘no’, ‘verbose’
          or ‘veryverbose’.  Only ‘no’ currently changes the build: it
          compiles logging out entirely via GNUNET_CULL_LOGGING.  The
          two verbose levels are accepted but presently have no effect.

          Beware that ‘--disable-logging’ does *not* turn logging off;
          write ‘--enable-logging=no’ for that.

     --enable-only-doc
          Build the documentation only, skipping all C targets.

     --enable-install-rpath
          Record an rpath pointing at the install prefix in the installed
          binaries.

   There are no ‘--with-’ options.

   Meson understands one option that ‘configure’ does not forward,
‘disable-doc’.  To build without documentation, configure with Meson
directly:

     meson setup build -Ddisable-doc=true


Compilers and Options
=====================

   Compilers, tools and flags are set by passing ‘VARIABLE=VALUE’ on the
‘configure’ command line:

     ./configure CC=clang CFLAGS=-O2

The recognised variables are:

     tools   AR AS BISON CC CXX CPP FLEX INSTALL LD LDCONFIG LEX MAKE
             MAKEINFO RANLIB TEXI2DVI YACC CHGRP CHMOD CHOWN MKNOD RM
             NINJA MESON
     flags   ARFLAGS BISONFLAGS CFLAGS CXXFLAGS CPPFLAGS FLEXFLAGS
             INSTALLFLAGS LDFLAGS LDCONFIGFLAGS LFLAGS MAKEFLAGS
             MAKEINFOFLAGS RANLIBFLAGS TEXI2DVIFLAGS YACCFLAGS
             CHGRPFLAGS CHMODFLAGS CHOWNFLAGS MKNODFLAGS
     other   INSTALL_DATA INSTALL_PROGRAM INSTALL_SCRIPT

‘MESON’ and ‘NINJA’ are useful when those tools are not on the default
path.  Most of the rest are inherited from the wrapper’s generic template
and have no effect on a Meson build; ‘CC’, ‘CXX’, ‘CFLAGS’, ‘CPPFLAGS’
and ‘LDFLAGS’ are the ones that matter.


Compiling For Multiple Architectures
====================================

   Meson always builds out of tree, so several build directories can
coexist.  Give each one its own build and install directory:

     ./configure --mesonbuilddir=build-debug --prefix=/opt/anastasis-debug

Each ‘configure’ run overwrites the top-level ‘Makefile’, so ‘make’ always
drives whichever build directory was configured last.  To work with
several at once, use ninja directly: ‘ninja -C build-debug’.

   ‘configure’ has no ‘--build’, ‘--host’ or ‘--target’ options — the
Autoconf spellings are silently ignored, and passing them will *not*
produce a cross build.  To cross-compile, invoke Meson directly with a
cross file:

     meson setup build --cross-file my-cross-file.txt
     ninja -C build


Other ‘make’ Targets
====================

   The generated ‘Makefile’ also provides:

     make clean          remove the build outputs
     make uninstall      remove the installed files
     make dist           create a distribution tarball
     make format         reformat the sources with uncrustify
     make distclean      remove ‘Makefile’ and ‘config.status’


‘configure’ Invocation
======================

   Run ‘./configure --help’ for a generated summary of the options
described above.
