Deprecate meson.build_root() and meson.source_root()

Those function are common source of issue when used in a subproject because they
point to the parent project root which is rarely what is expected and is a
violation of subproject isolation.

docs/markdown/Reference-manual.md

@@ -1804,17 +1804,17 @@ the following methods.
   or `xcode`.
 
 - `build_root()`: returns a string with the absolute path to the build
-  root directory. Note: this function will return the build root of
-  the parent project if called from a subproject, which is usually
+  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()`.
 
 - `source_root()`: returns a string with the absolute path to the
   source root directory. Note: you should use the `files()` function
   to refer to files in the root source directory instead of
-  constructing paths manually with `meson.source_root()`. 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()`.
+  constructing paths manually with `meson.source_root()`.
+  *(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()`.
 
 - `current_build_dir()`: returns a string with the absolute path to the
   current build directory.

docs/markdown/snippets/deprecate_source_build_root.md

@@ -0,0 +1,5 @@
+## `meson.build_root()` and `meson.source_root()` are deprecated
+
+Those function are common source of issue when used in a subproject because they
+point to the parent project root which is rarely what is expected and is a
+violation of subproject isolation.

mesonbuild/interpreter.py

@@ -2061,11 +2061,13 @@ class MesonMain(InterpreterObject):
 
     @noPosargs
     @permittedKwargs({})
+    @FeatureDeprecated('meson.source_root', '0.56.0', 'use meson.current_source_dir instead.')
     def source_root_method(self, args, kwargs):
         return self.interpreter.environment.source_dir
 
     @noPosargs
     @permittedKwargs({})
+    @FeatureDeprecated('meson.build_root', '0.56.0', 'use meson.current_build_dir instead.')
     def build_root_method(self, args, kwargs):
         return self.interpreter.environment.build_dir