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