Debian Codegraph @

subprojects/meson-docs/docs/markdown/Wrap-best-practices-and-tips.md

raw
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.