musl.cc does not allow downloads from GitHub Actions. But adding the tgz files is far too large for a default checkout of yafl. So we add downloading from a GitHub mirror to the CI process and script it so that it can be done by users on their own machines.

Author: kyle-github

.gitattributes

@@ -1,3 +1,15 @@
 # Git LFS configuration for large binary files
+#
+# These files are optional and only needed if you plan to run musl.cc-based
+# cross-compilation workflows locally. Most developers can skip them:
+#
+#   GIT_LFS_SKIP_SMUDGE=1 git clone <repo>
+#   # or
+#   git clone --no-lfs <repo>
+#
+# To pull these files later:
+#   git lfs pull
+#
+
 # Cross-compiler toolchains (stored with Git LFS)
 cross-compilers/*.tgz filter=lfs diff=lfs merge=lfs -text

.github/workflows/armv7-musl-linux.yml

@@ -16,18 +16,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Install build tools
-        run: sudo apt-get update && sudo apt-get install -y cmake make
-      - name: Extract musl.cc cross-compiler
-        run: |
-          mkdir -p /opt/cross
-          cd /opt/cross
-          tar xzf ${{ github.workspace }}/cross-compilers/arm-linux-musleabihf-cross.tgz
-          echo "Cross-compiler extracted successfully"
+        run: sudo apt-get update && sudo apt-get install -y cmake make wget
+      - name: Download and install musl-cross toolchain
+        run: ./scripts/download-musl-cross.sh arm-unknown-linux-musleabihf
       - name: Configure and Build
         run: |
           mkdir -p build && cd build
-          cmake -DTARGET=arm-unknown-linux-gnueabihf \
-                -DCMAKE_C_COMPILER=/opt/cross/arm-linux-musleabihf-cross/bin/arm-linux-musleabihf-gcc \
+          cmake -DTARGET=arm-unknown-linux-musleabihf \
+                -DCMAKE_C_COMPILER=${{ github.workspace }}/cross-compilers/x-tools/arm-unknown-linux-musleabihf/bin/arm-unknown-linux-musleabihf-gcc \
                 -DCMAKE_C_FLAGS='-static' \
                 -DCMAKE_SYSTEM_NAME=Linux \
                 -DCMAKE_SYSTEM_PROCESSOR=arm \

.github/workflows/ppc64le-musl-linux.yml

@@ -16,18 +16,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Install build tools
-        run: sudo apt-get update && sudo apt-get install -y cmake make
-      - name: Extract musl.cc cross-compiler
-        run: |
-          mkdir -p /opt/cross
-          cd /opt/cross
-          tar xzf ${{ github.workspace }}/cross-compilers/powerpc64le-linux-musl-cross.tgz
-          echo "Cross-compiler extracted successfully"
+        run: sudo apt-get update && sudo apt-get install -y cmake make wget
+      - name: Download and install musl-cross toolchain
+        run: ./scripts/download-musl-cross.sh powerpc64le-unknown-linux-musl
       - name: Configure and Build
         run: |
           mkdir -p build && cd build
-          cmake -DTARGET=powerpc64le-unknown-linux-gnu \
-                -DCMAKE_C_COMPILER=/opt/cross/powerpc64le-linux-musl-cross/bin/powerpc64le-linux-musl-gcc \
+          cmake -DTARGET=powerpc64le-unknown-linux-musl \
+                -DCMAKE_C_COMPILER=${{ github.workspace }}/cross-compilers/x-tools/powerpc64le-unknown-linux-musl/bin/powerpc64le-unknown-linux-musl-gcc \
                 -DCMAKE_C_FLAGS='-static' \
                 -DCMAKE_SYSTEM_NAME=Linux \
                 -DCMAKE_SYSTEM_PROCESSOR=ppc64le \

.github/workflows/riscv64-musl-linux.yml

@@ -16,18 +16,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Install build tools
-        run: sudo apt-get update && sudo apt-get install -y cmake make
-      - name: Extract musl.cc cross-compiler
-        run: |
-          mkdir -p /opt/cross
-          cd /opt/cross
-          tar xzf ${{ github.workspace }}/cross-compilers/riscv64-linux-musl-cross.tgz
-          echo "Cross-compiler extracted successfully"
+        run: sudo apt-get update && sudo apt-get install -y cmake make wget
+      - name: Download and install musl-cross toolchain
+        run: ./scripts/download-musl-cross.sh riscv64-unknown-linux-musl
       - name: Configure and Build
         run: |
           mkdir -p build && cd build
-          cmake -DTARGET=riscv64-unknown-linux-gnu \
-                -DCMAKE_C_COMPILER=/opt/cross/riscv64-linux-musl-cross/bin/riscv64-linux-musl-gcc \
+          cmake -DTARGET=riscv64-unknown-linux-musl \
+                -DCMAKE_C_COMPILER=${{ github.workspace }}/cross-compilers/x-tools/riscv64-unknown-linux-musl/bin/riscv64-unknown-linux-musl-gcc \
                 -DCMAKE_C_FLAGS='-static' \
                 -DCMAKE_SYSTEM_NAME=Linux \
                 -DCMAKE_SYSTEM_PROCESSOR=riscv64 \

.github/workflows/s390x-musl-linux.yml

@@ -16,18 +16,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Install build tools
-        run: sudo apt-get update && sudo apt-get install -y cmake make
-      - name: Extract musl.cc cross-compiler
-        run: |
-          mkdir -p /opt/cross
-          cd /opt/cross
-          tar xzf ${{ github.workspace }}/cross-compilers/s390x-linux-musl-cross.tgz
-          echo "Cross-compiler extracted successfully"
+        run: sudo apt-get update && sudo apt-get install -y cmake make wget
+      - name: Download and install musl-cross toolchain
+        run: ./scripts/download-musl-cross.sh s390x-ibm-linux-musl
       - name: Configure and Build
         run: |
           mkdir -p build && cd build
-          cmake -DTARGET=s390x-ibm-linux-gnu \
-                -DCMAKE_C_COMPILER=/opt/cross/s390x-linux-musl-cross/bin/s390x-linux-musl-gcc \
+          cmake -DTARGET=s390x-ibm-linux-musl \
+                -DCMAKE_C_COMPILER=${{ github.workspace }}/cross-compilers/x-tools/s390x-ibm-linux-musl/bin/s390x-ibm-linux-musl-gcc \
                 -DCMAKE_C_FLAGS='-static' \
                 -DCMAKE_SYSTEM_NAME=Linux \
                 -DCMAKE_SYSTEM_PROCESSOR=s390x \

.gitignore

@@ -55,4 +55,7 @@ coverage.info
 __pycache__/
 *.pyc
 
+# Downloaded musl-cross toolchains (generated by scripts/download-musl-cross.sh)
+/cross-compilers/x-tools/
+
 .claude

CMakeLists.txt

@@ -143,6 +143,32 @@ else()
 endif()
 
 message(STATUS "Loading configuration for triple: ${TRIPLE}")
+
+# Check if this is a musl target that requires cross-compiler binaries
+string(REGEX MATCH "musl" IS_MUSL_TARGET "${TRIPLE}")
+
+if(IS_MUSL_TARGET)
+    # For musl targets, check if cross-compiler is available in the repo
+    set(MUSL_X_TOOLS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/cross-compilers/x-tools")
+    set(MUSL_TOOLCHAIN_DIR "${MUSL_X_TOOLS_DIR}/${TRIPLE}")
+
+    if(NOT EXISTS "${MUSL_TOOLCHAIN_DIR}")
+        message(FATAL_ERROR
+            "Musl cross-compiler toolchain not found: ${MUSL_TOOLCHAIN_DIR}\n"
+            "\n"
+            "To enable musl-based cross-compilation, download and install the toolchain:\n"
+            "  ./scripts/download-musl-cross.sh\n"
+            "\n"
+            "This will download pre-built toolchains from:\n"
+            "  https://github.com/cross-tools/musl-cross/releases\n"
+            "\n"
+            "If you don't need musl cross-compilation, you can build without it:\n"
+            "  cmake -DTARGET=<native-triple> ..\n"
+        )
+    endif()
+    message(STATUS "Using musl cross-compiler from: ${MUSL_TOOLCHAIN_DIR}")
+endif()
+
 if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/toolchains/${TRIPLE}.cmake")
     include(toolchains/${TRIPLE}.cmake)
 else()

cross-compilers/README.md

@@ -1,82 +1,71 @@
 # Cross-Compiler Toolchains
 
-This directory contains pre-built cross-compiler toolchains from [musl.cc](https://musl.cc/).
+This directory contains downloaded musl-cross pre-built toolchains for cross-compilation support.
 
-## Files
+## Installation
 
-These files are stored with Git LFS (Large File Storage) and are downloaded via GitHub Actions CI/CD:
+The musl cross-compiler binaries are downloaded on-demand and stored in the `x-tools/` subdirectory.
 
-- `arm-linux-musleabihf-cross.tgz` - ARM 32-bit (ARMv7) EABI Hard Float
-- `riscv64-linux-musl-cross.tgz` - RISC-V 64-bit
-- `s390x-linux-musl-cross.tgz` - IBM System z (s390x)
-- `powerpc64le-linux-musl-cross.tgz` - PowerPC 64-bit Little Endian
+To install the musl-cross toolchains locally:
 
-## Downloading Toolchains Locally
+```bash
+./scripts/download-musl-cross.sh
+```
 
-To download these toolchains to your local machine:
+This will download all four supported architectures from the [cross-tools/musl-cross](https://github.com/cross-tools/musl-cross) GitHub releases.
 
-1. **Install Git LFS** (if not already installed):
-   ```bash
-   # macOS
-   brew install git-lfs
+To download a specific architecture only:
 
-   # Ubuntu/Debian
-   sudo apt-get install git-lfs
+```bash
+./scripts/download-musl-cross.sh arm-unknown-linux-musleabihf
+./scripts/download-musl-cross.sh riscv64-unknown-linux-musl
+./scripts/download-musl-cross.sh s390x-ibm-linux-musl
+./scripts/download-musl-cross.sh powerpc64le-unknown-linux-musl
+```
 
-   # Other systems: https://git-lfs.com/
-   ```
+## Building with Musl
 
-2. **Initialize Git LFS in this repository** (one-time setup):
-   ```bash
-   git lfs install
-   ```
+Once installed, you can build for musl targets:
 
-3. **Run the download script**:
-   ```bash
-   ./scripts/download-musl-cc.sh
-   ```
+```bash
+mkdir build && cd build
+cmake -DTARGET=arm-unknown-linux-musleabihf ..
+cmake --build .
+```
 
-   This script will:
-   - Create this directory if it doesn't exist
-   - Download all four cross-compiler toolchains
-   - Retry up to 3 times if downloads fail
-   - Store them for Git LFS tracking
+## Supported Architectures
 
-4. **Commit and push to GitHub**:
-   ```bash
-   git add cross-compilers/ .gitattributes
-   git commit -m "Add musl.cc cross-compiler toolchains"
-   git push
-   ```
+- **arm-unknown-linux-musleabihf** - ARM 32-bit (ARMv7) EABI Hard Float
+- **riscv64-unknown-linux-musl** - RISC-V 64-bit
+- **s390x-ibm-linux-musl** - IBM System z (s390x)
+- **powerpc64le-unknown-linux-musl** - PowerPC 64-bit Little Endian
 
-## Git LFS Tracking
+## Directory Structure
 
-These files are tracked with Git LFS, which means:
+```
+cross-compilers/
+├── README.md (this file)
+├── .gitkeep
+└── x-tools/
+    ├── arm-unknown-linux-musleabihf/
+    ├── riscv64-unknown-linux-musl/
+    ├── s390x-ibm-linux-musl/
+    └── powerpc64le-unknown-linux-musl/
+```
 
-- Git stores pointers to the actual files instead of the full archives
-- The repository size remains small
-- When you clone or pull, Git LFS downloads only the files you need
-- Bandwidth usage is optimized for large binary files
+The `x-tools/` directory is generated by the download script and is not checked into Git.
 
-To verify Git LFS is working correctly, check the `.gitattributes` file to see which patterns are tracked.
+## Optional
 
-## Why These Toolchains?
+These toolchains are **optional**. If you don't need musl cross-compilation, you can build for your native platform without downloading them:
 
-The musl.cc project provides pre-built, statically-linked cross-compiler toolchains. They're:
-- Ready to use without system dependencies
-- Statically compiled (portable across Linux distributions)
-- Designed for cross-compilation to various architectures
-- Updated regularly with latest compiler versions
-
-## Updates
-
-To update these toolchains to newer versions in the future:
-
-1. Run the download script again: `./scripts/download-musl-cc.sh`
-2. Git will detect changes if new versions are available
-3. Commit and push the updated files
+```bash
+mkdir build && cd build
+cmake ..  # Auto-detects your native platform
+cmake --build .
+```
 
 ## References
 
-- [musl.cc](https://musl.cc/) - Pre-built musl libc cross-compiler toolchains
-- [Git LFS Documentation](https://git-lfs.com/)
+- [cross-tools/musl-cross](https://github.com/cross-tools/musl-cross) - Pre-built musl libc cross-compiler toolchains
+- [musl libc](https://musl.libc.org) - Standard C library for Linux

scripts/download-musl-cross.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+#
+# Download and install musl-cross pre-built toolchains
+#
+# This script downloads pre-built cross-compiler toolchains from the
+# cross-tools/musl-cross GitHub releases and installs them to the
+# cross-compilers/x-tools/ directory for use with CMake builds.
+#
+# Usage: ./scripts/download-musl-cross.sh [optional: specific architecture]
+#        ./scripts/download-musl-cross.sh                    # Download all
+#        ./scripts/download-musl-cross.sh arm-unknown-linux-musleabihf  # Download one
+#
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+X_TOOLS_DIR="$REPO_ROOT/cross-compilers/x-tools"
+
+# musl-cross release version
+RELEASE="20250929"
+
+# Array of architectures we need
+declare -a ARCHITECTURES=(
+    "arm-unknown-linux-musleabihf"
+    "riscv64-unknown-linux-musl"
+    "s390x-ibm-linux-musl"
+    "powerpc64le-unknown-linux-musl"
+)
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}Downloading musl-cross toolchains${NC}"
+echo "Release: ${RELEASE}"
+echo "Destination: $X_TOOLS_DIR"
+echo ""
+
+# Create x-tools directory if it doesn't exist
+mkdir -p "$X_TOOLS_DIR"
+
+# If specific architecture requested, override the array
+if [ $# -gt 0 ]; then
+    ARCHITECTURES=("$1")
+    echo "Downloading only: $1"
+    echo ""
+fi
+
+# Download each toolchain
+for arch in "${ARCHITECTURES[@]}"; do
+    filename="${arch}.tar.xz"
+    filepath="$X_TOOLS_DIR/$filename"
+    extract_dir="$X_TOOLS_DIR/$arch"
+    url="https://github.com/cross-tools/musl-cross/releases/download/${RELEASE}/${filename}"
+
+    # Skip if already exists
+    if [ -d "$extract_dir" ]; then
+        echo -e "${GREEN}✓${NC} $arch already installed, skipping"
+        continue
+    fi
+
+    echo -e "${BLUE}Downloading${NC} $filename..."
+
+    # Download with retries
+    for attempt in 1 2 3; do
+        if wget -O "$filepath" "$url"; then
+            echo -e "${BLUE}Extracting${NC} $filename..."
+            tar xf "$filepath" -C "$X_TOOLS_DIR"
+            rm "$filepath"
+            echo -e "${GREEN}✓${NC} Installed: $arch"
+            break
+        else
+            if [ $attempt -lt 3 ]; then
+                echo "  Attempt $attempt failed, retrying in 10 seconds..."
+                sleep 10
+            else
+                echo -e "${RED}✗${NC} Failed to download $filename after 3 attempts"
+                rm -f "$filepath"
+                exit 1
+            fi
+        fi
+    done
+done
+
+echo ""
+echo -e "${GREEN}All musl-cross toolchains ready!${NC}"
+echo ""
+echo "You can now build with musl targets:"
+echo "  cmake -DTARGET=arm-unknown-linux-musleabihf .."
+echo "  cmake -DTARGET=riscv64-unknown-linux-musl .."
+echo "  cmake -DTARGET=s390x-ibm-linux-musl .."
+echo "  cmake -DTARGET=powerpc64le-unknown-linux-musl .."

toolchains/arm-unknown-linux-musleabihf.cmake

@@ -0,0 +1,13 @@
+# CMake toolchain configuration for arm-unknown-linux-musleabihf
+# Uses musl-cross pre-built toolchain from /opt/x-tools
+# Compiler path must be specified: -DCMAKE_C_COMPILER=/opt/x-tools/arm-unknown-linux-musleabihf/bin/arm-unknown-linux-musleabihf-gcc
+# Copyright Kyle Hayes (2026)
+# Distributed under the Boost Software License, Version 1.0.
+# See LICENSE file for details
+
+set(ASM_FILES
+    src/asm/arm/make_arm_aapcs_elf_gas.S
+    src/asm/arm/jump_arm_aapcs_elf_gas.S
+)
+enable_language(ASM)
+add_compile_options(-Wall -Wextra -Werror -g -O2 -static)