custom_target()

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.

custom_target('foo', output: 'file.txt', ...)

The files passed to output: cannot contain path separators. See the manual on custom build targets for an explanation on where output files should be placed.

You can install the outputted files with the install_dir: kwarg, see below.

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

Signature

# Create a custom top level build target
custom_tgt custom_target(
  str [name],   # The *unique* id of the custom target

  # Keyword arguments:
  build_always       : bool                                        # If `true` this target is always considered out of
  build_always_stale : bool                                        # If `true` the target is always considered out of date
  build_by_default   : bool                                        # Causes, when set to true, to
  capture            : bool                                        # There are some compilers that can't be told to write
  command            : array[str | file | exe | external_program]  # Command to run to create outputs from inputs
  console            : bool                                        # Keyword argument conflicts with `capture`, and is meant
  depend_files       : array[str | file]                           # files (str,
  depends            : array[build_tgt | custom_tgt | custom_idx]  # Specifies that this target depends on the specified
  depfile            : str                                         # A dependency file that the command can write listing
  env                : env | array[str] | dict[str]                # environment variables to set, such as
  feed               : bool                                        # There are some compilers that can't be told to read
  input              : array[str | file]                           # Array of source files
  install            : bool                                        # When true, one or more files of this target are installed during the install step (see `install_dir` for details)
  install_dir        : str | array[str | bool]                     # If only one install_dir is provided, all outputs are installed there
  install_mode       : array[str | int]                            # The file mode and optionally the owner/uid and group/gid
  install_tag        : array[str]                                  # An array of strings, one per output, used by the `meson install --tags` command
  output             : array[str]                                  # Array of output files
)

Arguments

The function custom_target() accepts the following positional arguments:

Name Type Description Tags
name str

The unique id of the custom target

This posarg is optional since 0.60.0. It defaults to the basename of the first output.

[optional]

Finally, custom_target() accepts the following keyword arguments:

Name Type Description Tags
build_always bool

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.

DEPRECATED

in 0.47.0
build_always_stale bool

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.

(since 0.47.0)

default = false
build_by_default bool

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.

(since 0.38.0)
capture bool

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 array may not contain @OUTPUT@ when capture mode is active.

default = false
command array[str | file | exe | external_program]

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

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, which has special properties such as not buffering stdout and serializing all targets in this pool.

(since 0.48.0)
depend_files array[str | file]

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 array[build_tgt | custom_tgt | custom_idx]

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 str

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.
env env | array[str] | dict[str]

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.

(since 0.57.0)
feed bool

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 array may not contain @INPUT@ when feed mode is active.

(since 0.59.0)

default = false
input array[str | file]

Array of source files. (since 0.41.0) the array is flattened.
install bool

When true, one or more files of this target are installed during the install step (see install_dir for details).
install_dir str | array[str | bool]

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:

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:

    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 array[str | int]

The file mode and optionally the owner/uid and group/gid. See the install_mode kwarg of install_data() for more information.

(since 0.47.0)
install_tag array[str]

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

(since 0.60.0)
output array[str]

Array of output files. These cannot contain path separators.

The results of the search are