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