| 1 |
name: generator |
| 2 |
returns: generator |
| 3 |
description: | |
| 4 |
See also: [[custom_target]] |
| 5 |
|
| 6 |
This function creates a [[@generator]] object that can |
| 7 |
be used to run custom compilation commands. The only positional |
| 8 |
argument is the executable to use. It can either be a self-built |
| 9 |
executable or one returned by find_program. |
| 10 |
|
| 11 |
The template strings passed to all the keyword arguments accept |
| 12 |
the following special substitutions: |
| 13 |
|
| 14 |
- `@PLAINNAME@`: the complete input file name, e.g: `foo.c` becomes `foo.c` (unchanged) |
| 15 |
- `@BASENAME@`: the base of the input filename, e.g.: `foo.c.y` becomes `foo.c` (extension is removed) |
| 16 |
|
| 17 |
Each string passed to the `output` keyword argument *must* be |
| 18 |
constructed using one or both of these two substitutions. |
| 19 |
|
| 20 |
In addition to the above substitutions, the `arguments` keyword |
| 21 |
argument also accepts the following: |
| 22 |
|
| 23 |
- `@OUTPUT@`: the full path to the output file |
| 24 |
- `@INPUT@`: the full path to the input file |
| 25 |
- `@DEPFILE@`: the full path to the depfile |
| 26 |
- `@SOURCE_DIR@`: the full path to the root of the source tree |
| 27 |
- `@CURRENT_SOURCE_DIR@`: this is the directory where the currently processed meson.build is located in |
| 28 |
- `@BUILD_DIR@`: the full path to the root of the build dir where the output will be placed |
| 29 |
|
| 30 |
NOTE: Generators should only be used for outputs that will ***only*** |
| 31 |
be used as inputs for a [[build_target]] or a [[custom_target]]. |
| 32 |
When you use the processed output of a |
| 33 |
generator in multiple targets, the generator will be run multiple |
| 34 |
times to create outputs for each target. Each output will be created |
| 35 |
in a target-private directory `@BUILD_DIR@`. |
| 36 |
|
| 37 |
If you want to generate files for general purposes such as for |
| 38 |
generating headers to be used by several sources, or data that will be |
| 39 |
installed, and so on, use a [[custom_target]] instead. |
| 40 |
|
| 41 |
posargs: |
| 42 |
exe: |
| 43 |
type: exe | external_program |
| 44 |
description: Executable for the command to run |
| 45 |
|
| 46 |
kwargs: |
| 47 |
arguments: |
| 48 |
type: list[str] |
| 49 |
description: A list of template strings that will be the command line arguments passed to the executable. |
| 50 |
|
| 51 |
depends: |
| 52 |
# Not sure why this is not just `target` |
| 53 |
type: list[build_tgt | custom_tgt | custom_idx] |
| 54 |
since: 0.51.0 |
| 55 |
description: | |
| 56 |
An array of build targets that must be built before |
| 57 |
this generator can be run. This is used if you have a generator that calls |
| 58 |
a second executable that is built in this project (custom_idx was not |
| 59 |
available between 0.60 and 1.4.0). |
| 60 |
|
| 61 |
depfile: |
| 62 |
type: str |
| 63 |
description: | |
| 64 |
A template string pointing to a dependency file that a |
| 65 |
generator can write listing all the additional files this target |
| 66 |
depends on, for example a C compiler would list all the header files |
| 67 |
it included, and a change in any one of these files triggers a |
| 68 |
recompilation, |
| 69 |
|
| 70 |
output: |
| 71 |
type: list[str] |
| 72 |
description: | |
| 73 |
Template string (or list of template strings) defining |
| 74 |
how an output file name is (or multiple output names are) generated |
| 75 |
from a single source file name. |
| 76 |
|
| 77 |
capture: |
| 78 |
type: bool |
| 79 |
default: false |
| 80 |
since: 0.43.0 |
| 81 |
description: | |
| 82 |
When this argument is set to true, Meson captures `stdout` |
| 83 |
of the `executable` and writes it to the target file |
| 84 |
specified as `output`. |