From 5592b5fbfb71b21a1daa6175000158d03894216c Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Mon, 19 May 2025 16:58:47 +0200
Subject: [PATCH 01/13] Build static and dynamic

---
 .github/actions/setup-haskell/action.yaml |  48 +++++++
 .github/workflows/waspc-build.yaml        | 156 ++++++++++++++++++++++
 waspc/run                                 |   6 +
 3 files changed, 210 insertions(+)
 create mode 100644 .github/actions/setup-haskell/action.yaml
 create mode 100644 .github/workflows/waspc-build.yaml

diff --git a/.github/actions/setup-haskell/action.yaml b/.github/actions/setup-haskell/action.yaml
new file mode 100644
index 0000000000..ffe25d212e
--- /dev/null
+++ b/.github/actions/setup-haskell/action.yaml
@@ -0,0 +1,48 @@
+name: Setup Haskell
+description: |
+  This action sets up a Haskell environment for use in actions by
+  adding the GHC and Cabal binaries to the PATH. It also caches
+  the GHC and Cabal installations to speed up subsequent runs.
+inputs:
+  ghc-version:
+    description: |
+      The version of GHC to install.
+    required: false
+    default: "8.10.7"
+
+  cabal-version:
+    description: |
+      The version of Cabal to install.
+    required: false
+    default: "latest"
+
+runs:
+  using: composite
+
+  steps:
+    - uses: haskell-actions/setup@v2
+      id: setup-haskell
+      with:
+        ghc-version: ${{ inputs.ghc-version }}
+        cabal-version: ${{ inputs.cabal-version }}
+
+    - name: Verify Haskell setup
+      shell: bash
+      run: |
+        ghc --version
+        cabal --version
+
+    # Based on the official recipe for Cabal caching:
+    # https://github.com/actions/cache/blob/v4.2.3/examples.md#haskell---cabal
+    - name: Cache Cabal dependencies
+      uses: actions/cache@v4
+      with:
+        path: |
+          ${{ steps.setup-haskell.outputs.cabal-store }}
+        # Caches are immutable, so we use the official recipe for simulating an updatable cache:
+        # https://github.com/actions/cache/blob/v4.2.3/tips-and-workarounds.md#update-a-cache
+        key: |
+          ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}-${{ github.run_id }}
+        restore-keys: |
+          ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}-
+          ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-
diff --git a/.github/workflows/waspc-build.yaml b/.github/workflows/waspc-build.yaml
new file mode 100644
index 0000000000..6ce24de508
--- /dev/null
+++ b/.github/workflows/waspc-build.yaml
@@ -0,0 +1,156 @@
+name: Build binaries
+
+# We never trigger this workflow directly.
+# We can call it manually (workflow_dispatch) or from other workflows (workflow_call).
+on:
+  workflow_dispatch:
+    inputs:
+      ghc-version:
+        description: 'GHC version to use'
+        default: '8.10.7'
+        required: false
+      node-version:
+        description: 'Node.js version to use'
+        default: '22'
+        required: false
+  workflow_call:
+    inputs:
+      ghc-version:
+        description: 'GHC version to use'
+        default: '8.10.7'
+        type: string
+        required: false
+      node-version:
+        description: 'Node.js version to use'
+        default: '22'
+        type: string
+        required: false
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+
+      matrix:
+        # == Why such a big, heterogeneous list? ==
+        # This is a bit of mish-mash of different platforms and architectures,
+        # so we need to build some of these directly in the runners, and some in
+        # containers. Each environment is a different OS and needs different
+        # dependencies.
+        env:
+          - name: linux-x86_64
+            runner: ubuntu-latest
+            container: ubuntu:20.04 # Old Ubuntu version so we have a low glibc requirement
+            install-deps: |
+              export DEBIAN_FRONTEND=noninteractive
+              apt-get update -y
+              # GHCup dependencies (https://www.haskell.org/ghcup/install/#version-2004-2010)
+              apt-get install -y build-essential curl libffi-dev libffi7 libgmp-dev libgmp10 libncurses-dev libncurses5 libtinfo5
+              # Cabal dependencies
+              apt-get install -y zlib1g-dev
+
+          # TODO: Add a Linux ARM64 build once we update the GHC version (#1446)
+          # GHC 8.10.7 does not support ARM64 on Linux yet
+
+          - name: linux-x86_64-static
+            runner: ubuntu-latest
+            # actions/setup-node does not work in alpine to work around this, we
+            # use the alpine variant of the official node image, which already
+            # has it installed.
+            container: node:${{ inputs.node-version }}-alpine
+            skip-node-install: true
+            static: true
+            install-deps: |
+              apk update
+              # GHCup dependencies (https://www.haskell.org/ghcup/install/#linux-alpine)
+              apk add binutils-gold curl gcc g++ gmp-dev libc-dev libffi-dev make musl-dev ncurses-dev perl pkgconfig tar xz
+              # Build script dependencies
+              apk add bash
+              # Cabal dependencies
+              apk add zlib-dev zlib-static
+
+          - name: darwin-x86_64
+            runner: macos-13 # Latest image still based on Intel architecture that can be used for free
+
+          - name: darwin-aarch64
+            runner: macos-latest # Latest macOS images are already Apple Silicon-based
+            install-deps: |
+              # We need to install llvm@13 for building on Apple Silicon (prebuilt libraries
+              # are only available for x86_64). The llvm@13 formula is not available in
+              # Homebrew by default, but we can edit it and remove the disable! line.
+              curl -fsSL https://raw.githubusercontent.com/Homebrew/homebrew-core/74572f47ce6a2463c19d7fa164ab9fb8c91bbe61/Formula/l/llvm%4013.rb > /tmp/llvm@13.rb
+              sed -i '' 's/disable!/# disable!/' /tmp/llvm@13.rb
+              brew install --formula /tmp/llvm@13.rb
+              brew link --force llvm@13
+
+    runs-on: ${{ matrix.env.runner }}
+    container: ${{ matrix.env.container }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: ${{ matrix.env.install-deps }}
+
+      - uses: ./.github/actions/setup-haskell
+        with:
+          ghc-version: ${{ inputs.ghc-version }}
+
+      - uses: actions/setup-node@v4
+        if: ${{ !matrix.env.skip-node-install }}
+        with:
+          node-version: ${{ inputs.node-version }}
+
+      - name: Build and package
+        working-directory: waspc
+        env:
+          LC_ALL: C.UTF-8 # In some Docker containers the LOCALE is not UTF-8 by default
+        run: |
+          ./run build:all${{ matrix.env.static && ':static' || '' }}
+          mkdir -p artifacts
+          ./tools/make_binary_package.sh "artifacts/wasp-${{ matrix.env.name }}.tar.gz"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          path: ./waspc/artifacts/*
+          name: wasp-${{ matrix.env.name }}
+          if-no-files-found: error
+
+  build-universal:
+    needs: build
+    runs-on: macos-latest
+    steps:
+      - name: Download macOS binaries
+        uses: actions/download-artifact@v4
+        with:
+          pattern: wasp-darwin-*
+
+      - name: Unpack, create universal binary and pack
+        run: |
+          set -ex # Fail on error and print each command
+
+          input_arch=(
+            darwin-x86_64
+            darwin-aarch64
+          )
+
+          # Extract each architecture
+          for arch in "${input_arch[@]}"; do
+            mkdir "arch-$arch"
+            tar -xzf "wasp-${arch}.tar.gz" -C "arch-$arch"
+          done
+
+          mkdir universal
+          # Create the universal binary
+          lipo -create arch-*/wasp-bin -output universal/wasp-bin
+          # Copy the data folder too
+          cp -R "arch-${input_arch[0]}/data" universal/
+
+          # Pack back up
+          tar -czf wasp-darwin-universal.tar.gz -C universal .
+
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wasp-darwin-universal
+          path: ./wasp-darwin-universal.tar.gz
diff --git a/waspc/run b/waspc/run
index e671ef1d58..a0f77755e4 100755
--- a/waspc/run
+++ b/waspc/run
@@ -21,6 +21,7 @@ WASP_PACKAGES_COMPILE="${SCRIPT_DIR}/tools/install_packages_to_data_dir.sh"
 BUILD_HS_CMD="cabal build all"
 BUILD_HS_FULL_CMD="cabal build all --enable-tests --enable-benchmarks"
 BUILD_ALL_CMD="$WASP_PACKAGES_COMPILE && $BUILD_HS_CMD"
+BUILD_ALL_STATIC_CMD="$WASP_PACKAGES_COMPILE && $BUILD_HS_CMD --enable-executable-static"
 
 INSTALL_CMD="$WASP_PACKAGES_COMPILE && cabal install --overwrite-policy=always"
 
@@ -76,6 +77,8 @@ print_usage () {
                     "Builds the Haskell project."
     print_usage_cmd "build:all" \
                     "Builds the Haskell project + all sub-projects (i.e. TS packages)."
+    print_usage_cmd "build:all:static" \
+                    "Builds the Haskell project statically + all sub-projects (i.e. TS packages). Only useful for release builds."
     print_usage_cmd "build:packages" \
                     "Builds the TypeScript projects under packages/."
     echo            ""
@@ -133,6 +136,9 @@ case $COMMAND in
     build:all)
         echo_and_eval "$BUILD_ALL_CMD"
         ;;
+    build:all:static)
+        echo_and_eval "$BUILD_ALL_STATIC_CMD"
+        ;;
     build:packages)
         echo_and_eval "$WASP_PACKAGES_COMPILE"
         ;;

From 4c1fd6ff7bd7a2ac25f58960d485caccc5e700ec Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Thu, 22 May 2025 17:05:58 +0200
Subject: [PATCH 02/13] Leftover from merge

---
 .github/actions/setup-haskell/action.yml | 36 ------------------------
 1 file changed, 36 deletions(-)
 delete mode 100644 .github/actions/setup-haskell/action.yml

diff --git a/.github/actions/setup-haskell/action.yml b/.github/actions/setup-haskell/action.yml
deleted file mode 100644
index f443c110bf..0000000000
--- a/.github/actions/setup-haskell/action.yml
+++ /dev/null
@@ -1,36 +0,0 @@
-name: Setup Haskell
-description: |
-  This action sets up a Haskell environment for use in actions by
-  adding the GHC and Cabal binaries to the PATH. It also caches
-  the GHC and Cabal installations to speed up subsequent runs.
-
-inputs:
-  ghc-version:
-    description: |
-      The version of GHC to install.
-    required: false
-    default: "8.10.7"
-
-runs:
-  using: composite
-
-  steps:
-    - uses: haskell-actions/setup@v2
-      id: setup-haskell
-      with:
-        ghc-version: ${{ inputs.ghc-version }}
-
-    # Based on the official recipe for Cabal caching:
-    # https://github.com/actions/cache/blob/5a3ec84eff668545956fd18022155c47e93e2684/examples.md#haskell---cabal
-    - name: Cache Cabal dependencies
-      uses: actions/cache@v4
-      with:
-        path: |
-          ${{ steps.setup-haskell.outputs.cabal-store }}
-          waspc/dist-newstyle
-        # Caches are immutable, so we use the official recipe for simulating an updatable cache:
-        # https://github.com/actions/cache/blob/5a3ec84eff668545956fd18022155c47e93e2684/tips-and-workarounds.md#update-a-cache
-        key: ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}-${{ github.run_id }}
-        restore-keys: |
-          ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}-
-          ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-

From b7afb1dfb11f9b6cea6724e1043d8a0c035bf71f Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Thu, 22 May 2025 17:07:14 +0200
Subject: [PATCH 03/13] More merge fixes

---
 .github/actions/setup-haskell/action.yaml | 1 +
 .github/workflows/check-formatting.yaml   | 2 --
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/.github/actions/setup-haskell/action.yaml b/.github/actions/setup-haskell/action.yaml
index ffe25d212e..a5c92238d1 100644
--- a/.github/actions/setup-haskell/action.yaml
+++ b/.github/actions/setup-haskell/action.yaml
@@ -3,6 +3,7 @@ description: |
   This action sets up a Haskell environment for use in actions by
   adding the GHC and Cabal binaries to the PATH. It also caches
   the GHC and Cabal installations to speed up subsequent runs.
+
 inputs:
   ghc-version:
     description: |
diff --git a/.github/workflows/check-formatting.yaml b/.github/workflows/check-formatting.yaml
index 140b900e20..835defb72e 100644
--- a/.github/workflows/check-formatting.yaml
+++ b/.github/workflows/check-formatting.yaml
@@ -37,8 +37,6 @@ jobs:
       - uses: actions/checkout@v4
 
       - uses: ./.github/actions/setup-haskell
-        with:
-          cabal-project: dev-tool.project
 
       - working-directory: waspc
         run: ./run ormolu:check

From 7de4d9edd927f7dfcd169b8dbfbc159c20cdc3c1 Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Tue, 27 May 2025 14:13:30 +0200
Subject: [PATCH 04/13] Add comment

---
 .github/actions/setup-haskell/action.yaml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/actions/setup-haskell/action.yaml b/.github/actions/setup-haskell/action.yaml
index a5c92238d1..c739ce8330 100644
--- a/.github/actions/setup-haskell/action.yaml
+++ b/.github/actions/setup-haskell/action.yaml
@@ -35,6 +35,9 @@ runs:
 
     # Based on the official recipe for Cabal caching:
     # https://github.com/actions/cache/blob/v4.2.3/examples.md#haskell---cabal
+    # We don't cache the `dist-newstyle` directory because we build on different runners
+    # with mismatching libc versions. Docker images also have different UIDs and
+    # permissions that lead to mismatches.
     - name: Cache Cabal dependencies
       uses: actions/cache@v4
       with:

From 04f9c6d0fb90739c90fab15e198396107bdfd41a Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Tue, 27 May 2025 14:45:04 +0200
Subject: [PATCH 05/13] Remove immutable cache trick

---
 .github/actions/setup-haskell/action.yaml | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/.github/actions/setup-haskell/action.yaml b/.github/actions/setup-haskell/action.yaml
index c739ce8330..4a699cba92 100644
--- a/.github/actions/setup-haskell/action.yaml
+++ b/.github/actions/setup-haskell/action.yaml
@@ -43,10 +43,8 @@ runs:
       with:
         path: |
           ${{ steps.setup-haskell.outputs.cabal-store }}
-        # Caches are immutable, so we use the official recipe for simulating an updatable cache:
-        # https://github.com/actions/cache/blob/v4.2.3/tips-and-workarounds.md#update-a-cache
         key: |
-          ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}-${{ github.run_id }}
+          ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}
         restore-keys: |
-          ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}-
+          ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}
           ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-

From e380e38fcf0a20f24e45b731662c9777476394f1 Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Tue, 27 May 2025 14:47:19 +0200
Subject: [PATCH 06/13] More comments

---
 .github/workflows/waspc-build.yaml | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/.github/workflows/waspc-build.yaml b/.github/workflows/waspc-build.yaml
index 0b94235f9e..213db65c37 100644
--- a/.github/workflows/waspc-build.yaml
+++ b/.github/workflows/waspc-build.yaml
@@ -37,10 +37,14 @@ jobs:
         # so we need to build some of these directly in the runners, and some in
         # containers. Each environment is a different OS and needs different
         # dependencies.
+        #
+        # When possible, we build inside containers so we are not affected when
+        # GitHub updates the runners or deprecates old ones.
         env:
           - name: linux-x86_64
             runner: ubuntu-latest
             container: ubuntu:20.04 # Old Ubuntu version so we have a low glibc requirement
+            static: false # So we dynamically link to the low glibc version
             install-deps: |
               export DEBIAN_FRONTEND=noninteractive
               apt-get update -y
@@ -72,8 +76,15 @@ jobs:
           - name: darwin-x86_64
             runner: macos-13 # Latest image still based on Intel architecture that can be used for free
 
+            # macOS's syscalls are private and change between versions, so we
+            # can't statically link the binary. However, on macOS programs link
+            # to `libSystem`, which is quite stable between releases, so we're
+            # fine depending on it.
+            static: false
+
           - name: darwin-aarch64
             runner: macos-latest # Latest macOS images are already Apple Silicon-based
+            static: false # Check the comment above for why we can't statically link on macOS
             install-deps: |
               # We need to install llvm@13 for building on Apple Silicon (prebuilt libraries
               # are only available for x86_64). The llvm@13 formula is not available in

From e584e595209566d48350b9c2f5b5db58067d5357 Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Wed, 28 May 2025 11:25:02 +0200
Subject: [PATCH 07/13] Update cache keys

---
 .github/actions/setup-haskell/action.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/actions/setup-haskell/action.yaml b/.github/actions/setup-haskell/action.yaml
index 4a699cba92..959ef33993 100644
--- a/.github/actions/setup-haskell/action.yaml
+++ b/.github/actions/setup-haskell/action.yaml
@@ -44,7 +44,7 @@ runs:
         path: |
           ${{ steps.setup-haskell.outputs.cabal-store }}
         key: |
-          ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}
+          cabal-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}
         restore-keys: |
-          ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}
-          ${{ runner.os }}-cabal-${{ inputs.ghc-version }}-
+          cabal-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}
+          cabal-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-

From 7e409c634e0150603e42549997b228e918ad7190 Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Wed, 28 May 2025 11:41:58 +0200
Subject: [PATCH 08/13] Better comments

---
 .github/actions/setup-haskell/action.yaml | 10 +++++++--
 .github/workflows/waspc-build.yaml        | 25 +++++++++++++++--------
 waspc/run                                 |  2 +-
 3 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/.github/actions/setup-haskell/action.yaml b/.github/actions/setup-haskell/action.yaml
index 959ef33993..f2f7e10301 100644
--- a/.github/actions/setup-haskell/action.yaml
+++ b/.github/actions/setup-haskell/action.yaml
@@ -17,6 +17,12 @@ inputs:
     required: false
     default: "latest"
 
+  working-directory:
+    description: |
+      The working directory for the action.
+    required: false
+    default: "${{ inputs.working-directory }}"
+
 runs:
   using: composite
 
@@ -44,7 +50,7 @@ runs:
         path: |
           ${{ steps.setup-haskell.outputs.cabal-store }}
         key: |
-          cabal-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}
+          cabal-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-${{ hashFiles('${{ inputs.working-directory }}/*.cabal', '${{ inputs.working-directory }}/*.project', '${{ inputs.working-directory }}/*.project.freeze') }}
         restore-keys: |
-          cabal-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-${{ hashFiles('waspc/*.cabal', 'waspc/*.project', 'waspc/*.project.freeze') }}
+          cabal-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-${{ hashFiles('${{ inputs.working-directory }}/*.cabal', '${{ inputs.working-directory }}/*.project', '${{ inputs.working-directory }}/*.project.freeze') }}
           cabal-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-
diff --git a/.github/workflows/waspc-build.yaml b/.github/workflows/waspc-build.yaml
index 213db65c37..744ddbc594 100644
--- a/.github/workflows/waspc-build.yaml
+++ b/.github/workflows/waspc-build.yaml
@@ -1,4 +1,4 @@
-name: Build binaries
+name: Build wasp-cli binaries for multiple platforms
 
 # We never trigger this workflow directly.
 # We can call it manually (workflow_dispatch) or from other workflows (workflow_call).
@@ -39,12 +39,18 @@ jobs:
         # dependencies.
         #
         # When possible, we build inside containers so we are not affected when
-        # GitHub updates the runners or deprecates old ones.
+        # GitHub updates the runners or deprecates old ones. When we build inside
+        # containers, the runner is only used to host the container, and all the
+        # steps are run inside the container and not the host (like a Dockerfile).
         env:
           - name: linux-x86_64
             runner: ubuntu-latest
-            container: ubuntu:20.04 # Old Ubuntu version so we have a low glibc requirement
-            static: false # So we dynamically link to the low glibc version
+            # We use an old Ubuntu version so we can link to a low `glibc` version.
+            # `glibc` is backwards-compatible but not forwards-compatible, so it
+            # is a good idea to use the oldest version we reasonably can. This way,
+            # we don't impose stringent `glibc` version requirements on users.
+            container: ubuntu:20.04
+            static: false
             install-deps: |
               export DEBIAN_FRONTEND=noninteractive
               apt-get update -y
@@ -58,9 +64,10 @@ jobs:
 
           - name: linux-x86_64-static
             runner: ubuntu-latest
-            # actions/setup-node does not work in alpine to work around this, we
-            # use the alpine variant of the official node image, which already
-            # has it installed.
+            # actions/setup-node does not work in alpine.
+            # https://github.com/actions/setup-node/issues/1293
+            # To work around this, we use the alpine variant of the official node
+            # image, which already has a working Node.js version installed.
             container: node:${{ inputs.node-version }}-alpine
             skip-node-install: true
             static: true
@@ -68,7 +75,7 @@ jobs:
               apk update
               # GHCup dependencies (https://www.haskell.org/ghcup/install/#linux-alpine)
               apk add binutils-gold curl gcc g++ gmp-dev libc-dev libffi-dev make musl-dev ncurses-dev perl pkgconfig tar xz
-              # Build script dependencies
+              # `./run` script dependencies
               apk add bash
               # Cabal dependencies
               apk add zlib-dev zlib-static
@@ -88,7 +95,7 @@ jobs:
             install-deps: |
               # We need to install llvm@13 for building on Apple Silicon (prebuilt libraries
               # are only available for x86_64). The llvm@13 formula is not available in
-              # Homebrew by default, but we can edit it and remove the disable! line.
+              # Homebrew by default, but we can edit it and comment out the `disable!` line.
               curl -fsSL https://raw.githubusercontent.com/Homebrew/homebrew-core/74572f47ce6a2463c19d7fa164ab9fb8c91bbe61/Formula/l/llvm%4013.rb > /tmp/llvm@13.rb
               sed -i '' 's/disable!/# disable!/' /tmp/llvm@13.rb
               brew install --formula /tmp/llvm@13.rb
diff --git a/waspc/run b/waspc/run
index ee5c5d0bad..9c68a81a6e 100755
--- a/waspc/run
+++ b/waspc/run
@@ -80,7 +80,7 @@ print_usage() {
   print_usage_cmd "build:all" \
     "Builds the Haskell project + all sub-projects (i.e. TS packages)."
   print_usage_cmd "build:all:static" \
-    "Builds the Haskell project statically + all sub-projects (i.e. TS packages). Only useful for release builds."
+    "Builds the Haskell project statically + all sub-projects (i.e. TS packages). Only useful for release builds. Needs to be run on a musl-based Linux distribution (e.g. Alpine)."
   print_usage_cmd "build:packages" \
     "Builds the TypeScript projects under packages/."
   echo ""

From 43796fbb9d7c31b1e43135e10ecd5726993d0f36 Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Wed, 28 May 2025 11:44:02 +0200
Subject: [PATCH 09/13] Fix

---
 .github/actions/setup-haskell/action.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/actions/setup-haskell/action.yaml b/.github/actions/setup-haskell/action.yaml
index f2f7e10301..e831968cff 100644
--- a/.github/actions/setup-haskell/action.yaml
+++ b/.github/actions/setup-haskell/action.yaml
@@ -21,7 +21,7 @@ inputs:
     description: |
       The working directory for the action.
     required: false
-    default: "${{ inputs.working-directory }}"
+    default: "waspc"
 
 runs:
   using: composite

From 923e983ac67d88a0dd0a1c54ee597a509ad59ce5 Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Thu, 29 May 2025 10:34:19 +0200
Subject: [PATCH 10/13] Fixes

---
 .github/actions/setup-haskell/action.yaml | 13 ++++++-------
 .github/workflows/waspc-build.yaml        |  5 +++--
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.github/actions/setup-haskell/action.yaml b/.github/actions/setup-haskell/action.yaml
index e831968cff..4f3accf32d 100644
--- a/.github/actions/setup-haskell/action.yaml
+++ b/.github/actions/setup-haskell/action.yaml
@@ -17,7 +17,7 @@ inputs:
     required: false
     default: "latest"
 
-  working-directory:
+  cabal-project-dir:
     description: |
       The working directory for the action.
     required: false
@@ -41,16 +41,15 @@ runs:
 
     # Based on the official recipe for Cabal caching:
     # https://github.com/actions/cache/blob/v4.2.3/examples.md#haskell---cabal
-    # We don't cache the `dist-newstyle` directory because we build on different runners
-    # with mismatching libc versions. Docker images also have different UIDs and
-    # permissions that lead to mismatches.
     - name: Cache Cabal dependencies
       uses: actions/cache@v4
       with:
+        # We don't cache the `dist-newstyle` directory because it builds quite
+        # fast, and our code changes often enough that a cache would need to be
+        # invalidated on every run, and make our caching story much more complex.
         path: |
           ${{ steps.setup-haskell.outputs.cabal-store }}
         key: |
-          cabal-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-${{ hashFiles('${{ inputs.working-directory }}/*.cabal', '${{ inputs.working-directory }}/*.project', '${{ inputs.working-directory }}/*.project.freeze') }}
+          cabal-${{ inputs.cabal-project-dir }}-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-${{ hashFiles('${{ inputs.cabal-project-dir }}/*.cabal', '${{ inputs.cabal-project-dir }}/*.project', '${{ inputs.cabal-project-dir }}/*.project.freeze') }}
         restore-keys: |
-          cabal-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-${{ hashFiles('${{ inputs.working-directory }}/*.cabal', '${{ inputs.working-directory }}/*.project', '${{ inputs.working-directory }}/*.project.freeze') }}
-          cabal-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-
+          cabal-${{ inputs.cabal-project-dir }}-${{ runner.os }}-${{ runner.arch }}-${{ inputs.ghc-version }}-
diff --git a/.github/workflows/waspc-build.yaml b/.github/workflows/waspc-build.yaml
index 744ddbc594..a07f38944d 100644
--- a/.github/workflows/waspc-build.yaml
+++ b/.github/workflows/waspc-build.yaml
@@ -47,8 +47,9 @@ jobs:
             runner: ubuntu-latest
             # We use an old Ubuntu version so we can link to a low `glibc` version.
             # `glibc` is backwards-compatible but not forwards-compatible, so it
-            # is a good idea to use the oldest version we reasonably can. This way,
-            # we don't impose stringent `glibc` version requirements on users.
+            # is a good idea to use the oldest version we reasonably can. Otherwise,
+            # the wasp binary would possibly not work on the system using a newer
+            # glibc than what it was built with (e.g. a newer Ubuntu version).
             container: ubuntu:20.04
             static: false
             install-deps: |

From e7e24e96e81d50b4e9563b610155430a3a57d44b Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Thu, 29 May 2025 10:35:02 +0200
Subject: [PATCH 11/13] Fix fix

---
 .github/workflows/waspc-build.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/waspc-build.yaml b/.github/workflows/waspc-build.yaml
index a07f38944d..31b3c173d4 100644
--- a/.github/workflows/waspc-build.yaml
+++ b/.github/workflows/waspc-build.yaml
@@ -48,8 +48,8 @@ jobs:
             # We use an old Ubuntu version so we can link to a low `glibc` version.
             # `glibc` is backwards-compatible but not forwards-compatible, so it
             # is a good idea to use the oldest version we reasonably can. Otherwise,
-            # the wasp binary would possibly not work on the system using a newer
-            # glibc than what it was built with (e.g. a newer Ubuntu version).
+            # the wasp binary would possibly not work on the system using an older
+            # glibc than what it was built with (e.g. an older Ubuntu version).
             container: ubuntu:20.04
             static: false
             install-deps: |

From e7aeff5dda539c20f185b597919e7623b4cb737a Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Thu, 29 May 2025 15:51:46 +0200
Subject: [PATCH 12/13] More comment

---
 .github/actions/setup-haskell/action.yaml | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/.github/actions/setup-haskell/action.yaml b/.github/actions/setup-haskell/action.yaml
index 4f3accf32d..ab5911fc05 100644
--- a/.github/actions/setup-haskell/action.yaml
+++ b/.github/actions/setup-haskell/action.yaml
@@ -44,9 +44,22 @@ runs:
     - name: Cache Cabal dependencies
       uses: actions/cache@v4
       with:
-        # We don't cache the `dist-newstyle` directory because it builds quite
-        # fast, and our code changes often enough that a cache would need to be
-        # invalidated on every run, and make our caching story much more complex.
+        # There are two extra directories that are commonly cache, that we've
+        # decided not to cache:
+        #
+        # - `dist-newstyle`: Our internal code builds quite fast, and changes often
+        # enough that a cache would need to be invalidated on every run, and make
+        # our caching story much more complex.
+        #
+        # - ~/.cabal/packages: This is a local cache of the package index. While
+        # it could be useful, we build in heterogeneous environments and it is
+        # not always in the same paths. From testing, in packages with a frozen
+        # `index-state` like ours, the build will just download a single ~4kb file.
+        # So it is not worth the complexity of caching.
+        #
+        # We do cache the Cabal store, which is where the actual built packages
+        # are stored, as it is the most expensive part of the build, and easily
+        # reusable.
         path: |
           ${{ steps.setup-haskell.outputs.cabal-store }}
         key: |

From 9b8bd454c506d34c9ebec6df1c3620932da5e9df Mon Sep 17 00:00:00 2001
From: Carlos Precioso <carlos@wasp-lang.dev>
Date: Thu, 29 May 2025 15:52:27 +0200
Subject: [PATCH 13/13] comment fixes

---
 .github/actions/setup-haskell/action.yaml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/actions/setup-haskell/action.yaml b/.github/actions/setup-haskell/action.yaml
index ab5911fc05..117d528b16 100644
--- a/.github/actions/setup-haskell/action.yaml
+++ b/.github/actions/setup-haskell/action.yaml
@@ -47,11 +47,11 @@ runs:
         # There are two extra directories that are commonly cache, that we've
         # decided not to cache:
         #
-        # - `dist-newstyle`: Our internal code builds quite fast, and changes often
-        # enough that a cache would need to be invalidated on every run, and make
-        # our caching story much more complex.
+        # - `./dist-newstyle`: Our internal code builds quite fast, and changes
+        # often enough that a cache would need to be invalidated on every run, and
+        # make our caching story much more complex.
         #
-        # - ~/.cabal/packages: This is a local cache of the package index. While
+        # - `~/.cabal/packages`: This is a local cache of the package index. While
         # it could be useful, we build in heterogeneous environments and it is
         # not always in the same paths. From testing, in packages with a frozen
         # `index-state` like ours, the build will just download a single ~4kb file.