1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
---
short-description: Automatic modification of the build system files
...
# Meson file rewriter
Since version 0.50.0, meson has the functionality to perform some basic
modification on the `meson.build` files from the command line. The currently
supported operations are:
- For build targets:
- Add/Remove source files
- Add/Remove targets
- Modify a select set of kwargs
- Print some JSON information
- For dependencies:
- Modify a select set of kwargs
- For the project function:
- Modify a select set of kwargs
- Modify the default options list
The rewriter has both, a normal command line interface and a "script mode". The
normal CLI is mostly designed for everyday use. The "script mode", on the
other hand, is meant to be used by external programs (IDEs, graphical
frontends, etc.)
The rewriter itself is considered stable, however the user interface and the
"script mode" API might change in the future. These changes may also break
backwards comaptibility to older releases.
We are also open to suggestions for API improvements.
## Using the rewriter
All rewriter functions are accessed via `meson rewrite`. The meson rewriter
assumes that it is run inside the project root directory. If this isn't the
case, use `--sourcedir` to specify the actual project source directory.
### Adding and removing sources
The most common operations will probably be the adding and removing of source
files to a build target. This can be easily done with:
```bash
meson rewrite target <target name/id> {add/rm} [list of sources]
```
For instance, given the following example
```meson
src = ['main.cpp', 'fileA.cpp']
exe1 = executable('testExe', src)
```
the source `fileB.cpp` can be added with:
```bash
meson rewrite target testExe add fileB.cpp
```
After executing this command, the new `meson.build` will look like this:
```meson
src = ['main.cpp', 'fileA.cpp', 'fileB.cpp']
exe1 = executable('testExe', src)
```
In this case, `exe1` could also have been used for the target name. This is
possible because the rewriter also searches for assignments and unique meson
IDs, which can be acquired with introspection. If there are multiple targets
with the same name, meson will do nothing and print an error message.
For more information see the help output of the rewriter target command.
### Setting the project version
It is also possible to set kwargs of specific functions with the rewriter. The
general command for setting or removing kwargs is:
```bash
meson rewrite kwargs {set/delete} <function type> <function ID> <key1> <value1> <key2> <value2> ...
```
For instance, setting the project version can be achieved with this command:
```bash
meson rewrite kwargs set project / version 1.0.0
```
Currently, only the following function types are supported:
- dependency
- target (any build target, the function ID is the target name/ID)
- project (the function ID must be `/` since project() can only be called once)
For more information see the help output of the rewrite kwargs command.
### Setting the project default options
For setting and deleting default options, use the following command:
```bash
meson rewrite default-options {set/delete} <opt1> <value1> <opt2> <value2> ...
```
## Limitations
Rewriting a meson file is not guaranteed to keep the indentation of the modified
functions. Additionally, comments inside a modified statement will be removed.
Furthermore, all source files will be sorted alphabetically.
For instance adding `e.c` to srcs in the following code
```meson
# Important comment
srcs = [
'a.c', 'c.c', 'f.c',
# something important about b
'b.c', 'd.c', 'g.c'
]
# COMMENT
```
would result in the following code:
```meson
# Important comment
srcs = [
'a.c',
'b.c',
'c.c',
'd.c',
'e.c',
'f.c',
'g.c'
]
# COMMENT
```
## Using the "script mode"
The "script mode" should be the preferred API for third party programs, since
it offers more flexibility and higher API stability. The "scripts" are stored
in JSON format and executed with `meson rewrite command <JSON file or string>`.
The JSON format is defined as follows:
```json
[
{
"type": "function to execute",
...
}, {
"type": "other function",
...
},
...
]
```
Each object in the main array must have a `type` entry which specifies which
function should be executed.
Currently, the following functions are supported:
- target
- kwargs
- default_options
### Target modification format
The format for the type `target` is defined as follows:
```json
{
"type": "target",
"target": "target ID/name/assignment variable",
"operation": "one of ['src_add', 'src_rm', 'target_rm', 'target_add', 'info']",
"sources": ["list", "of", "source", "files", "to", "add, remove"],
"subdir": "subdir where the new target should be added (only has an effect for operation 'tgt_add')",
"target_type": "function name of the new target -- same as in the CLI (only has an effect for operation 'tgt_add')"
}
```
The keys `sources`, `subdir` and `target_type` are optional.
### kwargs modification format
The format for the type `target` is defined as follows:
```json
{
"type": "kwargs",
"function": "one of ['dependency', 'target', 'project']",
"id": "function ID",
"operation": "one of ['set', 'delete', 'add', 'remove', 'remove_regex', 'info']",
"kwargs": {
"key1": "value1",
"key2": "value2",
...
}
}
```
### Default options modification format
The format for the type `default_options` is defined as follows:
```json
{
"type": "default_options",
"operation": "one of ['set', 'delete']",
"options": {
"opt1": "value1",
"opt2": "value2",
...
}
}
```
For operation `delete`, the values of the `options` can be anything (including `null`)
## Extracting information
The rewriter also offers operation `info` for the types `target` and `kwargs`.
When this operation is used, meson will print a JSON dump to stderr, containing
all available information to the rewriter about the build target / function
kwargs in question.
The output format is currently experimental and may change in the future.
|
