| 1 |
# An in-depth tutorial |
| 2 |
|
| 3 |
In this tutorial we set up a project with multiple targets, unit tests |
| 4 |
and dependencies between targets. Our main product is a shared library |
| 5 |
called *foo* that is written in `C++11`. We are going to ignore the |
| 6 |
contents of the source files, as they are not really important from a |
| 7 |
build definition point of view. The library makes use of the `GLib` |
| 8 |
library so we need to detect and link it properly. We also make the |
| 9 |
resulting library installable. |
| 10 |
|
| 11 |
The source tree contains three subdirectories `src`, `include` and |
| 12 |
`test` that contain, respectively, the source code, headers and unit |
| 13 |
tests of our project. |
| 14 |
|
| 15 |
To start things up, here is the top level `meson.build` file. |
| 16 |
|
| 17 |
```meson |
| 18 |
project('c++ foolib', 'cpp', |
| 19 |
version : '1.0.0', |
| 20 |
license : 'MIT') |
| 21 |
add_global_arguments('-DSOME_TOKEN=value', language : 'cpp') |
| 22 |
glib_dep = dependency('glib-2.0') |
| 23 |
|
| 24 |
inc = include_directories('include') |
| 25 |
|
| 26 |
subdir('include') |
| 27 |
subdir('src') |
| 28 |
subdir('test') |
| 29 |
|
| 30 |
pkg_mod = import('pkgconfig') |
| 31 |
pkg_mod.generate(libraries : foolib, |
| 32 |
version : '1.0', |
| 33 |
name : 'libfoobar', |
| 34 |
filebase : 'foobar', |
| 35 |
description : 'A Library to barnicate your foos.') |
| 36 |
``` |
| 37 |
|
| 38 |
The definition always starts with a call to the `project` function. In |
| 39 |
it you must specify the project's name and programming languages to |
| 40 |
use, in this case only `C++`. We also specify two additional |
| 41 |
arguments, the project's version and the license it is under. Our |
| 42 |
project is version `1.0.0` and is specified to be under the MIT |
| 43 |
license. |
| 44 |
|
| 45 |
Then we find GLib, which is an *external dependency*. The `dependency` |
| 46 |
function tells Meson to find the library (by default using |
| 47 |
`pkg-config`). If the library is not found, Meson will raise an error |
| 48 |
and stop processing the build definition. |
| 49 |
|
| 50 |
Then we add a global compiler argument `-DSOME_TOKEN=value`. This flag |
| 51 |
is used for *all* C++ source file compilations. It is not possible to |
| 52 |
unset it for some targets. The reason for this is that it is hard to |
| 53 |
keep track of what compiler flags are in use if global settings change |
| 54 |
per target. |
| 55 |
|
| 56 |
Since `include` directory contains the header files, we need a way to |
| 57 |
tell compilations to add that directory to the compiler command line. |
| 58 |
This is done with the `include_directories` command that takes a |
| 59 |
directory and returns an object representing this directory. It is |
| 60 |
stored in variable `inc` which makes it accessible later on. |
| 61 |
|
| 62 |
After this are three `subdir` commands. These instruct Meson to go to |
| 63 |
the specified subdirectory, open the `meson.build` file that's in |
| 64 |
there and execute it. The last few lines are a stanza to generate a |
| 65 |
`pkg-config` file. We'll skip that for now and come back to it at the |
| 66 |
end of this document. |
| 67 |
|
| 68 |
The first subdirectory we go into is `include`. In it we have a |
| 69 |
header file for the library that we want to install. This requires one |
| 70 |
line. |
| 71 |
|
| 72 |
```meson |
| 73 |
install_headers('foolib.h') |
| 74 |
``` |
| 75 |
|
| 76 |
This installs the given header file to the system's header directory. |
| 77 |
This is by default `/[install prefix]/include`, but it can be changed |
| 78 |
with a command line argument. |
| 79 |
|
| 80 |
The Meson definition of `src` subdir is simple. |
| 81 |
|
| 82 |
```meson |
| 83 |
foo_sources = ['source1.cpp', 'source2.cpp'] |
| 84 |
foolib = shared_library('foo', |
| 85 |
foo_sources, |
| 86 |
include_directories : inc, |
| 87 |
dependencies : glib_dep, |
| 88 |
install : true) |
| 89 |
``` |
| 90 |
|
| 91 |
Here we just tell Meson to build the library with the given sources. |
| 92 |
We also tell it to use the include directories we stored to variable |
| 93 |
`inc` earlier. Since this library uses GLib, we tell Meson to add all |
| 94 |
necessary compiler and linker flags with the `dependencies` keyword |
| 95 |
argument. Its value is `glib_dep` which we set at the top level |
| 96 |
`meson.build` file. The `install` argument tells Meson to install the |
| 97 |
result. As with the headers, the shared library is installed to the |
| 98 |
system's default location (usually `/[install prefix]/lib`) but is |
| 99 |
again overridable. |
| 100 |
|
| 101 |
The resulting library is stored in variable `foolib` just like the |
| 102 |
include directory was stored in the previous file. |
| 103 |
|
| 104 |
Once Meson has processed the `src` subdir it returns to the main Meson |
| 105 |
file and executes the next line that moves it into the `test` subdir. |
| 106 |
Its contents look like this. |
| 107 |
|
| 108 |
```meson |
| 109 |
testexe = executable('testexe', 'footest.cpp', |
| 110 |
include_directories : inc, |
| 111 |
link_with : foolib) |
| 112 |
test('foolib test', testexe) |
| 113 |
``` |
| 114 |
|
| 115 |
First we build a test executable that has the same include directory |
| 116 |
as the main library and which also links against the freshly built |
| 117 |
shared library. Note that you don't need to specify `glib_dep` here |
| 118 |
just to be able to use the built library `foolib`. If the executable |
| 119 |
used GLib functionality itself, then we would of course need to add it |
| 120 |
as a keyword argument here. |
| 121 |
|
| 122 |
Finally we define a test with the name `foolib test`. It consists of |
| 123 |
running the binary we just built. If the executable exits with a zero |
| 124 |
return value, the test is considered passed. Nonzero return values |
| 125 |
mark the test as failed. |
| 126 |
|
| 127 |
At this point we can return to the pkg-config generator line. All |
| 128 |
shared libraries should provide a pkg-config file, which explains how |
| 129 |
that library is used. Meson provides this simple generator that should |
| 130 |
be sufficient for most simple projects. All you need to do is list a |
| 131 |
few basic pieces of information and Meson takes care of generating an |
| 132 |
appropriate file. More advanced users might want to create their own |
| 133 |
pkg-config files using Meson's [configuration file generator |
| 134 |
system](Configuration.md). |
| 135 |
|
| 136 |
With these four files we are done. To configure, build and run the |
| 137 |
test suite, we just need to execute the following commands (starting |
| 138 |
at source tree root directory). |
| 139 |
|
| 140 |
```console |
| 141 |
$ meson setup builddir && cd builddir |
| 142 |
$ meson compile |
| 143 |
$ meson test |
| 144 |
``` |
| 145 |
|
| 146 |
To then install the project you only need one command. |
| 147 |
|
| 148 |
```console |
| 149 |
$ meson install |
| 150 |
``` |