Merge pull request #4949 from mensinda/introTargetNoBD

mintro: Introspect targets and deps without a build directory

2 files changed, 46 insertions, 0 deletions

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 0000000..cfae58b
--- /dev/null
+++ b/docs/markdown/snippets/introspect_deps_no_bd.md
@@ -0,0 +1,25 @@
+## `introspect --scan-dependencies` can now be used to scan for dependencies used in a project
+
+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:
+
+```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.
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 0000000..0172a4e
--- /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