Debian Codegraph @

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

raw
1 name: configure_file
2 returns: file
3 description: |
4 This function can run in three modes depending on the keyword arguments
5 passed to it.
6
7 When a [[@cfg_data]] object is passed
8 to the `configuration:` keyword argument, it takes a template file as
9 the `input:` (optional) and produces the `output:` (required) by
10 substituting values from the configuration data as detailed in [the
11 configuration file documentation](Configuration.md). *(since 0.49.0)*
12 A dictionary can be passed instead of a
13 [[@cfg_data]] object.
14
15 When a list of strings is passed to the `command:` keyword argument,
16 it takes any source or configured file as the `input:` and assumes
17 that the `output:` is produced when the specified command is run.
18
19 *(since 0.47.0)* When the `copy:` keyword argument is set to `true`,
20 this function will copy the file provided in `input:` to a file in the
21 build directory with the name `output:` in the current directory.
22
23 warnings:
24 - the `install_mode` kwarg ignored integer values between 0.62 -- 1.1.0.
25
26 kwargs:
27 capture:
28 type: bool
29 since: 0.41.0
30 default: false
31 description: |
32 When this argument is set to true,
33 Meson captures `stdout` of the `command` and writes it to the target
34 file specified as `output`.
35
36 command:
37 type: list[str | file | compiler | external_program | exe]
38 description: |
39 As explained above, if specified, Meson does not create
40 the file itself but rather runs the specified command, which allows
41 you to do fully custom file generation. *(since 0.52.0)* The command can contain
42 file objects and more than one file can be passed to the `input` keyword
43 argument, see [[custom_target]] for details about string
44 substitutions.
45
46 configuration:
47 type: "cfg_data | dict[str | int | bool]"
48 description: |
49 As explained above, when passed this will provide the replacement
50 data for the input file (if provided) or key value pairs to be
51 written to the output.
52
53 copy:
54 type: bool
55 default: false
56 since: 0.47.0
57 description: |
58 As explained above, if specified Meson only
59 copies the file from input to output.
60
61 depfile:
62 type: str
63 since: 0.52.0
64 description: |
65 A dependency file that the command can write listing
66 all the additional files this target depends on. A change
67 in any one of these files triggers a reconfiguration.
68
69 format:
70 type: str
71 since: 0.46.0
72 default: "'meson'"
73 description: |
74 The format of defines. It defaults to `'meson'`, and so substitutes
75 `#mesondefine` statements and variables surrounded by `@` characters, you can also use `'cmake'`
76 to replace `#cmakedefine` statements and variables with the `${variable}` syntax. Finally you can use
77 `'cmake@'` in which case substitutions will apply on `#cmakedefine` statements and variables with
78 the `@variable@` syntax.
79
80 input:
81 type: str | file
82 description: |
83 The input file name. If it's not specified in configuration
84 mode, all the variables in the `configuration:` object (see above)
85 are written to the `output:` file.
86
87 install:
88 type: bool
89 default: false
90 since: 0.50.0
91 description: |
92 When true, this generated file is installed during
93 the install step, and `install_dir` must be set and not empty. When false, this
94 generated file is not installed regardless of the value of `install_dir`.
95 When omitted it defaults to true when `install_dir` is set and not empty,
96 false otherwise.
97
98 install_dir:
99 type: str | bool
100 description: |
101 The subdirectory to install the generated file to
102 (e.g. `share/myproject`), if omitted or given the value of empty
103 string, the file is not installed.
104
105 install_mode:
106 type: list[str | int | bool]
107 since: 0.47.0
108 description: |
109 Specify the file mode in symbolic format
110 and optionally the owner/uid and group/gid for the installed files.
111
112 See the `install_mode` kwarg of [[install_data]] for more information.
113
114 install_tag:
115 type: str
116 since: 0.60.0
117 description: |
118 A string used by the `meson install --tags` command
119 to install only a subset of the files. By default the file has no install
120 tag which means it is not being installed when `--tags` argument is specified.
121
122 output:
123 type: str
124 description: |
125 The output file name. *(since 0.41.0)* may contain
126 `@PLAINNAME@` or `@BASENAME@` substitutions, as well as *(since 1.5.0)*
127 their indexed versions, like `@PLAINNAME0@` or `@BASENAME0@`.
128 In configuration mode,
129 the permissions of the input file (if it is specified) are copied to
130 the output file.
131
132 output_format:
133 type: str
134 since: 0.47.0
135 description: |
136 The format of the output to generate when no input
137 was specified. It defaults to `c`, in which case preprocessor directives
138 will be prefixed with `#`, you can also use `nasm`, in which case the
139 prefix will be `%`. *(since 1.3.0)* `json` format can also be used.
140
141 encoding:
142 type: str
143 default: "'utf-8'"
144 since: 0.47.0
145 description: |
146 Set the file encoding for the input and output file.
147 The supported encodings are those of python3, see
148 [standard-encodings](https://docs.python.org/3/library/codecs.html#standard-encodings).
149
150 macro_name:
151 type: str
152 since: 1.3.0
153 description: |
154 When specified, macro guards will be used instead of '#pragma once'. The
155 macro guard name will be the specified name.