README.meson

# Building GALAHAD with [meson](https://mesonbuild.com)

All commands below are to be run from the top of the GALAHAD source tree.

##  Install meson

Refer to https://mesonbuild.com/Getting-meson.html

## Set up the build directory and select build options

The command
```
meson setup builddir [options...]
```
creates the build directory `builddir` and populates it in preparation for a build.

Currently supported options with their default value:
* `-Dmodules=true`: install Fortran modules;
* `-Dciface=true`: build the C interfaces;
* `-Dpythoniface=false`: build the Python interfaces in double precision;
* `-Dexamples=true`: generate the examples;
* `-Dtests=true`: generate the tests;
* `-Dsingle=true`: generate the single precision library, tests and examples;
* `-Ddouble=true`: generate the double precision library, tests and examples;
* `-Dssids=true`: build ssids;
* `-Dlibblas=openblas`: BLAS library against which to link;
* `-Dliblapack=openblas`: LAPACK library against which to link;
* `-Dlibmetis=metis`: METIS library against which to link;
* `-Dlibhsl=hsl`: HSL library against which to link;
* `-Dlibcutest=cutest`: HSL library against which to link;
* `-Dlibwsmp=wsmp`: WSMP library against which to link;
* `-Dlibumfpack=umfpack`: UMFPACK library against which to link;
* `-Dlibpardiso=pardiso`: PARDISO library against which to link;
* `-Dlibspmf=spmf`: SPMF library against which to link;
* `-Dlibpastix=pastix`: PASTIX library against which to link;
* `-Dlibmkl_pardiso=mkl_pardiso`: Intel MKL PARDISO library against which to link;
* `-Dlibampl=ampl`: AMPL library against which to link;
* `-Dlibblas_path=[]`: additional directories to search for the BLAS library;
* `-Dliblapack_path=[]`: additional directories to search for the LAPACK library;
* `-Dlibmetis_path=[]`: additional directories to search for the METIS library;
* `-Dlibhsl_path=[]`: additional directories to search for the HSL library;
* `-Dlibcutest_path=[]`: additional directories to search for the CUTEST library;
* `-Dlibwsmp_path=[]`: additional directories to search for the WSMP library;
* `-Dlibumfpack_path=[]`: additional directories to search for the UMFPACK library;
* `-Dlibpardiso_path=[]`: additional directories to search for the PARDISO library;
* `-Dlibspmf_path=[]`: additional directories to search for the SPMF library;
* `-Dlibpastix_path=[]`: additional directories to search for the PASTIX library;
* `-Dlibmumps_path=[]`: additional directories to search for the MUMPS libraries;
* `-Dlibmkl_pardiso_path=[]`: additional directories to search for the Intel MKL library;
* `-Dlibampl_path=[]`: additional directories to search for the AMPL library library;
* `-Dlibhsl_modules[]`: additional directories to search for the HSL modules;
* `-Dlibmetis_version=5`: version of the METIS library.

Non-default compilers can be selected by setting the `CC`, `CXX` and `FC` shell variables.
For instance,
```
CC=icc CXX=icpc FC=ifort meson setup builddir [options...]
CC=icx CXX=icpx FC=ifx meson setup builddir [options...]
```
See https://mesonbuild.com/Reference-tables.html for supported compilers and linkers.

## Build

The command
```
meson compile -C builddir
```
should result in several shared libraries and executables in `builddir`.
The executables are the example programs and unit tests.
They can be run right away:
```
./builddir/glrts
```

It is also possible (and equivalent) to build directly with Ninja:
```
ninja -C builddir
```

## Run Tests

The command
```
meson test -C builddir
```
runs the unit tests.
A unit test succeeds when the return code of the test executable is zero.

Similarly, the tests can be executed directly with Ninja:
```
ninja test -C builddir
```

Specify test(s) by name like:
```
meson test -C builddir ugo_single
```

Tests belonging to a suite can be run as follows:
```
meson test -C builddir --suite ugo
meson test -C builddir --suite single
meson test -C builddir --suite C
```

Currently supported suites:
* `package`;
* `fortran`;
* `C`;
* `Python`;
* `single`;
* `double`.

## Info

If ninja fails, run "ninja reconfigure" or "meson --reconfigure" to force Meson to regenerate.

If build failures persist, run "meson setup --wipe builddir [options...]" to rebuild from scratch.