Setup

This chapter gets you from a clean checkout to a signed firmware image. All steps are traced to the upstream README.md at the pinned baseline; the Build System chapter explains what happens underneath.

Host environment

OpenSMA builds on Ubuntu 24.04 (README.md:5). Install the system packages (README.md:8) — the toolchain-adjacent ones matter most: git-lfs, clang-tidy-18 / clang-format-18 (lint/format, see Reference), gcc-13/g++-13, lcov (coverage), doxygen/graphviz/asciidoctor (docs), and xxd/jq/xz-utils. Then the Python packages (README.md:19): jsonschema, ruamel.yaml, and spsdk (NXP’s Secure Provisioning SDK — used for signing).

Finally, link make into the build system’s bin/ (README.md:26):

ln -sf /usr/bin/make corepdk/ubs/bin/make

Toolchains

OpenSMA uses three toolchains, all extracted into libexec/toolchain/ (README.md:29):

Toolchain	Version	Purpose
ARM GNU (arm-none-eabi)	14.2.rel1	Primary C/C++ cross-compiler (README.md:30)
GCC ARM (gcc-arm-none-eabi)	10.3-2021.10	Secondary GCC (README.md:32)
GNAT (gnat_arm_elf)	14.2.1	Ada compiler, fetched via alr (README.md:34)

The GNAT toolchain is obtained with Alire: alr get gnat_arm_elf=14.2.1 (README.md:35), then moved into libexec/toolchain/. mcu_build.sh expects the toolchains under MCU_TOOLCHAIN_ROOT (default /toolchain, mcu_build.sh:44) and invokes, e.g., arm-none-eabi-objcopy from the 14.2 toolchain (mcu_build.sh:50).

NXP SDK

Download the MCUXpresso SDK for MCXN556S, version 25.09.00 from mcuxpresso.nxp.com (select Linux host, all toolchains, all middlewares) and extract it into libexec/sdk/SDK_25_09_00_MCXN556S (README.md:38, README.md:43):

mkdir -p libexec/sdk/SDK_25_09_00_MCXN556S
tar -xvzf SDK_25_09_00_MCXN556S.tar.gz -C libexec/sdk/SDK_25_09_00_MCXN556S

Then apply the bundled SDK patch (README.md:49):

cd libexec/sdk/SDK_25_09_00_MCXN556S
xz -dc ../../patch/mcu.patch.xz | patch -p1 -N

First build

With toolchains and SDK in place, build and sign the reference project (README.md:56, README.md:61):

./mcu_build.sh PROJECT=mcxn547helloworld BOARD=mcxn547helloworld \
    PLATFORM=mcxn556-both MODE=rel SIGN_KEYSET=local RUN_LOCAL=1

Artifacts land in the build/ folder. RUN_LOCAL=1 runs the flow directly instead of inside the UBS Docker image; SIGN_KEYSET=local selects local signing. The selectors are explained in the Build System chapter.

Build with Docker (recommended)

To avoid installing the toolchains on the host, build inside the pinned UBS image (README.md:64):

# Build the image once
docker build -f ./libexec/ubs.dockerfile -t opensma .
# Run it, mounting the repo
docker run --rm -it --user=${UID}:${GID} -v $(pwd):/opensma opensma
# Inside the container, build + sign
./mcu_build.sh PROJECT=mcxn547helloworld BOARD=mcxn547helloworld \
    PLATFORM=mcxn556-both MODE=rel SIGN_KEYSET=local RUN_LOCAL=1

The Dockerfile (libexec/ubs.dockerfile) captures the exact build and signing environment, which is why the Docker path is the most reproducible.

Next

• Architecture — how the image you just built is composed.
• Build System — what mcu_build.sh and ./ubs actually do.