| 1 |
--- |
| 2 |
title: FAQ |
| 3 |
... |
| 4 |
# Meson Frequently Asked Questions |
| 5 |
|
| 6 |
See also [How do I do X in Meson](howtox.md). |
| 7 |
|
| 8 |
## Why is it called Meson? |
| 9 |
|
| 10 |
When the name was originally chosen, there were two main limitations: |
| 11 |
there must not exist either a Debian package or a Sourceforge project |
| 12 |
of the given name. This ruled out tens of potential project names. At |
| 13 |
some point the name Gluon was considered. Gluons are elementary |
| 14 |
particles that hold protons and neutrons together, much like a build |
| 15 |
system's job is to take pieces of source code and a compiler and bind |
| 16 |
them to a complete whole. |
| 17 |
|
| 18 |
Unfortunately this name was taken, too. Then the rest of subatomic |
| 19 |
particles were examined and Meson was found to be available. |
| 20 |
|
| 21 |
## What is the correct way to use threads (such as pthreads)? |
| 22 |
|
| 23 |
```meson |
| 24 |
thread_dep = dependency('threads') |
| 25 |
``` |
| 26 |
|
| 27 |
This will set up everything on your behalf. People coming from |
| 28 |
Autotools or CMake want to do this by looking for `libpthread.so` |
| 29 |
manually. Don't do that, it has tricky corner cases especially when |
| 30 |
cross compiling. |
| 31 |
|
| 32 |
## How to use Meson on a host where it is not available in system packages? |
| 33 |
|
| 34 |
Starting from version 0.29.0, Meson is available from the [Python |
| 35 |
Package Index](https://pypi.python.org/pypi/meson/), so installing it |
| 36 |
simply a matter of running this command: |
| 37 |
|
| 38 |
```console |
| 39 |
$ pip3 install <your options here> meson |
| 40 |
``` |
| 41 |
|
| 42 |
If you don't have access to PyPI, that is not a problem either. Meson |
| 43 |
has been designed to be easily runnable from an extracted source |
| 44 |
tarball or even a git checkout. First you need to download Meson. Then |
| 45 |
use this command to set up you build instead of plain `meson`. |
| 46 |
|
| 47 |
```console |
| 48 |
$ /path/to/meson.py <options> |
| 49 |
``` |
| 50 |
|
| 51 |
After this you don't have to care about invoking Meson any more. It |
| 52 |
remembers where it was originally invoked from and calls itself |
| 53 |
appropriately. As a user the only thing you need to do is to `cd` into |
| 54 |
your build directory and invoke `meson compile`. |
| 55 |
|
| 56 |
## Why can't I specify target files with a wildcard? |
| 57 |
|
| 58 |
Instead of specifying files explicitly, people seem to want to do this: |
| 59 |
|
| 60 |
```meson |
| 61 |
executable('myprog', sources : '*.cpp') # This does NOT work! |
| 62 |
``` |
| 63 |
|
| 64 |
Meson does not support this syntax and the reason for this is simple. |
| 65 |
This cannot be made both reliable and fast. By reliable we mean that |
| 66 |
if the user adds a new source file to the subdirectory, Meson should |
| 67 |
detect that and make it part of the build automatically. |
| 68 |
|
| 69 |
One of the main requirements of Meson is that it must be fast. This |
| 70 |
means that a no-op build in a tree of 10 000 source files must take no |
| 71 |
more than a fraction of a second. This is only possible because Meson |
| 72 |
knows the exact list of files to check. If any target is specified as |
| 73 |
a wildcard glob, this is no longer possible. Meson would need to |
| 74 |
re-evaluate the glob every time and compare the list of files produced |
| 75 |
against the previous list. This means inspecting the entire source |
| 76 |
tree (because the glob pattern could be `src/\*/\*/\*/\*.cpp` or |
| 77 |
something like that). This is impossible to do efficiently. |
| 78 |
|
| 79 |
The main backend of Meson is Ninja, which does not support wildcard |
| 80 |
matches either, and for the same reasons. |
| 81 |
|
| 82 |
Because of this, all source files must be specified explicitly. |
| 83 |
|
| 84 |
## But I really want to use wildcards! |
| 85 |
|
| 86 |
If the tradeoff between reliability and convenience is acceptable to |
| 87 |
you, then Meson gives you all the tools necessary to do wildcard |
| 88 |
globbing. You are allowed to run arbitrary commands during |
| 89 |
configuration. First you need to write a script that locates the files |
| 90 |
to compile. Here's a simple shell script that writes all `.c` files in |
| 91 |
the current directory, one per line. |
| 92 |
|
| 93 |
|
| 94 |
```bash |
| 95 |
#!/bin/sh |
| 96 |
|
| 97 |
for i in *.c; do |
| 98 |
echo $i |
| 99 |
done |
| 100 |
``` |
| 101 |
|
| 102 |
Then you need to run this script in your Meson file, convert the |
| 103 |
output into a string array and use the result in a target. |
| 104 |
|
| 105 |
```meson |
| 106 |
c = run_command('grabber.sh', check: true) |
| 107 |
sources = c.stdout().strip().split('\n') |
| 108 |
e = executable('prog', sources) |
| 109 |
``` |
| 110 |
|
| 111 |
The script can be any executable, so it can be written in shell, |
| 112 |
Python, Lua, Perl or whatever you wish. |
| 113 |
|
| 114 |
As mentioned above, the tradeoff is that just adding new files to the |
| 115 |
source directory does *not* add them to the build automatically. To |
| 116 |
add them you need to tell Meson to reinitialize itself. The simplest |
| 117 |
way is to touch the `meson.build` file in your source root. Then Meson |
| 118 |
will reconfigure itself next time the build command is run. Advanced |
| 119 |
users can even write a small background script that utilizes a |
| 120 |
filesystem event queue, such as |
| 121 |
[inotify](https://en.wikipedia.org/wiki/Inotify), to do this |
| 122 |
automatically. |
| 123 |
|
| 124 |
## Should I use `subdir` or `subproject`? |
| 125 |
|
| 126 |
The answer is almost always `subdir`. Subproject exists for a very |
| 127 |
specific use case: embedding external dependencies into your build |
| 128 |
process. As an example, suppose we are writing a game and wish to use |
| 129 |
SDL. Let us further suppose that SDL comes with a Meson build |
| 130 |
definition. Let us suppose even further that we don't want to use |
| 131 |
prebuilt binaries but want to compile SDL for ourselves. |
| 132 |
|
| 133 |
In this case you would use `subproject`. The way to do it would be to |
| 134 |
grab the source code of SDL and put it inside your own source |
| 135 |
tree. Then you would do `sdl = subproject('sdl')`, which would cause |
| 136 |
Meson to build SDL as part of your build and would then allow you to |
| 137 |
link against it or do whatever else you may prefer. |
| 138 |
|
| 139 |
For every other use you would use `subdir`. As an example, if you |
| 140 |
wanted to build a shared library in one dir and link tests against it |
| 141 |
in another dir, you would do something like this: |
| 142 |
|
| 143 |
```meson |
| 144 |
project('simple', 'c') |
| 145 |
subdir('src') # library is built here |
| 146 |
subdir('tests') # test binaries would link against the library here |
| 147 |
``` |
| 148 |
|
| 149 |
## Why is there not a Make backend? |
| 150 |
|
| 151 |
Because Make is slow. This is not an implementation issue, Make simply |
| 152 |
cannot be made fast. For further info we recommend you read [this |
| 153 |
post](http://neugierig.org/software/chromium/notes/2011/02/ninja.html) |
| 154 |
by Evan Martin, the author of Ninja. Makefiles also have a syntax that |
| 155 |
is very unpleasant to write which makes them a big maintenance burden. |
| 156 |
|
| 157 |
The only reason why one would use Make instead of Ninja is working on |
| 158 |
a platform that does not have a Ninja port. Even in this case it is an |
| 159 |
order of magnitude less work to port Ninja than it is to write a Make |
| 160 |
backend for Meson. |
| 161 |
|
| 162 |
Just use Ninja, you'll be happier that way. I guarantee it. |
| 163 |
|
| 164 |
## Why is Meson not just a Python module so I could code my build setup in Python? |
| 165 |
|
| 166 |
A related question to this is *Why is Meson's configuration language |
| 167 |
not Turing-complete?* |
| 168 |
|
| 169 |
There are many good reasons for this, most of which are summarized on |
| 170 |
this web page: [Against The Use Of Programming Languages in |
| 171 |
Configuration Files](https://taint.org/2011/02/18/001527a.html). |
| 172 |
|
| 173 |
In addition to those reasons, not exposing Python or any other "real" |
| 174 |
programming language makes it possible to port Meson's implementation |
| 175 |
to a different language. This might become necessary if, for example, |
| 176 |
Python turns out to be a performance bottleneck. This is an actual |
| 177 |
problem that has caused complications for GNU Autotools and SCons. |
| 178 |
|
| 179 |
## How do I do the equivalent of Libtools export-symbol and export-regex? |
| 180 |
|
| 181 |
Either by using [GCC symbol |
| 182 |
visibility](https://gcc.gnu.org/wiki/Visibility) or by writing a |
| 183 |
[linker |
| 184 |
script](https://sourceware.org/binutils/docs/ld.html). This |
| 185 |
has the added benefit that your symbol definitions are in a standalone |
| 186 |
file instead of being buried inside your build definitions. An example |
| 187 |
can be found |
| 188 |
[here](https://github.com/jpakkane/meson/tree/master/test%20cases/linuxlike/3%20linker%20script). |
| 189 |
|
| 190 |
## My project works fine on Linux and MinGW but fails to link with MSVC due to a missing .lib file (fatal error LNK1181). Why? |
| 191 |
|
| 192 |
With GCC, all symbols on shared libraries are exported automatically |
| 193 |
unless you specify otherwise. With MSVC no symbols are exported by |
| 194 |
default. If your shared library exports no symbols, MSVC will silently |
| 195 |
not produce an import library file leading to failures. The solution |
| 196 |
is to add symbol visibility definitions [as specified in GCC |
| 197 |
wiki](https://gcc.gnu.org/wiki/Visibility). |
| 198 |
|
| 199 |
## I added some compiler flags and now the build fails with weird errors. What is happening? |
| 200 |
|
| 201 |
You probably did the equivalent to this: |
| 202 |
|
| 203 |
```meson |
| 204 |
executable('foobar', ... |
| 205 |
c_args : '-some_arg -other_arg') |
| 206 |
``` |
| 207 |
|
| 208 |
Meson is *explicit*. In this particular case it will **not** |
| 209 |
automatically split your strings at whitespaces, instead it will take |
| 210 |
it as is and work extra hard to pass it to the compiler unchanged, |
| 211 |
including quoting it properly over shell invocations. This is |
| 212 |
mandatory to make e.g. files with spaces in them work flawlessly. To |
| 213 |
pass multiple command line arguments, you need to explicitly put them |
| 214 |
in an array like this: |
| 215 |
|
| 216 |
```meson |
| 217 |
executable('foobar', ... |
| 218 |
c_args : ['-some_arg', '-other_arg']) |
| 219 |
``` |
| 220 |
|
| 221 |
## Why are changes to default project options ignored? |
| 222 |
|
| 223 |
You probably had a project that looked something like this: |
| 224 |
|
| 225 |
```meson |
| 226 |
project('foobar', 'cpp') |
| 227 |
``` |
| 228 |
|
| 229 |
This defaults to `c++11` on GCC compilers. Suppose you want to use |
| 230 |
`c++14` instead, so you change the definition to this: |
| 231 |
|
| 232 |
```meson |
| 233 |
project('foobar', 'cpp', default_options : ['cpp_std=c++14']) |
| 234 |
``` |
| 235 |
|
| 236 |
But when you recompile, it still uses `c++11`. The reason for this is |
| 237 |
that default options are only looked at when you are setting up a |
| 238 |
build directory for the very first time. After that the setting is |
| 239 |
considered to have a value and thus the default value is ignored. To |
| 240 |
change an existing build dir to `c++14`, either reconfigure your build |
| 241 |
dir with `meson configure` or delete the build dir and recreate it |
| 242 |
from scratch. |
| 243 |
|
| 244 |
The reason we don't automatically change the option value when the |
| 245 |
default is changed is that it is impossible to know to do that |
| 246 |
reliably. The actual question that we need to solve is "if the |
| 247 |
option's value is foo and the default value is bar, should we change |
| 248 |
the option value to bar also". There are many choices: |
| 249 |
|
| 250 |
- if the user has changed the value themselves from the default, then |
| 251 |
we must not change it back |
| 252 |
|
| 253 |
- if the user has not changed the value, but changes the default |
| 254 |
value, then this section's premise would seem to indicate that the |
| 255 |
value should be changed |
| 256 |
|
| 257 |
- suppose the user changes the value from the default to foo, then |
| 258 |
back to bar and then changes the default value to bar, the correct |
| 259 |
step to take is ambiguous by itself |
| 260 |
|
| 261 |
In order to solve the latter question we would need to remember not |
| 262 |
only the current and old value, but also all the times the user has |
| 263 |
changed the value and from which value to which other value. Since |
| 264 |
people don't remember their own actions that far back, toggling |
| 265 |
between states based on long history would be confusing. |
| 266 |
|
| 267 |
Because of this we do the simple and understandable thing: default |
| 268 |
values are only defaults and will never affect the value of an option |
| 269 |
once set. |
| 270 |
|
| 271 |
## Does wrap download sources behind my back? |
| 272 |
|
| 273 |
It does not. In order for Meson to download anything from the net |
| 274 |
while building, two conditions must be met. |
| 275 |
|
| 276 |
First of all there needs to be a `.wrap` file with a download URL in |
| 277 |
the `subprojects` directory. If one does not exist, Meson will not |
| 278 |
download anything. |
| 279 |
|
| 280 |
The second requirement is that there needs to be an explicit |
| 281 |
subproject invocation in your `meson.build` files. Either |
| 282 |
`subproject('foobar')` or `dependency('foobar', fallback : ['foobar', |
| 283 |
'foo_dep'])`. If these declarations either are not in any build file |
| 284 |
or they are not called (due to e.g. `if/else`) then nothing is |
| 285 |
downloaded. |
| 286 |
|
| 287 |
If this is not sufficient for you, starting from release 0.40.0 Meson |
| 288 |
has a option called `wrap-mode` which can be used to disable wrap |
| 289 |
downloads altogether with `--wrap-mode=nodownload`. You can also |
| 290 |
disable dependency fallbacks altogether with `--wrap-mode=nofallback`, |
| 291 |
which also implies the `nodownload` option. |
| 292 |
|
| 293 |
If on the other hand, you want Meson to always use the fallback |
| 294 |
for dependencies, even when an external dependency exists and could |
| 295 |
satisfy the version requirements, for example in order to make |
| 296 |
sure your project builds when fallbacks are used, you can use |
| 297 |
`--wrap-mode=forcefallback` since 0.46.0. |
| 298 |
|
| 299 |
## Why is Meson implemented in Python rather than [programming language X]? |
| 300 |
|
| 301 |
Because build systems are special in ways normal applications aren't. |
| 302 |
|
| 303 |
Perhaps the biggest limitation is that because Meson is used to build |
| 304 |
software at the very lowest levels of the OS, it is part of the core |
| 305 |
bootstrap for new systems. Whenever support for a new CPU architecture |
| 306 |
is added, Meson must run on the system before software using it can be |
| 307 |
compiled natively. This requirement adds two hard limitations. |
| 308 |
|
| 309 |
The first one is that Meson must have the minimal amount of |
| 310 |
dependencies, because they must all be built during the bootstrap to |
| 311 |
get Meson to work. |
| 312 |
|
| 313 |
The second is that Meson must support all CPU architectures, both |
| 314 |
existing and future ones. As an example many new programming languages |
| 315 |
have only an LLVM based compiler available. LLVM has limited CPU |
| 316 |
support compared to, say, GCC, and thus bootstrapping Meson on such |
| 317 |
platforms would first require adding new processor support to |
| 318 |
LLVM. This is in most cases unfeasible. |
| 319 |
|
| 320 |
A further limitation is that we want developers on as many platforms |
| 321 |
as possible to submit to Meson development using the default tools |
| 322 |
provided by their operating system. In practice what this means is |
| 323 |
that Windows developers should be able to contribute using nothing but |
| 324 |
Visual Studio. |
| 325 |
|
| 326 |
At the time of writing (April 2018) there are only three languages |
| 327 |
that could fulfill these requirements: |
| 328 |
|
| 329 |
- C |
| 330 |
- C++ |
| 331 |
- Python |
| 332 |
|
| 333 |
Out of these we have chosen Python because it is the best fit for our |
| 334 |
needs. |
| 335 |
|
| 336 |
## But I really want a version of Meson that doesn't use python! |
| 337 |
|
| 338 |
Ecosystem diversity is good. We encourage interested users to write this |
| 339 |
competing implementation of Meson themselves. As of September 2021, there are 3 |
| 340 |
projects attempting to do just this: |
| 341 |
|
| 342 |
- [muon](https://git.sr.ht/~lattis/muon) |
| 343 |
- [Meson++](https://github.com/dcbaker/meson-plus-plus) |
| 344 |
- [boson](https://git.sr.ht/~bl4ckb0ne/boson) |
| 345 |
|
| 346 |
## I have proprietary compiler toolchain X that does not work with Meson, how can I make it work? |
| 347 |
|
| 348 |
Meson needs to know several details about each compiler in order to |
| 349 |
compile code with it. These include things such as which compiler |
| 350 |
flags to use for each option and how to detect the compiler from its |
| 351 |
output. This information cannot be input via a configuration file, |
| 352 |
instead it requires changes to Meson's source code that need to be |
| 353 |
submitted to Meson master repository. In theory you can run your own |
| 354 |
forked version with custom patches, but that's not good use of your |
| 355 |
time. Please submit the code upstream so everyone can use the |
| 356 |
toolchain. |
| 357 |
|
| 358 |
The steps for adding a new compiler for an existing language are |
| 359 |
roughly the following. For simplicity we're going to assume a C |
| 360 |
compiler. |
| 361 |
|
| 362 |
- Create a new class with a proper name in |
| 363 |
`mesonbuild/compilers/c.py`. Look at the methods that other |
| 364 |
compilers for the same language have and duplicate what they do. |
| 365 |
|
| 366 |
- If the compiler can only be used for cross compilation, make sure to |
| 367 |
flag it as such (see existing compiler classes for examples). |
| 368 |
|
| 369 |
- Add detection logic to `mesonbuild/environment.py`, look for a |
| 370 |
method called `detect_c_compiler`. |
| 371 |
|
| 372 |
- Run the test suite and fix issues until the tests pass. |
| 373 |
|
| 374 |
- Submit a pull request, add the result of the test suite to your MR |
| 375 |
(linking an existing page is fine). |
| 376 |
|
| 377 |
- If the compiler is freely available, consider adding it to the CI |
| 378 |
system. |
| 379 |
|
| 380 |
## Why does building my project with MSVC output static libraries called `libfoo.a`? |
| 381 |
|
| 382 |
The naming convention for static libraries on Windows is usually |
| 383 |
`foo.lib`. Unfortunately, import libraries are also called `foo.lib`. |
| 384 |
|
| 385 |
This causes filename collisions with the default library type where we |
| 386 |
build both shared and static libraries, and also causes collisions |
| 387 |
during installation since all libraries are installed to the same |
| 388 |
directory by default. |
| 389 |
|
| 390 |
To resolve this, we decided to default to creating static libraries of |
| 391 |
the form `libfoo.a` when building with MSVC. This has the following |
| 392 |
advantages: |
| 393 |
|
| 394 |
1. Filename collisions are completely avoided. |
| 395 |
1. The format for MSVC static libraries is `ar`, which is the same as the GNU |
| 396 |
static library format, so using this extension is semantically correct. |
| 397 |
1. The static library filename format is now the same on all platforms and with |
| 398 |
all toolchains. |
| 399 |
1. Both Clang and GNU compilers can search for `libfoo.a` when specifying |
| 400 |
a library as `-lfoo`. This does not work for alternative naming schemes for |
| 401 |
static libraries such as `libfoo.lib`. |
| 402 |
1. Since `-lfoo` works out of the box, pkgconfig files will work correctly for |
| 403 |
projects built with both MSVC, GCC, and Clang on Windows. |
| 404 |
1. MSVC does not have arguments to search for library filenames, and [it does |
| 405 |
not care what the extension is](https://docs.microsoft.com/en-us/cpp/build/reference/link-input-files?view=vs-2019), |
| 406 |
so specifying `libfoo.a` instead of `foo.lib` does not change the workflow, |
| 407 |
and is an improvement since it's less ambiguous. |
| 408 |
1. Projects built with the MinGW compiler are fully compatible with |
| 409 |
MSVC as long as they use the same CRT (e.g. UCRT with MSYS2). |
| 410 |
These projects also name their static libraries `libfoo.a`. |
| 411 |
|
| 412 |
If, for some reason, you really need your project to output static |
| 413 |
libraries of the form `foo.lib` when building with MSVC, you can set |
| 414 |
the |
| 415 |
[`name_prefix:`](https://mesonbuild.com/Reference-manual.html#library) |
| 416 |
kwarg to `''` and the |
| 417 |
[`name_suffix:`](https://mesonbuild.com/Reference-manual.html#library) |
| 418 |
kwarg to `'lib'`. To get the default behaviour for each, you can |
| 419 |
either not specify the kwarg, or pass `[]` (an empty array) to it. |
| 420 |
|
| 421 |
## Do I need to add my headers to the sources list like in Autotools? |
| 422 |
|
| 423 |
Autotools requires you to add private and public headers to the sources list so |
| 424 |
that it knows what files to include in the tarball generated by `make dist`. |
| 425 |
Meson's `dist` command simply gathers everything committed to your git/hg |
| 426 |
repository and adds it to the tarball, so adding headers to the sources list is |
| 427 |
pointless. |
| 428 |
|
| 429 |
Meson uses Ninja which uses compiler dependency information to automatically |
| 430 |
figure out dependencies between C sources and headers, so it will rebuild |
| 431 |
things correctly when a header changes. |
| 432 |
|
| 433 |
The only exception to this are generated headers, for which you must [declare |
| 434 |
dependencies correctly](#how-do-i-tell-meson-that-my-sources-use-generated-headers). |
| 435 |
|
| 436 |
If, for whatever reason, you do add non-generated headers to the sources list |
| 437 |
of a target, Meson will simply ignore them. |
| 438 |
|
| 439 |
## How do I tell Meson that my sources use generated headers? |
| 440 |
|
| 441 |
Let's say you use a [`custom_target()`](https://mesonbuild.com/Reference-manual.html#custom_target) |
| 442 |
to generate the headers, and then `#include` them in your C code. Here's how |
| 443 |
you ensure that Meson generates the headers before trying to compile any |
| 444 |
sources in the build target: |
| 445 |
|
| 446 |
```meson |
| 447 |
libfoo_gen_headers = custom_target('gen-headers', ..., output: 'foo-gen.h') |
| 448 |
libfoo_sources = files('foo-utils.c', 'foo-lib.c') |
| 449 |
# Add generated headers to the list of sources for the build target |
| 450 |
libfoo = library('foo', sources: [libfoo_sources + libfoo_gen_headers]) |
| 451 |
``` |
| 452 |
|
| 453 |
Now let's say you have a new target that links to `libfoo`: |
| 454 |
|
| 455 |
```meson |
| 456 |
libbar_sources = files('bar-lib.c') |
| 457 |
libbar = library('bar', sources: libbar_sources, link_with: libfoo) |
| 458 |
``` |
| 459 |
|
| 460 |
This adds a **link-time** dependency between the two targets, but note that the |
| 461 |
sources of the targets have **no compile-time** dependencies and can be built |
| 462 |
in any order; which improves parallelism and speeds up builds. |
| 463 |
|
| 464 |
If the sources in `libbar` *also* use `foo-gen.h`, that's a *compile-time* |
| 465 |
dependency, and you'll have to add `libfoo_gen_headers` to `sources:` for |
| 466 |
`libbar` too: |
| 467 |
|
| 468 |
```meson |
| 469 |
libbar_sources = files('bar-lib.c') |
| 470 |
libbar = library('bar', sources: libbar_sources + libfoo_gen_headers, link_with: libfoo) |
| 471 |
``` |
| 472 |
|
| 473 |
Alternatively, if you have multiple libraries with sources that link to |
| 474 |
a library and also use its generated headers, this code is equivalent to above: |
| 475 |
|
| 476 |
```meson |
| 477 |
# Add generated headers to the list of sources for the build target |
| 478 |
libfoo = library('foo', sources: libfoo_sources + libfoo_gen_headers) |
| 479 |
|
| 480 |
# Declare a dependency that will add the generated headers to sources |
| 481 |
libfoo_dep = declare_dependency(link_with: libfoo, sources: libfoo_gen_headers) |
| 482 |
|
| 483 |
... |
| 484 |
|
| 485 |
libbar = library('bar', sources: libbar_sources, dependencies: libfoo_dep) |
| 486 |
``` |
| 487 |
|
| 488 |
**Note:** You should only add *headers* to `sources:` while declaring |
| 489 |
a dependency. If your custom target outputs both sources and headers, you can |
| 490 |
use the subscript notation to get only the header(s): |
| 491 |
|
| 492 |
```meson |
| 493 |
libfoo_gen_sources = custom_target('gen-headers', ..., output: ['foo-gen.h', 'foo-gen.c']) |
| 494 |
libfoo_gen_headers = libfoo_gen_sources[0] |
| 495 |
|
| 496 |
# Add static and generated sources to the target |
| 497 |
libfoo = library('foo', sources: libfoo_sources + libfoo_gen_sources) |
| 498 |
|
| 499 |
# Declare a dependency that will add the generated *headers* to sources |
| 500 |
libfoo_dep = declare_dependency(link_with: libfoo, sources: libfoo_gen_headers) |
| 501 |
... |
| 502 |
libbar = library('bar', sources: libbar_sources, dependencies: libfoo_dep) |
| 503 |
``` |
| 504 |
|
| 505 |
A good example of a generator that outputs both sources and headers is |
| 506 |
[`gnome.mkenums()`](https://mesonbuild.com/Gnome-module.html#gnomemkenums). |
| 507 |
|
| 508 |
## How do I disable exceptions and RTTI in my C++ project? |
| 509 |
|
| 510 |
With the `cpp_eh` and `cpp_rtti` options. A typical invocation would |
| 511 |
look like this: |
| 512 |
|
| 513 |
``` |
| 514 |
meson -Dcpp_eh=none -Dcpp_rtti=false <other options> |
| 515 |
``` |
| 516 |
|
| 517 |
The RTTI option is only available since Meson version 0.53.0. |
| 518 |
|
| 519 |
## Should I check for `buildtype` or individual options like `debug` in my build files? |
| 520 |
|
| 521 |
This depends highly on what you actually need to happen. The |
| 522 |
´buildtype` option is meant do describe the current build's |
| 523 |
_intent_. That is, what it will be used for. Individual options are |
| 524 |
for determining what the exact state is. This becomes clearer with a |
| 525 |
few examples. |
| 526 |
|
| 527 |
Suppose you have a source file that is known to miscompile when using |
| 528 |
`-O3` and requires a workaround. Then you'd write something like this: |
| 529 |
|
| 530 |
```meson |
| 531 |
if get_option('optimization') == '3' |
| 532 |
add_project_arguments('-DOPTIMIZATION_WORKAROUND', ...) |
| 533 |
endif |
| 534 |
``` |
| 535 |
|
| 536 |
On the other hand if your project has extra logging and sanity checks |
| 537 |
that you would like to be enabled during the day to day development |
| 538 |
work (which uses the `debug` buildtype), you'd do this instead: |
| 539 |
|
| 540 |
```meson |
| 541 |
if get_option('buildtype') == 'debug' |
| 542 |
add_project_arguments('-DENABLE_EXTRA_CHECKS', ...) |
| 543 |
endif |
| 544 |
``` |
| 545 |
|
| 546 |
In this way the extra options are automatically used during |
| 547 |
development but are not compiled in release builds. Note that (since |
| 548 |
Meson 0.57.0) you can set optimization to, say, 2 in your debug builds |
| 549 |
if you want to. If you tried to set this flag based on optimization |
| 550 |
level, it would fail in this case. |
| 551 |
|
| 552 |
## How do I use a library before declaring it? |
| 553 |
|
| 554 |
This is valid (and good) code: |
| 555 |
``` |
| 556 |
libA = library('libA', 'fileA.cpp', link_with : []) |
| 557 |
libB = library('libB', 'fileB.cpp', link_with : [libA]) |
| 558 |
``` |
| 559 |
But there is currently no way to get something like this to work: |
| 560 |
``` |
| 561 |
libB = library('libB', 'fileB.cpp', link_with : [libA]) |
| 562 |
libA = library('libA', 'fileA.cpp', link_with : []) |
| 563 |
``` |
| 564 |
This means that you HAVE to write your `library(...)` calls in the order that the |
| 565 |
dependencies flow. While ideas to make arbitrary orders possible exist, they were |
| 566 |
rejected because reordering the `library(...)` calls was considered the "proper" |
| 567 |
way. See [here](https://github.com/mesonbuild/meson/issues/8178) for the discussion. |
| 568 |
|
| 569 |
## Why doesn't meson have user defined functions/macros? |
| 570 |
|
| 571 |
The tl;dr answer to this is that meson's design is focused on solving specific |
| 572 |
problems rather than providing a general purpose language to write complex |
| 573 |
code solutions in build files. Build systems should be quick to write and |
| 574 |
quick to understand, functions muddle this simplicity. |
| 575 |
|
| 576 |
The long answer is twofold: |
| 577 |
|
| 578 |
First, Meson aims to provide a rich set of tools that solve specific problems |
| 579 |
simply out of the box. This is similar to the "batteries included" mentality of |
| 580 |
Python. By providing tools that solve common problems in the simplest way |
| 581 |
possible *in* Meson we are solving that problem for everyone instead of forcing |
| 582 |
everyone to solve that problem for themselves over and over again, often |
| 583 |
badly. One example of this are Meson's dependency wrappers around various |
| 584 |
config-tool executables (sdl-config, llvm-config, etc). In other build |
| 585 |
systems each user of that dependency writes a wrapper and deals with the |
| 586 |
corner cases (or doesn't, as is often the case), in Meson we handle them |
| 587 |
internally, everyone gets fixes and the corner cases are ironed out for |
| 588 |
*everyone*. Providing user defined functions or macros goes directly against |
| 589 |
this design goal. |
| 590 |
|
| 591 |
Second, functions and macros makes the build system more difficult to reason |
| 592 |
about. When you encounter some function call, you can refer to the reference |
| 593 |
manual to see that function and its signature. Instead of spending |
| 594 |
frustrating hours trying to interpret some bit of m4 or follow long include |
| 595 |
paths to figure out what `function1` (which calls `function2`, which calls |
| 596 |
`function3`, ad infinitum), you know what the build system is doing. Unless |
| 597 |
you're actively developing Meson itself, it's just a tool to orchestrate |
| 598 |
building the thing you actually care about. We want you to spend as little |
| 599 |
time worrying about build systems as possible so you can spend more time on |
| 600 |
*your code*. |
| 601 |
|
| 602 |
Many times user defined functions are used due to a lack of loops or |
| 603 |
because loops are tedious to use in the language. Meson has both arrays/lists |
| 604 |
and hashes/dicts natively. Compare the following pseudo code: |
| 605 |
|
| 606 |
```meson |
| 607 |
func(name, sources, extra_args) |
| 608 |
executable( |
| 609 |
name, |
| 610 |
sources, |
| 611 |
c_args : extra_args |
| 612 |
) |
| 613 |
endfunc |
| 614 |
|
| 615 |
func(exe1, ['1.c', 'common.c'], []) |
| 616 |
func(exe2, ['2.c', 'common.c'], []) |
| 617 |
func(exe2_a, ['2.c', 'common.c'], ['-arg']) |
| 618 |
``` |
| 619 |
|
| 620 |
```meson |
| 621 |
foreach e : [['1', '1.c', []], |
| 622 |
['2', '2.c', []], |
| 623 |
['2', '2.c', ['-arg']]] |
| 624 |
executable( |
| 625 |
'exe' + e[0], |
| 626 |
e[1], |
| 627 |
c_args : e[2], |
| 628 |
) |
| 629 |
endforeach |
| 630 |
``` |
| 631 |
|
| 632 |
The loop is both less code and is much easier to reason about than the function |
| 633 |
version is, especially if the function were to live in a separate file, as is |
| 634 |
common in other popular build systems. |
| 635 |
|
| 636 |
Build system DSLs also tend to be badly thought out as generic programming |
| 637 |
languages, Meson tries to make it easy to use external scripts or programs |
| 638 |
for handling complex problems. While one can't always convert build logic |
| 639 |
into a scripting language (or compiled language), when it can be done this is |
| 640 |
often a better solution. External languages tend to be well-thought-out and |
| 641 |
tested, generally don't regress, and users are more likely to have domain |
| 642 |
knowledge about them. They also tend to have better tooling (such as |
| 643 |
autocompletion, linting, testing solutions), which make them a lower |
| 644 |
maintenance burden over time. |
| 645 |
|
| 646 |
## Why don't the arguments passed to `add_project_link_arguments` affect anything? |
| 647 |
|
| 648 |
Given code like this: |
| 649 |
```meson |
| 650 |
add_project_link_arguments(['-Wl,-foo'], language : ['c']) |
| 651 |
executable( |
| 652 |
'main', |
| 653 |
'main.c', |
| 654 |
'helper.cpp', |
| 655 |
) |
| 656 |
``` |
| 657 |
|
| 658 |
One might be surprised to find that `-Wl,-foo` is *not* applied to the linkage |
| 659 |
of the `main` executable. In this Meson is working as expected, since meson will |
| 660 |
attempt to determine the correct linker to use automatically. This avoids |
| 661 |
situations like in autotools where dummy C++ sources have to be added to some |
| 662 |
compilation targets to get correct linkage. So in the above case the C++ linker |
| 663 |
is used, instead of the C linker, as `helper.cpp` likely cannot be linked using |
| 664 |
the C linker. |
| 665 |
|
| 666 |
Generally the best way to resolve this is to add the `cpp` language to the |
| 667 |
`add_project_link_arguments` call. |
| 668 |
```meson |
| 669 |
add_project_link_arguments(['-Wl,-foo'], language : ['c', 'cpp']) |
| 670 |
executable( |
| 671 |
'main', |
| 672 |
'main.c', |
| 673 |
'helper.cpp', |
| 674 |
) |
| 675 |
``` |
| 676 |
|
| 677 |
To force the use of the C linker anyway the `link_language` keyword argument can |
| 678 |
be used. Note that this can result in a compilation failure if there are symbols |
| 679 |
that the C linker cannot resolve. |
| 680 |
```meson |
| 681 |
add_project_link_arguments(['-Wl,-foo'], language : ['c']) |
| 682 |
executable( |
| 683 |
'main', |
| 684 |
'main.c', |
| 685 |
'helper.cpp', |
| 686 |
link_language : 'c', |
| 687 |
) |
| 688 |
``` |
| 689 |
|
| 690 |
## How do I ignore the build directory in my VCS? |
| 691 |
|
| 692 |
You don't need to, assuming you use git or mercurial! Meson >=0.57.0 will |
| 693 |
create a `.gitignore` and `.hgignore` file for you, inside each build |
| 694 |
directory. It glob ignores ```"*"```, since all generated files should not be |
| 695 |
checked into git. |
| 696 |
|
| 697 |
Users of older versions of Meson may need to set up ignore files themselves. |
| 698 |
|
| 699 |
## How to add preprocessor defines to a target? |
| 700 |
|
| 701 |
Just add `-DFOO` to `c_args` or `cpp_args`. This works for all known compilers. |
| 702 |
|
| 703 |
```meson |
| 704 |
mylib = library('mylib', 'mysource.c', c_args: ['-DFOO']) |
| 705 |
``` |
| 706 |
|
| 707 |
Even though [MSVC documentation](https://learn.microsoft.com/en-us/cpp/build/reference/d-preprocessor-definitions) |
| 708 |
uses `/D` for preprocessor defines, its [command-line syntax](https://learn.microsoft.com/en-us/cpp/build/reference/compiler-command-line-syntax) |
| 709 |
accepts `-` instead of `/`. |
| 710 |
It's not necessary to treat preprocessor defines specially in Meson ([GH-6269](https://github.com/mesonbuild/meson/issues/6269#issuecomment-560003922)). |