@ -4,39 +4,110 @@ 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`.
All the resources required for such a IDE integration can be found in
the `meson-info` directory 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.
With this command meson will configure the project and also generate
introspection information that is stored in `intro-*.json` files in the
`meson-info` directory. The introspection dump will be automatically updated
when meson is (re)configured, or the build options change. Thus, an IDE can
watch for changes in this directory 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 `meson-info` directory should contain the following files:
`intro-buildoptions.json` | Contains a full list of meson configuration options for the project
`intro-buildsystem_files.json` | Full list of all meson build files
`intro-dependencies.json` | Lists all dependencies used in the project
`intro-installed.json` | Contains mapping of files to their installed location
`intro-projectinfo.json` | Stores basic information about the project (name, version, etc.)
`intro-targets.json` | Full list of all build targets
`intro-tests.json` | Lists all tests with instructions how to run them
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 the JSON files 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 file for an IDE is probably `intro-targets.json`. 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", "generated", "files"],
"build_by_default": true / false,
"target_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 `intro-targets.json` file also stores a list of all source objects of the
target in the `target_sources`. With this information, an IDE can provide code
`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
`run` | A Meson run target
`jar` | A Java JAR target
## Build Options
The list of all build options (build type, warning level, etc.) is stored in
the `intro-buildoptions.json` file. Here is the JSON format for each option.
```json
{
@ -56,7 +127,8 @@ The supported types are:
- integer
- array
For the type `combo` the key `choices` is also present. Here all valid values for the option are stored.
For the type `combo` the key `choices` is also present. Here all valid values
for the option are stored.
The possible values for `section` are:
@ -74,25 +146,49 @@ Since Meson 0.50.0 it is also possible to get the default buildoptions
without a build directory by providing the root `meson.build` instead of a
build directory to `meson introspect --buildoptions`.
Running `--buildoptions` without a build directory produces the same output as running
it with a freshly configured build directory.
Running `--buildoptions` without a build directory produces the same output as
running it with a freshly configured build directory.
However, this behavior is not guaranteed if subprojects are present. Due to internal
limitations all subprojects are processed even if they are never used in a real meson run.
Because of this options for the subprojects can differ.
However, this behavior is not guaranteed if subprojects are present. Due to
internal limitations all subprojects are processed even if they are never used
in a real meson run. Because of this options for the subprojects can differ.
## Tests
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`.
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
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
`intro-tests.json` and `intro-benchmarks.json` files. This provides you with
all the information needed to run the test: what command to execute, command
line arguments and environment variable settings.
```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"
}
}
```
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.
# Programmatic interface
meson introspect --tests
Meson also provides the `meson introspect` for project introspection via the
command line. Use `meson introspect -h` to see all available options.
This provides you with all the information needed to run the test: what command to execute, command line arguments and environment variable settings.
This API can also work without a build directory for the `--projectinfo` command.
Jussi Pakkanen
6 years ago
committed by
GitHub