Debian Codegraph @

subprojects/meson-docs/docs/yaml/functions/_build_target_base.yaml

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