README.meson

# Building GALAHAD with [meson](https://mesonbuild.com)
# This version: GALAHAD 5.0 - 2024-06-07 AT 08:50 GMT.
# Alexis Montoison, for GALAHAD productions

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

# Cheat sheet

## If you are in a hurry ... default install (using gfortran/gcc) with tests

```shell
meson setup builddir/pc64.lnx.gfo -Dtests=true
meson compile -C builddir/pc64.lnx.gfo
meson install -C builddir/pc64.lnx.gfo
meson test -C builddir/pc64.lnx.gfo
```

## If you make a mistake!

```shell
meson setup --wipe builddir/pc64.lnx.gfo
```

## Performance of debugging?

meson setup builddir/pc64.lnx.gfo --buildtype=release (default)
meson setup builddir/pc64.lnx.gfo --buildtype=debug

## Static or shared libraries?

meson setup builddir/pc64.lnx.gfo -Ddefault_library=shared (default)
meson setup builddir/pc64.lnx.gfo -Ddefault_library=static
meson setup builddir/pc64.lnx.gfo -Ddefault_library=both

## 32-bit or 64-bit integers?

```shell
meson setup builddir/pc64.lnx.gfo -Dint64=false (default)
meson setup builddir/pc64.lnx.gfo -Dint64=true
```

Note that all dependencies (BLAS, LAPACK, etc...) must also be compiled with 64-bit integers.
To force Meson to not use a dependency compiled with 32-bit integers, you can use the option `-Dlibdep=`
where `libdep` is an option described below to provide the name of the library.
GALAHAD will not link with the dependency or compile its own 64-bit version, except for BLAS and LAPACK.

```shell
meson setup builddir/pc64.lnx.gfo -Dint64=true -Dlibblas= -Dliblapack= -Dlibmetis=
```

For instance, GALAHAD is compiled with our own version of BLAS, LAPACK and METIS.

# Details

##  Install meson

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

## Set up the build directory and select build options

The command
```shell
meson setup builddir [options...]
```
creates the build directory `builddir` and populates it in preparation
for a build. Separate builds may be placed in separate  `builddir` 
subdirectories, e.g., builddir/pc64.lnx.gfo builddir/pc64.lnx.ifx as above

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=false`: generate the examples;
* `-Dtests=false`: generate the tests;
* `-Dsingle=true`: generate the single precision library, tests and examples;
* `-Ddouble=true`: generate the double precision library, tests and examples;
* `-Dquadruple=false`: generate the quadruple 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;
* `-Dlibhsl=hsl_subset`: HSL library against which to link;
* `-Dlibcutest_single=cutest_single`: CUTEst library in single precision against which to link;
* `-Dlibcutest_double=cutest_double`: CUTEst library in double precision against which to link;
* `-Dlibcutest_quadruple=cutest_quadruple`: CUTEst library in quadruple precision against which to link;
* `-Dlibwsmp=wsmp`: WSMP 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;
* `-Dlibsmumps=smumps`: Single-precision MUMPS library against which to link;
* `-Dlibdmumps=dmumps`: Double-precision MUMPS library against which to link;
* `-Dlibampl=ampl`: AMPL library against which to link;
* `-Dlibhwloc=hwloc`: HWLOC 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;
* `-Dlibhsl_path=[]`: additional directories to search for the HSL library;
* `-Dlibcutest_path=[]`: additional directories to search for the CUTEST libraries;
* `-Dlibwsmp_path=[]`: additional directories to search for the WSMP 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;
* `-Dlibampl_path=[]`: additional directories to search for the AMPL library library;
* `-Dlibhwloc_path=[]`: additional directories to search for the HWLOC library;
* `-Dlibhwloc_include=[]`: additional directories to search for the HWLOC header files;
* `-Dlibhsl_modules[]`: additional directories to search for the HSL modules;
* `-Dlibcutest_modules[]`: additional directories to search for the CUTEst modules;
* `-Dint64=false`: compile GALAHAD with 64-bit integer.

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

## Dependencies

### MKL Pardiso

Note that the Intel MKL Pardiso linear solver is only available when GALAHAD
is compiled with Intel MKL.
This implies that `libblas` or `liblapack` should be set to `mkl_rt`.


### HSL

To compile GALAHAD with the HSL subset, use the following commands:
```shell
meson setup builddir_int32 -Dlibmetis= -Dlibhsl=hsl_subset -Dlibhsl_path=... -Dlibhsl_modules=...
meson compile -C builddir_int32

meson setup builddir_int64 -Dint64=true -Dlibmetis= -Dlibhsl=hsl_subset_64 -Dlibhsl_path=... -Dlibhsl_modules=...
meson compile -C builddir_int64
```

## Build

The command
```shell
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:
```shell
./builddir/glrts
```

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

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.

## Run Tests

The command
```shell
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:
```shell
ninja test -C builddir
```

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

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

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

# Meson build tips for developers

## Add a new package in GALAHAD

To update the Meson build system for a new package `abcd`, the procedure
is composed of three steps.

The first one is to update the main `meson.build` at the root of GALAHAD
by adding the line `subdir("src/abcd")`.

The second step is to add a file `meson.build` in the subfolder
`src/abcd` of GALAHAD.  Depending on whether the new package `abcd` has
C and Python interfaces, as well as multiple examples and tests in
different languages, the content of the file `meson.build` will look
like this:

```
libgalahad_src += files('abcd.F90')

libgalahad_c_src += files('C/abcd_ciface.F90')

galahad_binaries += [['abcd_program', files('abcd_program.F90')]]

libgalahad_python_src += [['abcd', files('Python/abcd_pyiface.c',
                                         '../efgh/Python/efgh_pyiface.c','../ijkl/Python/ijkl_pyiface.c',
                                         '../mnop/Python/mnop_pyiface.c','../qrst/Python/qrst_pyiface.c')]]

libgalahad_cutest_src += files('useabcd.F90')

galahad_cutest_binaries += [['runabcd_sif', files('runabcd_sif.F90')]]

galahad_tests += [['abcd', 'abcdt', files('abcdt.F90')],
                  ['abcd', 'abcdti', files('abcdti.F90')]]

galahad_c_tests += [['abcd', 'abcdt_c', files('C/abcdt.c')],
                    ['abcd', 'abcdtf_c', files('C/abcdtf.c')]]

galahad_python_tests += [['abcd', 'abcd_py', files('Python/test_abcd.py')]]

galahad_examples += [['abcds', files('abcds.f90')],
                     ['abcds2', files('abcds2.f90')]]

galahad_c_examples += [['abcds_c', files('C/abcds.c')],
                       ['abcds2_c', files('C/abcds2.c')]]
```

For `galahad_tests`, `galahad_c_tests` and `galahad_python_tests`, the
first value 'abcd' specifies the name of the package.  Thanks to that,
we can run all tests of `abcd` with `meson test -C builddir --suite
abcd`.  The second value of `galahad_tests`, `galahad_c_tests` and
`galahad_python_tests` specifies the name of the test.  If a binary is
generated for the test, the binary has the same name as the test.  A
specific test can be run with Meson thanks to the command `meson test -C
builddir abcdt`.  Note that the binary has the suffix `.exe` on Windows.
The third value of `galahad_tests`, `galahad_c_tests` and
`galahad_python_tests` is the file that contains the test.

Similarly, the first value of `galahad_examples` and
`galahad_c_examples` is the name of the binary (without the suffix
`.exe` on Windows) based on the example file specified by the second
value.

The last step is to update the file `meson.build` in the subfolder
`include` of GALAHAD if the new package has a C interface.  You need to
add a line `'galahad_abcd.h'` so that this new header can be installed.

## Create a new release of GALAHAD

When we do a new release of GALAHAD, we should update the `version`
(line 4) of the main `meson.build`.

## Variables defined in meson.build files

- `libgalahad_single_deps`: dependencies for single precision;
- `libgalahad_double_deps`: dependencies for double precision;
- `libgalahad_deps`: dependencies for both precision;
- `libgalahad_single_src`: Fortran files *.F90 or *.f90 for single precision;
- `libgalahad_double_src`: Fortran files *.F90 or *.f90 for double precision;
- `libgalahad_src`: Fortran files *.F90 or *.f90 for both precision;
- `libgalahad_f_single_src`: Fortran files *.f for single precision;
- `libgalahad_f_double_src`: Fortran files *.f for double precision;
- `libgalahad_f_src`: Fortran files *.f for both precision;
- `galahad_binaries`: Fortran files that contain programs;
- `galahad_headers`: Header files to install;
- `libgalahad_c_single_src`: Fortran files for the C interfaces in single precision;
- `libgalahad_c_double_src`: Fortran files for the C interfaces in double precision;
- `libgalahad_c_src`: Fortran files for the C interfaces in both precision;
- `libgalahad_python_src`: C files for the Python interfaces;
- `libgalahad_cutest_src`: Fortran files related to the CUTEst interfaces;
- `galahad_cutest_binaries`: Fortran files that contain CUTEst programs;
- `libgalahad_cpp_src`: C++ files required by GALAHAD;
- `libgalahad_cc_src`: C files required by GALAHAD;
- `galahad_examples`: Fortran examples;
- `galahad_tests`: Fortran tests;
- `galahad_c_examples`: C examples for the C interfaces;
- `galahad_c_tests`: C tests for the C interfaces;
- `galahad_python_tests`: Python tests for the Python interfaces;
- `libgalahad_include`: Folders that contain headers and Fortran modules.