Provide a distribution tarball with generated code and documentation.

meson dist produces the tarball via src/build/dist.sh, which regenerates help.auto.c.inc and interface.auto.c.inc, copies the man page and HTML into doc, and writes a dist marker to the root. When the marker is present the build uses the shipped files and skips build-code, libyaml, and the doc and test tools, so the tarball compiles and installs without the code generation or documentation tooling. .gitattributes export-ignore rules limit the tarball to what is needed to build: src (except the src/build code generation sources), meson.build, meson_options.txt, and LICENSE, plus the generated files, docs, marker, and a README copied from doc/DIST.md. RELEASE.md documents building the tarball, attaching it to a draft release, verifying it, and publishing. The user guides demonstrate building from the tarball.
2026-10-23 21:28:56 +03:00 · 2026-07-16 13:05:20 +07:00
parent 85ddcc94f9
commit 8fcfef5d87
13 changed files with 381 additions and 83 deletions
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,3 +1,13 @@
 # Classify all .h/c.inc files as C
 *.h linguist-language=C
 *.c.inc linguist-language=C
+
+# The distribution tarball (git archive) ships only what is needed to build pgbackrest: exclude everything, then re-include the
+# build inputs. src/build (code generation) is excluded because dist.sh ships the generated files instead. dist.sh also adds the
+# generated docs, the .inc files, the dist marker, and a distribution README.
+/* export-ignore
+/src -export-ignore
+/src/build export-ignore
+/meson.build -export-ignore
+/meson_options.txt -export-ignore
+/LICENSE -export-ignore
--- a/doc/DIST.md
+++ b/doc/DIST.md
@@ -0,0 +1,41 @@
+# pgBackRest Distribution
+
+This is a pgBackRest build distribution. Unlike a checkout of the [git repository](https://github.com/pgbackrest/pgbackrest), it ships the generated source and the rendered documentation pre-built, so pgBackRest can be built and installed without the code generation or the documentation tooling.
+
+See <https://pgbackrest.org> for complete documentation.
+
+## Contents
+
+- `src` -- pgBackRest source, including the pre-generated `*.auto.c.inc` files
+- `doc/man` -- command reference
+- `doc/html` -- HTML documentation
+- `meson.build`, `meson_options.txt` -- build configuration
+- `LICENSE`
+
+## Build
+
+pgBackRest builds with meson and ninja. The required libraries are libpq, OpenSSL (>= 1.1.1), libxml2, lz4, bz2, and zlib; zstd, libssh2 (for SFTP), and libsystemd are optional. For example, on Debian/Ubuntu:
+
+```
+apt-get install meson gcc pkg-config libpq-dev libssl-dev libxml2-dev \
+    liblz4-dev libzstd-dev libbz2-dev libz-dev libssh2-1-dev libsystemd-dev
+```
+
+Then configure, build, and install:
+```
+meson setup build .
+ninja -C build
+meson install -C build
+```
+
+The `pgbackrest` binary is built at `build/src/pgbackrest`.
+
+## Documentation
+
+The rendered documentation is in `doc`: the command reference in `doc/man` and the HTML documentation in `doc/html`.
+
+Two user guides are provided, Debian/Ubuntu and RHEL/Rocky/Alma. If only one user guide is required, replace user-guide-index.html with the desired user guide. For example, to keep only the Debian/Ubuntu user guide:
+```
+mv user-guide.html user-guide-index.html
+rm user-guide-rhel.html
+```
--- a/doc/RELEASE.md
+++ b/doc/RELEASE.md
@@ -140,31 +140,122 @@ Documentation Features:

 Commit to integration with the above message and push to CI.

+Wait for CI testing to complete before proceeding to the next step.
+
+## Create release on Github and dist tarball
+
+Set the release variables. `GITHUB_TOKEN` needs the `contents: write` permission:
+```
+export GITHUB_TOKEN=?
+export GITHUB_REPO=pgbackrest/pgbackrest
+export GIT_BRANCH=integration
+```
+
+Build the distribution tarball from a fresh checkout so the tree is clean for `meson dist`. Run the commands below from an empty directory.
+
+Shallow clone the release branch, then derive the version, release commit, and commit subject from the checkout. `RELEASE_COMMIT` is the tip commit, but only if its subject starts with `v${VERSION}:` -- if it comes back blank a later commit was added and the release steps are out of order:
+```
+rm -rf dist
+git clone --depth 1 --branch ${GIT_BRANCH?} https://github.com/${GITHUB_REPO?}.git dist/repo
+export VERSION=$(sed -n "s/^    version: '\([^']*\)',.*/\1/p" dist/repo/meson.build)
+export RELEASE_COMMIT=$(git -C dist/repo log --no-walk HEAD --grep="^v${VERSION?}: " --format=%H)
+export RELEASE_TITLE=$(git -C dist/repo log -1 --format=%s)
+echo ${RELEASE_COMMIT?}
+echo ${RELEASE_TITLE?}
+```
+
+Generate the distribution documentation. This writes the man page and HTML to `dist/repo/doc/output`, which the dist tarball picks up (the gitignored output does not dirty the tree):
+```
+dist/repo/doc/release.pl --dist
+```
+
+Configure the build and build the code generator, which the dist script uses to produce the shipped files:
+```
+meson setup dist/build dist/repo
+ninja -C dist/build src/build-code
+```
+
+Build the tarball. `meson dist` runs `src/build/dist.sh` to generate the `.inc` files, copy the documentation into `doc`, and write the `dist` marker, then builds and tests the extracted tarball to confirm it compiles without the code generation tooling:
+```
+meson dist -C dist/build --formats gztar
+```
+
+This produces `dist/build/meson-dist/pgbackrest-2.14.0.tar.gz` (named from the version in `meson.build`) along with its `pgbackrest-2.14.0.tar.gz.sha256sum` checksum. A successful `meson dist` means the tarball is self-contained and is the exact artifact to release.
+
+Immutable releases are enabled, so release assets are locked once the release is published. Create the release as a draft with the tarball attached, then set the notes and publish it in the next section.
+
+Generate the release body from the release commit message. It is the same content as the commit, so this bolds the section headers and any leading notes, and converts the bullets to markdown:
+```
+printf '%s' "$(git -C dist/repo log -1 --format=%b ${RELEASE_COMMIT?} |
+    sed -E 's/^([A-Za-z][A-Za-z ]*):$/**\1**:/; s/^([A-Z][A-Z ]*): /**\1**: /; s/^\* /- /')" > dist/release-body
+```
+
+Create the draft release and capture its id (requires `jq`). The title is the release commit subject and the body is read from the generated file. The `release/${VERSION}` tag is not created until the release is published:
+```
+RELEASE_ID=$(curl -sS -X POST \
+    -H "Authorization: Bearer ${GITHUB_TOKEN?}" -H "Accept: application/vnd.github+json" \
+    https://api.github.com/repos/${GITHUB_REPO?}/releases \
+    -d "$(jq -n --arg tag "release/${VERSION?}" --arg commit "${RELEASE_COMMIT?}" \
+        --arg name "${RELEASE_TITLE?}" --rawfile body dist/release-body \
+        '{tag_name: $tag, target_commitish: $commit, name: $name, body: $body, draft: true}')" \
+    | jq -r .id)
+echo $RELEASE_ID
+```
+
+Upload the tarball and its checksum as release assets:
+```
+ASSET_ID=$(curl -sS -X POST \
+    -H "Authorization: Bearer ${GITHUB_TOKEN?}" -H "Content-Type: application/gzip" \
+    --data-binary @dist/build/meson-dist/pgbackrest-${VERSION?}.tar.gz \
+    "https://uploads.github.com/repos/${GITHUB_REPO?}/releases/${RELEASE_ID?}/assets?name=pgbackrest-${VERSION?}.tar.gz" \
+    | jq -r .id)
+curl -sS -X POST \
+    -H "Authorization: Bearer ${GITHUB_TOKEN?}" -H "Content-Type: text/plain" \
+    --data-binary @dist/build/meson-dist/pgbackrest-${VERSION?}.tar.gz.sha256sum \
+    "https://uploads.github.com/repos/${GITHUB_REPO?}/releases/${RELEASE_ID?}/assets?name=pgbackrest-${VERSION?}.tar.gz.sha256sum"
+```
+
+The draft now has both assets attached. Set the notes and publish it in the next section; publishing creates the `release/${VERSION}` tag from `RELEASE_COMMIT` and locks the assets into the immutable release.
+
+Before publishing, download the attached asset into `dist/verify`, extract it, and build it. This proves the exact released bytes are self-contained before publishing:
+```
+rm -rf dist/verify
+mkdir -p dist/verify
+curl -fsSL -H "Authorization: Bearer ${GITHUB_TOKEN?}" -H "Accept: application/octet-stream" \
+    "https://api.github.com/repos/${GITHUB_REPO?}/releases/assets/${ASSET_ID?}" | tar zx -C dist/verify
+
+ls -lahR \
+    dist/verify/pgbackrest-${VERSION?}/src/command/help/help.auto.c.inc \
+    dist/verify/pgbackrest-${VERSION?}/src/postgres/interface.auto.c.inc \
+    dist/verify/pgbackrest-${VERSION?}/doc/html \
+    dist/verify/pgbackrest-${VERSION?}/doc/man
+
+rm -rf .cache/ccache
+meson setup dist/verify/build dist/verify/pgbackrest-${VERSION?}
+ninja -C dist/verify/build
+dist/verify/build/src/pgbackrest version
+```
+
 ## Push to main

 Push release commit to main once CI testing is complete.

-## Create release on github
+## Publish the release on github

-Create release notes based on pattern in prior releases (this should be automated at some point), e.g.
+The draft created above already has the correct title, body, tag, and assets. Show them to verify before publishing:
 ```
-v2.14.0: Bug Fix and Improvements
-
-**Bug Fixes**:
-
- Fix segfault when process-max > 8 for archive-push/archive-get. (Reported by User.)
-
-**Improvements**:
-
- Bypass database checks when stanza-delete issued with force. (Contributed by User. Suggested by User.)
- Add configure script for improved multi-platform support.
-
-**Documentation Features**:
-
- Add user guide for Debian.
+curl -sS -H "Authorization: Bearer ${GITHUB_TOKEN?}" \
+    https://api.github.com/repos/${GITHUB_REPO?}/releases/${RELEASE_ID?} |
+    jq -r '"TITLE: " + .name, "TAG: " + .tag_name, "COMMIT: " + .target_commitish, "BODY:", .body, "ASSETS:", (.assets[] | .name + " (" + (.size | tostring) + " bytes, " + .state + ", " + (if .digest then (.digest | ltrimstr("sha256:") | .[:8]) else "no digest" end) + ")")'
 ```

-The first line will be the release title and the rest will be the body. The tag field should be updated with the current version so a tag is created from main. **Be sure to select the release commit explicitly rather than auto-tagging the last commit in main!**
+When the output is correct, publish the release. This creates the `release/${VERSION}` tag from the release commit and locks the assets into the immutable release:
+```
+curl -sS -X PATCH \
+    -H "Authorization: Bearer ${GITHUB_TOKEN?}" -H "Accept: application/vnd.github+json" \
+    https://api.github.com/repos/${GITHUB_REPO?}/releases/${RELEASE_ID?} \
+    -d '{"draft": false}'
+```

 ## Push web documentation to main and deploy
 ```
--- a/doc/release.pl
+++ b/doc/release.pl
@@ -60,6 +60,8 @@ release.pl [options]
 Release Options:
   --build          Build the cache before release (should be included in the release commit)
   --deploy         Deploy documentation to website (can be done as docs are updated)
+   --dist           Deploy documentation to dist
+   --no-exe         Skip doc execution (just generate HTML, only applies to dist)
   --no-gen         Don't auto-generate
   --vm             vm to build documentation for
 =cut
@@ -73,7 +75,9 @@ my $bQuiet = false;
 my $strLogLevel = 'info';
 my $bBuild = false;
 my $bDeploy = false;
+my $bDist = false;
 my $bNoGen = false;
+my $bNoExe = false;
 my $strVm = undef;

 GetOptions ('help' => \$bHelp,
@@ -82,7 +86,9 @@ GetOptions ('help' => \$bHelp,
            'log-level=s' => \$strLogLevel,
            'build' => \$bBuild,
            'deploy' => \$bDeploy,
+            'dist' => \$bDist,
            'no-gen' => \$bNoGen,
+            'no-exe' => \$bNoExe,
            'vm=s' => \$strVm)
    or pod2usage(2);

@@ -106,9 +112,9 @@ eval
    }

    # If neither build nor deploy is requested then error
-    if (!$bBuild && !$bDeploy)
+    if (!$bBuild && !$bDeploy && !$bDist)
    {
-        confess &log(ERROR, 'neither --build nor --deploy requested, nothing to do');
+        confess &log(ERROR, 'neither --build nor --deploy nor --dist requested, nothing to do');
    }

    # Set console log level
@@ -307,6 +313,20 @@ eval
        executeTest("find ${strDeployPath} -path .git -prune -type f -exec chmod 640 {} +");
    }

+    # Generate dist documentation
+    if ($bDist)
+    {
+        &log(INFO, "Generate dist documentation");
+
+        my $strParam =
+            "--var=project-url-root=index.html --exclude=metric --exclude=news --var=logo=n --var=news=n --var=sponsor=n" .
+            ($bNoExe ? ' --no-exe' : ($bDev ? '' : ' --cache-only --var=release-date-static=y'));
+
+        executeTest("${strDocExe} ${strParam} --key-var=os-type=rhel --out=html");
+        $oStorageDoc->move("$strDocHtml/user-guide.html", "$strDocHtml/user-guide-rhel.html");
+        executeTest("${strDocExe} ${strParam} --out-preserve --out=html --out=man");
+    }
+
    # Exit with success
    exit 0;
 }
--- a/doc/xml/user-guide.xml
+++ b/doc/xml/user-guide.xml
@@ -61,7 +61,8 @@

        <!-- Path where builds are performed -->
        <variable key="build-path">/build</variable>
-        <variable key="build-br-path">{[build-path]}/pgbackrest-release-{[version]}</variable>
+        <variable key="build-br-path">{[build-path]}/pgbackrest-{[version]}</variable>
+        <variable key="build-br-path-tmp">{[build-path]}/pgbackrest-{[version]}-tmp</variable>
        <variable key="build-meson-path">{[build-path]}/pgbackrest</variable>

        <!-- PostreSQL versions to run documentation for and min/max versions represented -->
@@ -316,7 +317,7 @@
        RUN rm /etc/apt/apt.conf.d/70debconf &amp;&amp; \
            apt-get update &amp;&amp; \
            apt-get install -y --no-install-recommends sudo ssh curl vim gnupg lsb-release iputils-ping ca-certificates \
-                    tzdata locales libssh2-1-dev awscli 2>&amp;1
+                    tzdata locales libssh2-1-dev awscli git libyaml-dev libxml-checker-perl 2>&amp;1

        {[sudo-disable-core-dump]}

@@ -360,7 +361,7 @@
        VOLUME [ "/sys/fs/cgroup" ]

        # Install packages
-        RUN yum install -y openssh-server openssh-clients sudo wget vim openssl findutils dnf-plugins-core awscli2 2>&amp;1
+        RUN yum install -y openssh-server openssh-clients sudo wget vim openssl findutils dnf-plugins-core awscli2 git 2>&amp;1

        # Install and enable epel repository
        RUN dnf -y install epel-release
@@ -369,6 +370,9 @@
        # Install packages that require epel
        RUN dnf install -y azure-cli

+        # Install dev packages
+        RUN yum install -y libyaml-devel 2>&amp;1
+
        # Install CA certificate
        RUN update-ca-trust extract

@@ -387,6 +391,12 @@
        # Install PostgreSQL
        RUN yum install -y postgresql{[pg-version]}-server postgresql{[pg-version-upgrade]}-server

+        # XML::Checker::Parser has no RHEL package; install its packaged XML::Parser dependency, cpanm the pure-Perl layer, and
+        # remove the build tools in the same layer so they do not persist in the image
+        RUN yum install -y perl-XML-Parser perl-App-cpanminus make perl-ExtUtils-MakeMaker &amp;&amp; \
+            cpanm --notest XML::Checker::Parser &amp;&amp; \
+            yum remove -y perl-App-cpanminus make perl-ExtUtils-MakeMaker
+
        # Install systemctl replacement that works without systemd running
        ENV SYSCTL_REP_VER=1.5.8066
        RUN wget -q -O - https://github.com/gdraheim/docker-systemctl-replacement/archive/refs/tags/v${SYSCTL_REP_VER?}.tar.gz | \
@@ -995,17 +1005,6 @@
                    tar zx -C {[build-path]}
                </exe-cmd>
            </execute>
-
-            <!-- These commands simulate what the command above would do if it could be run -->
-            <execute user="root" show="n">
-                <exe-cmd>mkdir -p {[build-br-path]}</exe-cmd>
-            </execute>
-            <execute user="root" show="n">
-                <exe-cmd>cp -r {[pgbackrest-repo-path]}/* {[build-br-path]}</exe-cmd>
-            </execute>
-            <execute user="root" show="n">
-                <exe-cmd>chown -R {[host-build-user]} {[build-path]}</exe-cmd>
-            </execute>
        </execute-list>

        <execute-list host="{[host-build]}">
@@ -1018,20 +1017,71 @@
            <execute if="{[os-type-is-debian]}" user="root" pre="y">
                <exe-cmd>
                    apt-get install python3-distutils meson gcc libpq-dev libssl-dev libxml2-dev
-                    pkg-config liblz4-dev libzstd-dev libbz2-dev libz-dev libyaml-dev libssh2-1-dev
-                    libsystemd-dev
+                    pkg-config liblz4-dev libzstd-dev libbz2-dev libz-dev libssh2-1-dev libsystemd-dev
                </exe-cmd>
                <exe-cmd-extra>-y 2>&amp;1</exe-cmd-extra>
            </execute>

            <execute if="{[os-type-is-rhel]}" user="root" pre="y">
                <exe-cmd>
-                    yum install meson gcc postgresql{[pg-version]}-devel openssl-devel
-                    libxml2-devel lz4-devel libzstd-devel bzip2-devel libyaml-devel libssh2-devel
-                    systemd-devel
+                    yum install meson gcc postgresql{[pg-version]}-devel openssl-devel libxml2-devel
+                    lz4-devel libzstd-devel bzip2-devel libssh2-devel systemd-devel
                </exe-cmd>
                <exe-cmd-extra>-y 2>&amp;1</exe-cmd-extra>
            </execute>
+
+            <!-- These rest of the commands in this execute-block simulate downloading the distribution tarball -->
+            <execute user="root" user-force="y" show="n" bash-wrap="y">
+                <exe-cmd>
+                    mkdir -p {[build-br-path-tmp]} &amp;&amp;
+                    chown -R {[host-build-user]} {[build-path]}
+                </exe-cmd>
+            </execute>
+            <execute show="n">
+                <exe-cmd>
+                    git config --global --add safe.directory {[pgbackrest-repo-path]} &amp;&amp;
+                    git -C {[pgbackrest-repo-path]} ls-files -c --others --exclude-standard |
+                    grep -v '^doc/resource/exe\.cache$' |
+                    tar -C {[pgbackrest-repo-path]} -cf - -T - | tar -C {[build-br-path-tmp]} -xf -
+                </exe-cmd>
+            </execute>
+
+            <!-- Build a git repo that can be used with meson dist. We need a new repo because there may be files that are not
+                 checked in during development and meson dist will ignore them -->
+            <execute show="n">
+                <exe-cmd>
+                    git config --global user.name "test" &amp;&amp;
+                    git config --global user.email "test@test.com" &amp;&amp;
+                    git -C {[build-br-path-tmp]} init 2>&amp;1 &amp;&amp;
+                    git -C {[build-br-path-tmp]} add . &amp;&amp;
+                    git -C {[build-br-path-tmp]} commit -a -m "test"
+                </exe-cmd>
+            </execute>
+
+            <!-- Create a distribution tarball with meson dist. Fake the dist output of release.pl to save time. -->
+            <execute show="n">
+                <exe-cmd>
+                    meson setup {[build-meson-path]} {[build-br-path-tmp]} &amp;&amp;
+                    ninja -C {[build-meson-path]} src/build-code &amp;&amp;
+                    mkdir -p {[build-br-path-tmp]}/doc/output/html &amp;&amp;
+                    mkdir -p {[build-br-path-tmp]}/doc/output/man &amp;&amp;
+                    PYTHONWARNINGS=ignore meson dist -C {[build-meson-path]} --formats gztar &amp;&amp;
+                    tar zx -C {[build-path]} -f {[build-meson-path]}/meson-dist/pgbackrest-{[version]}.tar.gz &amp;&amp;
+                    rm -rf {[build-meson-path]}
+                </exe-cmd>
+            </execute>
+
+            <!-- Remove libyaml now that we are done with it so future dependencies will cause a failure -->
+            <execute if="{[os-type-is-debian]}" user="root" show="n">
+                <exe-cmd>
+                    apt-get remove -y libyaml-dev 2>&amp;1
+                </exe-cmd>
+            </execute>
+            <execute if="{[os-type-is-rhel]}" user="root" show="n">
+                <exe-cmd>
+                    yum remove -y libyaml-devel 2>&amp;1
+                </exe-cmd>
+            </execute>
        </execute-list>

        <execute-list host="{[host-build]}">
--- a/meson.build
+++ b/meson.build
@@ -161,6 +161,21 @@ file_prefix = run_command(
 add_project_arguments(cc.get_supported_arguments('-fmacro-prefix-map=@0@/src/=' . format(file_prefix)), language: 'c')
 add_project_arguments(cc.get_supported_arguments('-fmacro-prefix-map=@0@/test/src/=test/' . format(file_prefix)), language: 'c')

+####################################################################################################################################
+# Detect a distribution tarball, which is marked by the dist file written into the tarball root by meson dist. A distribution
+# tarball ships the generated files, so the code generation tooling (build-code, the doc and test tools, libyaml) is not built. A
+# normal source tree such as a git checkout has no marker and generates the files.
+####################################################################################################################################
+dist = run_command(
+    [
+        python,
+        '-c',
+        'import os, sys; sys.exit(0 if os.path.exists(os.path.join(sys.argv[1], "dist")) else 1)',
+        meson.current_source_dir(),
+    ],
+    check: false,
+).returncode() == 0
+
 ####################################################################################################################################
 # Build configuration
 ####################################################################################################################################
@@ -203,8 +218,10 @@ lib_pq = dependency('libpq')
 # Find required xml library
 lib_xml = dependency('libxml-2.0')

-# Find required yaml library (only used for build)
-lib_yaml = dependency('yaml-0.1')
+# Find yaml library (only used by the code generation tooling, which is not built from a distribution tarball)
+if not dist
+    lib_yaml = dependency('yaml-0.1')
+endif

 # Find required gz library
 lib_z = dependency('zlib')
@@ -265,5 +282,12 @@ endif
 # Include subdirs
 ####################################################################################################################################
 subdir('src')
-subdir('doc/src')
-subdir('test/src')
+
+# The doc and test tools generate code and are not built from a distribution tarball
+if not dist
+    subdir('doc/src')
+    subdir('test/src')
+
+    # Bake the generated files and the dist marker into the tarball so it builds without the code generation tooling
+    meson.add_dist_script('src/build/dist.sh')
+endif
--- a/src/build/dist.sh
+++ b/src/build/dist.sh
@@ -0,0 +1,43 @@
+#!/bin/sh
+####################################################################################################################################
+# Prepare the distribution so the tarball can be built and installed without the code generation or documentation tooling: generate
+# the code files, copy the man pages and HTML documentation into doc, copy the distribution README, and write the dist marker that
+# tells the build to use the shipped generated files.
+#
+# build-code reads its inputs from the source tree and writes the generated files into the distribution. The inputs come from the
+# source rather than the distribution because src/build (the code generation sources) is excluded from the tarball. The read path
+# is passed with a trailing component because build-code uses the parent directory of that argument as the repo root.
+####################################################################################################################################
+set -eu
+
+build_code="$MESON_BUILD_ROOT/src/build-code"
+
+if [ ! -x "$build_code" ]; then
+    echo "dist: $build_code not found; run ninja before meson dist" >&2
+    exit 1
+fi
+
+"$build_code" help "$MESON_SOURCE_ROOT/." "$MESON_DIST_ROOT"
+"$build_code" postgres "$MESON_SOURCE_ROOT/." "$MESON_DIST_ROOT"
+
+# Copy the man pages and HTML documentation generated by doc/release.pl --dist into doc/man and doc/html
+mkdir -p "$MESON_DIST_ROOT/doc"
+
+for doc in man html; do
+    doc_src="$MESON_SOURCE_ROOT/doc/output/$doc"
+
+    if [ ! -d "$doc_src" ]; then
+        echo "dist: $doc_src not found; run 'doc/release.pl --dist' before meson dist" >&2
+        exit 1
+    fi
+
+    cp -R "$doc_src" "$MESON_DIST_ROOT/doc/"
+done
+
+# Copy the distribution README into the tarball root
+cp "$MESON_SOURCE_ROOT/doc/DIST.md" "$MESON_DIST_ROOT/README.md"
+
+# Write the dist marker to the root. Its presence is what switches the build to the shipped generated files; it records the version
+# for traceability.
+version=$(basename "$MESON_DIST_ROOT")
+echo "${version#pgbackrest-}" > "$MESON_DIST_ROOT/dist"
--- a/src/command/help/meson.build
+++ b/src/command/help/meson.build
@@ -1,16 +1,22 @@
 ####################################################################################################################################
 # Generate help
 ####################################################################################################################################
-help_auto_c_inc = custom_target(
-    'help.auto.c.inc',
-    output: 'help.auto.c.inc',
-    depend_files: [
-        '../../build/config/config.yaml',
-        '../../build/help/help.xml',
-    ],
-    command: [
-        build_code,
-        'help',
-        '@CURRENT_SOURCE_DIR@/../../..',
-    ],
-)
+# Generate help.auto.c.inc, unless this is a distribution tarball that ships the file
+if not dist
+    help_auto_c_inc = custom_target(
+        'help.auto.c.inc',
+        output: 'help.auto.c.inc',
+        depend_files: [
+            '../../build/config/config.yaml',
+            '../../build/help/help.xml',
+        ],
+        command: [
+            build_code,
+            'help',
+            '@CURRENT_SOURCE_DIR@/../../..',
+        ],
+    )
+else
+    # The shipped file is included by main.c via the implicit source include path, so it is not a compiled source
+    help_auto_c_inc = []
+endif
--- a/src/meson.build
+++ b/src/meson.build
@@ -94,25 +94,27 @@ src_build_code = [
    'common/compress/bz2/compress.c',
 ]

-build_code = executable(
-    'build-code',
-    src_common,
-    src_build_code,
-    dependencies: [
-        lib_backtrace,
-        lib_bz2,
-        lib_xml,
-        lib_yaml
-    ],
-    c_args: [
-        arg_unity,
-    ],
-)
+if not dist
+    build_code = executable(
+        'build-code',
+        src_common,
+        src_build_code,
+        dependencies: [
+            lib_backtrace,
+            lib_bz2,
+            lib_xml,
+            lib_yaml
+        ],
+        c_args: [
+            arg_unity,
+        ],
+    )
+endif

-# Build help.auto.c.inc
+# Build help.auto.c.inc (or use the copy shipped in the distribution tarball)
 subdir('command/help')

-# Build interface.auto.c.inc
+# Build interface.auto.c.inc (or use the copy shipped in the distribution tarball)
 subdir('postgres')

 ####################################################################################################################################
--- a/src/postgres/meson.build
+++ b/src/postgres/meson.build
@@ -1,15 +1,21 @@
 ####################################################################################################################################
 # Generate PostgreSQL interfaces
 ####################################################################################################################################
-interface_auto_c_inc = custom_target(
-    'interface.auto.c.inc',
-    output: 'interface.auto.c.inc',
-    depend_files: [
-        '../build/postgres/postgres.yaml',
-    ],
-    command: [
-        build_code,
-        'postgres',
-        '@CURRENT_SOURCE_DIR@/../..',
-    ],
-)
+# Generate interface.auto.c.inc, unless this is a distribution tarball that ships the file
+if not dist
+    interface_auto_c_inc = custom_target(
+        'interface.auto.c.inc',
+        output: 'interface.auto.c.inc',
+        depend_files: [
+            '../build/postgres/postgres.yaml',
+        ],
+        command: [
+            build_code,
+            'postgres',
+            '@CURRENT_SOURCE_DIR@/../..',
+        ],
+    )
+else
+    # The shipped file is included by interface.c via the implicit source include path, so it is not a compiled source
+    interface_auto_c_inc = []
+endif
--- a/test/src/command/test/build.c
+++ b/test/src/command/test/build.c
@@ -398,6 +398,9 @@ testBldUnit(TestBuild *const this)
        // Comment out subdirs that are not used for testing
        strReplace(mesonBuild, STRDEF("subdir('"), STRDEF("# subdir('"));

+        // Comment out the distribution script, which is only used when building a distribution tarball
+        strReplace(mesonBuild, STRDEF("meson.add_dist_script("), STRDEF("# meson.add_dist_script("));
+
        if (!testBldBackTrace(this))
        {
            strReplace(
--- a/test/src/module/test/testTest.c
+++ b/test/src/module/test/testTest.c
@@ -192,6 +192,7 @@ testRun(void)

        HRN_STORAGE_PUT_Z(storageTest, "repo/meson.build", strZ(mesonBuildRoot));
        strReplace(mesonBuildRoot, STRDEF("subdir('"), STRDEF("# subdir('"));
+        strReplace(mesonBuildRoot, STRDEF("meson.add_dist_script("), STRDEF("# meson.add_dist_script("));

        strCatZ(
            mesonBuildRoot,
--- a/test/test.pl
+++ b/test/test.pl
@@ -565,6 +565,7 @@ eval
                $strFile eq 'doc/release.pl' ||
                $strFile eq 'test/ci.pl' ||
                $strFile eq 'test/test.pl' ||
+                $strFile eq 'src/build/dist.sh' ||
                $hManifest->{$strFile}{type} eq 'd')
            {
                $strExpectedMode = sprintf('%04o', oct($hManifest->{$strFile}{mode}) & 0777);