The Meson Build System
http://mesonbuild.com/
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
213 lines
8.4 KiB
213 lines
8.4 KiB
name: custom_target |
|
returns: custom_tgt |
|
description: | |
|
Create a custom top level build target. The only positional argument |
|
is the name of this target and the keyword arguments are the |
|
following. |
|
|
|
The list of strings passed to the `command` keyword argument accept |
|
the following special string substitutions: |
|
|
|
- `@INPUT@`: the full path to the input passed to `input`. If more than |
|
one input is specified, all of them will be substituted as separate |
|
arguments only if the command uses `'@INPUT@'` as a |
|
standalone-argument. For instance, this would not work: `command : |
|
['cp', './@INPUT@']`, but this would: `command : ['cp', '@INPUT@']`. |
|
- `@OUTPUT@`: the full path to the output passed to `output`. If more |
|
than one outputs are specified, the behavior is the same as |
|
`@INPUT@`. |
|
- `@INPUT0@` `@INPUT1@` `...`: the full path to the input with the specified array index in `input` |
|
- `@OUTPUT0@` `@OUTPUT1@` `...`: the full path to the output with the specified array index in `output` |
|
- `@OUTDIR@`: the full path to the directory where the output(s) must be written |
|
- `@DEPFILE@`: the full path to the dependency file passed to `depfile` |
|
- `@PLAINNAME@`: the input filename, without a path |
|
- `@BASENAME@`: the input filename, with extension removed |
|
- `@PRIVATE_DIR@` *(since 0.50.1)*: path to a directory where the custom target must store all its intermediate files. |
|
- `@SOURCE_ROOT@`: the path to the root of the source tree. Depending on the backend, |
|
this may be an absolute or a relative to current workdir path. |
|
- `@BUILD_ROOT@`: the path to the root of the build tree. Depending on the backend, |
|
this may be an absolute or a relative to current workdir path. |
|
- `@CURRENT_SOURCE_DIR@`: this is the directory where the currently |
|
processed meson.build is located in. Depending on the backend, |
|
this may be an absolute or a relative to current workdir path. |
|
|
|
*(since 0.47.0)* The `depfile` keyword argument also accepts the |
|
`@BASENAME@` and `@PLAINNAME@` substitutions. |
|
|
|
The returned object also has methods that are documented in [[@custom_tgt]]. |
|
|
|
notes: |
|
- | |
|
Assuming that `command:` is executed by a POSIX `sh` shell |
|
is not portable, notably to Windows. Instead, consider using a |
|
`native: true` [[executable]], or a python script. |
|
|
|
posargs: |
|
name: |
|
type: str |
|
description: The *unique* id of the custom target |
|
|
|
kwargs: |
|
build_by_default: |
|
type: bool |
|
since: 0.38.0 |
|
description: | |
|
Causes, when set to true, to |
|
have this target be built by default. This means it will be built when |
|
`meson compile` is called without any arguments. The default value is `false`. |
|
|
|
*(since 0.50.0)* If `build_by_default` is explicitly set to false, `install` |
|
will no longer override it. If `build_by_default` is not set, `install` will |
|
still determine its default. |
|
|
|
build_always: |
|
type: bool |
|
deprecated: 0.47.0 |
|
description: | |
|
If `true` this target is always considered out of |
|
date and is rebuilt every time. Equivalent to setting both |
|
`build_always_stale` and `build_by_default` to true. |
|
|
|
build_always_stale: |
|
type: bool |
|
since: 0.47.0 |
|
default: false |
|
description: | |
|
If `true` the target is always considered out of date. |
|
Useful for things such as build timestamps or revision control tags. |
|
The associated command is run even if the outputs are up to date. |
|
|
|
capture: |
|
type: bool |
|
default: false |
|
description: | |
|
There are some compilers that can't be told to write |
|
their output to a file but instead write it to standard output. When |
|
this argument is set to true, Meson captures `stdout` and writes it |
|
to the target file. Note that your command argument list may not |
|
contain `@OUTPUT@` when capture mode is active. |
|
|
|
console: |
|
type: bool |
|
since: 0.48.0 |
|
description: | |
|
Keyword argument conflicts with `capture`, and is meant |
|
for commands that are resource-intensive and take a long time to |
|
finish. With the Ninja backend, setting this will add this target |
|
to [Ninja's `console` pool](https://ninja-build.org/manual.html#_the_literal_console_literal_pool), |
|
which has special properties such as not buffering stdout and |
|
serializing all targets in this pool. |
|
|
|
command: |
|
type: list[str | file | exe | external_program] |
|
description: | |
|
Command to run to create outputs from inputs. The command |
|
may be strings or the return value of functions that return file-like |
|
objects such as [[find_program]], |
|
[[executable]], [[configure_file]], |
|
[[files]], [[custom_target]], etc. |
|
Meson will automatically insert the appropriate dependencies on |
|
targets and files listed in this keyword argument. |
|
Note: always specify commands in array form `['commandname', |
|
'-arg1', '-arg2']` rather than as a string `'commandname -arg1 |
|
-arg2'` as the latter will *not* work. |
|
|
|
depend_files: |
|
type: list[str | file] |
|
description: | |
|
files ([[@str]], |
|
[[@file]], or the return value of [[configure_file]] that |
|
this target depends on but are not listed in the `command` keyword |
|
argument. Useful for adding regen dependencies. |
|
|
|
depends: |
|
type: list[tgt] |
|
description: | |
|
Specifies that this target depends on the specified |
|
target(s), even though it does not take any of them as a command |
|
line argument. This is meant for cases where you have a tool that |
|
e.g. does globbing internally. Usually you should just put the |
|
generated sources as inputs and Meson will set up all dependencies |
|
automatically. |
|
|
|
depfile: |
|
type: str |
|
description: | |
|
A dependency file that the command can write listing |
|
all the additional files this target depends on, for example a C |
|
compiler would list all the header files it included, and a change |
|
in any one of these files triggers a recompilation. |
|
|
|
input: |
|
type: list[str | file] |
|
description: List of source files. *(since 0.41.0)* the list is flattened. |
|
|
|
install: |
|
type: bool |
|
description: When true, this target is installed during the install step. |
|
|
|
install_dir: |
|
type: str | list[str] |
|
description: | |
|
If only one install_dir is provided, all outputs are installed there. |
|
*Since 0.40.0* Allows you to specify the installation directory for each |
|
corresponding output. For example: |
|
```meson |
|
custom_target('different-install-dirs', |
|
output : ['first.file', 'second.file'], |
|
install : true, |
|
install_dir : ['somedir', 'otherdir]) |
|
``` |
|
This would install `first.file` to `somedir` and `second.file` to `otherdir`. |
|
|
|
To only install some outputs, pass `false` for the outputs that you |
|
don't want installed. For example: |
|
```meson |
|
custom_target('only-install-second', |
|
output : ['first.file', 'second.file'], |
|
install : true, |
|
install_dir : [false, 'otherdir]) |
|
``` |
|
This would install `second.file` to `otherdir` and not install `first.file`. |
|
|
|
install_mode: |
|
type: list[str | int] |
|
since: 0.47.0 |
|
description: | |
|
The file mode and optionally the owner/uid and group/gid. |
|
See the `install_mode` kwarg of [[install_data]] for more information. |
|
|
|
install_tag: |
|
type: list[str] |
|
since: 0.60.0 |
|
description: | |
|
A list of strings, one per output, used by the `meson install --tags` command |
|
to install only a subset of the files. |
|
|
|
By default all outputs have no install tag which means they are not being |
|
installed when `--tags` argument is specified. If only one tag is specified, |
|
it is assumed that all outputs have the same tag. `false` can be used for |
|
outputs that have no tag or are not installed. |
|
|
|
output: |
|
type: list[str] |
|
description: List of output files. |
|
|
|
env: |
|
since: 0.57.0 |
|
type: env | list[str] | dict[str] |
|
description: | |
|
environment variables to set, such as |
|
`{'NAME1': 'value1', 'NAME2': 'value2'}` or `['NAME1=value1', 'NAME2=value2']`, |
|
or an [[@env]] object which allows more |
|
sophisticated environment juggling. |
|
|
|
feed: |
|
type: bool |
|
since: 0.59.0 |
|
default: false |
|
description: | |
|
There are some compilers that can't be told to read |
|
their input from a file and instead read it from standard input. When this |
|
argument is set to `true`, Meson feeds the input file to `stdin`. Note that |
|
your argument list may not contain `@INPUT@` when feed mode is active.
|
|
|