Skip to main content

Installation

The Alp SDK is supported equally on Linux, macOS, and Windows (native PowerShell or WSL2) per ADR 0012: cross-platform developer hosts are a load-bearing SDK principle, so customers never feel "I need Linux to use the alp-sdk." Yocto is Linux-only by upstream constraint (use WSL2 on Windows); the Zephyr-on-M-class workflow is first-class on every host. Tooling versions are identical across hosts; only the install commands differ.

For the full per-OS quickstart (gotchas, MAX_PATH on Windows, Gatekeeper on macOS, serial device naming, what's-Linux-only-and-why), see docs/cross-platform-setup.md in the SDK repo.

Prerequisites​

ToolVersionNotes
Zephyrv4.4.0Pinned by the SDK's west.yml. See the version policy.
Python3.10+For west, the board.yaml orchestrator (alp_orchestrate.py), validators.
Python depspyyaml, jsonschema, imgtoolInstalled by scripts/bootstrap.sh (or scripts/bootstrap.ps1 on native Windows). Manual install: pip install pyyaml jsonschema imgtool.
CMake3.20+find_package(Zephyr) minimum.
C compilerGCC 11+ / Clang 14+native_sim builds; cross-toolchain for real silicon.
west1.2+pip install west if your distro doesn't ship it.

Install the toolchain​

Linux (Debian / Ubuntu)​

sudo apt update
sudo apt install -y cmake ninja-build python3 python3-pip git
pip3 install west

macOS (Homebrew)​

brew install cmake ninja python git
pip3 install west

Windows (native, PowerShell)​

winget install -e --id Kitware.CMake
winget install -e --id Ninja-build.Ninja
winget install -e --id Python.Python.3.12
winget install -e --id Git.Git
pip install west

Windows (WSL2)​

wsl --install -d Ubuntu

Then use the Linux instructions inside the Ubuntu shell.

Zephyr SDK (for real silicon)​

For builds against actual hardware you also need the Zephyr SDK cross-toolchains — bootstrap.sh does not install them; run west sdk install from the workspace once after bootstrapping. native_sim builds use only the host compiler and don't require the Zephyr SDK.

Clone and bootstrap​

The simplest path uses the SDK's bootstrap script:

git clone https://github.com/alplabai/alp-sdk
cd alp-sdk
bash scripts/bootstrap.sh
source ../zephyrproject/.venv/bin/activate
export ZEPHYR_BASE="$PWD/../zephyrproject/zephyr"

scripts/bootstrap.sh creates a Zephyr workspace one level up from alp-sdk/, runs west update --narrow, and installs west plus the Zephyr Python deps and the SDK's extras (jsonschema, imgtool) — and an editable install of the alp CLI — into a workspace venv (zephyrproject/.venv); your system Python is never touched. Because the CLI install is editable, a later git pull in the alp-sdk checkout updates alp in place. The script also prints OS-specific apt / brew commands for the optional native libraries the Yocto backends need.

The script is idempotent (re-running skips completed work) and respects an existing $ZEPHYR_BASE: if it points at a compatible v4.4.x workspace, bootstrap reuses it and never modifies your tree. Useful flags: --no-pip, --no-west, and --print-env (prints the env-var lines to source).

Windows (native) bootstrap​

On native Windows, scripts/bootstrap.ps1 is the PowerShell-7+ companion to bootstrap.sh — it lays down the same workspace layout (Zephyr tree beside the checkout, a hermetic zephyrproject/.venv with west + the Python deps, and the editable alp CLI):

git clone https://github.com/alplabai/alp-sdk
cd alp-sdk
pwsh scripts\bootstrap.ps1
& ..\zephyrproject\.venv\Scripts\Activate.ps1
$env:ZEPHYR_BASE = "$PWD\..\zephyrproject\zephyr"

It is idempotent, and it stays honest about scope: it does not install git / CMake / Python / Ninja themselves (a missing prerequisite prints the matching winget install one-liner and exits), and it does not install the Arm GNU Toolchain or the Zephyr SDK (both are manual GUI installs on Windows — the script prints hints at the end). native_sim does not exist on native Windows; use WSL2 for the simulator and the Yocto halves. Mirror flags: -NoPip, -NoWest, -PrintEnv.

<parent>/
├── alp-sdk/                  # this repo
└── zephyrproject/
    ├── .venv/                # hermetic west + Zephyr Python deps
    ├── zephyr/               # v4.4.0
    └── modules/

Manual west init (alternative)​

If you'd rather drive west directly:

mkdir alp-workspace && cd alp-workspace
west init -m https://github.com/alplabai/alp-sdk
west update --narrow -o=--depth=1
west zephyr-export

After this the workspace contains:

alp-workspace/
├── zephyr/         # Zephyr v4.4.0 (pinned)
├── modules/        # standard Zephyr modules
└── alp-sdk/        # this repo, mounted as a Zephyr module

west update --narrow -o=--depth=1 keeps the clone shallow — saves ~30 GB of unrelated git history.

Importing alp-sdk via west init -m also surfaces the west alp-build extension command that the Quick Start uses.

Verify​

Once bootstrapped, the alp CLI is the single front door (build / run / flash / emit / doctor / monitor). Confirm the host is build-ready, then build + run the GPIO example on native_sim:

alp doctor                 # host-environment preflight: PASS / WARN / FAIL
cd alp-sdk/examples/peripheral-io/gpio-button-led
alp run                    # build for native_sim + execute

The same check driving west directly:

cd alp-workspace
west alp-build --version
west alp-build -b native_sim/native/64 alp-sdk/examples/peripheral-io/gpio-button-led
west build -d build -t run

A successful run prints *** Booting Zephyr OS build v4.4.0 *** followed by the example's output. See the Quick Start for the full walk-through.

Install the alplabai.alp-sdk extension for:

  • Schema-aware board.yaml editing (autocomplete on SKUs, board presets, libraries, v0.6 blocks)
  • Inline validator diagnostics in the Problems panel
  • GUI configurator panel with dropdowns for every released MPN + board preset
  • One-keypress Alp: Generate all command for the loader's emit modes
  • west wrappers (build / flash / run native_sim)
  • Per-OS dependency bootstrap

See the VS Code page.

SDK directory layout​

alp-sdk/
├── include/alp/     # PUBLIC headers (the consumer surface)
├── src/             # common/ + zephyr/ + baremetal/ + yocto/ backends
├── chips/           # 70+ opt-in chip drivers (Tier 0 stable + v0.5 §D ecosystem)
├── vendors/         # per-SoM HAL bindings (alif, renesas-rzv2n, nxp-imx93, deepx-dxm1)
├── metadata/        # schemas, templates, e1m_modules/<MPN>.yaml, boards/, socs/, library-profiles/
├── scripts/         # board.yaml orchestrator, validators, soc_caps + ABI generators
├── examples/        # reference apps (gpio-button-led, rpmsg-v2n, edgeai-vision-aen, ...)
├── docs/            # architecture, board-config, ADRs, test-plan, ...
├── tests/           # Python script tests + ztest suites
├── meta-alp-sdk/    # Yocto layer + per-cluster MACHINE confs (v0.6 layout)
└── west.yml         # Zephyr manifest

Next steps​

Questions about this page? Discuss in Community Forum