path: root/docs/markdown/IDE-integration.md

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

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.

    meson setup 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. Note that `meson-info.json` guaranteed
to be the last file written.

The `meson-info` directory should contain the following files:

| File                           | Description                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------- |
| `intro-benchmarks.json`        | Lists all benchmarks                                                          |
| `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-install_plan.json`      | Dictionary of data types with the source files and their installation details |
| `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 content of the JSON files is further specified in the remainder of
this document.

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

```json
{
    "name": "Name of the target",
    "id": "The internal ID meson uses",
    "type": "<TYPE>",
    "defined_in": "/Path/to/the/targets/meson.build",
    "subproject": null,
    "filename": ["list", "of", "generated", "files"],
    "build_by_default": true / false,
    "target_sources": [],
    "extra_files": ["/path/to/file1.hpp", "/path/to/file2.hpp"],
    "installed": true / false,
}
```

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

The `subproject` key specifies the name of the subproject this target
was defined in, or `null` if the target was defined in the top level
project.

*(New in 0.56.0)* The `extra_files` key lists all files specified via
the `extra_files` kwarg of a build target. See
[[executable]].

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.

```json
{
    "language": "language ID",
    "compiler": ["The", "compiler", "command"],
    "parameters": ["list", "of", "compiler", "parameters"],
    "sources": ["list", "of", "all", "source", "files", "for", "this", "language"],
    "generated_sources": ["list", "of", "all", "source", "files", "that", "where", "generated", "somewhere", "else"]
}
```

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.

| value of `type`  | Description                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `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                                                                             |


### Install plan

The `intro-install_plan.json` file contains a list of the files that are going
to be installed on the system.

The data contains a list of files grouped by data type. Each file maps to a
dictionary containing the `destination` and `tag` keys, with the key being the
file location at build time. `destination` is the destination path using
placeholders for the base directories. New keys may be added in the future.

```json
{
    "targets": {
        "/path/to/project/builddir/some_executable": {
            "destination": "{bindir}/some_executable",
            "tag": "runtime"
        },
        "/path/to/project/builddir/libsomelib.so": {
            "destination": "{libdir_shared}/libsomelib.so",
            "tag": "runtime"
        }
    },
    "data": {
        "/path/to/project/some_data": {
            "destination": "{datadir}/some_data",
            "tag": null
        }
    },
    "headers": {
        "/path/to/project/some_header.h": {
            "destination": "{includedir}/some_header.h",
            "tag": "devel"
        }
    }
}
```

Additionally, the `intro-installed.json` file contains the mapping of the
file path at build time to the absolute system location.

```json
{
    "/path/to/project/builddir/some_executable": "/usr/bin/some_executable",
    "/path/to/project/builddir/libsomelib.so": "/user/lib/libsomelib.so",
    "/path/to/project/some_data": "/usr/share/some_data",
    "/path/to/project/some_header.h": "/usr/include/some_header.h"
}
```


### Using `--targets` without a build directory

It is also possible to get most targets without a build directory.
This can be done by running `meson introspect --targets
/path/to/meson.build`.

The generated output is similar to running the introspection with a
build directory or reading the `intro-targets.json`. However, there
are some key differences:

- The paths in `filename` now are _relative_ to the future build directory
- The `install_filename` key is completely missing
- There is only one entry in `target_sources`:
  - With the language set to `unknown`
  - Empty lists for `compiler` and `parameters` and `generated_sources`
  - The `sources` list _should_ contain all sources of the target

There is no guarantee that the sources list in `target_sources` is
correct. There might be differences, due to internal limitations. It
is also not guaranteed that all targets will be listed in the output.
It might even be possible that targets are listed, which won't exist
when Meson is run normally. This can happen if a target is defined
inside an if statement. Use this feature with care.

## 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
{
    "name": "name of the option",
    "description": "the description",
    "type": "type ID",
    "value": "value depends on type",
    "section": "section ID",
    "machine": "machine ID"
}
```

The supported types are:

 - string
 - boolean
 - combo
 - integer
 - array

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:

 - core
 - backend
 - base
 - compiler
 - directory
 - user
 - test

The `machine` key specifies the machine configuration for the option.
Possible values are:

 - any
 - host
 - build

To set the options, use the `meson configure` command.

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.

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.

## The dependencies section

The list of all _found_ dependencies can be acquired from
`intro-dependencies.json`. Here, the name, version, compiler and
linker arguments for a dependency are listed.

### Scanning for dependencies with `--scan-dependencies`

It is also possible to get most dependencies used without a build
directory. This can be done by running `meson introspect
--scan-dependencies /path/to/meson.build`.

The output format is as follows:

```json
[
  {
    "name": "The name of the dependency",
    "required": true,
    "version": [">=1.2.3"],
    "conditional": false,
    "has_fallback": false
  }
]
```

The `required` keyword specifies whether the dependency is marked as
required in the `meson.build` (all dependencies are required by
default). The `conditional` key indicates whether the `dependency()`
function was called inside a conditional block. In a real Meson run
these dependencies might not be used, thus they _may_ not be required,
even if the `required` key is set. The `has_fallback` key just
indicates whether a fallback was directly set in the `dependency()`
function. The `version` key always contains a list of version
requirements from the `meson.build` and **not** the actual version of
the dependency on disc. The version list is empty if no version was
specified in the `meson.build`.

## Tests

Compilation and unit tests are done as usual by running the `meson
compile` and `meson 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
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, environment variable
settings and how to process the output.

```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,
    "protocol": "exitcode" / "tap",
    "cmd": ["command", "to", "run"],
    "depends": ["target1-id", "target2-id"],
    "env": {
        "VARIABLE1": "value 1",
        "VARIABLE2": "value 2"
    }
}
```

The `depends` entry *(since 0.56.0)* contains target ids; they can be
looked up in the targets introspection data. The executable pointed to
by `cmd` is also included in the entry, as are any arguments to the
test that are build products.

## Build system files

It is also possible to get Meson build files used in your current
project. This can be done by running `meson introspect
--buildsystem-files /path/to/builddir`.

The output format is as follows:

```json
[
    "/Path/to/the/targets/meson.build",
    "/Path/to/the/targets/meson.options",
    "/Path/to/the/targets/subdir/meson.build"
]
```

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

# AST of a `meson.build`

Since Meson *0.55.0* it is possible to dump the AST of a `meson.build`
as a JSON object. The interface for this is `meson introspect --ast
/path/to/meson.build`.

Each node of the AST has at least the following entries:

| Key          | Description                                             |
| ------------ | ------------------------------------------------------- |
| `node`       | Type of the node (see following table)                  |
| `lineno`     | Line number of the node in the file                     |
| `colno`      | Column number of the node in the file                   |
| `end_lineno` | Marks the end of the node (may be the same as `lineno`) |
| `end_colno`  | Marks the end of the node (may be the same as `colno`)  |

Possible values for `node` with additional keys:

| Node type            | Additional keys                                  |
| -------------------- | ------------------------------------------------ |
| `BooleanNode`        | `value`: bool                                    |
| `IdNode`             | `value`: str                                     |
| `NumberNode`         | `value`: int                                     |
| `StringNode`         | `value`: str                                     |
| `ContinueNode`       |                                                  |
| `BreakNode`          |                                                  |
| `ArgumentNode`       | `positional`: node list; `kwargs`: accept_kwargs |
| `ArrayNode`          | `args`: node                                     |
| `DictNode`           | `args`: node                                     |
| `EmptyNode`          |                                                  |
| `OrNode`             | `left`: node; `right`: node                      |
| `AndNode`            | `left`: node; `right`: node                      |
| `ComparisonNode`     | `left`: node; `right`: node; `ctype`: str        |
| `ArithmeticNode`     | `left`: node; `right`: node; `op`: str           |
| `NotNode`            | `right`: node                                    |
| `CodeBlockNode`      | `lines`: node list                               |
| `IndexNode`          | `object`: node; `index`: node                    |
| `MethodNode`         | `object`: node; `args`: node; `name`: str        |
| `FunctionNode`       | `args`: node; `name`: str                        |
| `AssignmentNode`     | `value`: node; `var_name`: str                   |
| `PlusAssignmentNode` | `value`: node; `var_name`: str                   |
| `ForeachClauseNode`  | `items`: node; `block`: node; `varnames`: list   |
| `IfClauseNode`       | `ifs`: node list; `else`: node                   |
| `IfNode`             | `condition`: node; `block`: node                 |
| `UMinusNode`         | `right`: node                                    |
| `TernaryNode`        | `condition`: node; `true`: node; `false`: node   |

We do not guarantee the stability of this format since it is heavily
linked to the internal Meson AST. However, breaking changes (removal
of a node type or the removal of a key) are unlikely and will be
announced in the release notes.


# JSON Reference manual

In additional to the online [Reference manual](Reference-manual.md), Meson also
offers the manual as JSON file. The content of this file is generated from the
same source as the online documentation. The two versions are thus identical
in content.

This JSON document is attached to every Meson release since *0.60.0*. The JSON
schema is defined by the class structure given in
[`jsonschema.py`](https://github.com/mesonbuild/meson/blob/master/docs/refman/jsonschema.py)

# Existing integrations

- [Gnome Builder](https://wiki.gnome.org/Apps/Builder)
- [KDevelop](https://www.kdevelop.org)
- [Eclipse CDT](https://www.eclipse.org/cdt/)
- [Meson Syntax Highlighter](https://plugins.jetbrains.com/plugin/13269-meson-syntax-highlighter) plugin for JetBrains IDEs.
- [vscode-meson](https://github.com/mesonbuild/vscode-meson) extension for VS Code/Codium
- [Qt Creator](https://doc.qt.io/qtcreator/creator-project-meson.html)
- [mmeson](https://github.com/stephanlachnit/mmeson) (ccmake clone for Meson)