From ab7e7329862c57fd2bc27927a522f62ee9184483 Mon Sep 17 00:00:00 2001
From: Max Perrello <20795292+maxtheaxe@users.noreply.github.com>
Date: Sun, 21 Sep 2025 19:09:41 +0200
Subject: [PATCH] update build scripts and readme to ensure required submodules
 get initialized

---
 README.md               |  3 +++
 scripts/docker-build.sh |  7 +++++++
 scripts/shared.sh       | 19 +++++++++++++++++++
 3 files changed, 29 insertions(+)

diff --git a/README.md b/README.md
index f917fdd..b959635 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,9 @@ Any content imported from other projects retains its original license (for
 example, any original unmodified code imported from ungoogled-chromium remains
 licensed under their [BSD 3-Clause license](LICENSE.ungoogled_chromium)).
 
+## Getting Started
+Initialize the git submodule, using `git submodule update --init --recursive`. You can skip this if you cloned using `--recurse-submodules`.
+
 ## Building
 To build the binary, run `scripts/docker-build.sh` from the repo root.
 
diff --git a/scripts/docker-build.sh b/scripts/docker-build.sh
index 9e4e931..d559b92 100755
--- a/scripts/docker-build.sh
+++ b/scripts/docker-build.sh
@@ -4,6 +4,13 @@ set -euo pipefail
 _base_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" &>/dev/null && cd .. && pwd)"
 _image="chromium-builder:trixie-slim"
 
+# Fail fast: required submodule must be initialized before any Docker work
+if [ ! -f "${_base_dir}/helium-chromium/utils/downloads.py" ] && [ ! -f "${_base_dir}/helium-chromium/utils/clone.py" ]; then
+    echo "error: submodule 'helium-chromium' is not initialized (missing utils/*)" >&2
+    echo "hint: run 'git submodule update --init --recursive' in the repo root" >&2
+    exit 1
+fi
+
 if [ -z "${_use_existing_image:-}" ]; then
     echo "building docker image '${_image}'"
     cd "${_base_dir}/docker" && docker buildx build --load -t "${_image}" -f ./build.Dockerfile .
diff --git a/scripts/shared.sh b/scripts/shared.sh
index dabac4a..5c247b2 100755
--- a/scripts/shared.sh
+++ b/scripts/shared.sh
@@ -47,6 +47,25 @@ setup_environment() {
     setup_arch
 
     _has_pgo=false
+
+    verify_submodules
+}
+
+# Verify required git submodules are present (helium-chromium)
+verify_submodules() {
+    if [ ! -d "${_main_repo}" ]; then
+        echo "error: required submodule directory not found: ${_main_repo}" >&2
+        echo "hint: run 'git submodule update --init --recursive' in the repo root" >&2
+        exit 1
+    fi
+
+    # One of these utilities must exist if the submodule is initialized
+    if [ ! -f "${_main_repo}/utils/downloads.py" ] && [ ! -f "${_main_repo}/utils/clone.py" ]; then
+        echo "error: submodule 'helium-chromium' appears uninitialized or incomplete" >&2
+        echo "missing: ${_main_repo}/utils/downloads.py (and/or clone.py)" >&2
+        echo "hint: run 'git submodule update --init --recursive' in the repo root" >&2
+        exit 1
+    fi
 }
 
 fetch_sources() {