@ -4,39 +4,86 @@ short-description: Meson's API to integrate Meson support into an IDE
# IDE integration
Meson has exporters for Visual Studio and XCode, but writing a custom backend for every IDE out there is not a scalable approach. To solve this problem, Meson provides an API that makes it easy for any IDE or build tool to integrate Meson builds and provide an experience comparable to a solution native to the IDE.
Meson has exporters for Visual Studio and XCode, but writing a custom backend for every IDE out there is not a scalable approach. To solve this problem, Meson provides an API that makes it easy for any IDE or build tools to integrate Meson builds and provide an experience comparable to a solution native to the IDE.
The basic tool for this is `meson introspect`.
The basic resource for this is the `meson-introspection.json` file in the build directory.
The first thing to do when setting up a Meson project in an IDE is to select the source and build directories. For this example we assume that the source resides in an Eclipse-like directory called `workspace/project` and the build tree is nested inside it as `workspace/project/build`. First we initialise Meson by running the following command in the source directory.
The first thing to do when setting up a Meson project in an IDE is to select the source and build directories. For this example we assume that the source resides in an Eclipse-like directory called `workspace/project` and the build tree is nested inside it as `workspace/project/build`. First, we initialize Meson by running the following command in the source directory.
meson builddir
For the remainder of the document we assume that all commands are executed inside the build directory unless otherwise specified.
The `meson-introspection.json` can then be found in the root of this build directory. It will be automatically updated when meson is (re)configured, or the build options change. As a result, an IDE can watch for changes in this file to know when something changed.
The first thing you probably want is to get a list of top level targets. For that we use the introspection tool. It comes with extensive command line help so we recommend using that in case problems appear.
The basic JSON format structure defined as follows:
The JSON formats will not be specified in this document. The easiest way of learning them is to look at sample output from the tool.
The content of each JSON entry in this format is further specified in the remainder of this document.
Once you have a list of targets, you probably need the list of source files that comprise the target. To get this list for a target, say `exampletarget`, issue the following command.
## The `targets` section
meson introspect --target-files exampletarget
The most important entry for an IDE is probably the `targets` section. Here each target with its sources and compiler parameters is specified. The JSON format for one target is defined as follows:
In order to make code completion work, you need the compiler flags for each compilation step. Meson does not provide this itself, but the Ninja tool Meson uses to build does provide it. To find out the compile steps necessary to build target foo, issue the following command.
```json
{
"name": "Name of the target",
"id": "The internal ID meson uses",
"type": "<TYPE>",
"filename": ["list", "of", "generate", "files"],
"build_by_default": true / false,
"sources": [],
"installed": true / false,
}
```
ninja -t commands foo
If the key `installed` is set to `true`, the key `install_filename` will also be present. It stores the installation location for each file in `filename`. If one file in `filename` is not installed, its corresponding install location is set to `null`.
Note that if the target has dependencies (such as generated sources), then the commands for those show up in this list as well, so you need to do some filtering. Alternatively you can grab every command invocation in the [Clang tools db](https://clang.llvm.org/docs/JSONCompilationDatabase.html) format that is written to a file called `compile_commands.json` in the build directory.
A target usually generates only one file. However, it is possible for custom targets to have multiple outputs.
## Build Options
### Target sources
The `sources` entry stores a list of all source objects of the target. With this information, an IDE can provide code completion for all source files.
`executable` | This target will generate an executable file
`static library` | Target for a static library
`shared library` | Target for a shared library
`shared module` | A shared library that is meant to be used with dlopen rather than linking into something else
`custom` | A custom target
`unknown target` | The current target format is unknown. This is probably a bug
## Build Options
The list of all build options (build type, warning level, etc.) is stored in the `buildoptions` list. Here is the JSON format for each option.
```json
{
@ -85,11 +132,29 @@ Because of this options for the subprojects can differ.
Compilation and unit tests are done as usual by running the `ninja` and `ninja test` commands. A JSON formatted result log can be found in `workspace/project/builddir/meson-logs/testlog.json`.
When these tests fail, the user probably wants to run the failing test in a debugger. To make this as integrated as possible, extract the test test setups with this command.
When these tests fail, the user probably wants to run the failing test in a debugger. To make this as integrated as possible, extract the tests from the `tests` and `benchmarks` entries.
This provides you with all the information needed to run the test: what command to execute, command line arguments and environment variable settings.
meson introspect --tests
```json
{
"name": "name of the test",
"workdir": "the working directory (can be null)",
"timeout": "the test timeout",
"suite": ["list", "of", "test", "suites"],
"is_parallel": true / false,
"cmd": ["command", "to", "run"],
"env": {
"VARIABLE1": "value 1",
"VARIABLE2": "value 2"
}
}
```
This provides you with all the information needed to run the test: what command to execute, command line arguments and environment variable settings.
# Programmatic interface
Meson also provides the `meson introspect` for project introspection via the command line. Use `meson introspect -h` to see all available options.
This API can also work without a build directory for the `--projectinfo` command.
Daniel Mensinger
6 years ago