Debian Codegraph @

subprojects/meson-docs/docs/yaml/functions/generator.yaml

raw
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`.