docs/yaml/functions/custom_target.yaml - meson - Git at Google

 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`. However, `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
   - `@PLAINNAME0@` `@PLAINNAME1@` `...` *(since 1.5.0)*: the input filename without a path, with the specified array index in `input`
   - `@BASENAME@`: the input filename, with extension removed
   - `@BASENAME0@` `@BASENAME1@` `...` *(since 1.5.0)*: the input filename with extension removed, with the specified array index in `input`
   - `@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.

 warnings:
   - the `install_mode` kwarg ignored integer values between 0.60.0 -- 1.1.0.

 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[build_tgt | custom_tgt | custom_idx]
     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 (custom_idx was unavailable as a type between 0.60
       and 1.4.0).

   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, one or more files of this target are installed during
       the install step (see `install_dir` for details).

   install_dir:
     type: str | list[str | bool]
     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.
	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`. However, `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
	- `@PLAINNAME0@` `@PLAINNAME1@` `...` (since 1.5.0): the input filename without a path, with the specified array index in `input`
	- `@BASENAME@`: the input filename, with extension removed
	- `@BASENAME0@` `@BASENAME1@` `...` (since 1.5.0): the input filename with extension removed, with the specified array index in `input`
	- `@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.

	warnings:
	- the `install_mode` kwarg ignored integer values between 0.60.0 -- 1.1.0.

	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[build_tgt \| custom_tgt \| custom_idx]
	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 (custom_idx was unavailable as a type between 0.60
	and 1.4.0).

	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, one or more files of this target are installed during
	the install step (see `install_dir` for details).

	install_dir:
	type: str \| list[str \| bool]
	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.