Add global_source/build_root()

2 files changed, 26 insertions, 0 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 74f3324..e4c4703 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1989,6 +1989,9 @@ the following methods.
   root directory. *(deprecated since 0.56.0)*: this function will return the
   build root of the parent project if called from a subproject, which is usually
   not what you want. Try using `current_build_dir()` or `project_build_root()`.
+  In the rare cases where the root of the main project is needed,
+  use `global_build_root()` that has the same behaviour but with a more explicit
+  name.
 
 - `source_root()`: returns a string with the absolute path to the
   source root directory. Note: you should use the `files()` function
@@ -1997,6 +2000,9 @@ the following methods.
   *(deprecated since 0.56.0)*: This function will return the source root of the
   parent project if called from a subproject, which is usually not what you want.
   Try using `current_source_dir()` or `project_source_root()`.
+  In the rare cases where the root of the main project is needed,
+  use `global_source_root()` that has the same behaviour but with a more explicit
+  name.
 
 - `project_build_root()` *(since 0.56.0)*: returns a string with the absolute path
   to the build root directory of the current (sub)project.
@@ -2004,6 +2010,16 @@ the following methods.
 - `project_source_root()` *(since 0.56.0)*: returns a string with the absolute path
   to the source root directory of the current (sub)project.
 
+- `global_build_root()` *(since 0.58.0)*: returns a string with the absolute path
+  to the build root directory. This function will return the build root of the
+  main project if called from a subproject, which is usually not what you want.
+  It is usually preferable to use `current_build_dir()` or `project_build_root()`.
+
+- `global_source_root()` *(since 0.58.0)*: returns a string with the absolute path
+  to the source root directory. This function will return the source root of the
+  main project if called from a subproject, which is usually not what you want.
+  It is usually preferable to use `current_source_dir()` or `project_source_root()`.
+
 - `current_build_dir()`: returns a string with the absolute path to the
   current build directory.
 
diff --git a/docs/markdown/snippets/global_root.md b/docs/markdown/snippets/global_root.md
new file mode 100644
index 0000000..8590f82
--- /dev/null
+++ b/docs/markdown/snippets/global_root.md
@@ -0,0 +1,10 @@
+## New `meson.global_build_root()` and `meson.global_source_root()` methods
+
+Returns the root source and build directory of the main project.
+
+Those are direct replacement for `meson.build_root()` and `meson.source_root()`
+that have been deprecated since 0.56.0. In some rare occasions they could not be
+replaced by `meson.project_source_root()` or `meson.current_source_dir()`, in
+which case the new methods can now be used instead. Old methods are still
+deprecated because their names are not explicit enough and created many issues
+when a project is being used as a subproject.