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