# Base image: Ubuntu 24.04 provides a stable environment for the ARM cross-compilation toolchain
FROM ubuntu:24.04

# Install all dependencies required to cross-compile C code for the Raspberry Pi Pico (RP2040):
#   - cmake: build system generator used by the Pico SDK
#   - gcc-arm-none-eabi: ARM cross-compiler that produces binaries for the Pico's Cortex-M0+ CPU
#   - libnewlib-arm-none-eabi: C standard library implementation for bare-metal ARM targets
#   - build-essential: provides make and other essential build utilities
#   - git: needed to clone the Pico SDK and its submodules
#   - python3: required by the Pico SDK build scripts for UF2 generation and other tooling
#   - clangd: C/C++ language server used by the VS Code Dev Container for
#             intellisense (go-to-definition, hover types, autocomplete) -
#             must live INSIDE the container so it can resolve Pico SDK
#             headers under /opt/pico-sdk at their real paths
RUN apt-get update && apt-get install -y \
    cmake \
    gcc-arm-none-eabi \
    libnewlib-arm-none-eabi \
    build-essential \
    git \
    python3 \
    clangd \
    && rm -rf /var/lib/apt/lists/*

# Clone the official Raspberry Pi Pico SDK into the container.
# The SDK provides hardware abstraction libraries, startup code, and linker scripts
# needed to build firmware for the RP2040 microcontroller.
# Submodules include tinyusb (USB stack) and other vendor-specific dependencies.
RUN git clone https://github.com/raspberrypi/pico-sdk.git /opt/pico-sdk \
    && cd /opt/pico-sdk \
    && git submodule update --init

# Tell CMake where to find the Pico SDK. The SDK's CMake scripts look for this
# environment variable to locate platform files, toolchain config, and libraries.
ENV PICO_SDK_PATH=/opt/pico-sdk

# All build commands will run from /project, which is where the host source code
# gets mounted via docker-compose volumes
WORKDIR /project