# syntax=docker/dockerfile:1
#
# Reproducible PlatformIO build environment for the friend-finder badge.
# Builds the firmware identically on any machine — no host PlatformIO needed.
#
#   docker build -t badge-fw .                       # build the image (also verifies the FW compiles)
#   docker run --rm badge-fw pio run -e oled_v3      # build a specific env from the baked-in source
#   docker run --rm -v "$PWD/firmware:/project" badge-fw pio run -e oled_v3   # build your LIVE tree
#
# The image bakes in the heavy one-time downloads (pioarduino core-3.x platform,
# the xtensa toolchain, the registry libs) so container builds are fast and work
# offline. See docs/docker.md for the full workflow.
#
# ⚠️ FLASHING is a HOST concern, not a container one. Docker Desktop on macOS /
# Windows cannot pass a USB serial port into the container, so build here and
# flash from the host (`pio run -t upload`). On a LINUX host you *can* flash from
# the container with `--device=/dev/ttyUSB0`. Details in docs/docker.md.

FROM python:3.13-slim

# git            — currently UNUSED in-container: no lib_deps are git URLs anymore, and
#                  .git isn't COPYed below, so the pre:git_rev.py hook stamps GIT_REV="nogit"
#                  regardless. Kept as cheap insurance for a build that later vendors .git.
# ca-certificates— the pioarduino platform + packages are fetched over https
RUN apt-get update && apt-get install -y --no-install-recommends \
        git ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Pin PlatformIO Core to match the dev machine (parity). Bump deliberately, in
# lockstep with whatever the team builds against locally.
ARG PLATFORMIO_VERSION=6.1.19
RUN pip install --no-cache-dir "platformio==${PLATFORMIO_VERSION}" intelhex
#                                                                   ^^^^^^^^
# intelhex: once pioarduino is installed, the STOCK-espressif32 fallback envs
# (`oled`, `esp32dev`) fail at the image-packaging step without it
# The core-3.x badge builds don't need it; it's cheap
# insurance so every env in platformio.ini builds in this image.

# Keep PlatformIO's package cache INSIDE the image (committed in the warm layer
# below) so container builds need no network.
ENV PLATFORMIO_CORE_DIR=/opt/pio

WORKDIR /project

# ── Warm layer ──────────────────────────────────────────────────────────────
# Copy ONLY platformio.ini first, then fetch every declared dependency. Editing
# source later won't re-trigger this (large, slow) toolchain download — it's a
# separate, cache-friendly layer keyed on platformio.ini alone.
COPY firmware/platformio.ini ./platformio.ini
RUN pio pkg install -e esp32dev_v3 -e oled_v3

# ── Source + self-verifying compile ─────────────────────────────────────────
# Copy the project and compile both core-3.x targets during the image build, so
# `docker build` itself proves the firmware compiles. Uses the warmed /opt/pio
# cache, so this is just a (fast, offline) compile — no re-downloads.
COPY firmware/ ./
RUN pio run -e esp32dev_v3 -e oled_v3

# Default action: build the default env (oled_v3). Override per-invocation,
# e.g. `docker run --rm badge-fw pio run -e esp32dev_v3`.
CMD ["pio", "run"]
