# ============================================================================
# Docker Compose configuration for the Raspberry Pi Pico firmware project
# ============================================================================
# The container is configured to be long-running (sleep infinity) rather than
# running the build on startup. This lets the same container be used for:
#   1. One-shot builds from the host
#   2. Interactive shells (docker compose exec) for debugging
#   3. VS Code Dev Containers - which expects the container to stay alive
#      so it can attach clangd, install extensions, and open a terminal
#
# Usage:
#   docker compose build                                  - (re)build the image after Dockerfile changes
#   docker compose up -d                                  - start the persistent container in the background
#   docker compose exec pico-build bash                   - shell into the running container
#   docker compose run --rm pico-build bash build.sh      - one-shot firmware build, container removed after
#   docker compose down                                   - stop and remove the persistent container
# ============================================================================

services:
  pico-build:
    # Build the image from the Dockerfile in the project root
    build: .

    # Mount project source and the shared common components into the container.
    # The project mounts at /project (working directory). The common submodules
    # mount at /common so the CMake COMMON_DIR path (../common relative to the
    # project root) resolves correctly inside the container.
    volumes:
      - .:/project
      - ../common:/common
      - ../build.sh:/scripts/build.sh

    # Keep the container alive indefinitely. We intentionally do NOT run the
    # build on startup - `sleep infinity` lets the container stay up so it can
    # be used as a persistent dev environment (VS Code Dev Containers, shells
    # via `docker compose exec`, etc.). To trigger a build, run:
    #     docker compose run --rm pico-build bash build.sh
    # or, if you're already inside the container:
    #     bash build.sh
    command: sleep infinity