Debian Codegraph @

subprojects/meson-docs/docs/markdown/Rewriter.md

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