From 80ee0f85f97b145058e2ca93090501f33a980a23 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sat, 24 Nov 2018 17:51:13 +0100 Subject: Added release snippet --- docs/markdown/snippets/introspect_target_new.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/markdown/snippets/introspect_target_new.md (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_target_new.md b/docs/markdown/snippets/introspect_target_new.md new file mode 100644 index 0000000..cf0fd6a --- /dev/null +++ b/docs/markdown/snippets/introspect_target_new.md @@ -0,0 +1,7 @@ +## New `include_directories` and `extra_args` keys for the target introspection + +Meson now also prints the include directories and extra compiler arguments for +the target introspection (`meson introspect --targets`). + +The `include_directories` key stores a list of absolute paths and the `extra_args` +key holds a dict of compiler arguments for each language. -- cgit v1.1 From 8288555aa1dcab1ae38831d40529c6a2fbe3c8fd Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 25 Nov 2018 21:40:38 +0100 Subject: mintro: Added option to introspect multiple parameters at once --- docs/markdown/snippets/introspect_multiple.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/markdown/snippets/introspect_multiple.md (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md new file mode 100644 index 0000000..b7266f8 --- /dev/null +++ b/docs/markdown/snippets/introspect_multiple.md @@ -0,0 +1,12 @@ +## Added option to introspect multiple parameters at once + +Meson introspect can now print the results of multiple parameters +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` and `-i,--indent` was added to +print all introspection information in one go and format the +JSON output (the default is still compact JSON). \ No newline at end of file -- cgit v1.1 From b91c5aad854bff3a13c27aa1a6ade85ded216207 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Thu, 29 Nov 2018 14:21:07 +0100 Subject: Update intro dump on meson configure --- docs/markdown/snippets/introspect_multiple.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index b7266f8..d05eae6 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -1,12 +1,13 @@ ## Added option to introspect multiple parameters at once -Meson introspect can now print the results of multiple parameters -in a single call. The results are then printed as a single JSON +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` and `-i,--indent` was added to -print all introspection information in one go and format the -JSON output (the default is still compact JSON). \ No newline at end of file +Furthermore the option `-a,--all`, `-i,--indent` and `-f,--force-new` +were added to print all introspection information in one go, format the +JSON output (the default is still compact JSON) and foce use the new +output format, even if only one introspection command was given. \ No newline at end of file -- cgit v1.1 From b034f52656c19f378fc144abd9087e7526b1e27f Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Thu, 29 Nov 2018 14:53:28 +0100 Subject: Filenames are now lists --- docs/markdown/snippets/introspect_multiple.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index d05eae6..17d0a3f 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -10,4 +10,9 @@ compatibility. Furthermore the option `-a,--all`, `-i,--indent` and `-f,--force-new` were added to print all introspection information in one go, format the JSON output (the default is still compact JSON) and foce use the new -output format, even if only one introspection command was given. \ No newline at end of file +output format, even if only one introspection command was given. + +Additionlly the format of target was changed: + - `filename` is now a list of output filenames + - `install_filename` is now also a list of installed files + - New: the `sources` key. It stores the source files of a target and there compiler parameters -- cgit v1.1 From b11df88395a6543ab1ea9354050f0b885959854a Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Thu, 29 Nov 2018 16:19:01 +0100 Subject: Documentation and unit test update --- docs/markdown/IDE-integration.md | 103 +++++++++++++++++++----- docs/markdown/snippets/introspect_target_new.md | 7 -- 2 files changed, 84 insertions(+), 26 deletions(-) delete mode 100644 docs/markdown/snippets/introspect_target_new.md (limited to 'docs') diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index c75392c..a6c89bb 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -4,39 +4,86 @@ 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`. +The basic resource for this is the `meson-introspection.json` file 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. +The `meson-introspection.json` can then be found in the root of this build directory. It will be automatically updated when meson is (re)configured, or the build options change. As a result, an IDE can watch for changes in this file 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 basic JSON format structure defined as follows: - meson introspect --targets +```json +{ + "benchmarks": [], + "buildoptions": [], + "buildsystem_files": ["just", "a", "list", "of", "meson", "files"], + "dependencies": [], + "installed": {}, + "projectinfo": { + "version": "1.2.3", + "descriptive_name": "Project Name", + "subprojects": [] + }, + "targets": [], + "tests": [] +} +``` -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 each JSON entry in this format 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 entry for an IDE is probably the `targets` section. 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": "", + "filename": ["list", "of", "generate", "files"], + "build_by_default": true / false, + "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 `sources` entry stores a list of all source objects of the target. 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"], + "source_files": ["list", "of", "all", "source", "files", "for", "this", "language"] +} +``` -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. +### Possible values for `type` - meson introspect --buildoptions +The following table shows all valid types for a target. -This command returns a list of all supported buildoptions with the format: + 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 + `unknown target` | The current target format is unknown. This is probably a bug + +## Build Options + +The list of all build options (build type, warning level, etc.) is stored in the `buildoptions` list. Here is the JSON format for each option. ```json { @@ -85,11 +132,29 @@ Because of this options for the subprojects can differ. 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 test test setups with this command. +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 `tests` and `benchmarks` entries. +This provides you with all the information needed to run the test: what command to execute, command line arguments and environment variable settings. - meson introspect --tests +```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" + } +} +``` -This provides you with all the information needed to run the test: what command to execute, command line arguments and environment variable settings. +# 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. # Existing integrations diff --git a/docs/markdown/snippets/introspect_target_new.md b/docs/markdown/snippets/introspect_target_new.md deleted file mode 100644 index cf0fd6a..0000000 --- a/docs/markdown/snippets/introspect_target_new.md +++ /dev/null @@ -1,7 +0,0 @@ -## New `include_directories` and `extra_args` keys for the target introspection - -Meson now also prints the include directories and extra compiler arguments for -the target introspection (`meson introspect --targets`). - -The `include_directories` key stores a list of absolute paths and the `extra_args` -key holds a dict of compiler arguments for each language. -- cgit v1.1 From b9c4913cf032144eed0cb6308aaff4e77a825f08 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 2 Dec 2018 19:53:34 +0100 Subject: Updated documentation --- docs/markdown/IDE-integration.md | 40 ++++++++++++--------------- docs/markdown/snippets/introspect_multiple.md | 3 ++ 2 files changed, 20 insertions(+), 23 deletions(-) (limited to 'docs') diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index a6c89bb..bd5dff2 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -6,38 +6,32 @@ short-description: Meson's API to integrate Meson support into an 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 resource for this is the `meson-introspection.json` file 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. meson builddir -The `meson-introspection.json` can then be found in the root of this build directory. It will be automatically updated when meson is (re)configured, or the build options change. As a result, an IDE can watch for changes in this file 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. All files 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 basic JSON format structure defined as follows: +The `meson-info` directory should contain the following files: -```json -{ - "benchmarks": [], - "buildoptions": [], - "buildsystem_files": ["just", "a", "list", "of", "meson", "files"], - "dependencies": [], - "installed": {}, - "projectinfo": { - "version": "1.2.3", - "descriptive_name": "Project Name", - "subprojects": [] - }, - "targets": [], - "tests": [] -} -``` + 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 content of each JSON entry in this format 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 entry for an IDE is probably the `targets` section. 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 { @@ -57,7 +51,7 @@ A target usually generates only one file. However, it is possible for custom tar ### Target sources -The `sources` entry stores a list of all source objects of the target. With this information, an IDE can provide code completion for all source files. +The `intro-sources.json` file stores a list of all source objects of the target. With this information, an IDE can provide code completion for all source files. ```json { @@ -83,7 +77,7 @@ 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 `buildoptions` list. 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 { diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index 17d0a3f..1514219 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -12,6 +12,9 @@ were added to print all introspection information in one go, format the JSON output (the default is still compact JSON) and foce 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 alwys be (re)generated on every meson run. + Additionlly the format of target was changed: - `filename` is now a list of output filenames - `install_filename` is now also a list of installed files -- cgit v1.1 From fde10eaee9886f5834a4ab92deadfd39b2d05424 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Tue, 11 Dec 2018 17:59:35 +0100 Subject: Updated the docs --- docs/markdown/IDE-integration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index bd5dff2..6fb2321 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -58,7 +58,8 @@ The `intro-sources.json` file stores a list of all source objects of the target. "language": "language ID", "compiler": ["The", "compiler", "command"], "parameters": ["list", "of", "compiler", "parameters"], - "source_files": ["list", "of", "all", "source", "files", "for", "this", "language"] + "sources": ["list", "of", "all", "source", "files", "for", "this", "language"], + "generated_sources": ["list", "of", "all", "soruce", "files", "that", "where", "generated", "somewhere", "else"] } ``` -- cgit v1.1 From eb2cc9eccd240fd76c290b77bd28c8285b313b5c Mon Sep 17 00:00:00 2001 From: textshell Date: Fri, 28 Dec 2018 21:18:01 +0100 Subject: Update docs/markdown/snippets/introspect_multiple.md Co-Authored-By: mensinda --- docs/markdown/snippets/introspect_multiple.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index 1514219..38bd90c 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -13,7 +13,7 @@ JSON output (the default is still compact JSON) and foce 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 alwys be (re)generated on every meson run. +directory. This dump will be (re)generated each time meson updates the configuration of the build directory. Additionlly the format of target was changed: - `filename` is now a list of output filenames -- cgit v1.1 From c1838d9e4ce6539b6d6694ea0a7935ad07521006 Mon Sep 17 00:00:00 2001 From: textshell Date: Fri, 28 Dec 2018 21:18:39 +0100 Subject: Update docs/markdown/snippets/introspect_multiple.md Co-Authored-By: mensinda --- docs/markdown/snippets/introspect_multiple.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index 38bd90c..75580d3 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -15,7 +15,7 @@ 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 target was changed: +Additionlly the format of `meson introspect target` was changed: - `filename` is now a list of output filenames - `install_filename` is now also a list of installed files - New: the `sources` key. It stores the source files of a target and there compiler parameters -- cgit v1.1 From 7cf0e307074f11028c383a85616ff7c5a3a1b529 Mon Sep 17 00:00:00 2001 From: textshell Date: Fri, 28 Dec 2018 21:20:15 +0100 Subject: Update docs/markdown/IDE-integration.md Co-Authored-By: mensinda --- docs/markdown/IDE-integration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index 6fb2321..765c2c4 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -59,7 +59,7 @@ The `intro-sources.json` file stores a list of all source objects of the target. "compiler": ["The", "compiler", "command"], "parameters": ["list", "of", "compiler", "parameters"], "sources": ["list", "of", "all", "source", "files", "for", "this", "language"], - "generated_sources": ["list", "of", "all", "soruce", "files", "that", "where", "generated", "somewhere", "else"] + "generated_sources": ["list", "of", "all", "source", "files", "that", "where", "generated", "somewhere", "else"] } ``` @@ -155,4 +155,4 @@ This API can also work without a build directory for the `--projectinfo` command - [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) -- cgit v1.1 From 2e81631d0c892d4842412c5244d9374b390f3787 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 30 Dec 2018 10:59:58 +0100 Subject: Keep 'filename' and 'install_filename' as strings --- docs/markdown/snippets/introspect_multiple.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index 75580d3..53278e6 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -16,6 +16,5 @@ 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: - - `filename` is now a list of output filenames - - `install_filename` is now also a list of installed files + - New: the `sources` key. It stores the source files of a target and there compiler parameters -- cgit v1.1 From 1268597df590413539099f0f3797fae7bcb5c09a Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 30 Dec 2018 11:09:08 +0100 Subject: Slight modification of the wording --- docs/markdown/IDE-integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index 765c2c4..4b5c360 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -12,7 +12,7 @@ The first thing to do when setting up a Meson project in an IDE is to select the 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. All files 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: -- cgit v1.1 From 5c39dd0668ffe301aee66453b86591bbdb29a954 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 30 Dec 2018 11:31:03 +0100 Subject: Doc updates and throw if no target type is set --- docs/markdown/IDE-integration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index 4b5c360..639f4a0 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -74,7 +74,8 @@ The following table shows all valid types for a target. `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 - `unknown target` | The current target format is unknown. This is probably a bug + `run` | A Meson run target + `jar` | A Java JAR target ## Build Options -- cgit v1.1 From 84948ea6cd61c54404d6e0df82594a56e19fe01f Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 30 Dec 2018 11:37:50 +0100 Subject: Renamed `--force-new` to `--force-dict-output` --- docs/markdown/snippets/introspect_multiple.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index 53278e6..97fdf8c 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -7,7 +7,7 @@ object. The format for a single command was not changed to keep backward compatibility. -Furthermore the option `-a,--all`, `-i,--indent` and `-f,--force-new` +Furthermore the option `-a,--all`, `-i,--indent` and `-f,--force-dict-output` were added to print all introspection information in one go, format the JSON output (the default is still compact JSON) and foce use the new output format, even if only one introspection command was given. -- cgit v1.1 From 02734cc5c34faabe8ec0685139451f8349469993 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 30 Dec 2018 12:38:55 +0100 Subject: Better documentation --- docs/markdown/snippets/introspect_multiple.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index 97fdf8c..2a885e4 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -18,3 +18,4 @@ directory. This dump will be (re)generated each time meson updates the configura Additionlly the format of `meson introspect target` was changed: - New: the `sources` key. It stores the source files of a target and there compiler parameters + - Added new target types (`jar`, `shared module`) -- cgit v1.1 From 1e374feb1ce09e866f9625a3ea378b58fddaf768 Mon Sep 17 00:00:00 2001 From: textshell Date: Sun, 30 Dec 2018 22:34:57 +0100 Subject: Update docs/markdown/IDE-integration.md Co-Authored-By: mensinda --- docs/markdown/IDE-integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index 639f4a0..1b79c74 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -38,7 +38,7 @@ The most important file for an IDE is probably `intro-targets.json`. Here each t "name": "Name of the target", "id": "The internal ID meson uses", "type": "", - "filename": ["list", "of", "generate", "files"], + "filename": ["list", "of", "generated", "files"], "build_by_default": true / false, "sources": [], "installed": true / false, -- cgit v1.1 From fb4bdd3330b5857cc0187dec1c75f307fe8889f8 Mon Sep 17 00:00:00 2001 From: textshell Date: Sun, 30 Dec 2018 22:35:42 +0100 Subject: Update docs/markdown/IDE-integration.md Co-Authored-By: mensinda --- docs/markdown/IDE-integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index 1b79c74..81fd43f 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -128,7 +128,7 @@ Because of this options for the subprojects can differ. 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 `tests` and `benchmarks` entries. +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 -- cgit v1.1 From 248adbab9ad0775e513b920e9047b2e93664ae2e Mon Sep 17 00:00:00 2001 From: textshell Date: Sun, 30 Dec 2018 22:35:56 +0100 Subject: Update docs/markdown/snippets/introspect_multiple.md Co-Authored-By: mensinda --- docs/markdown/snippets/introspect_multiple.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index 2a885e4..3bbe6cc 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -9,7 +9,7 @@ compatibility. Furthermore the option `-a,--all`, `-i,--indent` and `-f,--force-dict-output` were added to print all introspection information in one go, format the -JSON output (the default is still compact JSON) and foce use the new +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` -- cgit v1.1 From bd8bad46c3fad6e53e259f73408a73eeca920dc7 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 30 Dec 2018 23:04:59 +0100 Subject: Code cleanup and renamed variables --- docs/markdown/IDE-integration.md | 4 ++-- docs/markdown/snippets/introspect_multiple.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index 81fd43f..d4554ae 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -40,7 +40,7 @@ The most important file for an IDE is probably `intro-targets.json`. Here each t "type": "", "filename": ["list", "of", "generated", "files"], "build_by_default": true / false, - "sources": [], + "target_sources": [], "installed": true / false, } ``` @@ -51,7 +51,7 @@ A target usually generates only one file. However, it is possible for custom tar ### Target sources -The `intro-sources.json` file stores a list of all source objects of the target. 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 { diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index 3bbe6cc..0d53d48 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -7,7 +7,7 @@ object. The format for a single command was not changed to keep backward compatibility. -Furthermore the option `-a,--all`, `-i,--indent` and `-f,--force-dict-output` +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. -- cgit v1.1 From 428f85e8605034e30f835542f2d26600e967f4f0 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Tue, 1 Jan 2019 22:57:16 +0100 Subject: Updated the docs [skip ci] --- docs/markdown/IDE-integration.md | 73 +++++++++++++++++++++++++++++----------- 1 file changed, 54 insertions(+), 19 deletions(-) (limited to 'docs') diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index d4554ae..25d262a 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -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 +`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. +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. -- cgit v1.1 From bcb8146280ed89d1fabc3136e2e65a6173b31214 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Wed, 2 Jan 2019 21:58:04 +0100 Subject: Indent flag only toggles --- docs/markdown/snippets/introspect_multiple.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index 0d53d48..131bf58 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -13,7 +13,8 @@ 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. +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: -- cgit v1.1 From 0b0ec5895c6db491cb1fefaadbdc091c1e77189a Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sat, 5 Jan 2019 18:04:01 +0100 Subject: Fixed typo [skip ci] --- docs/markdown/snippets/introspect_multiple.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index 131bf58..06df733 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -18,5 +18,5 @@ 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 there compiler parameters + - New: the `sources` key. It stores the source files of a target and their compiler parameters - Added new target types (`jar`, `shared module`) -- cgit v1.1 From 52071c6d4ee15c750f8a8620e038b78627db890e Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sat, 5 Jan 2019 18:04:44 +0100 Subject: Fixed missing dots [skip ci] --- docs/markdown/snippets/introspect_multiple.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/markdown/snippets/introspect_multiple.md b/docs/markdown/snippets/introspect_multiple.md index 06df733..67f517a 100644 --- a/docs/markdown/snippets/introspect_multiple.md +++ b/docs/markdown/snippets/introspect_multiple.md @@ -18,5 +18,5 @@ 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`) + - New: the `sources` key. It stores the source files of a target and their compiler parameters. + - Added new target types (`jar`, `shared module`). -- cgit v1.1