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 cannot contain path separators (`/` or `\`). The name of custom target might not be used by every backends, for instance with the Ninja backend, `subdir/meson.build` containing the example below, `ninja -C builddir foo` or `ninja -C builddir subdir/foo` won't work, it is instead `ninja -C builddir subdir/file.txt`. Howerver, `meson compile subdir/foo` is accepted. ```meson custom_target('foo', output: 'file.txt', ...) ``` *Since 0.60.0* the name argument is optional and defaults to the basename of the first output (`file.txt` in the example above). 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. optargs: name: type: str description: | The *unique* id of the custom target This posarg is optional *since 0.60.0*. It defaults to the basename of the first output. 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. *(since 0.47.0)* the `@BASENAME@` and `@PLAINNAME@` substitutions are also accepted. 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.