name: generator
returns: generator
description: |
  See also: [[custom_target]]

  This function creates a [[@generator]] object that can
  be used to run custom compilation commands. The only positional
  argument is the executable to use. It can either be a self-built
  executable or one returned by find_program.

  The template strings passed to all the keyword arguments accept
  the following special substitutions:

  - `@PLAINNAME@`: the complete input file name, e.g: `foo.c` becomes `foo.c` (unchanged)
  - `@BASENAME@`: the base of the input filename, e.g.: `foo.c.y` becomes `foo.c` (extension is removed)

  Each string passed to the `output` keyword argument *must* be
  constructed using one or both of these two substitutions.

  In addition to the above substitutions, the `arguments` keyword
  argument also accepts the following:

  - `@OUTPUT@`: the full path to the output file
  - `@INPUT@`: the full path to the input file
  - `@DEPFILE@`: the full path to the depfile
  - `@SOURCE_DIR@`: the full path to the root of the source tree
  - `@CURRENT_SOURCE_DIR@`: this is the directory where the currently processed meson.build is located in
  - `@BUILD_DIR@`: the full path to the root of the build dir where the output will be placed

  NOTE: Generators should only be used for outputs that will ***only***
  be used as inputs for a [[build_target]] or a [[custom_target]].
  When you use the processed output of a
  generator in multiple targets, the generator will be run multiple
  times to create outputs for each target. Each output will be created
  in a target-private directory `@BUILD_DIR@`.

  If you want to generate files for general purposes such as for
  generating headers to be used by several sources, or data that will be
  installed, and so on, use a [[custom_target]] instead.

posargs:
  exe:
    type: exe | program
    description: Executable for the command to run

kwargs:
  arguments:
    type: array[str]
    description: An array of template strings that will be the command line arguments passed to the executable.

  depends:
    # Not sure why this is not just `target`
    type: array[build_tgt | custom_tgt | custom_idx | program]
    since: 0.51.0
    description: |
      An array of build targets that must be built before
      this generator can be run. This is used if you have a generator that calls
      a second executable that is built in this project (custom_idx was not
      available between 0.60 and 1.4.0).  `program` is supported *since 1.11.2*.

  depfile:
    type: str
    description: |
      A template string pointing to a dependency file that a
      generator 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,

  output:
    type: array[str]
    description: |
      Template string (or array of template strings) defining
      how an output file name is (or multiple output names are) generated
      from a single source file name.

  capture:
    type: bool
    default: false
    since: 0.43.0
    description: |
      When this argument is set to true, Meson captures `stdout`
      of the `executable` and writes it to the target file
      specified as `output`.