| 1 |
name: _build_target_base |
| 2 |
returns: void |
| 3 |
description: PRIVATE |
| 4 |
|
| 5 |
posargs: |
| 6 |
target_name: |
| 7 |
description: The *unique* name of the build target |
| 8 |
type: str |
| 9 |
|
| 10 |
varargs: |
| 11 |
name: source |
| 12 |
type: str | file | custom_tgt | custom_idx | generated_list |
| 13 |
description: | |
| 14 |
Input source to compile. The following types are supported: |
| 15 |
|
| 16 |
- Strings relative to the current source directory |
| 17 |
- [[@file]] objects defined in any preceding build file |
| 18 |
- The return value of configure-time generators such as [[configure_file]] |
| 19 |
- The return value of build-time generators such as |
| 20 |
[[custom_target]] or [[generator.process]] |
| 21 |
|
| 22 |
These input files can be sources, objects, libraries, or any other |
| 23 |
file. Meson will automatically categorize them based on the extension |
| 24 |
and use them accordingly. For instance, sources (`.c`, `.cpp`, |
| 25 |
`.vala`, `.rs`, etc) will be compiled and objects (`.o`, `.obj`) and |
| 26 |
libraries (`.so`, `.dll`, etc) will be linked. |
| 27 |
|
| 28 |
With the Ninja backend, Meson will create a build-time [order-only |
| 29 |
dependency](https://ninja-build.org/manual.html#ref_dependencies) on |
| 30 |
all generated input files, including unknown files. This is needed to |
| 31 |
bootstrap the generation of the real dependencies in the |
| 32 |
[depfile](https://ninja-build.org/manual.html#ref_headers) generated |
| 33 |
by your compiler to determine when to rebuild sources. Ninja relies on |
| 34 |
this dependency file for all input files, generated and non-generated. |
| 35 |
The behavior is similar for other backends. |
| 36 |
|
| 37 |
warnings: |
| 38 |
- The `link_language` kwarg was broken until 0.55.0 |
| 39 |
|
| 40 |
kwargs: |
| 41 |
<lang>_pch: |
| 42 |
type: str |
| 43 |
description: precompiled header file to use for the given language |
| 44 |
|
| 45 |
<lang>_args: |
| 46 |
type: list[str] |
| 47 |
description: | |
| 48 |
compiler flags to use for the given language; |
| 49 |
eg: `cpp_args` for C++ |
| 50 |
|
| 51 |
vala_args: |
| 52 |
type: list[str | file] |
| 53 |
description: | |
| 54 |
Compiler flags for Vala. Unlike other languages this may contain Files |
| 55 |
|
| 56 |
sources: |
| 57 |
type: str | file | custom_tgt | custom_idx | generated_list | structured_src |
| 58 |
description: Additional source files. Same as the source varargs. |
| 59 |
|
| 60 |
build_by_default: |
| 61 |
type: bool |
| 62 |
default: true |
| 63 |
since: 0.38.0 |
| 64 |
description: | |
| 65 |
Causes, when set to `true`, to have this target be built by default. |
| 66 |
This means it will be built when `meson compile` is called without any |
| 67 |
arguments. The default value is `true` for all built target types. |
| 68 |
|
| 69 |
build_rpath: |
| 70 |
type: str |
| 71 |
since: 0.42.0 |
| 72 |
description: | |
| 73 |
A string to add to target's rpath definition in the build dir, |
| 74 |
but which will be removed on install |
| 75 |
|
| 76 |
dependencies: |
| 77 |
type: list[dep] |
| 78 |
description: | |
| 79 |
one or more dependency objects |
| 80 |
created with |
| 81 |
[[dependency]] or [[compiler.find_library]] |
| 82 |
(for external deps) or [[declare_dependency]] |
| 83 |
(for deps built by the project) |
| 84 |
|
| 85 |
extra_files: |
| 86 |
type: str | file | custom_tgt | custom_idx |
| 87 |
description: | |
| 88 |
Not used for the build itself but are shown as source files in IDEs |
| 89 |
that group files by targets (such as Visual Studio) |
| 90 |
|
| 91 |
gui_app: |
| 92 |
type: bool |
| 93 |
deprecated: 0.56.0 |
| 94 |
default: false |
| 95 |
description: | |
| 96 |
When set to true flags this target as a GUI application |
| 97 |
on platforms where this makes a difference, **deprecated** since |
| 98 |
0.56.0, use `win_subsystem` instead. |
| 99 |
|
| 100 |
link_args: |
| 101 |
type: list[str] |
| 102 |
description: | |
| 103 |
Flags to use during linking. You can use UNIX-style |
| 104 |
flags here for all platforms. |
| 105 |
|
| 106 |
link_depends: |
| 107 |
type: str | file | custom_tgt | custom_idx |
| 108 |
description: | |
| 109 |
Strings, files, or custom targets the link step depends on |
| 110 |
such as a symbol visibility map. The purpose is to |
| 111 |
automatically trigger a re-link (but not a re-compile) of the target |
| 112 |
when this file changes. |
| 113 |
|
| 114 |
link_language: |
| 115 |
type: str |
| 116 |
since: 0.51.0 |
| 117 |
description: | |
| 118 |
Makes the linker for this target be for the specified language. |
| 119 |
It is generally unnecessary to set |
| 120 |
this, as Meson will detect the right linker to use in most cases. There are |
| 121 |
only two cases where this is needed. One, your main function in an |
| 122 |
executable is not in the language Meson picked, or second you want to force |
| 123 |
a library to use only one ABI. |
| 124 |
|
| 125 |
*(broken until 0.55.0)* |
| 126 |
|
| 127 |
link_whole: |
| 128 |
type: list[lib | custom_tgt | custom_idx] |
| 129 |
since: 0.40.0 |
| 130 |
description: | |
| 131 |
Links all contents of the given static libraries whether they are used or |
| 132 |
not, equivalent to the `-Wl,--whole-archive` argument flag of GCC, or the |
| 133 |
'/WHOLEARCHIVE' MSVC linker option. This allows the linked target to |
| 134 |
re-export symbols from all objects in the static libraries. |
| 135 |
|
| 136 |
*(since 0.41.0)* If passed a list that list will be flattened. |
| 137 |
|
| 138 |
*(since 0.51.0)* This argument also accepts outputs produced by |
| 139 |
custom targets. The user must ensure that the output is a library in |
| 140 |
the correct format. |
| 141 |
|
| 142 |
link_with: |
| 143 |
type: list[lib | custom_tgt | custom_idx] |
| 144 |
description: | |
| 145 |
One or more shared or static libraries |
| 146 |
(built by this project) that this target should be linked with. *(since 0.41.0)* If passed a |
| 147 |
list this list will be flattened. *(since 0.51.0)* The arguments can also be custom targets. |
| 148 |
In this case Meson will assume that merely adding the output file in the linker command |
| 149 |
line is sufficient to make linking work. If this is not sufficient, |
| 150 |
then the build system writer must write all other steps manually. |
| 151 |
|
| 152 |
implicit_include_directories: |
| 153 |
type: bool |
| 154 |
since: 0.42.0 |
| 155 |
default: true |
| 156 |
description: Controls whether Meson adds the current source and build directories to the include path |
| 157 |
|
| 158 |
include_directories: |
| 159 |
type: list[inc | str] |
| 160 |
description: | |
| 161 |
one or more objects created with the [[include_directories]] function, |
| 162 |
or *(since 0.50.0)* strings, which will be transparently expanded to include directory objects |
| 163 |
|
| 164 |
install: |
| 165 |
type: bool |
| 166 |
default: false |
| 167 |
description: When set to true, this executable should be installed. |
| 168 |
|
| 169 |
install_dir: |
| 170 |
type: str |
| 171 |
description: | |
| 172 |
override install directory for this file. If the value is a relative path, |
| 173 |
it will be considered relative the `prefix` option. |
| 174 |
For example, if you want to install plugins into a subdir, you'd use |
| 175 |
something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`. |
| 176 |
|
| 177 |
install_mode: |
| 178 |
type: list[str | int] |
| 179 |
since: 0.47.0 |
| 180 |
description: | |
| 181 |
Specify the file mode in symbolic format |
| 182 |
and optionally the owner/uid and group/gid for the installed files. |
| 183 |
|
| 184 |
See the `install_mode` kwarg of [[install_data]] for more information. |
| 185 |
|
| 186 |
install_tag: |
| 187 |
type: str |
| 188 |
since: 0.60.0 |
| 189 |
description: | |
| 190 |
A string used by the `meson install --tags` command |
| 191 |
to install only a subset of the files. By default all build targets have the |
| 192 |
tag `runtime` except for static libraries that have the `devel` tag. |
| 193 |
|
| 194 |
install_rpath: |
| 195 |
type: str |
| 196 |
description: | |
| 197 |
A string to set the target's rpath to after install |
| 198 |
(but *not* before that). On Windows, this argument has no effect. |
| 199 |
|
| 200 |
objects: |
| 201 |
type: list[extracted_obj | file | str] |
| 202 |
description: | |
| 203 |
List of object files that should be linked in this target. |
| 204 |
|
| 205 |
**Since 1.1.0** this can include generated files in addition to |
| 206 |
object files that you don't have source to or that object files |
| 207 |
produced by other build targets. In earlier release, generated |
| 208 |
object files had to be placed in `sources`. |
| 209 |
|
| 210 |
name_prefix: |
| 211 |
type: str | list[void] |
| 212 |
description: | |
| 213 |
The string that will be used as the prefix for the |
| 214 |
target output filename by overriding the default (only used for |
| 215 |
libraries). By default this is `lib` on all platforms and compilers, |
| 216 |
except for MSVC shared libraries where it is omitted to follow |
| 217 |
convention, and Cygwin shared libraries where it is `cyg`. |
| 218 |
|
| 219 |
Set this to `[]`, or omit the keyword argument for the default behaviour. |
| 220 |
|
| 221 |
name_suffix: |
| 222 |
type: str | list[void] |
| 223 |
description: | |
| 224 |
The string that will be used as the extension for the |
| 225 |
target by overriding the default. By default on Windows this is |
| 226 |
`exe` for executables and on other platforms it is omitted. |
| 227 |
|
| 228 |
For shared libraries, the default value |
| 229 |
is `dylib` on macOS, `dll` on Windows, and `so` everywhere else. |
| 230 |
For static libraries, it is `a` everywhere. By convention MSVC |
| 231 |
static libraries use the `lib` suffix, but we use `a` to avoid a |
| 232 |
potential name clash with shared libraries which also generate |
| 233 |
import libraries with a `lib` suffix. |
| 234 |
|
| 235 |
Set this to `[]`, or omit the keyword argument for the default behaviour. |
| 236 |
|
| 237 |
override_options: |
| 238 |
type: list[str] | dict[str | bool | int | list[str]] |
| 239 |
since: 0.40.0 |
| 240 |
description: | |
| 241 |
takes an array of strings in the same format as `project`'s `default_options` |
| 242 |
overriding the values of these options |
| 243 |
for this target only. |
| 244 |
*(since 1.2.0)*: A dictionary may now be passed. |
| 245 |
|
| 246 |
gnu_symbol_visibility: |
| 247 |
type: str |
| 248 |
since: 0.48.0 |
| 249 |
description: | |
| 250 |
Specifies how symbols should be exported, see |
| 251 |
e.g [the GCC Wiki](https://gcc.gnu.org/wiki/Visibility) for more |
| 252 |
information. This value can either be an empty string or one of |
| 253 |
`default`, `internal`, `hidden`, `protected` or `inlineshidden`, which |
| 254 |
is the same as `hidden` but also includes things like C++ implicit |
| 255 |
constructors as specified in the GCC manual. Ignored on compilers that |
| 256 |
do not support GNU visibility arguments. |
| 257 |
|
| 258 |
d_import_dirs: |
| 259 |
type: list[inc | str] |
| 260 |
since: 0.62.0 |
| 261 |
description: | |
| 262 |
the directories to add to the string search path (i.e. `-J` switch for DMD). |
| 263 |
Must be [[@inc]] objects or plain strings. |
| 264 |
|
| 265 |
d_unittest: |
| 266 |
type: bool |
| 267 |
default: false |
| 268 |
description: When set to true, the D modules are compiled in debug mode. |
| 269 |
|
| 270 |
d_module_versions: |
| 271 |
type: list[str | int] |
| 272 |
description: List of module version identifiers set when compiling D sources. |
| 273 |
|
| 274 |
d_debug: |
| 275 |
type: list[str] |
| 276 |
description: | |
| 277 |
The [D version identifiers](https://dlang.org/spec/version.html#version) to add |
| 278 |
during the compilation of D source files. |
| 279 |
|
| 280 |
native: |
| 281 |
type: bool |
| 282 |
default: false |
| 283 |
description: Controls whether the target is compiled for the build or host machines. |
| 284 |
|
| 285 |
win_subsystem: |
| 286 |
type: str |
| 287 |
default: "'console'" |
| 288 |
since: 0.56.0 |
| 289 |
description: | |
| 290 |
Specifies the subsystem type to use |
| 291 |
on the Windows platform. Typical values include `console` for text |
| 292 |
mode programs and `windows` for gui apps. The value can also contain |
| 293 |
version specification such as `windows,6.0`. See [MSDN |
| 294 |
documentation](https://docs.microsoft.com/en-us/cpp/build/reference/subsystem-specify-subsystem) |
| 295 |
for the full list. |
| 296 |
|
| 297 |
rust_crate_type: |
| 298 |
type: str |
| 299 |
since: 0.42.0 |
| 300 |
deprecated: 1.3.0 |
| 301 |
description: | |
| 302 |
Set the specific type of rust crate to compile (when compiling rust). |
| 303 |
|
| 304 |
If the target is an [[executable]] this defaults to "bin", the only |
| 305 |
allowed value. |
| 306 |
|
| 307 |
If it is a [[static_library]] it defaults to "lib", and may be "lib", |
| 308 |
"staticlib", or "rlib". If "lib" then Rustc will pick a default, "staticlib" |
| 309 |
means a C ABI library, "rlib" means a Rust ABI. |
| 310 |
|
| 311 |
If it is a [[shared_library]] it defaults to "lib", and may be "lib", |
| 312 |
"dylib", "cdylib", or "proc-macro". If "lib" then Rustc will pick a |
| 313 |
default, "cdylib" means a C ABI library, "dylib" means a Rust ABI, and |
| 314 |
"proc-macro" is a special rust procedural macro crate. |
| 315 |
|
| 316 |
"proc-macro" is new in 0.62.0. |
| 317 |
|
| 318 |
*Since 1.3.0* this is deprecated and replaced by "rust_abi" keyword argument. |
| 319 |
`proc_macro` crates are now handled by the [`rust.proc_macro()`](Rust-module.md#proc_macro) |
| 320 |
method. |
| 321 |
|
| 322 |
rust_dependency_map: |
| 323 |
type: dict[str] |
| 324 |
since: 1.2.0 |
| 325 |
description: | |
| 326 |
On rust targets this provides a map of library names to the crate name |
| 327 |
with which it would be available inside the rust code. |
| 328 |
|
| 329 |
This allows renaming similar to the dependency renaming feature of cargo |
| 330 |
or `extern crate foo as bar` inside rust code. |