Debian Codegraph @

subprojects/meson-docs/docs/markdown/FAQ.md

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