| 1 |
# Wrap best practices and tips |
| 2 |
|
| 3 |
There are several things you need to take into consideration when |
| 4 |
writing a Meson build definition for a project. This is especially |
| 5 |
true when the project will be used as a subproject. This page lists a |
| 6 |
few things to consider when writing your definitions. |
| 7 |
|
| 8 |
## Do not put config.h in external search path |
| 9 |
|
| 10 |
Many projects use a `config.h` header file that they use for |
| 11 |
configuring their project internally. These files are never installed |
| 12 |
to the system header files so there are no inclusion collisions. This |
| 13 |
is not the case with subprojects, your project tree may have an |
| 14 |
arbitrary number of configuration files, so we need to ensure they |
| 15 |
don't clash. |
| 16 |
|
| 17 |
The basic problem is that the users of the subproject must be able to |
| 18 |
include subproject headers without seeing its `config.h` file. The |
| 19 |
most correct solution is to rename the `config.h` file into something |
| 20 |
unique, such as `foobar-config.h`. This is usually not feasible unless |
| 21 |
you are the maintainer of the subproject in question. |
| 22 |
|
| 23 |
The pragmatic solution is to put the config header in a directory that |
| 24 |
has no other header files and then hide that from everyone else. One |
| 25 |
way is to create a top level subdirectory called `internal` and use |
| 26 |
that to build your own sources, like this: |
| 27 |
|
| 28 |
```meson |
| 29 |
subdir('internal') # create config.h in this subdir |
| 30 |
internal_inc = include_directories('internal') |
| 31 |
shared_library('foo', 'foo.c', include_directories : internal_inc) |
| 32 |
``` |
| 33 |
|
| 34 |
Many projects keep their `config.h` in the top level directory that |
| 35 |
has no other source files in it. In that case you don't need to move |
| 36 |
it but can just do this instead: |
| 37 |
|
| 38 |
```meson |
| 39 |
internal_inc = include_directories('.') # At top level meson.build |
| 40 |
``` |
| 41 |
|
| 42 |
## Make libraries buildable both as static and shared |
| 43 |
|
| 44 |
Some platforms (e.g. iOS) requires linking everything in your main app |
| 45 |
statically. In other cases you might want shared libraries. They are |
| 46 |
also faster during development due to Meson's relinking optimization. |
| 47 |
However building both library types on all builds is slow and |
| 48 |
wasteful. |
| 49 |
|
| 50 |
Your project should use the `library` method that can be toggled |
| 51 |
between shared and static with the `default_library` builtin option. |
| 52 |
|
| 53 |
|
| 54 |
```meson |
| 55 |
mylib = library('foo', 'foo.c') |
| 56 |
``` |
| 57 |
|
| 58 |
## Declare generated headers explicitly |
| 59 |
|
| 60 |
Meson's Ninja backend works differently from Make and other |
| 61 |
systems. Rather than processing things directory per directory, it |
| 62 |
looks at the entire build definition at once and runs the individual |
| 63 |
compile jobs in what might look to the outside as a random order. |
| 64 |
|
| 65 |
The reason for this is that this is much more efficient so your builds |
| 66 |
finish faster. The downside is that you have to be careful with your |
| 67 |
dependencies. The most common problem here is headers that are |
| 68 |
generated at compile time with e.g. code generators. If these headers |
| 69 |
are needed when building code that uses these libraries, the compile |
| 70 |
job might be run before the code generation step. The fix is to make |
| 71 |
the dependency explicit like this: |
| 72 |
|
| 73 |
```meson |
| 74 |
myheader = custom_target(...) |
| 75 |
mylibrary = shared_library(...) |
| 76 |
mydep = declare_dependency(link_with : mylibrary, |
| 77 |
include_directories : include_directories(...), |
| 78 |
sources : myheader) |
| 79 |
``` |
| 80 |
|
| 81 |
And then you can use the dependency in the usual way: |
| 82 |
|
| 83 |
```meson |
| 84 |
executable('dep_using_exe', 'main.c', |
| 85 |
dependencies : mydep) |
| 86 |
``` |
| 87 |
|
| 88 |
Meson will ensure that the header file has been built before compiling `main.c`. |
| 89 |
|
| 90 |
## Avoid exposing compilable source files in declare_dependency |
| 91 |
|
| 92 |
The main use for the `sources` argument in `declare_dependency` is to |
| 93 |
construct the correct dependency graph for the backends, as |
| 94 |
demonstrated in the previous section. It is extremely important to |
| 95 |
note that it should *not* be used to directly expose compilable |
| 96 |
sources (`.c`, `.cpp`, etc.) of dependencies, and should rather only |
| 97 |
be used for header/config files. The following example will illustrate |
| 98 |
what can go wrong if you accidentally expose compilable source files. |
| 99 |
|
| 100 |
So you've read about unity builds and how Meson natively supports |
| 101 |
them. You decide to expose the sources of dependencies in order to |
| 102 |
have unity builds that include their dependencies. For your support |
| 103 |
library you do |
| 104 |
|
| 105 |
```meson |
| 106 |
my_support_sources = files(...) |
| 107 |
|
| 108 |
mysupportlib = shared_library( |
| 109 |
... |
| 110 |
sources : my_support_sources, |
| 111 |
...) |
| 112 |
mysupportlib_dep = declare_dependency( |
| 113 |
... |
| 114 |
link_with : mylibrary, |
| 115 |
sources : my_support_sources, |
| 116 |
...) |
| 117 |
``` |
| 118 |
|
| 119 |
And for your main project you do: |
| 120 |
|
| 121 |
```meson |
| 122 |
mylibrary = shared_library( |
| 123 |
... |
| 124 |
dependencies : mysupportlib_dep, |
| 125 |
...) |
| 126 |
myexe = executable( |
| 127 |
... |
| 128 |
link_with : mylibrary, |
| 129 |
dependencies : mysupportlib_dep, |
| 130 |
...) |
| 131 |
``` |
| 132 |
|
| 133 |
This is extremely dangerous. When building, `mylibrary` will build and |
| 134 |
link the support sources `my_support_sources` into the resulting |
| 135 |
shared library. Then, for `myexe`, these same support sources will be |
| 136 |
compiled again, will be linked into the resulting executable, in |
| 137 |
addition to them being already present in `mylibrary`. This can |
| 138 |
quickly run afoul of the [One Definition Rule |
| 139 |
(ODR)](https://en.wikipedia.org/wiki/One_Definition_Rule) in C++, as |
| 140 |
you have more than one definition of a symbol, yielding undefined |
| 141 |
behavior. While C does not have a strict ODR rule, there is no |
| 142 |
language in the standard which guarantees such behavior to work. |
| 143 |
Violations of the ODR can lead to weird idiosyncratic failures such as |
| 144 |
segfaults. In the overwhelming number of cases, exposing library |
| 145 |
sources via the `sources` argument in `declare_dependency` is thus |
| 146 |
incorrect. If you wish to get full cross-library performance, consider |
| 147 |
building `mysupportlib` as a static library instead and employing LTO. |
| 148 |
|
| 149 |
There are exceptions to this rule. If there are some natural |
| 150 |
constraints on how your library is to be used, you can expose sources. |
| 151 |
For instance, the WrapDB module for GoogleTest directly exposes the |
| 152 |
sources of GTest and GMock. This is valid, as GTest and GMock will |
| 153 |
only ever be used in *terminal* link targets. A terminal target is the |
| 154 |
final target in a dependency link chain, for instance `myexe` in the |
| 155 |
last example, whereas `mylibrary` is an intermediate link target. For |
| 156 |
most libraries this rule is not applicable though, as you cannot in |
| 157 |
general control how others consume your library, and as such should |
| 158 |
not expose sources. |