Debian Codegraph @

subprojects/meson-docs/docs/markdown/Build-targets.md

raw
1 ---
2 short-description: Definition of build targets
3 ...
4
5 # Build targets
6
7 Meson provides four kinds of build targets: executables, libraries
8 (which can be set to be built as static or shared or both of them at
9 the build configuration time), static libraries, and shared libraries.
10 They are created with the commands `executable`, `library`,
11 `static_library` and `shared_library`, respectively. All objects created
12 in this way are **immutable**. That is, you cannot change any aspect of
13 them after they have been constructed. This ensures that all information
14 pertaining to a given build target is specified in one well defined
15 place.
16
17 Libraries and executables
18 --
19
20 As an example, here is how you would build a library.
21
22 ```meson
23 project('shared lib', 'c')
24 library('mylib', 'source.c')
25 ```
26
27 It is generally preferred to use the `library` command instead of
28 `shared_library` and `static_library` and then configure which
29 libraries (static or shared or both of them) will be built at the
30 build configuration time using the `default_library`
31 [built-in option](Builtin-options.md).
32
33 In Unix-like operating systems, shared libraries can be
34 versioned. Meson supports this with keyword arguments, which will be
35 ignored if the library is configured as static at the compile time.
36
37 ```meson
38 project('shared lib', 'c')
39 library('mylib', 'source.c', version : '1.2.3', soversion : '1')
40 ```
41
42 It is common to build a library and then an executable that links
43 against it. This is supported as well.
44
45 ```meson
46 project('shared lib', 'c')
47 lib = library('mylib', 'source.c')
48 executable('program', 'prog.c', link_with : lib)
49 ```
50
51 Meson sets things up so that the resulting executable can be run
52 directly from the build directory. There is no need to write shell
53 scripts or set environment variables.
54
55 One target can have multiple language source files.
56
57 ```meson
58 project('multilang', 'c', 'cpp')
59 executable('multiexe', 'file.c', 'file2.cc')
60 ```
61
62 Object files
63 --
64
65 Sometimes you can't build files from sources but need to utilize an
66 existing object file. A typical case is using an object file provided
67 by a third party. Object files can be specified just like sources.
68
69 ```meson
70 exe = executable('myexe', 'source.cpp', objects : 'third_party_object.o')
71 ```
72
73 A different case is when you want to use object files built in one
74 target directly in another. A typical case is when you build a shared
75 library and it has an internal class that is not exported in the
76 ABI. This means you can't access it even if you link against the
77 library. Typical workarounds for this include building both a shared
78 and static version of the library or putting the source file in the
79 test executable's source list. Both of these approaches cause the
80 source to be built twice, which is slow.
81
82 In Meson you can extract object files from targets and use them as-is
83 on other targets. This is the syntax for it.
84
85 ```meson
86 lib = shared_library('somelib', 'internalclass.cc', 'file.cc', ...)
87 eo = lib.extract_objects('internalclass.cc')
88 executable('classtest', 'classtest.cpp', objects : eo)
89 ```
90
91 Here we take the internal class object and use it directly in the
92 test. The source file is only compiled once.
93
94 Note that careless use of this feature may cause strange bugs. As an
95 example trying to use objects of an executable or static library in a
96 shared library will not work because shared library objects require
97 special compiler flags. Getting this right is the user's
98 responsibility. For this reason it is strongly recommended that you
99 only use this feature for generating unit test executables in the
100 manner described above.