Debian Codegraph @

subprojects/meson-docs/docs/markdown/IDE-integration.md

raw
1 ---
2 short-description: Meson's API to integrate Meson support into an IDE
3 ...
4
5 # IDE integration
6
7 Meson has exporters for Visual Studio and XCode, but writing a custom
8 backend for every IDE out there is not a scalable approach. To solve
9 this problem, Meson provides an API that makes it easy for any IDE or
10 build tools to integrate Meson builds and provide an experience
11 comparable to a solution native to the IDE.
12
13 All the resources required for such a IDE integration can be found in
14 the `meson-info` directory in the build directory.
15
16 The first thing to do when setting up a Meson project in an IDE is to
17 select the source and build directories. For this example we assume
18 that the source resides in an Eclipse-like directory called
19 `workspace/project` and the build tree is nested inside it as
20 `workspace/project/build`. First, we initialize Meson by running the
21 following command in the source directory.
22
23 meson setup builddir
24
25 With this command Meson will configure the project and also generate
26 introspection information that is stored in `intro-*.json` files in
27 the `meson-info` directory. The introspection dump will be
28 automatically updated when Meson is (re)configured, or the build
29 options change. Thus, an IDE can watch for changes in this directory
30 to know when something changed. Note that `meson-info.json` guaranteed
31 to be the last file written.
32
33 The `meson-info` directory should contain the following files:
34
35 | File | Description |
36 | ------------------------------ | ----------------------------------------------------------------------------- |
37 | `intro-benchmarks.json` | Lists all benchmarks |
38 | `intro-buildoptions.json` | Contains a full list of Meson configuration options for the project |
39 | `intro-buildsystem_files.json` | Full list of all Meson build files |
40 | `intro-dependencies.json` | Lists all dependencies used in the project |
41 | `intro-installed.json` | Contains mapping of files to their installed location |
42 | `intro-install_plan.json` | Dictionary of data types with the source files and their installation details |
43 | `intro-projectinfo.json` | Stores basic information about the project (name, version, etc.) |
44 | `intro-targets.json` | Full list of all build targets |
45 | `intro-tests.json` | Lists all tests with instructions how to run them |
46
47 The content of the JSON files is further specified in the remainder of
48 this document.
49
50 ## The `targets` section
51
52 The most important file for an IDE is probably `intro-targets.json`.
53 Here each target with its sources and compiler parameters is
54 specified. The JSON format for one target is defined as follows:
55
56 ```json
57 {
58 "name": "Name of the target",
59 "id": "The internal ID meson uses",
60 "type": "<TYPE>",
61 "defined_in": "/Path/to/the/targets/meson.build",
62 "subproject": null,
63 "filename": ["list", "of", "generated", "files"],
64 "build_by_default": true / false,
65 "target_sources": [],
66 "extra_files": ["/path/to/file1.hpp", "/path/to/file2.hpp"],
67 "installed": true / false,
68 }
69 ```
70
71 If the key `installed` is set to `true`, the key `install_filename`
72 will also be present. It stores the installation location for each
73 file in `filename`. If one file in `filename` is not installed, its
74 corresponding install location is set to `null`.
75
76 The `subproject` key specifies the name of the subproject this target
77 was defined in, or `null` if the target was defined in the top level
78 project.
79
80 *(New in 0.56.0)* The `extra_files` key lists all files specified via
81 the `extra_files` kwarg of a build target. See
82 [[executable]].
83
84 A target usually generates only one file. However, it is possible for
85 custom targets to have multiple outputs.
86
87 ### Target sources
88
89 The `intro-targets.json` file also stores a list of all source objects
90 of the target in the `target_sources`. With this information, an IDE
91 can provide code completion for all source files.
92
93 ```json
94 {
95 "language": "language ID",
96 "machine": "build" / "host",
97 "compiler": ["The", "compiler", "command"],
98 "parameters": ["list", "of", "compiler", "parameters"],
99 "sources": ["list", "of", "all", "source", "files", "for", "this", "language"],
100 "generated_sources": ["list", "of", "all", "source", "files", "that", "where", "generated", "somewhere", "else"]
101 }
102 ```
103
104 *(New in 1.7.0)* The `machine` and `language` keys make it possible to
105 to access further information about the compiler in the `compilers`
106 introspection information. `machine` can be absent if `language` is
107 `unknown`. In this case, information about the compiler is not
108 available; Meson is therefore unable to know if the output relates
109 to either the build of the host machine.
110
111 It should be noted that the compiler parameters stored in the
112 `parameters` differ from the actual parameters used to compile the
113 file. This is because the parameters are optimized for the usage in an
114 IDE to provide autocompletion support, etc. It is thus not recommended
115 to use this introspection information for actual compilation.
116
117 ### Possible values for `type`
118
119 The following table shows all valid types for a target.
120
121 | value of `type` | Description |
122 | ---------------- | --------------------------------------------------------------------------------------------- |
123 | `executable` | This target will generate an executable file |
124 | `static library` | Target for a static library |
125 | `shared library` | Target for a shared library |
126 | `shared module` | A shared library that is meant to be used with dlopen rather than linking into something else |
127 | `custom` | A custom target |
128 | `run` | A Meson run target |
129 | `jar` | A Java JAR target |
130
131
132 ### Install plan
133
134 The `intro-install_plan.json` file contains a list of the files that are going
135 to be installed on the system.
136
137 The data contains a list of files grouped by data type. Each file maps to a
138 dictionary containing the `destination` and `tag` keys, with the key being the
139 file location at build time. `destination` is the destination path using
140 placeholders for the base directories. New keys may be added in the future.
141
142 ```json
143 {
144 "targets": {
145 "/path/to/project/builddir/some_executable": {
146 "destination": "{bindir}/some_executable",
147 "tag": "runtime"
148 },
149 "/path/to/project/builddir/libsomelib.so": {
150 "destination": "{libdir_shared}/libsomelib.so",
151 "tag": "runtime"
152 }
153 },
154 "data": {
155 "/path/to/project/some_data": {
156 "destination": "{datadir}/some_data",
157 "tag": null
158 }
159 },
160 "headers": {
161 "/path/to/project/some_header.h": {
162 "destination": "{includedir}/some_header.h",
163 "tag": "devel"
164 }
165 }
166 }
167 ```
168
169 Additionally, the `intro-installed.json` file contains the mapping of the
170 file path at build time to the absolute system location.
171
172 ```json
173 {
174 "/path/to/project/builddir/some_executable": "/usr/bin/some_executable",
175 "/path/to/project/builddir/libsomelib.so": "/user/lib/libsomelib.so",
176 "/path/to/project/some_data": "/usr/share/some_data",
177 "/path/to/project/some_header.h": "/usr/include/some_header.h"
178 }
179 ```
180
181
182 ### Using `--targets` without a build directory
183
184 It is also possible to get most targets without a build directory.
185 This can be done by running `meson introspect --targets
186 /path/to/meson.build`.
187
188 The generated output is similar to running the introspection with a
189 build directory or reading the `intro-targets.json`. However, there
190 are some key differences:
191
192 - The paths in `filename` now are _relative_ to the future build directory
193 - The `install_filename` key is completely missing
194 - There is only one entry in `target_sources`:
195 - With the language set to `unknown`
196 - Empty lists for `compiler` and `parameters` and `generated_sources`
197 - The `sources` list _should_ contain all sources of the target
198
199 There is no guarantee that the sources list in `target_sources` is
200 correct. There might be differences, due to internal limitations. It
201 is also not guaranteed that all targets will be listed in the output.
202 It might even be possible that targets are listed, which won't exist
203 when Meson is run normally. This can happen if a target is defined
204 inside an if statement. Use this feature with care.
205
206 ## Build Options
207
208 The list of all build options (build type, warning level, etc.) is
209 stored in the `intro-buildoptions.json` file. Here is the JSON format
210 for each option.
211
212 ```json
213 {
214 "name": "name of the option",
215 "description": "the description",
216 "type": "type ID",
217 "value": "value depends on type",
218 "section": "section ID",
219 "machine": "machine ID"
220 }
221 ```
222
223 The supported types are:
224
225 - string
226 - boolean
227 - combo
228 - integer
229 - array
230
231 For the type `combo` the key `choices` is also present. Here all valid
232 values for the option are stored.
233
234 The possible values for `section` are:
235
236 - core
237 - backend
238 - base
239 - compiler
240 - directory
241 - user
242 - test
243
244 The `machine` key specifies the machine configuration for the option.
245 Possible values are:
246
247 - any
248 - host
249 - build
250
251 To set the options, use the `meson configure` command.
252
253 Since Meson 0.50.0 it is also possible to get the default buildoptions
254 without a build directory by providing the root `meson.build` instead
255 of a build directory to `meson introspect --buildoptions`.
256
257 Running `--buildoptions` without a build directory produces the same
258 output as running it with a freshly configured build directory.
259
260 However, this behavior is not guaranteed if subprojects are present.
261 Due to internal limitations all subprojects are processed even if they
262 are never used in a real Meson run. Because of this options for the
263 subprojects can differ.
264
265 ## The dependencies section
266
267 The list of all _found_ dependencies can be acquired from
268 `intro-dependencies.json`. Here, the name, version, compiler and
269 linker arguments for a dependency are listed.
270
271 ### Scanning for dependencies with `--scan-dependencies`
272
273 It is also possible to get most dependencies used without a build
274 directory. This can be done by running `meson introspect
275 --scan-dependencies /path/to/meson.build`.
276
277 The output format is as follows:
278
279 ```json
280 [
281 {
282 "name": "The name of the dependency",
283 "required": true,
284 "version": [">=1.2.3"],
285 "conditional": false,
286 "has_fallback": false
287 }
288 ]
289 ```
290
291 The `required` keyword specifies whether the dependency is marked as
292 required in the `meson.build` (all dependencies are required by
293 default). The `conditional` key indicates whether the `dependency()`
294 function was called inside a conditional block. In a real Meson run
295 these dependencies might not be used, thus they _may_ not be required,
296 even if the `required` key is set. The `has_fallback` key just
297 indicates whether a fallback was directly set in the `dependency()`
298 function. The `version` key always contains a list of version
299 requirements from the `meson.build` and **not** the actual version of
300 the dependency on disc. The version list is empty if no version was
301 specified in the `meson.build`.
302
303 ## Tests
304
305 Compilation and unit tests are done as usual by running the `meson
306 compile` and `meson test` commands. A JSON formatted result log can be
307 found in `workspace/project/builddir/meson-logs/testlog.json`.
308
309 When these tests fail, the user probably wants to run the failing test
310 in a debugger. To make this as integrated as possible, extract the
311 tests from the `intro-tests.json` and `intro-benchmarks.json` files.
312 This provides you with all the information needed to run the test:
313 what command to execute, command line arguments, environment variable
314 settings and how to process the output.
315
316 ```json
317 {
318 "name": "name of the test",
319 "workdir": "the working directory (can be null)",
320 "timeout": "the test timeout",
321 "suite": ["list", "of", "test", "suites"],
322 "is_parallel": true / false,
323 "protocol": "exitcode" / "tap",
324 "cmd": ["command", "to", "run"],
325 "depends": ["target1-id", "target2-id"],
326 "env": {
327 "VARIABLE1": "value 1",
328 "VARIABLE2": "value 2"
329 }
330 }
331 ```
332
333 The `depends` entry *(since 0.56.0)* contains target ids; they can be
334 looked up in the targets introspection data. The executable pointed to
335 by `cmd` is also included in the entry, as are any arguments to the
336 test that are build products.
337
338 ## Build system files
339
340 It is also possible to get Meson build files used in your current
341 project. This can be done by running `meson introspect
342 --buildsystem-files /path/to/builddir`.
343
344 The output format is as follows:
345
346 ```json
347 [
348 "/Path/to/the/targets/meson.build",
349 "/Path/to/the/targets/meson.options",
350 "/Path/to/the/targets/subdir/meson.build"
351 ]
352 ```
353
354 # Programmatic interface
355
356 Meson also provides the `meson introspect` for project introspection
357 via the command line. Use `meson introspect -h` to see all available
358 options.
359
360 This API can also work without a build directory for the
361 `--projectinfo` command.
362
363 # AST of a `meson.build`
364
365 Since Meson *0.55.0* it is possible to dump the AST of a `meson.build`
366 as a JSON object. The interface for this is `meson introspect --ast
367 /path/to/meson.build`.
368
369 Each node of the AST has at least the following entries:
370
371 | Key | Description |
372 | ------------ | ------------------------------------------------------- |
373 | `node` | Type of the node (see following table) |
374 | `lineno` | Line number of the node in the file |
375 | `colno` | Column number of the node in the file |
376 | `end_lineno` | Marks the end of the node (may be the same as `lineno`) |
377 | `end_colno` | Marks the end of the node (may be the same as `colno`) |
378
379 Possible values for `node` with additional keys:
380
381 | Node type | Additional keys |
382 | -------------------- | ------------------------------------------------ |
383 | `BooleanNode` | `value`: bool |
384 | `IdNode` | `value`: str |
385 | `NumberNode` | `value`: int |
386 | `StringNode` | `value`: str |
387 | `ContinueNode` | |
388 | `BreakNode` | |
389 | `ArgumentNode` | `positional`: node list; `kwargs`: accept_kwargs |
390 | `ArrayNode` | `args`: node |
391 | `DictNode` | `args`: node |
392 | `EmptyNode` | |
393 | `OrNode` | `left`: node; `right`: node |
394 | `AndNode` | `left`: node; `right`: node |
395 | `ComparisonNode` | `left`: node; `right`: node; `ctype`: str |
396 | `ArithmeticNode` | `left`: node; `right`: node; `op`: str |
397 | `NotNode` | `right`: node |
398 | `CodeBlockNode` | `lines`: node list |
399 | `IndexNode` | `object`: node; `index`: node |
400 | `MethodNode` | `object`: node; `args`: node; `name`: str |
401 | `FunctionNode` | `args`: node; `name`: str |
402 | `AssignmentNode` | `value`: node; `var_name`: str |
403 | `PlusAssignmentNode` | `value`: node; `var_name`: str |
404 | `ForeachClauseNode` | `items`: node; `block`: node; `varnames`: list |
405 | `IfClauseNode` | `ifs`: node list; `else`: node |
406 | `IfNode` | `condition`: node; `block`: node |
407 | `UMinusNode` | `right`: node |
408 | `TernaryNode` | `condition`: node; `true`: node; `false`: node |
409
410 We do not guarantee the stability of this format since it is heavily
411 linked to the internal Meson AST. However, breaking changes (removal
412 of a node type or the removal of a key) are unlikely and will be
413 announced in the release notes.
414
415
416 # JSON Reference manual
417
418 In additional to the online [Reference manual](Reference-manual.md), Meson also
419 offers the manual as JSON file. The content of this file is generated from the
420 same source as the online documentation. The two versions are thus identical
421 in content.
422
423 This JSON document is attached to every Meson release since *0.60.0*. The JSON
424 schema is defined by the class structure given in
425 [`jsonschema.py`](https://github.com/mesonbuild/meson/blob/master/docs/refman/jsonschema.py)
426
427 # Existing integrations
428
429 - [CLion](https://www.jetbrains.com/clion/)
430 - [Eclipse CDT](https://www.eclipse.org/cdt/)
431 - [Gnome Builder](https://wiki.gnome.org/Apps/Builder)
432 - [KDevelop](https://www.kdevelop.org)
433 - [Meson Syntax Highlighter](https://plugins.jetbrains.com/plugin/13269-meson-syntax-highlighter) 3rd party plugin for JetBrains IDEs.
434 - [Meson-UI](https://github.com/dreamer-coding-555/meson-ui) (build GUI for Meson)
435 - [mmeson](https://github.com/stephanlachnit/mmeson) (ccmake clone for Meson)
436 - [Qt Creator](https://doc.qt.io/qtcreator/creator-project-meson.html)
437 - [vscode-meson](https://github.com/mesonbuild/vscode-meson) extension for VS Code/Codium