From f29f854861eff04a9b89883adfbe7f47040f96f8 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Mon, 18 Feb 2019 18:33:02 +0100 Subject: Added docs --- docs/markdown/IDE-integration.md | 58 ++++++++++++++++++++++ docs/markdown/snippets/introspect_deps_no_bd.md | 28 +++++++++++ docs/markdown/snippets/introspect_targets_no_bd.md | 21 ++++++++ 3 files changed, 107 insertions(+) create mode 100644 docs/markdown/snippets/introspect_deps_no_bd.md create mode 100644 docs/markdown/snippets/introspect_targets_no_bd.md (limited to 'docs') diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index ab157d1a8..35ce88391 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -109,6 +109,29 @@ The following table shows all valid types for a target. `run` | A Meson run target `jar` | A Java JAR 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`. + +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 @@ -158,6 +181,41 @@ 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, compiler and linker arguments for +a dependency are listed. + +### Using `--dependencies` without a build directory + +It is also possible to get most targets without a build directory. This can be +done by running `meson introspect --dependencies /path/to/meson.build`. + +However, the generated output is vastly different from running the introspection +command with a build directory. + +The output format is as follows: + +```json +[ + { + "name": "The name of the dependency", + "required": true, + "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. + ## Tests Compilation and unit tests are done as usual by running the `ninja` and diff --git a/docs/markdown/snippets/introspect_deps_no_bd.md b/docs/markdown/snippets/introspect_deps_no_bd.md new file mode 100644 index 000000000..a28b6679e --- /dev/null +++ b/docs/markdown/snippets/introspect_deps_no_bd.md @@ -0,0 +1,28 @@ +## `introspect --dependencies` can now be used without configured build directory + +It is now possible to run `meson introspect --dependencies /path/to/meson.build` +without a configured build directory. + +However, the generated output is vastly different from running the introspection +command with a build directory. + +The output format is as follows: + +```json +[ + { + "name": "The name of the dependency", + "required": true, + "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. \ No newline at end of file diff --git a/docs/markdown/snippets/introspect_targets_no_bd.md b/docs/markdown/snippets/introspect_targets_no_bd.md new file mode 100644 index 000000000..0172a4ec8 --- /dev/null +++ b/docs/markdown/snippets/introspect_targets_no_bd.md @@ -0,0 +1,21 @@ +## `introspect --targets` can now be used without configured build directory + +It is now possible to run `meson introspect --targets /path/to/meson.build` +without a configured build directory. + +The generated output is similar to running the introspection with a build +directory. 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. \ No newline at end of file -- cgit v1.2.3 From 7074f12644ae0ddc7f8d7471f776bce3375934d4 Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Sun, 3 Mar 2019 22:12:31 +0100 Subject: mintro: Renamed --dependencies --> --scan-dependencies --- docs/markdown/IDE-integration.md | 9 +++------ docs/markdown/snippets/introspect_deps_no_bd.md | 11 ++++------- mesonbuild/mintro.py | 11 +++++++++++ run_unittests.py | 2 +- 4 files changed, 19 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index 35ce88391..7bbec5d4b 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -187,13 +187,10 @@ The list of all _found_ dependencies can be acquired from `intro-dependencies.json`. Here, the name, compiler and linker arguments for a dependency are listed. -### Using `--dependencies` without a build directory +### Scanning for dependecie with `--scan-dependencies` -It is also possible to get most targets without a build directory. This can be -done by running `meson introspect --dependencies /path/to/meson.build`. - -However, the generated output is vastly different from running the introspection -command with a build directory. +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: diff --git a/docs/markdown/snippets/introspect_deps_no_bd.md b/docs/markdown/snippets/introspect_deps_no_bd.md index a28b6679e..cfae58b49 100644 --- a/docs/markdown/snippets/introspect_deps_no_bd.md +++ b/docs/markdown/snippets/introspect_deps_no_bd.md @@ -1,10 +1,7 @@ -## `introspect --dependencies` can now be used without configured build directory +## `introspect --scan-dependencies` can now be used to scan for dependencies used in a project -It is now possible to run `meson introspect --dependencies /path/to/meson.build` -without a configured build directory. - -However, the generated output is vastly different from running the introspection -command with a build directory. +It is now possible to run `meson introspect --scan-dependencies /path/to/meson.build` +without a configured build directory to scan for dependencies. The output format is as follows: @@ -25,4 +22,4 @@ in the `meson.build` (all dependencies are required by default). The 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. \ No newline at end of file +`dependency()` function. diff --git a/mesonbuild/mintro.py b/mesonbuild/mintro.py index b3cc4f541..243dc5d94 100644 --- a/mesonbuild/mintro.py +++ b/mesonbuild/mintro.py @@ -70,6 +70,11 @@ def get_meson_introspection_types(coredata: Optional[cdata.CoreData] = None, 'no_bd': lambda intr: list_deps_from_source(intr), 'desc': 'List external dependencies.', }, + 'scan_dependencies': { + 'no_bd': lambda intr: list_deps_from_source(intr), + 'desc': 'Scan for dependencies used in the meson.build file.', + 'key': 'scan-dependencies', + }, 'installed': { 'func': lambda: list_installed(installdata), 'desc': 'List all installed files and directories.', @@ -431,6 +436,8 @@ def run(options): # Extract introspection information from JSON for i in intro_types.keys(): + if 'func' not in intro_types[i]: + continue if not options.all and not getattr(options, i, False): continue curr = os.path.join(infodir, 'intro-{}.json'.format(i)) @@ -461,6 +468,8 @@ def generate_introspection_file(builddata: build.Build, backend: backends.Backen intro_info = [] for key, val in intro_types.items(): + if 'func' not in val: + continue intro_info += [(key, val['func']())] write_intro_info(intro_info, builddata.environment.info_dir) @@ -489,6 +498,8 @@ def write_meson_info_file(builddata: build.Build, errors: list, build_files_upda intro_info = {} for i in intro_types.keys(): + if 'func' not in intro_types[i]: + continue intro_info[i] = { 'file': 'intro-{}.json'.format(i), 'updated': i in updated_introspection_files diff --git a/run_unittests.py b/run_unittests.py index d1bd2012b..c1337a3c4 100755 --- a/run_unittests.py +++ b/run_unittests.py @@ -3545,7 +3545,7 @@ recommended as it is not supported on some platforms''') def test_introspect_dependencies_from_source(self): testdir = os.path.join(self.unit_test_dir, '52 introspection') testfile = os.path.join(testdir, 'meson.build') - res_nb = self.introspect_directory(testfile, ['--dependencies'] + self.meson_args) + res_nb = self.introspect_directory(testfile, ['--scan-dependencies'] + self.meson_args) expected = [ { 'name': 'threads', -- cgit v1.2.3