Setup and Install SDK using CLI

This guide walks through the required steps to set up the Astra MCU SDK for command-line builds on Windows, Linux, or macOS.

Throughout this guide, <sdk-root> refers to the directory where you extracted or cloned the SDK.

Table of Contents

Prerequisites
Get the SDK
Install the toolchain (choose one)
Install Python tools (for image generation and tooling)
Linux USB/serial permissions (recommended)
Set required environment variables
Verify the environment
Next: Build an example

Prerequisites

Windows users are strongly encouraged to use WSL2 with Ubuntu 22.04. See Astra MCU SDK - WSL User Guide.

Get the SDK

Extract or clone the SDK to a local directory (for example, <sdk-root>).
Keep the SDK path short on Windows to avoid path length issues.

Install the toolchain (choose one)

Select the host OS and toolchain guide that matches your environment:

Windows

Linux

macOS

GCC (Apple Silicon + Intel): macOS + GCC
LLVM Clang (Apple Silicon + Intel): macOS + LLVM Clang

Install Python tools (for image generation and tooling)

Create a local virtual environment and install the required packages:

If you are using pyenv, activate it before creating the virtual environment:

cd <sdk-root>
pyenv local 3.13.7
python --version

Linux/macOS (run these commands from <sdk-root>)

cd <sdk-root>
python3 -m venv .venv
source .venv/bin/activate
pip install -r tools/srsdk_image_generator/requirements.txt
pip install pyserial

Windows (PowerShell) (run these commands from <sdk-root>)

cd <sdk-root>
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r tools\srsdk_image_generator\requirements.txt
pip install pyserial

Activate the virtual environment later if needed:

# Linux/macOS
source .venv/bin/activate

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

Note: Keep the virtual environment active when running SDK commands.

Verify you are using the virtual environment Python:

which python
python --version

Expected: which python points to <sdk-root>/.venv/... and python --version shows 3.13.x.

Linux USB/serial permissions (recommended)

On Linux, add your user to the dialout group so the flashing tools can access USB CDC/UART devices:

sudo usermod -aG dialout $USER

Log out and log back in (or reboot) for the group change to take effect.

Set required environment variables

Set the SDK root and toolchain paths in your shell.

Linux/macOS

export SRSDK_DIR=<sdk-root>

Note: SRSDK_DIR must be set in any shell where you build from <sdk-root>/examples (including app-only builds).

Choose one toolchain variable (do not set multiple toolchains at the same time):

# GCC
export GCC_TOOLCHAIN_13_2_1=/path/to/gcc-arm-none-eabi/bin

# Arm Compiler 6
export AC6_TOOLCHAIN_6_19_0=/path/to/armclang/bin

# LLVM Clang
export LLVM_TOOLCHAIN_ROOT=/path/to/llvm/bin
export GCC_TOOLCHAIN_ROOT=/path/to/gcc-arm-none-eabi

Note: LLVM builds require GCC_TOOLCHAIN_ROOT for the GCC sysroot (ARM system headers) and the C++ standard library (libstdc++).

Windows PowerShell

$env:SRSDK_DIR = "<sdk-root>"

# GCC
$env:GCC_TOOLCHAIN_13_2_1 = "C:\path\to\gcc-arm-none-eabi\bin"

# Arm Compiler 6
$env:AC6_TOOLCHAIN_6_19_0 = "C:\path\to\armclang\bin"

# LLVM Clang
$env:LLVM_TOOLCHAIN_ROOT = "C:\path\to\llvm\bin"
$env:GCC_TOOLCHAIN_ROOT = "C:\path\to\gcc-arm-none-eabi"

Note: LLVM builds require GCC_TOOLCHAIN_ROOT for the GCC sysroot (ARM system headers) and the C++ standard library (libstdc++).

To persist these variables, add them to your shell profile (Linux/macOS) or your PowerShell profile / System Environment Variables (Windows).

Verify the environment

Run these to confirm tools are reachable:

cmake --version
ninja --version
make --version
python --version
openocd --version

Expected versions (or newer):

CMake 4.1.2
Ninja 1.13.1
GNU Make 4.x
Python 3.13.x
OpenOCD 0.12.x (distribution package versions may vary)

Verify your selected toolchain is on PATH:

GCC: arm-none-eabi-gcc --version
Arm Compiler 6: armclang --version
LLVM Clang: clang --version

Next: Build an example

For step-by-step command-line build flows, see: