Multi-Stage Dockerfile

Sol3 development requires users to build and run software on multiple platforms. While the software must ultimately run on the Sol3 platform itself (ARM64), users may have library code or tools they wish to build and run on their local machine (e.g. x64) for quick iteration and development. The Sol3 SDK supports these use cases through the use of a multi-stage Dockerfile that exposes a configurable BUILDPLATFORM (host machine) and TARGETPLATFORM (target machine), via the docker build --platform PLATFORM flag.

Overview

The Dockerfile consists of four primary stages, each serving a specific purpose in the build and deployment workflow:

  1. devcontainer: Builds a development environment with a compiler toolchain, targeting interactive development.

  2. sysroot: Installs runtime dependencies in a minimal sysroot environment.

  3. builder: Builds the project against the sysroot using the configured devcontainer toolchain.

  4. app_image: Installs the builder output on top of the sysroot base image, providing a runnable application image.

Stage 1: devcontainer

The devcontainer stage creates a development environment for interactive development and debugging. This stage serves as the devcontainer image, where users can develop interactively and iterate quickly. Users can customize this stage by adding their own dependencies directly to the Dockerfile.

Purpose

  • Provides C++ development toolchain (clang, CMake, ninja)

  • Includes debugging tools (gdb, valgrind, strace)

  • Sets up cross-compilation capabilities for ARM64

  • Installs the Python toolchain for the build host (selected by BUILDARCH, since this stage runs on BUILDPLATFORM)

  • Configures non-root development user with appropriate permissions

Usage

This stage is used by the devcontainer CLI, or as a VSCode Dev Container, to provide developers with a consistent environment for SDK development and application building.

Stage 2: sysroot

The sysroot stage creates architecture-specific runtime environments containing the libraries and dependencies needed to run Sol3 applications. The sysroot stage is intended to be run with either --platform=linux/arm64 (Sol3) or --platform=linux/amd64 (development PC), supporting both ARM64 and x64 sysroots.

During the build this is the only place that should be searched for runtime dependencies (includes, shared libraries, etc). This ensures that the build artifacts will execute properly within the app_image container.

Purpose

  • Provides target-platform-specific system libraries

  • Includes Sol3-specific dependencies (QRB5165 packages for ARM64)

  • Installs OpenCL and GBM (x64: ocl-icd/libgbm; ARM64: qti-adreno and the QRB5165 GBM debian) into the sysroot

  • Creates minimal runtime foundation for deployment

  • Ensures binary compatibility with target hardware

Stage 3: builder

The builder stage builds a target application within the devcontainer image, referencing the configured sysroot.

Purpose

  • Performs actual application compilation using SDK build system

  • Combines devcontainer toolchain with target sysroot

  • Executes CMake-based build process with appropriate presets

  • Installs built artifacts for deployment packaging

Stage 4: app_image

The app_image stage creates a minimal deployment image containing only the necessary components to run the compiled application.

Purpose

  • Provides lightweight deployment image without build dependencies

  • Configures runtime environment and user permissions

  • Sets up execution environment for Sol3 applications

  • Minimizes image size for production deployment

Usage

This stage produces the final deployable image suitable for:

  • Direct deployment to Sol3 hardware via container runtime

  • Integration testing in target-like environments (ARM64 runners)