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