Skip to content

Update meson build instructions #179

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 14, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 24 additions & 22 deletions _docs_v7/Build-SU2-Linux-MacOS.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Short summary of the minimal requirements:

If you have these tools installed, you can create a configuration using the `meson.py` found in the root source code folder:
```
./meson.py build
./meson.py setup build
```
Use `ninja` to compile and install the code

Expand All @@ -62,10 +62,10 @@ Use `ninja` to compile and install the code
### Compilers ###
Installing SU2 from source requires a C++ compiler. The GNU compilers (gcc/g++) are open-source, widely used, and reliable for building SU2. The Intel compiler set has been optimized to run on Intel hardware and has also been used successfully by the development team to build the source code, though it is commercially licensed. The Apple LLVM compiler (Clang) is also commonly used by the developers.

- GNU gcc / g++
- Intel icc / icpc
- GNU gcc / g++
- Intel icc / icpc
- Apple LLVM (clang)

**Note**: SU2 uses some C++11 features, that means at least GCC >= v4.7, Clang >= v3.0 or Intel C++ >= v12.0 is necessary.

### MPI ###
Expand All @@ -76,7 +76,7 @@ It is possible to force the MPI mode with the meson option `-Dcustom-mpi=true`,

### Python ###

SU2 requires Python 3 for compilation and for running the python scripts. Make sure that you have properly set up the `python3` executables in your environment.
SU2 requires Python 3 for compilation and for running the python scripts. Make sure that you have properly set up the `python3` executables in your environment.

### Optional: swig and mpi4py ###
If you want to use the python wrapper capabilities, also `swig` and `mpi4py` are required. On **Linux** `swig` should be available in the package manager of your distribution and `mpi4py` can be installed using [pip](https://pip.pypa.io/en/stable/).
Expand All @@ -89,45 +89,47 @@ Install mpi4py with Python pip using easy install:

$ easy_install pip
$ pip install mpi4py

---

## Automatically installed dependencies ##

The following dependencies are automatically downloaded (or initialized if source code was cloned using `git`) during the [configuration](#configuration-and-compilation).
The following dependencies are automatically downloaded (or initialized if source code was cloned using `git`) during the [configuration](#configuration-and-compilation).

### Meson and Ninja ###
The build system of SU2 is based on a combination of [meson](http://mesonbuild.com/) (as the front-end) and [ninja](https://ninja-build.org/) (as the back-end). Meson is an open source build system meant to be both extremely fast, and, even more importantly, as user friendly as possible. Ninja is a small low-level build system with a focus on speed.
The build system of SU2 is based on a combination of [meson](http://mesonbuild.com/) (as the front-end) and [ninja](https://ninja-build.org/) (as the back-end). Meson is an open source build system meant to be both extremely fast, and, even more importantly, as user friendly as possible. Ninja is a small low-level build system with a focus on speed.

### CoDiPack and MeDiPack ###
In order to use the discrete adjoint solver the compilation requires two additional (header-only) libraries. [CoDi](https://github.com/SciCompKL/CoDiPack) provides the AD datatype and [MeDi](https://github.com/SciCompKL/MeDiPack) provides the infrastructure for the MPI communication when the reverse mode of AD is used.
In order to use the discrete adjoint solver the compilation requires two additional (header-only) libraries. [CoDi](https://github.com/SciCompKL/CoDiPack) provides the AD datatype and [MeDi](https://github.com/SciCompKL/MeDiPack) provides the infrastructure for the MPI communication when the reverse mode of AD is used.

---
---
## Configuration and Compilation ##

Like mentioned above, SU2 uses meson and ninja for configuration and compilation, respectively. A configuration using meson is generated first and then an invocation of ninja is used to compile SU2 with this configuration.
Like mentioned above, SU2 uses meson and ninja for configuration and compilation, respectively. A configuration using meson is generated first and then an invocation of ninja is used to compile SU2 with this configuration.

### Basic Configuration ###
In the root folder of the sources you will find a python script called `meson.py`. This script generates a configuration. It will also check whether all dependencies are found and downloads some of them if necessary see [previous section](#automatically-installed-dependencies).
In the root folder of the sources you will find a python script called `meson.py`. This script generates a configuration. It will also check whether all dependencies are found and downloads some of them if necessary see [previous section](#automatically-installed-dependencies).

**Note**: For the following steps you can also use preinstalled versions of `meson` and `ninja` available on your machine. Just replace the `./meson.py` and `./ninja` calls with the binaries of the respective installations. However, this way you have to manually make sure that the correct versions of [CoDiPack and MeDiPack](#codipack-and-medipack) are placed in the `externals/` folders.

The only required argument for `meson.py` is a name of a directory where it should store the configuration. You can have multiple configurations in different folders next to each other. To generate a basic configuration that will be stored in the folder `build` use
A configuration can be generated using `meson.py setup [builddir] [options]`, where the only required argument is `[builddir]`. For example, to generate a basic configuration that will be stored in the folder `build`, use

```
./meson.py build
./meson.py setup build
```

You can have multiple configurations in different folders next to each other.

Options can be passed to the script to enable or disable different features of SU2. Below you find a list of project options and their default values:

| Option | Default value | Description |
|---| --- | --- |
| `-Denable-autodiff` | `false` | enable AD (reverse) support (needed for discrete adjoint solver) |
| `-Denable-directdiff` | `false` | enable AD (forward) support |
| `-Denable-pywrapper` | `false` | enable Python wrapper support|
| `-Dwith-mpi` | `auto` | Set dependency mode for MPI (`auto`,`enabled`,`disabled`) |
| `-Dwith-omp` | `false` | enable MPI+Threads support (experimental) |
| `-Denable-cgns` | `true` | enable CGNS support |
| `-Denable-cgns` | `true` | enable CGNS support |
| `-Denable-tecio` | `true` | enable TECIO support |
| `-Denable-mkl` | `false` | enable Intel MKL support |
| `-Denable-openblas` | `false` | enable OpenBLAS support |
Expand All @@ -139,20 +141,20 @@ Options can be passed to the script to enable or disable different features of S

For example to enable AD support pass the option to the `meson.py` script along with a value:
```
./meson.py build -Denable-autodiff=true
./meson.py setup build -Denable-autodiff=true
```
To set a installation directory for the binaries and python scripts, use the `--prefix` option, e.g.:

```
./meson.py build -Denable-autodiff=true --prefix=/home/username/SU2
./meson.py setup build -Denable-autodiff=true --prefix=/home/username/SU2
```
If you are not interested in setting custom compiler flags and other options you can now go directly to the [Compilation](#compilation) section, otherwise continue reading the next section.

### Advanced Configuration ###
In general meson appends flags set with the environment variable `CXXFLAGS`. It is however recommended to use
In general meson appends flags set with the environment variable `CXXFLAGS`. It is however recommended to use
mesons built-in options to set debug mode, warning levels and optimizations. All options can be found [here](https://mesonbuild.com/Builtin-options.html) or by using `./meson.py configure`. An already created configuration can be modified by using the `--reconfigure` flag, e.g.:
```
./meson.py build --reconfigure --buildtype=debug
./meson.py setup build --reconfigure --buildtype=debug
```
Note that it is only possible to change one option at once.

Expand Down Expand Up @@ -196,7 +198,7 @@ Profiling allows developers to identify inefficiencies in their code. SU2 can be
/path/to/binary/SU2_CFD config.cfg
```

After completion, a file called `gmon.out` is generated in your current working directory, indicating that the profiling was successful. In order to compile the analysis, run the command
After completion, a file called `gmon.out` is generated in your current working directory, indicating that the profiling was successful. In order to compile the analysis, run the command

```
gprof /path/to/binary/SU2_CFD > analysis.txt
Expand All @@ -206,7 +208,7 @@ Now the file `analysis.txt` contains the profiling analysis summary. For more ad

### Compilation ###

Finally to compile and install SU2 use
Finally to compile and install SU2 use
```
./ninja -C build install
```
Expand Down
4 changes: 2 additions & 2 deletions _docs_v7/Execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ Options:
* `-f FILE, --file=FILE` read config from FILE
* `-n PARTITIONS, --partitions=PARTITIONS` number of PARTITIONS
* `-s STEP, --step=STEP` finite difference STEP
* `-q QUIET, --quiet=QUIET` if True, output QUIET to log files
* `-q QUIET, --quiet=QUIET` if True, output QUIET to log files

### Shape Optimization Script (shape_optimization.py)

Expand All @@ -114,7 +114,7 @@ Options:

It is possible to call SU2 from python by importing it as a module. The first step is to compile SU2 with python wrapper support. For instance if your SU2 repository is in your home directory at *~/SU2*:

Usage: `$ ./meson.py build -Denable-pywrapper=true --prefix=~/SU2`
Usage: `$ ./meson.py setup build -Denable-pywrapper=true --prefix=~/SU2`

The python module will then be available in the installation folder *~/SU2/bin*. To make the SU2 python wrapper available from everywhere in the system, add the installation path to *PYTHONPATH*:

Expand Down
12 changes: 6 additions & 6 deletions _docs_v7/Running-Unit-Tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,19 +24,19 @@ In order to compile the unit tests, add the flag `-Denable-tests=true`
to your meson configure call. Then, you can build and run the tests by
calling `ninja test`.

## Running Tests
## Running Tests

There are three ways to run the main unit tests:

1. `meson test -C builddir`, where `builddir` is the build directory.
2. `ninja test -C builddir`, where `builddir` is the build directory.
1. `meson test -C [builddir]`, where `[builddir]` is the build directory.
2. `ninja test -C [builddir]`, where `[builddir]` is the build directory.
3. `./UnitTests/test_driver` from the SU2 build directory.

If you have run `ninja install`, then the `test_driver` executable will
also be located in the `bin` directory where you have installed SU2. The
first option will call ninja, which will then run the `test_driver`
executable. The second option will call the `test_driver` executable.
The last option, manually running the test driver, gives the most flexibility.
The last option, manually running the test driver, gives the most flexibility.
This help page will focus on the command-line options for that last option.

By default, Catch2 will only show the output from failing tests. To also
Expand All @@ -48,7 +48,7 @@ are actually three test drivers:
`test_driver`, `test_driver_AD`, and `test_driver_DD`. These test drivers
are built or run depending on the type of installation (e.g. direcdiff,
autodiff). For the most common use-case, you will not have a directdiff
or autodiff build and will only use `test_driver`. If you call
or autodiff build and will only use `test_driver`. If you call
`meson_test` or `ninja test`, the correct
drivers will run automatically. For more on tests using algorithmic
differentiation or direct differentiation, see the section "AD and
Expand Down Expand Up @@ -88,7 +88,7 @@ run:
```

To run tests matching a specific tag, write the tag name in square braces
as an argument for the test driver. For example, if I want to run the
as an argument for the test driver. For example, if I want to run the
tests with the tag "Dual Grid", I would run:

```
Expand Down
Loading