diff options
Diffstat (limited to 'docs/markdown/IDE-integration.md')
| -rw-r--r-- | docs/markdown/IDE-integration.md | 208 |
1 files changed, 112 insertions, 96 deletions
diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index 5cd72ba..9b550ca 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -4,29 +4,31 @@ 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. -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. Note that -`meson-info.json` guaranteed to be the last file written. +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: @@ -41,13 +43,14 @@ The `meson-info` directory should contain the following files: | `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 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: +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 { @@ -64,25 +67,27 @@ for one target is defined as follows: } ``` -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`. -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. +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()`](Reference-manual.md#executable). +*(New in 0.56.0)* The `extra_files` key lists all files specified via +the `extra_files` kwarg of a build target. See +[`executable()`](Reference-manual.md#executable). -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 { @@ -94,11 +99,11 @@ completion for all source files. } ``` -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. +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` @@ -116,12 +121,13 @@ The following table shows all valid types for a target. ### 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`. +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 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 @@ -130,17 +136,18 @@ differences: - 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. +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. +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 { @@ -161,8 +168,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: @@ -174,8 +181,8 @@ The possible values for `section` are: - user - test -The `machine` key specifies the machine configuration for the option. Possible -values are: +The `machine` key specifies the machine configuration for the option. +Possible values are: - any - host @@ -184,26 +191,28 @@ values are: 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`. +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. ## 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. +`intro-dependencies.json`. Here, the name, version, compiler and +linker arguments for a dependency are listed. ### Scanning for dependecie 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`. +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: @@ -219,28 +228,30 @@ The output format is as follows: ] ``` -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`. +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`. +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. +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 { @@ -260,14 +271,15 @@ line arguments, environment variable settings and how to process the output. ``` 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. +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`. +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: @@ -281,15 +293,18 @@ The output format is as follows: # 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. +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`. +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: @@ -332,9 +347,10 @@ Possible values for `node` with additional keys: | `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. +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. # Existing integrations |