Allow add_dist_script() in subprojects

Fixes: #8440.

2 files changed, 29 insertions, 6 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index d81be47..6e18e68 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1907,16 +1907,25 @@ the following methods.
   archived. Note that this runs the script file that is in the
   _staging_ directory, not the one in the source directory. If the
   script file can not be found in the staging directory, it is a hard
-  error. This command can only invoked from the main project, calling
-  it from a subproject is a hard error. *(since 0.49.0)* Accepts multiple arguments
-  for the script. *(since 0.54.0)* The `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT`
-  environment variables are set when dist scripts are run.
-
+  error. The `MESON_DIST_ROOT` environment variables is set when dist scripts is
+  run.
+  *(since 0.49.0)* Accepts multiple arguments for the script.
+  *(since 0.54.0)* The `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT`
+  environment variables are set when dist scripts are run. They are path to the
+  root source and build directory of the main project, even when the script
+  comes from a subproject.
   *(since 0.55.0)* The output of `configure_file`, `files`, and `find_program`
   as well as strings.
-
   *(since 0.57.0)* `file` objects and the output of `configure_file` may be
   used as the `script_name` parameter.
+  *(since 0.58.0)* This command can be invoked from a subproject, it was a hard
+  error in earlier versions. Subproject dist scripts will only be executed
+  when running `meson dist --include-subprojects`. `MESON_PROJECT_SOURCE_ROOT`,
+  `MESON_PROJECT_BUILD_ROOT` and `MESON_PROJECT_DIST_ROOT` environment
+  variables are set when dist scripts are run. They are identical to
+  `MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT` and `MESON_DIST_ROOT` for main project
+  scripts, but for subproject scripts they have the path to the root of the
+  subproject appended, usually `subprojects/<subproject-name>`.
 
 - `add_install_script(script_name, arg1, arg2, ...)`: causes the script
   given as an argument to be run during the install step, this script
diff --git a/docs/markdown/snippets/dist_script.md b/docs/markdown/snippets/dist_script.md
new file mode 100644
index 0000000..93b97aa
--- /dev/null
+++ b/docs/markdown/snippets/dist_script.md
@@ -0,0 +1,14 @@
+## `meson.add_dist_script()` allowd in subprojects
+
+`meson.add_dist_script()` can now be invoked from a subproject, it was a hard
+error in earlier versions. Subproject dist scripts will only be executed
+when running `meson dist --include-subprojects`. `MESON_PROJECT_SOURCE_ROOT`,
+`MESON_PROJECT_BUILD_ROOT` and `MESON_PROJECT_DIST_ROOT` environment variables
+are set when dist scripts are run. They are identical to `MESON_SOURCE_ROOT`,
+`MESON_BUILD_ROOT` and `MESON_DIST_ROOT` for main project scripts, but for
+subproject scripts they have the path to the root of the subproject appended,
+usually `subprojects/<subproject-name>`.
+
+Note that existing dist scripts likely need to be modified to use those new
+environment variables instead of `MESON_DIST_ROOT` to work properly when used
+from a subproject.