IndepthTutorial

An in-depth tutorial of Meson

In this tutorial we set up a project with multiple targets, unit tests and dependencies between targets. Our main product is a shared library called foo that is written in C++11. We are going to ignore the contents of the source files, as they are not really important from a build definition point of view.

The source tree contains three subdirectories src, include and test that contain, respectively, the source code, headers and unit tests of our project.

To start things up, here is the top level meson.build file.

project('c++ foolib', 'cpp')
add_global_arguments('-std=c++11', language : 'cpp')

inc = include_directories('include')
subdir('src')
subdir('test')

First we define the project's name and the programmin languages it uses (in this case only C++). Then we add a global compiler argument -std=c++11. This flag is used for all C++ source file compilations. It is not possible to unset it for some targets. The reason for this is that it is hard to keep track of what compiler flags are in use if global settings change per target.

Since include directory contains the header files, we need a way to tell compilations to add that directory to the compiler command line. This is done with the include_directories command that takes a directory and returns an object representing this directory. It is stored in variable inc which makes it accessible later on.

After this are two subdir commands. These instruct Meson to go to the specified subdirectory, open the meson.build file that's in there and execute it.

The Meson definition of src subdir is simple.

foolib = shared_library('foo', 'source1.cpp', 'source2.cpp',
                        include_directories : inc)

Here we just tell Meson to build the library with the given sources. We also tell it to use the include directories we stored to variable inc earlier. The result is stored in variable foolib just like the include directory was stored in the previous file.

Once Meson has processed the src subdir it returns one level up to the main Meson file and executes the next line that moves it into the test subdir. Its contents look like this.

testexe = executable('testexe', 'footest.cpp',
                     include_directories : inc,
                     link_with : foolib)
test('foolib test', testexe)

First we build a test executable that has the same include directory as the main library and which also links against the freshly built shared library. Then we define a test with the name foolib test. It consists of running the binary we just built. If the executable returns with a zero return value, it is considered passed. Other return values mark the test as failed.

With these three files we are done. To configure, build and run the test suite, we just need to execute the following commands (starting at source tree root directory).

mkdir build
cd build
meson ..
ninja
ninja test