Merge pull request #12804 from joukewitteveen/dist-rewriter

Support `meson dist` when getting project versions from VCS

3 files changed, 39 insertions, 0 deletions

diff --git a/docs/markdown/Creating-releases.md b/docs/markdown/Creating-releases.md
index 638125c87..e0c80af5b 100644
--- a/docs/markdown/Creating-releases.md
+++ b/docs/markdown/Creating-releases.md
@@ -86,3 +86,30 @@ meson setup builddir
 meson dist -C builddir
 ```
 This produces `builddir/meson-dist/mysubproject-1.0.tar.xz` tarball.
+
+## Cement a version obtained from VCS
+
+*Since 1.4.0* the `meson dist` command enables rewriting the build
+configuration of the distribution tarball. This is needed when the
+configuration depends on metadata from revision control such as in the
+following example.
+
+`meson.build`:
+```meson
+project('tig', 'c',
+  version : run_command('version.sh', 'get-vcs').stdout.strip())
+
+meson.add_dist_script('version.sh', 'set-dist', meson.project_version())
+```
+`version.sh`:
+```sh
+#!/bin/sh
+
+if [ "$1" = "get-vcs" ]; then
+  git -C "$MESON_SOURCE_ROOT" describe --always --dirty
+elif [ "$1" = "set-dist" ]; then
+  $MESONREWRITE --sourcedir="$MESON_PROJECT_DIST_ROOT" kwargs set project / version "$2"
+else
+  exit 1
+fi
+```
diff --git a/docs/markdown/Reference-tables.md b/docs/markdown/Reference-tables.md
index af6a9b9f0..02ac083e5 100644
--- a/docs/markdown/Reference-tables.md
+++ b/docs/markdown/Reference-tables.md
@@ -85,6 +85,7 @@ For languages that don't have separate dynamic linkers such as C# and Java, the
 | Value               | Comment                         |
 | -----               | -------                         |
 | MESONINTROSPECT     | Command to run to run the introspection command, may be of the form `python /path/to/meson introspect`, user is responsible for splitting the path if necessary. |
+| MESONREWRITE        | Command to run to run the rewriting command, only set when running `dist` scripts |
 | MESON_BUILD_ROOT    | Absolute path to the build dir  |
 | MESON_DIST_ROOT     | Points to the root of the staging directory, only set when running `dist` scripts |
 | MESON_SOURCE_ROOT   | Absolute path to the source dir |
diff --git a/docs/yaml/builtins/meson.yaml b/docs/yaml/builtins/meson.yaml
index 0d4eacf60..516e41c3d 100644
--- a/docs/yaml/builtins/meson.yaml
+++ b/docs/yaml/builtins/meson.yaml
@@ -32,6 +32,17 @@ methods:
       scripts, but for subproject scripts they have the path to the root of the
       subproject appended, usually `subprojects/<subproject-name>`.
 
+      *(since 1.4.0)* The `MESONREWRITE` environment variable contains the path
+      to the rewrite command that corresponds to the `meson` executable that
+      was used to configure the build. (This might be a different path than the
+      first executable found in `PATH`.) It can be used to remove or replace
+      any [[run_command]] that depends on the revision control system from the
+      build configuration. Note that the value will contain many parts. For
+      example, it may be `python3 /path/to/meson.py introspect`. The user is
+      responsible for splitting the string to an array if needed by splitting
+      lexically like a UNIX shell would. If your script uses Python,
+      `shlex.split()` is the easiest correct way to do this.
+
     posargs:
       script_name:
         type: str | file | external_program