blockblaz / blockblaz/zeam

Docker multi-platform build crashes on linux/amd64 due to Zig 0.15.2 stdlib bug under Rosetta

Open
#577 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Zig
Stars
97
Forks
39
PR merge metrics
No merged PRs in 30d

Description

## Summary

Multi-platform Docker builds (`--platform linux/amd64,linux/arm64`) consistently crash during the `zig build` step on the linux/amd64 platform when building on Apple Silicon Macs. The arm64 build succeeds.

## Root Cause

The crash is in Zig 0.15.2's standard library `std.Random.shuffleWithIndex`, called by the build runner's `constructGraphAndCheckForDependencyLoop`:

```
thread 29 panic: index out of bounds: index 2, len 2
/opt/zig/lib/std/Random.zig:375:34: in shuffleWithIndex
mem.swap(T, &buf[i], &buf[j]);
^
```

The `shuffleWithIndex` function calls `intRangeLessThan(usize, i, max)`, which internally uses `uintLessThan` with 128-bit wide multiplication (`math.mulWide`). Under **Rosetta x86_64 translation** on Apple Silicon, this 128-bit arithmetic produces incorrect results, causing `uintLessThan(usize, N)` to return `N` instead of a value strictly less than `N`.

This is **not** a Zig bug — it's a Rosetta translation issue with 128-bit integer operations. The same build succeeds:
- Natively on macOS arm64 (`zig build test` passes all 129 tests)
- On linux/arm64 Docker (native on Apple Silicon)
- On real x86_64 hardware (GitHub Actions CI)

## Reproduction

On an Apple Silicon Mac with OrbStack or Docker Desktop:

```bash
docker buildx build --platform linux/amd64,linux/arm64 -t 0xpartha/zeam:latest --push .
```

The linux/amd64 build fails at step 19/19 (`zig build -Doptimize=ReleaseFast`) with the `shuffleWithIndex` panic. Different seeds produce different index values but all hit the same out-of-bounds class:
- `--seed 0x99f47d37` → index 15, len 15
- `--seed 0x50412bb8` → index 2, len 2

## Workaround

Build only `linux/arm64` locally and rely on CI for multi-arch images:

```bash
# Local build (arm64 only — native, no Rosetta)
docker buildx build --platform linux/arm64 -t 0xpartha/zeam:latest --push .

# CI handles the full multi-platform build on real hardware
docker buildx build --platform linux/amd64,linux/arm64 -t 0xpartha/zeam:latest --push .
```

## Environment

- **Mac**: Apple Silicon (arm64)
- **Docker**: OrbStack (uses Rosetta for amd64 containers)
- **Zig**: 0.15.2
- **Dockerfile step**: `zig build -Doptimize=ReleaseFast`

## Relevant Files

- `Dockerfile` line 85–96 (the failing `RUN` step)
- Zig stdlib: `lib/std/Random.zig:375` (`shuffleWithIndex`)
- Zig stdlib: `lib/std/Random.zig:138-164` (`uintLessThan` — uses `math.mulWide` / 128-bit arithmetic)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with Dockerfile lines 85–96 and reproduce the multi-platform command on Apple Silicon. Compare the failing linux/amd64 build with native arm64 and real x86_64 results, then determine whether the issue has an actionable project change or only the documented CI workaround; the issue does not define a code-level completion condition.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, zig
Domain
build-system, devops
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.