Dockerfile.toolchain

# syntax=docker/dockerfile:1.6
# Zaparoo Frontend
# Copyright (c) 2026 Wizzo Pty Ltd and the Zaparoo Project contributors.
# SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
#
# Builds the reusable Qt + MiSTer ARM32 toolchain base image. Qt upstream
# version is pinned via the QT_VERSION arg below; the image tag is supplied
# by scripts/build-toolchain.sh, which reads it from scripts/toolchain/VERSION
# so CI and local dev agree on the tag.
#
# This image is built ONCE (or when Qt version bumps) and reused by
# Dockerfile.arm32 to keep per-commit builds fast (< 1 minute vs 45 min).
#
# Build command (run from repo root):
#   ./scripts/build-toolchain.sh
#
# Multi-stage layout: the `builder` stage runs every Qt build RUN as
# before, then the final `runtime` stage starts from a clean
# debian:bookworm-slim and `COPY --from=builder` only the artifacts
# Dockerfile.arm32 actually consumes at build time. The Qt source
# clones, host build trees, ARM build trees, and `-dev` apt headers
# never reach the published image, which is what slims it from ~30 GB
# to a few GB.
#
# Qt version pinned here — bump this line when updating Qt:
ARG QT_VERSION=6.10.3

FROM debian:bookworm-slim AS builder

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y \
    build-essential \
    cmake \
    ninja-build \
    pkg-config \
    git \
    perl \
    python3 \
    wget \
    xz-utils \
    libfontconfig1-dev \
    libfreetype-dev \
    libx11-dev \
    libx11-xcb-dev \
    libxext-dev \
    libxfixes-dev \
    libxi-dev \
    libxrender-dev \
    libxcb1-dev \
    libxcb-cursor-dev \
    libxcb-glx0-dev \
    libxcb-keysyms1-dev \
    libxcb-image0-dev \
    libxcb-shm0-dev \
    libxcb-icccm4-dev \
    libxcb-sync-dev \
    libxcb-xfixes0-dev \
    libxcb-shape0-dev \
    libxcb-randr0-dev \
    libxcb-render-util0-dev \
    libxcb-util-dev \
    libxcb-xinerama0-dev \
    libxcb-xkb-dev \
    libxkbcommon-dev \
    libxkbcommon-x11-dev \
    libgl1-mesa-dev \
    libgles2-mesa-dev \
    libegl1-mesa-dev \
    libssl-dev \
    libdbus-1-dev \
    libglib2.0-dev \
    libicu-dev \
    libpcre2-dev \
    zlib1g-dev \
    libjpeg-dev \
    libpng-dev \
    && rm -rf /var/lib/apt/lists/*

# MiSTer official ARM toolchain (gcc-arm-10.2-2020.11 targeting glibc 2.31)
RUN wget -q \
    https://developer.arm.com/-/media/Files/downloads/gnu-a/10.2-2020.11/binrel/gcc-arm-10.2-2020.11-x86_64-arm-none-linux-gnueabihf.tar.xz \
    && tar xf gcc-arm-10.2-2020.11-x86_64-arm-none-linux-gnueabihf.tar.xz -C /opt \
    && rm gcc-arm-10.2-2020.11-x86_64-arm-none-linux-gnueabihf.tar.xz

ENV PATH="/opt/gcc-arm-10.2-2020.11-x86_64-arm-none-linux-gnueabihf/bin:${PATH}"
ENV ARM_SYSROOT="/opt/gcc-arm-10.2-2020.11-x86_64-arm-none-linux-gnueabihf/arm-none-linux-gnueabihf/libc"

WORKDIR /build

ARG QT_VERSION
RUN git clone --depth 1 --branch v${QT_VERSION} https://github.com/qt/qtbase.git && \
    git clone --depth 1 --branch v${QT_VERSION} https://github.com/qt/qtshadertools.git && \
    git clone --depth 1 --branch v${QT_VERSION} https://github.com/qt/qtdeclarative.git && \
    git clone --depth 1 --branch v${QT_VERSION} https://github.com/qt/qttools.git && \
    git clone --depth 1 --branch v${QT_VERSION} https://github.com/qt/qtwebsockets.git && \
    git clone --depth 1 --branch v${QT_VERSION} https://github.com/qt/qtsvg.git && \
    git clone --depth 1 --branch v${QT_VERSION} https://github.com/qt/qtimageformats.git

# Stage 1: Qt6 host build (provides native tools: moc, rcc, qmllint, etc.)
# PrintSupport is intentionally enabled here even though the frontend itself
# doesn't print: Qt's `linguist` feature has condition `TARGET Qt::PrintSupport`,
# and qttools/src/linguist/CMakeLists.txt returns early when that feature is
# off — taking lupdate/lrelease/lconvert and the Qt6LinguistTools CMake
# package down with it. The ARM32 target qtbase below stays `-no-feature-
# printsupport` since the shipping binary never needs it.
RUN mkdir qtbase-host-build && cd qtbase-host-build && \
    ../qtbase/configure \
        -release \
        -prefix /opt/qt6-host \
        -nomake examples \
        -nomake tests \
        -no-opengl \
        -no-openssl \
        -no-dbus \
        -no-feature-accessibility \
        -no-feature-sql \
        -qt-zlib \
        -qt-libpng \
        -qt-libjpeg \
        -qt-freetype \
        -qt-pcre \
        -qt-harfbuzz \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

RUN mkdir qtshadertools-host-build && cd qtshadertools-host-build && \
    /opt/qt6-host/bin/qt-configure-module ../qtshadertools \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

RUN mkdir qtdeclarative-host-build && cd qtdeclarative-host-build && \
    /opt/qt6-host/bin/qt-configure-module ../qtdeclarative \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

# qttools (host only): provides lupdate/lrelease + the Qt6LinguistTools
# CMake package that qt_add_translations() requires at configure time.
# Feature-gated to the subset we use: Linguist command-line tools. The
# `linguist` feature is set explicitly so a future qtbase tweak can't
# silently disable it again — its only condition is `TARGET Qt::PrintSupport`,
# which the host qtbase above provides. The other FEATURE_* knobs disable
# GUI tools (assistant, designer) and CLI utilities we don't ship; pulling
# them in would either drag QtWidgets/Network into a host build that doesn't
# need them or build code we never invoke. Not cross-compiled for ARM32 —
# the frontend only needs .qm files at runtime, which are architecture-
# independent.
RUN mkdir qttools-host-build && cd qttools-host-build && \
    /opt/qt6-host/bin/qt-configure-module ../qttools \
        -- \
        -DFEATURE_linguist=ON \
        -DFEATURE_assistant=OFF \
        -DFEATURE_designer=OFF \
        -DFEATURE_qtattributionsscanner=OFF \
        -DFEATURE_qdbus=OFF \
        -DFEATURE_qtdiag=OFF \
        -DFEATURE_qtplugininfo=OFF \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

RUN mkdir qtwebsockets-host-build && cd qtwebsockets-host-build && \
    /opt/qt6-host/bin/qt-configure-module ../qtwebsockets \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

# qtsvg (host build): mirrors the qtshadertools/qtdeclarative pattern. The
# cross-built ARM32 qtsvg (below) needs a host counterpart at the same Qt
# version so qt-configure-module's prefix probe finds matching host tools.
RUN mkdir qtsvg-host-build && cd qtsvg-host-build && \
    /opt/qt6-host/bin/qt-configure-module ../qtsvg \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

# qtimageformats (host build): provides a matching host module for the ARM32
# cross-build below. Only WebP is enabled because Core can return WebP covers
# and MiSTer does not need the other optional image codecs.
RUN mkdir qtimageformats-host-build && cd qtimageformats-host-build && \
    /opt/qt6-host/bin/qt-configure-module ../qtimageformats \
        -feature-webp \
        -no-feature-jasper \
        -no-feature-mng \
        -no-feature-tiff \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

# Stage 2: CMake toolchain file for ARM32 cross-compilation.
# Single-quoted heredoc tag so ${CMAKE_SYSROOT} reaches the file literally
# rather than being expanded by the Dockerfile frontend.
COPY <<'EOF' /build/arm32-toolchain.cmake
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)

set(CMAKE_C_COMPILER arm-none-linux-gnueabihf-gcc)
set(CMAKE_CXX_COMPILER arm-none-linux-gnueabihf-g++)
set(CMAKE_AR arm-none-linux-gnueabihf-ar)
set(CMAKE_RANLIB arm-none-linux-gnueabihf-ranlib)
set(CMAKE_STRIP arm-none-linux-gnueabihf-strip)

set(CMAKE_SYSROOT /opt/gcc-arm-10.2-2020.11-x86_64-arm-none-linux-gnueabihf/arm-none-linux-gnueabihf/libc)
set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT})

set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

# MiSTer FPGA: Cyclone V SoC, Cortex-A9, NEON, hard-float ABI.
set(CMAKE_C_FLAGS_INIT   "-mcpu=cortex-a9 -mfloat-abi=hard -mtune=cortex-a9 -mfpu=neon")
set(CMAKE_CXX_FLAGS_INIT "-mcpu=cortex-a9 -mfloat-abi=hard -mtune=cortex-a9 -mfpu=neon")
EOF

# Stage 3: Qt6 cross-compiled for ARM32 (static, linuxfb, no GPU)
RUN mkdir qtbase-arm-build && cd qtbase-arm-build && \
    ../qtbase/configure \
        -release \
        -static \
        -prefix /opt/qt6-arm32 \
        -qt-host-path /opt/qt6-host \
        -nomake examples \
        -nomake tests \
        -no-opengl \
        -linuxfb \
        -no-openssl \
        -no-dbus \
        -no-icu \
        -no-feature-accessibility \
        -no-feature-printsupport \
        -no-feature-sql \
        -no-feature-concurrent \
        -no-feature-brotli \
        -qt-zlib \
        -qt-libpng \
        -qt-libjpeg \
        -qt-freetype \
        -qt-pcre \
        -qt-harfbuzz \
        -- -DCMAKE_TOOLCHAIN_FILE=/build/arm32-toolchain.cmake \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

RUN mkdir qtshadertools-arm-build && cd qtshadertools-arm-build && \
    /opt/qt6-arm32/bin/qt-configure-module ../qtshadertools \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

RUN mkdir qtdeclarative-arm-build && cd qtdeclarative-arm-build && \
    /opt/qt6-arm32/bin/qt-configure-module ../qtdeclarative \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

RUN mkdir qtwebsockets-arm-build && cd qtwebsockets-arm-build && \
    /opt/qt6-arm32/bin/qt-configure-module ../qtwebsockets \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

# qtsvg (ARM32 cross-build): provides Qt6Svg + the QSvgPlugin image-format
# plugin that QImageReader uses to load `.svg` Image sources. Static-linked
# into the frontend via Qt6::QSvgPlugin in cmake/ZaparooRust.cmake.
RUN mkdir qtsvg-arm-build && cd qtsvg-arm-build && \
    /opt/qt6-arm32/bin/qt-configure-module ../qtsvg \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

# qtimageformats (ARM32 cross-build): provides QWebpPlugin so Core-returned
# WebP covers decode in the static MiSTer build. The plugin is statically
# linked into the frontend via Qt6::QWebpPlugin in cmake/ZaparooRust.cmake.
RUN mkdir qtimageformats-arm-build && cd qtimageformats-arm-build && \
    /opt/qt6-arm32/bin/qt-configure-module ../qtimageformats \
        -feature-webp \
        -no-feature-jasper \
        -no-feature-mng \
        -no-feature-tiff \
    && cmake --build . --parallel $(nproc) \
    && cmake --install .

# Rust toolchain for cross-compiling frontend-rs to ARM32.
# Added AFTER the Qt builds so changes here don't invalidate the Qt layer cache.
# Installs stable with minimal profile plus the ARM32 cross-compile target.
# Uses wget (already installed) since curl is not in the base image.
RUN wget -qO- https://sh.rustup.rs \
        | sh -s -- -y --default-toolchain stable --profile minimal \
    && /root/.cargo/bin/rustup target add armv7-unknown-linux-gnueabihf

ENV PATH="/root/.cargo/bin:${PATH}"

# Global cargo config: ARM32 linker and C++ compiler point to the MiSTer ARM
# GCC toolchain. CC/CXX are required by cxx_qt_build (via the cc crate) so
# the generated CXX-Qt bridge code is compiled with the cross-compiler.
RUN printf '[target.armv7-unknown-linux-gnueabihf]\n\
linker = "arm-none-linux-gnueabihf-gcc"\n\
\n\
[env]\n\
CC_armv7-unknown-linux-gnueabihf = "arm-none-linux-gnueabihf-gcc"\n\
CXX_armv7-unknown-linux-gnueabihf = "arm-none-linux-gnueabihf-g++"\n\
AR_armv7-unknown-linux-gnueabihf = "arm-none-linux-gnueabihf-ar"\n\
' > /root/.cargo/config.toml

# Pre-warm rustup with the exact toolchain pinned by the repo-root
# rust-toolchain.toml
# (1.97.0 + armv7-unknown-linux-gnueabihf target). Without this, the first
# `cargo` invocation inside Dockerfile.arm32 has to download the pinned
# toolchain on every build because rustup's override falls through to the
# default `stable` channel installed above. The shipped toolchain.toml is
# the source of truth, so any bump there will trigger a fresh download
# until this image is rebuilt — which is the same behavior we'd get
# without this line, just deferred. Pre-installing here shifts that
# work into the toolchain-image build (which is rare) instead of every
# arm32 build (which is per-commit).
RUN rustup toolchain install 1.97.0 --profile minimal \
    && rustup target add --toolchain 1.97.0 armv7-unknown-linux-gnueabihf

# cargo-chef: caches the Rust dependency build as a Docker layer in
# Dockerfile.arm32 (planner → cook → build), so per-commit ARM builds only
# recompile the workspace crates, not the whole dependency tree. Installed
# here once; the binary rides into the runtime stage via the
# `COPY --from=builder /root/.cargo` below and is on PATH through
# /root/.cargo/bin. The version is pinned (and `--locked` pins cargo-chef's own
# dependency versions) so rebuilding this toolchain tag reproduces the same
# cargo-chef build.
RUN cargo install cargo-chef@0.1.77 --locked

# Strip DWARF debug info from Qt artifacts before they're copied into the
# slim runtime stage. `--strip-debug` preserves all symbols needed for
# linking (this is what Debian's qt6 packages do); the ELF size impact
# of debug info on Qt's static archives and host shared libs is large
# (often >50%). Errors are swallowed so files that don't have debug info
# (e.g. cmake configs) don't fail the build.
RUN find /opt/qt6-arm32 -name '*.a' \
        -exec /opt/gcc-arm-10.2-2020.11-x86_64-arm-none-linux-gnueabihf/bin/arm-none-linux-gnueabihf-strip \
              --strip-debug {} + 2>/dev/null || true
RUN find /opt/qt6-host \( -name '*.a' -o -name '*.so*' \) \
        -exec strip --strip-debug {} + 2>/dev/null || true \
    && find /opt/qt6-host/bin -type f -executable \
        -exec strip --strip-unneeded {} + 2>/dev/null || true


# ---------------------------------------------------------------------------
# Runtime stage — the published image. Starts from a clean
# debian:bookworm-slim and copies only the build-time artifacts
# Dockerfile.arm32 needs. The builder stage's source clones,
# qt*-host-build/ qt*-arm-build/ trees, and `-dev` apt headers are left
# behind here.
# ---------------------------------------------------------------------------
FROM debian:bookworm-slim AS toolchain-base

ENV DEBIAN_FRONTEND=noninteractive

# Build-time runtime deps for Dockerfile.arm32:
#   - cmake, ninja-build, pkg-config: invoked by qt-cmake / build.rs
#   - build-essential: host gcc/g++ for build.rs scripts that need a
#     native compiler (cxx-qt-build's host-side codegen)
#   - git, ca-certificates: misc build.rs hooks (commit lookup,
#     crates.io HTTPS) — kept for resilience even though
#     scripts/build-arm32.sh exports ZAPAROO_BUILD_COMMIT explicitly
#   - python3: a few Qt cmake helpers shell out to python3
#   - xz-utils: tar.xz extraction during transitive setup
#   - libglib2.0-0: runtime dependency of qmake and qmlimportscanner
#     (host Qt was built against libglib2.0-dev; the runtime variant
#     stays here, the dev headers stay in the builder stage)
# All `-dev` packages stay in the builder stage; the host Qt's installed
# cmake configs are self-contained.
RUN apt-get update && apt-get install -y --no-install-recommends \
        build-essential \
        ca-certificates \
        cmake \
        git \
        libglib2.0-0 \
        ninja-build \
        pkg-config \
        python3 \
        xz-utils \
    && rm -rf /var/lib/apt/lists/*

# Copy the artifacts Dockerfile.arm32 actually consumes:
#   - ARM cross compiler tree (binaries + sysroot)
#   - host Qt (qt-cmake, qmake, qmllint, qmlformat, lupdate, lrelease,
#     LinguistTools cmake config)
#   - ARM32 static Qt (.a libraries, plugins, lib/cmake configs)
#   - cargo config + rustup toolchain caches (1.97.0 + armv7 target)
#   - the cmake toolchain file referenced from qt-cmake
COPY --from=builder /opt/gcc-arm-10.2-2020.11-x86_64-arm-none-linux-gnueabihf \
                    /opt/gcc-arm-10.2-2020.11-x86_64-arm-none-linux-gnueabihf
COPY --from=builder /opt/qt6-host  /opt/qt6-host
COPY --from=builder /opt/qt6-arm32 /opt/qt6-arm32
COPY --from=builder /root/.cargo   /root/.cargo
COPY --from=builder /root/.rustup  /root/.rustup
COPY --from=builder /build/arm32-toolchain.cmake /build/arm32-toolchain.cmake

ENV PATH="/opt/gcc-arm-10.2-2020.11-x86_64-arm-none-linux-gnueabihf/bin:/root/.cargo/bin:${PATH}"
ENV ARM_SYSROOT="/opt/gcc-arm-10.2-2020.11-x86_64-arm-none-linux-gnueabihf/arm-none-linux-gnueabihf/libc"

WORKDIR /build