diff options
Diffstat (limited to 'docs/markdown')
| -rw-r--r-- | docs/markdown/IDE-integration.md | 150 | ||||
| -rw-r--r-- | docs/markdown/snippets/introspect_multiple.md | 22 |
2 files changed, 145 insertions, 27 deletions
diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index c75392c..25d262a 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -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: - meson introspect --targets + 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-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 +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"] +} +``` -The next thing to display is the list of options that can be set. These include build type and so on. Here's how to extract them. +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. - meson introspect --buildoptions +### Possible values for `type` -This command returns a list of all supported buildoptions with the format: +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 + +## 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 +`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 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. # Existing integrations - [Gnome Builder](https://wiki.gnome.org/Apps/Builder) - [Eclipse CDT](https://www.eclipse.org/cdt/) (experimental) -- [Meson Cmake Wrapper](https://github.com/prozum/meson-cmake-wrapper) (for cmake IDEs)
\ No newline at end of file +- [Meson Cmake Wrapper](https://github.com/prozum/meson-cmake-wrapper) (for cmake IDEs) diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md new file mode 100644 index 0000000..67f517a --- /dev/null +++ b/docs/markdown/snippets/introspect_multiple.md @@ -0,0 +1,22 @@ +## Added option to introspect multiple parameters at once + +Meson introspect can now print the results of multiple introspection +commands in a single call. The results are then printed as a single JSON +object. + +The format for a single command was not changed to keep backward +compatibility. + +Furthermore the option `-a,--all`, `-i,--indent` and `-f,--force-object-output` +were added to print all introspection information in one go, format the +JSON output (the default is still compact JSON) and force use the new +output format, even if only one introspection command was given. + +A complete introspection dump is also stored in the `meson-info` +directory. This dump will be (re)generated each time meson updates the +configuration of the build directory. + +Additionlly the format of `meson introspect target` was changed: + + - New: the `sources` key. It stores the source files of a target and their compiler parameters. + - Added new target types (`jar`, `shared module`). |