@ -4,15 +4,28 @@ 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 tools 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.
All the resources required for such a IDE integration can be found in the `meson-info` directory in the build directory.
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 initialize 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
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.
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 `meson-info` directory should contain the following files:
@ -31,7 +44,9 @@ The content of the JSON files is further specified in the remainder of this docu
## The `targets` section
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:
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:
```json
{
@ -45,13 +60,19 @@ The most important file for an IDE is probably `intro-targets.json`. Here each t
}
```
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`.
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`.
A target usually generates only one file. However, it is possible for custom targets to have multiple outputs.
A target usually generates only one file. However, it is possible for custom
targets to have multiple outputs.
### 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 completion for all source files.
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
completion for all source files.
```json
{
@ -63,6 +84,12 @@ The `intro-targets.json` file also stores a list of all source objects of the ta
}
```
It should be noted that the compiler parameters stored in the `parameters`
differ from the actual parameters used to compile the file. This is because
the parameters are optimized for the usage in an IDE to provide autocompletion
support, etc. It is thus not recommended to use this introspection information
for actual compilation.
### Possible values for `type`
The following table shows all valid types for a target.
@ -79,7 +106,8 @@ The following table shows all valid types for a 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.
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
{
@ -99,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:
@ -117,19 +146,24 @@ 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.
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
{
@ -148,7 +182,8 @@ This provides you with all the information needed to run the test: what command
# Programmatic interface
Meson also provides the `meson introspect` for project introspection via the command line. Use `meson introspect -h` to see all available options.
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