From 350ac54246220698483a5d42edb142051f00ad12 Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Mon, 22 Jul 2024 10:59:33 -0700
Subject: [PATCH] Add some more comments about where configuration comes in

---
 ci/docker/Dockerfile.arm64-linux  | 6 ++++++
 ci/docker/Dockerfile.common       | 6 ++++++
 ci/docker/Dockerfile.x86_64-linux | 6 ++++++
 3 files changed, 18 insertions(+)

diff --git a/ci/docker/Dockerfile.arm64-linux b/ci/docker/Dockerfile.arm64-linux
index b7113299e..6be6d6ed8 100644
--- a/ci/docker/Dockerfile.arm64-linux
+++ b/ci/docker/Dockerfile.arm64-linux
@@ -1,5 +1,11 @@
 FROM wasi-sdk-builder-base
 
+# Install an extra C++ toolchain which can target arm64 linux.
 RUN apt-get install -y g++-aarch64-linux-gnu
 
+# Configure Rust to use this new compiler for linking Rust executables.
 ENV CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER aarch64-linux-gnu-gcc
+
+# Note that `.github/workflows/main.yml` sets various bits and bobs of
+# configuration and cmake flags that may get passed to the underlying build. For
+# example LLVM is instructed to use the toolchain installed above.
diff --git a/ci/docker/Dockerfile.common b/ci/docker/Dockerfile.common
index 1ab98a61a..480e9b77d 100644
--- a/ci/docker/Dockerfile.common
+++ b/ci/docker/Dockerfile.common
@@ -4,6 +4,7 @@
 
 FROM ubuntu:18.04
 
+# Various build tooling and such necessary to build LLVM and a wasi-sysroot
 RUN apt-get update \
   && apt-get install -y --no-install-recommends \
   ccache \
@@ -16,6 +17,8 @@ RUN apt-get update \
   unzip \
   xz-utils
 
+# Install a more recent version of CMake than what 18.04 has since that's what
+# LLVM requires.
 RUN curl -sSLO https://github.com/Kitware/CMake/releases/download/v3.29.5/cmake-3.29.5-linux-x86_64.tar.gz \
   && tar xf cmake-3.29.5-linux-x86_64.tar.gz \
   && rm cmake-3.29.5-linux-x86_64.tar.gz \
@@ -24,9 +27,12 @@ RUN curl -sSLO https://github.com/Kitware/CMake/releases/download/v3.29.5/cmake-
 
 ENV PATH /opt/cmake/bin:$PATH
 
+# As with CMake install a later version of Ninja than waht 18.04 has.
 RUN curl -sSLO https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-linux.zip \
   && unzip ninja-linux.zip \
   && rm *.zip \
   && mv ninja /opt/cmake/bin
 
+# Tell programs to cache in a location that both isn't a `--volume` mounted root
+# and isn't `/root` in the container as that won't be writable during the build.
 ENV XDG_CACHE_HOME /tmp/cache
diff --git a/ci/docker/Dockerfile.x86_64-linux b/ci/docker/Dockerfile.x86_64-linux
index 979bdb9b3..9d443e530 100644
--- a/ci/docker/Dockerfile.x86_64-linux
+++ b/ci/docker/Dockerfile.x86_64-linux
@@ -1 +1,7 @@
 FROM wasi-sdk-builder-base
+
+# No extra configuration necessary for x86_64 over what `Dockerfile.common`
+# already has.
+#
+# Note though that `.github/workflows/main.yml` still sets various bits and bobs
+# of configuration and cmake flags that may get passed to the underlying build.