Debian Codegraph @

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

raw
1 name: custom_target
2 returns: custom_tgt
3 description: |
4 Create a custom top level build target. The only positional argument
5 is the name of this target and cannot contain path separators (`/` or `\`).
6 The name of custom target might not be used by every backends, for instance with
7 the Ninja backend, `subdir/meson.build` containing the example below,
8 `ninja -C builddir foo` or `ninja -C builddir subdir/foo` won't work,
9 it is instead `ninja -C builddir subdir/file.txt`. However, `meson compile subdir/foo`
10 is accepted.
11 ```meson
12 custom_target('foo', output: 'file.txt', ...)
13 ```
14
15 *Since 0.60.0* the name argument is optional and defaults to the basename of the first
16 output (`file.txt` in the example above).
17
18 The list of strings passed to the `command` keyword argument accept
19 the following special string substitutions:
20
21 - `@INPUT@`: the full path to the input passed to `input`. If more than
22 one input is specified, all of them will be substituted as separate
23 arguments only if the command uses `'@INPUT@'` as a
24 standalone-argument. For instance, this would not work: `command :
25 ['cp', './@INPUT@']`, but this would: `command : ['cp', '@INPUT@']`.
26 - `@OUTPUT@`: the full path to the output passed to `output`. If more
27 than one outputs are specified, the behavior is the same as
28 `@INPUT@`.
29 - `@INPUT0@` `@INPUT1@` `...`: the full path to the input with the specified array index in `input`
30 - `@OUTPUT0@` `@OUTPUT1@` `...`: the full path to the output with the specified array index in `output`
31 - `@OUTDIR@`: the full path to the directory where the output(s) must be written
32 - `@DEPFILE@`: the full path to the dependency file passed to `depfile`
33 - `@PLAINNAME@`: the input filename, without a path
34 - `@PLAINNAME0@` `@PLAINNAME1@` `...` *(since 1.5.0)*: the input filename without a path, with the specified array index in `input`
35 - `@BASENAME@`: the input filename, with extension removed
36 - `@BASENAME0@` `@BASENAME1@` `...` *(since 1.5.0)*: the input filename with extension removed, with the specified array index in `input`
37 - `@PRIVATE_DIR@` *(since 0.50.1)*: path to a directory where the custom target must store all its intermediate files.
38 - `@SOURCE_ROOT@`: the path to the root of the source tree. Depending on the backend,
39 this may be an absolute or a relative to current workdir path.
40 - `@BUILD_ROOT@`: the path to the root of the build tree. Depending on the backend,
41 this may be an absolute or a relative to current workdir path.
42 - `@CURRENT_SOURCE_DIR@`: this is the directory where the currently
43 processed meson.build is located in. Depending on the backend,
44 this may be an absolute or a relative to current workdir path.
45
46 *(since 0.47.0)* The `depfile` keyword argument also accepts the
47 `@BASENAME@` and `@PLAINNAME@` substitutions.
48
49 The returned object also has methods that are documented in [[@custom_tgt]].
50
51 notes:
52 - |
53 Assuming that `command:` is executed by a POSIX `sh` shell
54 is not portable, notably to Windows. Instead, consider using a
55 `native: true` [[executable]], or a python script.
56
57 warnings:
58 - the `install_mode` kwarg ignored integer values between 0.60.0 -- 1.1.0.
59
60 optargs:
61 name:
62 type: str
63 description: |
64 The *unique* id of the custom target
65
66 This posarg is optional *since 0.60.0*. It defaults to the basename
67 of the first output.
68
69 kwargs:
70 build_by_default:
71 type: bool
72 since: 0.38.0
73 description: |
74 Causes, when set to true, to
75 have this target be built by default. This means it will be built when
76 `meson compile` is called without any arguments. The default value is `false`.
77
78 *(since 0.50.0)* If `build_by_default` is explicitly set to false, `install`
79 will no longer override it. If `build_by_default` is not set, `install` will
80 still determine its default.
81
82 build_always:
83 type: bool
84 deprecated: 0.47.0
85 description: |
86 If `true` this target is always considered out of
87 date and is rebuilt every time. Equivalent to setting both
88 `build_always_stale` and `build_by_default` to true.
89
90 build_always_stale:
91 type: bool
92 since: 0.47.0
93 default: false
94 description: |
95 If `true` the target is always considered out of date.
96 Useful for things such as build timestamps or revision control tags.
97 The associated command is run even if the outputs are up to date.
98
99 capture:
100 type: bool
101 default: false
102 description: |
103 There are some compilers that can't be told to write
104 their output to a file but instead write it to standard output. When
105 this argument is set to true, Meson captures `stdout` and writes it
106 to the target file. Note that your command argument list may not
107 contain `@OUTPUT@` when capture mode is active.
108
109 console:
110 type: bool
111 since: 0.48.0
112 description: |
113 Keyword argument conflicts with `capture`, and is meant
114 for commands that are resource-intensive and take a long time to
115 finish. With the Ninja backend, setting this will add this target
116 to [Ninja's `console` pool](https://ninja-build.org/manual.html#_the_literal_console_literal_pool),
117 which has special properties such as not buffering stdout and
118 serializing all targets in this pool.
119
120 command:
121 type: list[str | file | exe | external_program | custom_tgt | build_tgt | custom_idx]
122 description: |
123 Command to run to create outputs from inputs. The command
124 may be strings or the return value of functions that return file-like
125 objects such as [[find_program]],
126 [[executable]], [[configure_file]],
127 [[files]], [[custom_target]], etc.
128 Meson will automatically insert the appropriate dependencies on
129 targets and files listed in this keyword argument.
130 Note: always specify commands in array form `['commandname',
131 '-arg1', '-arg2']` rather than as a string `'commandname -arg1
132 -arg2'` as the latter will *not* work.
133
134 depend_files:
135 type: list[str | file]
136 description: |
137 files ([[@str]],
138 [[@file]], or the return value of [[configure_file]] that
139 this target depends on but are not listed in the `command` keyword
140 argument. Useful for adding regen dependencies.
141
142 depends:
143 type: list[build_tgt | custom_tgt | custom_idx]
144 description: |
145 Specifies that this target depends on the specified
146 target(s), even though it does not take any of them as a command
147 line argument. This is meant for cases where you have a tool that
148 e.g. does globbing internally. Usually you should just put the
149 generated sources as inputs and Meson will set up all dependencies
150 automatically (custom_idx was unavailable as a type between 0.60
151 and 1.4.0).
152
153 depfile:
154 type: str
155 description: |
156 A dependency file that the command can write listing
157 all the additional files this target depends on, for example a C
158 compiler would list all the header files it included, and a change
159 in any one of these files triggers a recompilation.
160
161 *(since 0.47.0)* the `@BASENAME@` and `@PLAINNAME@` substitutions
162 are also accepted.
163
164 input:
165 type: list[str | file | build_tgt | custom_idx | custom_tgt | external_program | extracted_obj | generated_list]
166 description: List of source files. *(since 0.41.0)* the list is flattened.
167
168 install:
169 type: bool
170 description: When true, one or more files of this target are installed during
171 the install step (see `install_dir` for details).
172
173 install_dir:
174 type: bool | str | list[bool | str]
175 description: |
176 If only one install_dir is provided, all outputs are installed there.
177 *Since 0.40.0* Allows you to specify the installation directory for each
178 corresponding output. For example:
179 ```meson
180 custom_target('different-install-dirs',
181 output : ['first.file', 'second.file'],
182 install : true,
183 install_dir : ['somedir', 'otherdir'])
184 ```
185 This would install `first.file` to `somedir` and `second.file` to `otherdir`.
186
187 To only install some outputs, pass `false` for the outputs that you
188 don't want installed. For example:
189 ```meson
190 custom_target('only-install-second',
191 output : ['first.file', 'second.file'],
192 install : true,
193 install_dir : [false, 'otherdir'])
194 ```
195 This would install `second.file` to `otherdir` and not install `first.file`.
196
197 install_mode:
198 type: list[str | int | bool]
199 since: 0.47.0
200 description: |
201 The file mode and optionally the owner/uid and group/gid.
202 See the `install_mode` kwarg of [[install_data]] for more information.
203
204 install_tag:
205 type: list[str | bool]
206 since: 0.60.0
207 description: |
208 A list of strings, one per output, used by the `meson install --tags` command
209 to install only a subset of the files.
210
211 By default all outputs have no install tag which means they are not being
212 installed when `--tags` argument is specified. If only one tag is specified,
213 it is assumed that all outputs have the same tag. `false` can be used for
214 outputs that have no tag or are not installed.
215
216 output:
217 type: list[str]
218 description: List of output files.
219
220 env:
221 since: 0.57.0
222 type: env | list[str] | dict[str]
223 description: |
224 environment variables to set, such as
225 `{'NAME1': 'value1', 'NAME2': 'value2'}` or `['NAME1=value1', 'NAME2=value2']`,
226 or an [[@env]] object which allows more
227 sophisticated environment juggling.
228
229 feed:
230 type: bool
231 since: 0.59.0
232 default: false
233 description: |
234 There are some compilers that can't be told to read
235 their input from a file and instead read it from standard input. When this
236 argument is set to `true`, Meson feeds the input file to `stdin`. Note that
237 your argument list may not contain `@INPUT@` when feed mode is active.