The Meson Manual

321 Pages·2020·1.906 MB·English

by  Jussi Pakkanen

The Meson Manual
Jussi Pakkanen
October 26, 2020
©2020 Jussi Pakkanen
The sample code in this book is provided for instructional purposes only. It has been
tested with great care but it is not guaranteed to be free of errors or to work for any
particular purpose.
Typeset by the author in LATEX [11]. But given that you are the sort of person who
reads colophons you probably knew that already.
3rd edition.
ISBN: 978-952-94-2892-2
Publisher: Diffraction Labs
Meson is a registered trademark of Jussi Pakkanen. All other trademarks are the
property of their respective owners, and they are used only in an editorial fashion,
with no intention of infringement.
Preface
Whenyouspendalongtimeworkingonabook,deep,fundamentalquestionson
the task start bubbling in to your mind. For this book some of these questions
includedggggnnghwillthistaskneverend,maybeIshouldvacuummyapartment
one more time and what was the first ever build system in the world. For the
benefit of the reader we are going to ignore the first two and instead focus on
the last one.
Theobviousfollowupquestioniswhat is a build system. Ifwegobymodern
nomenclature, then a build system is a tool whose job is to transfer source
code from the user to the compilation process. This definition implies that the
first build system was not software but instead a physical object, namely the
cardboard box that operators used to carry punch cards from the keypunch
station to the punch card reader. Thus we find that build systems are one of
the oldest pieces of software development.
Given how fundamental a build system is for programming, it is quite as-
tounding how little they have changed over the years. Let’s take, for example,
the time period between the years 1978 and 2000. Computers got thousands of
timesfaster, manyhardwarecompanies, platformsandtoolchainsdied, newone
arose,flourishedandthendiedagain. Yetasoftwaredeveloperfromthelate70s
could feel quite at home, because most projects were built with Makefiles and
shell scripts.
Inthenewmillenniumthingsstartedtochange. Projectsgotbiggerandpeo-
ple started requiring more things from their build systems, such as dependency
management, unit testing and so on. Implementing all of this with Makefiles
got harder and harder and eventually new solutions with wholly different ap-
proaches appeared. One of these was Meson, which was started just before
Christmas2012. Thereweretwomainreasonsforitscreation. Thefirstonewas
that I was completely fed up with fixing the same things over and over again in
other peoples’ build definitions. The second was that I had not done a compiler
course so I wanted to learn how to write a parser and interpreter for my own
language.
iii
That was the easy part.
The really hard part was convincing other people to use Meson. Here we
finally discover that open source projects are not so much about the code, but
about the people working on it. Over the years we have had hundreds, possibly
even thousands of contributors ranging from code submitters to bug reporters,
documentation writers and just plain old advocates. I would love to thank each
and every one of you personally, but unfortunately there is not enough space
here. I dedicate this book to all of you.
For their help in making this book, I’d like to thank the following people:
JukkaLaurila, JuhaniSimola, TimMüller, NirbheekChauhan, AleksandrKolt-
soff. Their comments on earlier versions of this manuscript improved the end
result immensely. However, as an old Finnish saying goes, one fool can create
mistakes faster than ten smart people can fix, there are probably still some er-
rors in the text. If you find any, please let me know via email so they can be
fixed in the next edition.
Go forth and build!
Jussi Pakkanen
[email protected]
Espoo, Finland
January 2020
Preface to the 2nd edition
Thanks to Will Thompson, Tom-Robin Teschner and Will Wray for reporting
errors in the first version of the book.
Preface to the 3rd edition
Thanks to Zlatko Karakas for reporting errors in the second edition.
iv
Contents
Preface iii
Conventions used in this book xiii
I The user manual 1
1 Getting started 3
1.1 Obtaining Meson . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Creating the sample project . . . . . . . . . . . . . . . . . . . 5
1.3 Building from the command line . . . . . . . . . . . . . . . . . 6
1.4 Building with the Visual Studio IDE . . . . . . . . . . . . . . 7
2 How compilation works 9
2.1 Basic term definitions . . . . . . . . . . . . . . . . . . . . . . . 9
2.2 Building the Hello World application manually . . . . . . . . . 11
2.3 Basic symbol resolution . . . . . . . . . . . . . . . . . . . . . . 12
2.4 Static linking. . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.5 Shared linking . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.6 Linking multiple libraries . . . . . . . . . . . . . . . . . . . . . 17
2.7 Which is better, shared or static linking? . . . . . . . . . . . . 19
2.8 Dynamic linker and symbol resolution . . . . . . . . . . . . . . 19
3 Meson syntax 23
3.1 Original design principles . . . . . . . . . . . . . . . . . . . . . 24
3.2 Concrete design decisions . . . . . . . . . . . . . . . . . . . . . 25
3.3 Elementary types . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.4 Build system phases . . . . . . . . . . . . . . . . . . . . . . . . 31
3.5 Program flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.6 Object types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
v
3.7 Disablers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4 Building blocks of a software project 45
4.1 The elementary operations . . . . . . . . . . . . . . . . . . . . 46
4.2 Advanced build cases . . . . . . . . . . . . . . . . . . . . . . . 47
4.3 Generating data . . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.4 Defining the graph in Meson . . . . . . . . . . . . . . . . . . . 49
4.5 Splitting the project to multiple directories . . . . . . . . . . . 50
4.6 Target properties . . . . . . . . . . . . . . . . . . . . . . . . . 52
5 External dependencies 55
5.1 What is a dependency? . . . . . . . . . . . . . . . . . . . . . . 55
5.2 Finding and using dependencies . . . . . . . . . . . . . . . . . 56
5.3 Dependency provider backends . . . . . . . . . . . . . . . . . . 58
5.4 Executable dependencies . . . . . . . . . . . . . . . . . . . . . 60
5.5 Dependencies that don’t provide any dependency files . . . . . 61
6 Subprojects and internal dependencies 63
6.1 Subproject basics and layout . . . . . . . . . . . . . . . . . . . 63
6.2 Using subprojects . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.3 Internal dependencies . . . . . . . . . . . . . . . . . . . . . . . 66
6.4 Combining subprojects and internal dependencies . . . . . . . 66
6.5 Overriding executable lookup. . . . . . . . . . . . . . . . . . . 67
7 Configuring the project 71
7.1 Simple approaches to configuration . . . . . . . . . . . . . . . 71
7.2 Configuration files . . . . . . . . . . . . . . . . . . . . . . . . . 74
7.3 Advanced configuration options . . . . . . . . . . . . . . . . . 75
7.4 Introspecting the system . . . . . . . . . . . . . . . . . . . . . 78
7.5 Printing status messages . . . . . . . . . . . . . . . . . . . . . 81
8 Testing 85
8.1 Defining a test . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
8.2 Test properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
8.3 Advanced testing using the test tool . . . . . . . . . . . . . . . 93
8.4 Defining custom test setups . . . . . . . . . . . . . . . . . . . 96
8.5 Benchmarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
9 Installing 99
9.1 Directory layout . . . . . . . . . . . . . . . . . . . . . . . . . . 99
9.2 Installing build targets . . . . . . . . . . . . . . . . . . . . . . 102
9.3 Installing other files . . . . . . . . . . . . . . . . . . . . . . . . 103
vi
9.4 Running the install . . . . . . . . . . . . . . . . . . . . . . . . 104
9.5 Custom install tasks . . . . . . . . . . . . . . . . . . . . . . . . 106
9.6 Other things that happen during install . . . . . . . . . . . . . 107
9.7 Accessing data files before and after install . . . . . . . . . . . 108
10 Project options 111
10.1 Builtin options . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
10.2 Declaring and using project options . . . . . . . . . . . . . . . 112
10.3 Defining options . . . . . . . . . . . . . . . . . . . . . . . . . . 112
10.4 Exploring and setting option values . . . . . . . . . . . . . . . 114
10.5 Sharing options between projects . . . . . . . . . . . . . . . . 116
11 Custom build steps 119
11.1 Generating data files . . . . . . . . . . . . . . . . . . . . . . . 119
11.2 Dependency files . . . . . . . . . . . . . . . . . . . . . . . . . . 121
11.3 Special strings in command arguments . . . . . . . . . . . . . 122
11.4 Generating source code . . . . . . . . . . . . . . . . . . . . . . 123
11.5 Generating source and headers . . . . . . . . . . . . . . . . . . 124
11.6 Using generators . . . . . . . . . . . . . . . . . . . . . . . . . . 127
12 Cross compilation 131
12.1 A word about nomenclature . . . . . . . . . . . . . . . . . . . 132
12.2 A practical example . . . . . . . . . . . . . . . . . . . . . . . . 132
12.3 Other naming setups . . . . . . . . . . . . . . . . . . . . . . . 135
12.4 Cross compilation with Meson . . . . . . . . . . . . . . . . . . 135
12.5 Cross file lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 137
12.6 Multiple cross files . . . . . . . . . . . . . . . . . . . . . . . . . 138
12.7 Constants in cross files . . . . . . . . . . . . . . . . . . . . . . 138
12.8 Native files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
12.9 Running tests when cross compiling . . . . . . . . . . . . . . . 139
12.10 Cross compilation and code generators . . . . . . . . . . . . . 141
12.11 Firmware upload targets . . . . . . . . . . . . . . . . . . . . . 142
13 The Wrap dependency download mechanism 145
13.1 The basic design . . . . . . . . . . . . . . . . . . . . . . . . . . 146
13.2 Downloading revision control checkouts . . . . . . . . . . . . . 146
13.3 Downloading a release archive . . . . . . . . . . . . . . . . . . 147
13.4 Using the WrapDB . . . . . . . . . . . . . . . . . . . . . . . . 148
vii
14 Converting an existing project to Meson 151
14.1 Why change build systems? Is it even worth it? . . . . . . . . 151
14.2 Making sense of an existing build system . . . . . . . . . . . . 153
14.3 Build tasks ordered by difficulty . . . . . . . . . . . . . . . . . 155
14.4 Conversions involving an entire team . . . . . . . . . . . . . . 157
15 A library sample project 159
15.1 Design requirements . . . . . . . . . . . . . . . . . . . . . . . . 159
15.2 The external API . . . . . . . . . . . . . . . . . . . . . . . . . 160
15.3 Precompiled headers . . . . . . . . . . . . . . . . . . . . . . . 163
15.4 The C ↔ C++ bridge . . . . . . . . . . . . . . . . . . . . . . . . 164
15.5 Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
15.6 Project layout . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
15.7 Creating releases. . . . . . . . . . . . . . . . . . . . . . . . . . 169
15.8 Exercises for the reader . . . . . . . . . . . . . . . . . . . . . . 171
16 Practical tips for real world projects 173
16.1 Use options rather than hardcoding compiler flags . . . . . . . 173
16.2 Shipping pregenerated files . . . . . . . . . . . . . . . . . . . . 174
16.3 Do not treat files as strings . . . . . . . . . . . . . . . . . . . . 176
16.4 Running Python scripts that use extension modules . . . . . . 177
16.5 Move everything you can out of build files . . . . . . . . . . . 179
II The reference documentation 181
17 Elementary object reference 183
17.1 array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
17.2 boolean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
17.3 dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
17.4 disabler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
17.5 integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
17.6 string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
18 Domain specific object reference 195
18.1 build_machine . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
18.2 build_target . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
18.3 compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
18.4 configuration data . . . . . . . . . . . . . . . . . . . . . . . . . 207
18.5 custom_target . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
18.6 dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
18.7 environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
viii
18.8 external_library . . . . . . . . . . . . . . . . . . . . . . . . . . 215
18.9 external_program . . . . . . . . . . . . . . . . . . . . . . . . . 215
18.10 generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
18.11 host_machine . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
18.12 meson. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
18.13 python_installation . . . . . . . . . . . . . . . . . . . . . . . . 222
18.14 run_result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
18.15 source_configuration . . . . . . . . . . . . . . . . . . . . . . . 225
18.16 source_set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
18.17 target_machine . . . . . . . . . . . . . . . . . . . . . . . . . . 228
18.18 subproject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
19 Function reference 229
19.1 add_global_arguments . . . . . . . . . . . . . . . . . . . . . . 229
19.2 add_global_link_arguments . . . . . . . . . . . . . . . . . . . 230
19.3 add_languages . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
19.4 add_project_arguments . . . . . . . . . . . . . . . . . . . . . 232
19.5 add_project_link_arguments . . . . . . . . . . . . . . . . . . 232
19.6 add_test_setup . . . . . . . . . . . . . . . . . . . . . . . . . . 232
19.7 alias_target . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
19.8 assert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
19.9 benchmark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
19.10 both_libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
19.11 build_target . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
19.12 configuration_data . . . . . . . . . . . . . . . . . . . . . . . . 238
19.13 configure_file . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
19.14 custom_target . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
19.15 declare_dependency . . . . . . . . . . . . . . . . . . . . . . . . 242
19.16 dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
19.17 disabler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
19.18 environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
19.19 executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
19.20 error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
19.21 find_program . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
19.22 files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
19.23 generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
19.24 get_option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
19.25 get_variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
19.26 import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
19.27 include_directories . . . . . . . . . . . . . . . . . . . . . . . . 251
19.28 install_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
19.29 install_headers . . . . . . . . . . . . . . . . . . . . . . . . . . 253
ix
19.30 install_man . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
19.31 install_subdir . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
19.32 is_disabler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
19.33 is_variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
19.34 jar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
19.35 join_paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
19.36 library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
19.37 message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
19.38 run_command . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
19.39 run_target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
19.40 set_variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
19.41 shared_library . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
19.42 shared_module . . . . . . . . . . . . . . . . . . . . . . . . . . 261
19.43 static_library . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
19.44 subdir. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
19.45 subdir_done . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
19.46 subproject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
19.47 summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
19.48 test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
19.49 vcs_tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
20 Module reference 269
20.1 cmake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
20.2 dlang . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
20.3 fs (filesystem) . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
20.4 gnome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
20.5 hotdoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
20.6 i18n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
20.7 pkgconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
20.8 python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
20.9 qt5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
20.10 qt4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
20.11 rpm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
20.12 sourceset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
20.13 windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
III The appendixes 289
A Contributing to Meson 291
A.1 Checking out the code . . . . . . . . . . . . . . . . . . . . . . 291
A.2 Creating the merge request . . . . . . . . . . . . . . . . . . . . 293
x