Proposal: Simplify TA Build/Dev Environment

[m4sterchain]

The current Quick Start for the Teaclave TrustZone SDK requires first-time Trusted Application (TA) developers to manually follow multiple setup steps, making the onboarding process cumbersome. Meanwhile, the project already has reproducible CI environments in place—but those aren't directly usable by developers.

This proposal introduces prebuilt Docker images tailored for TA development, aiming to streamline the setup process and accelerate prototyping. These images will be parameterized built and versioned, which include:

• Specific combination of Teaclave SDK version and OP-TEE version
• Target platform (e.g. qemu_v8) and architecture for OP-TEE setup
• Build mode (e.g. build or dev)
• Runtime configuration (e.g. std or no_std) for Teaclave TA build

Docker Image Naming Convention

Images will follow this format:

teaclave-${SDK_VER}-optee-${OPTEE_VER}-${platform}-${ARCH}-${std|no_std}-${build|dev}

Examples:

teaclave-0.4.1-optee-4.5.0-qemu_v8-arm-no_std-build
teaclave-0.4.1-optee-4.5.0-qemu_v8-aarch64-std-build
teaclave-0.4.1-optee-4.5.0-qemu_v8-aarch64-no_std-dev

Image Types

• 🛠️ build: Contains all necessary toolchains to build TAs for the target platform.
• 🧪 dev: Superset of build, with additional runtime dependencies to run/test TAs on QEMU for daily development.

Benefits

• 🧃 One-step setup for new developers
• 📦 Reproducible builds with pinned dependencies
• 🧱 Configurable via Docker build arguments for advanced use cases
• 🚀 Enables real "Quick Start" experience

Example Usage

Once the images are published on DockerHub, beginner TA developers can start using the SDK out of the box with minimal setup, ideal for experimenting and developing in Rust. For more advanced developers, the provided Dockerfiles expose configurable build arguments, allowing them to customize and build images tailored to their specific platforms or preferences.

git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git
cd incubator-teaclave-trustzone-sdk

docker run -it -v $(pwd):/root/teaclave-sdk \
  teaclave-0.4.1-optee-4.5.0-qemu_v8-arm-no_std-build /bin/bash

cd teaclave-sdk
make examples
...

@ivila @DemesneGH — since you're the experts on the existing CI image setup, I’d love your input on extending the multi-stage Dockerfile to support customizable build/dev images for TA developers. This is still a rough proposal, so feel free to refine any part of it. Just wanted to share the concept and get your thoughts on how we might align this with the existing CI flow.

The idea is to streamline onboarding for beginners by providing prebuilt images, while also enabling advanced users to tweak their setup via build arguments. Here’s a rough sketch of the direction:

ARG SDK_VER=0.4.1
ARG OPTEE_VER=4.5.0
ARG PLATFORM=qemu_v8
ARG ARCH=aarch64
ARG STD_TYPE=no_std

FROM ubuntu:24.04 AS base
# Install dependencies (toolchains, etc.)

FROM base AS build
# Setup build environment based on parameters

FROM build AS dev
# Setup dev environment (e.g., QEMU, test tools)

Build example:

docker build \
    --build-arg SDK_VER=${SDK_VER} \
    --build-arg OPTEE_VER=${OPTEE_VER} \
    --build-arg PLATFORM=${PLATFORM} \
    --build-arg ARCH=${ARCH} \
    --build-arg STD_TYPE=${STD_TYPE} \
    --target ${stage} \
    -t ${TAG} 

[ivila]

For Docker Image Naming Convention, I think we should remove the ${ARCH}, as in OCI:

1. images are split by platform, not just architecture.
2. we can just build a multi platform image: MultiPlatform | Docker

Maybe just:

teaclave-${SDK_VER}-optee-${OPTEE_VER}-${emulator}-${std|no_std}-${build|dev}

PS: I also change the word platform to emulator to avoid confusion, because the first time I saw it, I thought it is the target_platform of docker😂

And with the image became a multi-platform image, the build example would be:

docker buildx build \
    --platform linux/amd64,linux/arm64
    --build-arg SDK_VER=${SDK_VER} \
    --build-arg OPTEE_VER=${OPTEE_VER} \
    --build-arg PLATFORM=${PLATFORM} \
    --build-arg ARCH=${ARCH} \
    --build-arg STD_TYPE=${STD_TYPE} \
    --target ${stage} \
    -t ${TAG} 

[DemesneGH]

Thanks for the proposal!

Since this Docker image is primarily used for cross-compilation, most dependencies are shared across architectures and configurations. To reduce maintenance overhead, how about using a single image and passing configuration via environment variables at runtime?

For example:

git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git
cd incubator-teaclave-trustzone-sdk

docker run -it -v $(pwd):/root/teaclave-sdk \
  -e TA_ARCH=aarch64 \
  -e CA_ARCH=arm \
  -e STD=y \
  -e OPTEE_VER=4.5.0 \
  teaclave-trustzone-sdk-v0.2.0 bash

A start.sh script inside the image can configure the environment based on these variables. Once set up, users can simply run:

make examples

On Build vs. Dev Scenarios

We should clarify the goals of build and dev scenarios. Is the following description correct?

• Build: Focused on quick start and testing to confirm that the building env works and examples compile.
• Dev: Involves writing a new TA, building it, and testing it on QEMU.

If that distinction makes sense, then it's not necessarily something the Docker image needs to separate. Instead, we could:

• Provide a script like quick_testing.sh for the build/validation scenario
• Offer developer guidance for the dev/debug workflow, including running QEMU and using debug scripts we provided.

Other Config Options

• SDK_VER: I suggest we encode this in the image tag (e.g., teaclave-trustzone-sdk:v0.2.0).
• PLATFORM: Since we currently only support qemu-v8 for dev, we can omit this as a runtime option and instead document it. For other hardware, developers can use their own TA_DEV_KIT_DIR to build, but testing would need to happen on their board. It's an advanced topic and can have some document about it.

[m4sterchain]

@ivila To clarify, the $platform variable originates from the manifest used to set up the OP-TEE environment. For example:

repo init -u https://github.com/OP-TEE/manifest.git -m qemu_v8.xml

We currently use qemu_v8 as the default, but TA developers can switch to other platforms by simply replacing the manifest.

The $arch variable refers to the target architecture for the TA binary. From what I’ve seen in CI, we’re supporting builds for both ARM (32-bit) and AArch64 (64-bit).

I am not sure where we should parameter these configurations ideally. Feel free to come up with a simple version and we can polish overtime.

==========
@DemesneGH The build image is also configurable for developers using physical boards. Our long-term goal is to consolidate all platform and architecture parameters into a global configuration, instead of scattering them across separate build scripts. This will allow us to support advanced use cases, such as building for i.MX boards, by supplying the appropriate parameters, without introducing unnecessary QEMU dependencies into the development environment.

Currently, the setup scripts have several limitations, such as implicit dependencies of config variables, setup order sensitivity, and hardcoded configurations. These are areas we aim to improve over time.

In the short term, we can start with a practical and achievable version, but it'll be preferred to structure it in a way that leaves room for long-term improvements—especially toward a cleaner and more flexible build configuration design, rather than hardcoding everything up front.

==========

@DemesneGH @ivila
I believe using the prebuilt build/dev docker image, we might also potentially simplify the existing CI workflow and boost CI validation time. But we can leave this as a separate topic for future discussion.