Skip to content

adding an arm pipeline build and supporting docs #631

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
EthanMBoos merged 1 commit into from
Apr 8, 2026
Merged

adding an arm pipeline build and supporting docs #631

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 93 additions & 21 deletions .github/workflows/ubuntu-24.04.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,33 +75,55 @@ on:
pull_request:
branches: [Ubuntu-24.04]
workflow_dispatch:
inputs:
build_arm64:
description: 'Build ARM64 image (slow, usually not needed)'
required: false
type: boolean
default: false

jobs:
build-and-test:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write

strategy:
matrix:
# ARM64 only runs on manual dispatch when explicitly requested
platform: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.build_arm64 == 'true' && fromJSON('["amd64", "arm64"]') || fromJSON('["amd64"]') }}

steps:
- uses: actions/checkout@v6

# Set up QEMU for cross-platform builds
- name: Set up QEMU
uses: docker/setup-qemu-action@v4
with:
platforms: linux/amd64,linux/arm64

- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v4

# Uses the slim image from ci/dockerfiles/ with all deps pre-installed
- name: Build dependency image
run: |
docker build \
docker buildx build \
--platform linux/${{ matrix.platform }} \
--load \
-f ci/dockerfiles/ubuntu-24.04-slim-dependency-only \
-t scrimmage-deps:24.04 .
-t scrimmage-deps:24.04-${{ matrix.platform }} .

# ==========================================================================
# Build 1: Coverage build (for testing and coverage reports)
# ==========================================================================
# ==========================================================================================
# Build 1: Coverage build with tests (amd64 only - running both amd64 and arm64 is too slow)
# ==========================================================================================
- name: Build and test with coverage
if: matrix.platform == 'amd64'
run: |
docker run --rm \
docker run --rm --platform linux/${{ matrix.platform }} \
-v ${{ github.workspace }}:/root/scrimmage \
-w /root/scrimmage \
scrimmage-deps:24.04 \
scrimmage-deps:24.04-${{ matrix.platform }} \
bash -ec "
git config --global --add safe.directory /root/scrimmage
apt-get update && apt-get install -y lcov
Expand All @@ -117,27 +139,37 @@ jobs:
lcov --quiet --capture --directory . --output-file coverage.info --ignore-errors mismatch,gcov 2>/dev/null
lcov --quiet --remove coverage.info '/usr/*' '*/build/_deps/*' '*/test/*' --output-file coverage.info --ignore-errors unused 2>/dev/null
lcov --quiet --extract coverage.info '*/src/*' --output-file coverage-src.info --ignore-errors unused 2>/dev/null
echo '=== Coverage Summary ==='
echo '=== Coverage Summary (${{ matrix.platform }}) ==='
lcov --summary coverage-src.info
echo ''
echo '=== Coverage by File ==='
lcov --list coverage-src.info
"

# Clean up coverage build before release build
# Clean up coverage build before release build (amd64 only)
- name: Clean coverage build
if: matrix.platform == 'amd64'
run: |
docker run --rm \
docker run --rm --platform linux/${{ matrix.platform }} \
-v ${{ github.workspace }}:/root/scrimmage \
-w /root/scrimmage \
scrimmage-deps:24.04 \
scrimmage-deps:24.04-${{ matrix.platform }} \
rm -rf build

# ==========================================================================
# Build 2: Clean release build (for GHCR)
# Build 2: Clean release build (for GHCR) - both platforms
# ==========================================================================
- name: Build scrimmage image
run: |
# Use default docker builder (not buildx) to see local images
docker buildx use default || true

# Tag platform-specific base image with simpler name for Dockerfile
docker tag scrimmage-deps:24.04-${{ matrix.platform }} scrimmage-deps:24.04

# Verify the tag worked
docker images scrimmage-deps:24.04

# Create image with scrimmage fully built and installed
cat > Dockerfile.scrimmage <<'EOF'
FROM scrimmage-deps:24.04
Expand All @@ -152,11 +184,13 @@ jobs:
# Usage: source /root/scrimmage/build/install/etc/scrimmage/env/scrimmage-setenv
EOF

docker build -f Dockerfile.scrimmage -t scrimmage:24.04 .
# Use DOCKER_BUILDKIT=0 to force legacy builder that can see local images
DOCKER_BUILDKIT=0 docker build -f Dockerfile.scrimmage -t scrimmage:24.04-${{ matrix.platform }} .

- name: Smoke test mission
run: |
docker run --rm scrimmage:24.04 bash -ec "
docker run --rm --platform linux/${{ matrix.platform }} \
scrimmage:24.04-${{ matrix.platform }} bash -ec "
source /root/scrimmage/build/install/etc/scrimmage/env/scrimmage-setenv
scrimmage /root/scrimmage/missions/straight-no-gui.xml
"
Expand All @@ -177,9 +211,47 @@ jobs:
run: |
IMAGE_NAME=ghcr.io/${{ github.repository_owner }}/scrimmage-24.04
SHORT_SHA=${GITHUB_SHA::7}
docker tag scrimmage:24.04 ${IMAGE_NAME}:${SHORT_SHA}
docker tag scrimmage:24.04 ${IMAGE_NAME}:latest
docker push ${IMAGE_NAME}:${SHORT_SHA}
docker push ${IMAGE_NAME}:latest
echo "Pushed: ${IMAGE_NAME}:${SHORT_SHA}"
echo "Pushed: ${IMAGE_NAME}:latest"
docker tag scrimmage:24.04-${{ matrix.platform }} ${IMAGE_NAME}:${SHORT_SHA}-${{ matrix.platform }}
docker tag scrimmage:24.04-${{ matrix.platform }} ${IMAGE_NAME}:latest-${{ matrix.platform }}
docker push ${IMAGE_NAME}:${SHORT_SHA}-${{ matrix.platform }}
docker push ${IMAGE_NAME}:latest-${{ matrix.platform }}
echo "Pushed: ${IMAGE_NAME}:${SHORT_SHA}-${{ matrix.platform }}"
echo "Pushed: ${IMAGE_NAME}:latest-${{ matrix.platform }}"

# Create multi-arch manifest after all platforms are built (only if ARM64 was built)
create-manifest:
runs-on: ubuntu-latest
needs: build-and-test
if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.event_name == 'workflow_dispatch' && github.event.inputs.build_arm64 == 'true'
permissions:
contents: read
packages: write

steps:
- name: Login to GHCR
uses: docker/login-action@v4
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}

- name: Create and push manifest
run: |
IMAGE_NAME=ghcr.io/${{ github.repository_owner }}/scrimmage-24.04
SHORT_SHA=${GITHUB_SHA::7}

# Create manifest for SHA tag
docker manifest create ${IMAGE_NAME}:${SHORT_SHA} \
${IMAGE_NAME}:${SHORT_SHA}-amd64 \
${IMAGE_NAME}:${SHORT_SHA}-arm64
docker manifest push ${IMAGE_NAME}:${SHORT_SHA}

# Create manifest for latest tag
docker manifest create ${IMAGE_NAME}:latest \
${IMAGE_NAME}:latest-amd64 \
${IMAGE_NAME}:latest-arm64
docker manifest push ${IMAGE_NAME}:latest

echo "Pushed multi-arch manifests:"
echo " ${IMAGE_NAME}:${SHORT_SHA}"
echo " ${IMAGE_NAME}:latest"
18 changes: 17 additions & 1 deletion development-docs/CONTAINERIZED_DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,16 @@ This guide covers all ways to run SCRIMMAGE in containers (Docker, enroot, etc.)

---

## Architecture Support

SCRIMMAGE containers are available for:
- **AMD64** (x86_64): Standard Intel/AMD processors
- **ARM64** (aarch64): Apple Silicon (M1/M2/M3), AWS Graviton, Raspberry Pi 4+

Docker will automatically pull the correct architecture for your system when using the manifest tags (`:latest` or `:${SHA}`).

---

## Option A: VS Code Dev Container (Build Locally)

Builds the dependency image from the Dockerfile in this repo.
Expand All @@ -37,13 +47,15 @@ This automatically configures clangd intellisense and X11 forwarding (Linux).

For running scrimmage without development. Everything is baked in.

### Auto-detect architecture (recommended)

```bash
docker run -it ghcr.io/gtri/scrimmage-24.04:latest bash
source /root/scrimmage/build/install/etc/scrimmage/env/scrimmage-setenv
scrimmage /root/scrimmage/missions/straight-no-gui.xml
```

For GUI support:
### GUI support (AMD64/ARM64)
```bash
xhost +local:docker
docker run -it --rm \
Expand All @@ -52,6 +64,8 @@ docker run -it --rm \
ghcr.io/gtri/scrimmage-24.04:latest bash
```

Note for Apple Silicon: GUI support on macOS is unreliable and not officially supported. XQuartz has significant compatibility issues, especially with Apple Silicon and OpenGL applications.

---

## Option C: HPC with enroot
Expand Down Expand Up @@ -85,6 +99,8 @@ rm scrimmage-24.04+latest.sqsh

### Build the Image

This automatically builds for the host architecture (AMD64 on Intel/AMD, ARM64 on Apple Silicon). Unlike pulling pre-built images where Docker reads a multi-arch manifest from the container registry, local builds simply compile for whatever CPU is being used. Docker handles all the architecture detection automatically—the result runs natively without emulation, no special flags needed.

```bash
cd /path/to/scrimmage
docker build -f ci/dockerfiles/ubuntu-24.04-slim-dependency-only -t scrimmage-dev:24.04 .
Expand Down