Merge pull request #6 from AkihiroSuda/dev

README.md: add environment variables

Author: AkihiroSuda

README.md

@@ -1,6 +1,20 @@
 # repro-sources-list.sh
 
-[`repro-sources-list.sh`](./repro-sources-list.sh) configures `/etc/apt/sources.list` and similar files for installing packages from a snapshot.
+[`repro-sources-list.sh`](./repro-sources-list.sh) configures `/etc/apt/sources.list` and similar files
+for installing packages from a snapshot to help [Reproducible Builds](https://reproducible-builds.org/).
+
+```dockerfile
+# SOURCE_DATE_EPOCH is set to 1691114774 (i.e., 20230804T020614Z, timestamp of /etc/apt/sources.list)
+FROM ubuntu:jammy-20230804
+ENV DEBIAN_FRONTEND=noninteractive
+RUN \
+  --mount=type=cache,target=/var/cache/apt,sharing=locked \
+  --mount=type=cache,target=/var/lib/apt,sharing=locked \
+  --mount=type=bind,source=./repro-sources-list.sh,target=/usr/local/bin/repro-sources-list.sh \
+  repro-sources-list.sh && \
+  apt-get update && \
+  apt-get install -y gcc
+```
 
 Examples:
 - [`Dockerfile.debian-11`](./Dockerfile.debian-11)
@@ -9,9 +23,27 @@ Examples:
 - [`Dockerfile.ubuntu-2304`](./Dockerfile.ubuntu-2304)
 - [`Dockerfile.archlinux`](./Dockerfile.archlinux)
 
-## Hint
+## Hints
 - To preserve the package cache on GHA, use <https://github.com/overmindtech/buildkit-cache-dance>.
   See [`.github/workflows/main.yaml`](./.github/workflows/main.yaml) for an example.
 
 - For Debian >= 13 and Ubuntu >= 23.10, see also [`./alternative/`](./alternative/)
   to lock packages without using [`repro-sources-list.sh`](./repro-sources-list.sh).
+
+### Environment variables
+
+| Variable                  | Description                                   | Default value                                                      |
+|---------------------------|-----------------------------------------------|--------------------------------------------------------------------|
+| `SOURCE_DATE_EPOCH`       | Timestamp of the snapshot (int64)             | Timestamp of `/etc/apt/sources.list`, etc. (See below)             |
+| `WRITE_SOURCE_DATE_EPOCH` | Write the `SOURCE_DATE_EPOCH` value to a file | `/dev/null`                                                        |
+| `SNAPSHOT_ARCHIVE_BASE`   | Base URL of the snapshot                      | `http://snapshot-cloudflare.debian.org/archive/`, etc. (See below) |
+| `BACKPORTS`               | Enable Debian backports                       | `0`                                                                |
+
+Distribution-specific default values:
+
+| Distribution   | `SOURCE_DATE_EPOCH`                                  | `SNAPSHOT_ARCHIVE_BASE`                          |
+|----------------|------------------------------------------------------|--------------------------------------------------|
+| Debian (<= 11) | Timestamp of `/etc/apt/sources.list`                 | `http://snapshot-cloudflare.debian.org/archive/` |
+| Debian (>= 12) | Timestamp of `/etc/apt/sources.list.d/debian.source` | `http://snapshot-cloudflare.debian.org/archive/` |
+| Ubuntu         | Timestamp of `/etc/apt/sources.list`                 | `http://snapshot.ubuntu.com/`                    |
+| ArchLinux      | Timestamp of `/var/log/pacman.log`                   | `http://archive.archlinux.org/`                  |

repro-sources-list.sh

@@ -82,15 +82,18 @@ case "${ID}" in
 	apt-get -o Acquire::https::Verify-Peer=false install -y ca-certificates >&2
 	;;
 "arch")
+	: "${SNAPSHOT_ARCHIVE_BASE:=http://archive.archlinux.org/}"
 	: "${SOURCE_DATE_EPOCH:=$(stat --format=%Y /var/log/pacman.log)}"
 	export SOURCE_DATE_EPOCH
 	# shellcheck disable=SC2016
-	date -d "@${SOURCE_DATE_EPOCH}" '+Server = https://archive.archlinux.org/repos/%Y/%m/%d/$repo/os/$arch' >/etc/pacman.d/mirrorlist
+	date -d "@${SOURCE_DATE_EPOCH}" "+Server = ${SNAPSHOT_ARCHIVE_BASE}repos/%Y/%m/%d/\$repo/os/\$arch" >/etc/pacman.d/mirrorlist
 	;;
 *)
 	echo >&2 "Unsupported distribution: ${ID}"
 	exit 1
 	;;
 esac
 
+: "${WRITE_SOURCE_DATE_EPOCH:=/dev/null}"
+echo "${SOURCE_DATE_EPOCH}" >"${WRITE_SOURCE_DATE_EPOCH}"
 echo "SOURCE_DATE_EPOCH=${SOURCE_DATE_EPOCH}"