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.1Pinned by the SDK's west.yml and metadata/bootstrap.json. See the version policy.
Zephyr SDK1.0.1Pinned by metadata/toolchains.json. Cross-toolchains for real silicon; native_sim builds don't need it.
Python (bootstrap floor)3.10+prerequisites.pythonMinVersion — the host-universal floor, and the one the bootstrap scripts actually enforce.
Python (Zephyr build floor)3.12+zephyr.pythonMinVersion — Zephyr's real build floor. Neither bootstrap.sh nor bootstrap.ps1 enforces it; it is enforced only by Zephyr's own CMake at west build time. Bootstrapping on 3.10 / 3.11 therefore succeeds and the build is what fails.
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.
tan CLI0.5.1The SDK's sole user-facing command. tan is a Python program, released as a self-contained PyInstaller --onedir freeze — it needs no Rust toolchain, no rustup, and no Python interpreter on the host. Installed by its own script (below), not by the SDK bootstrap.

The bootstrap prerequisites on POSIX hosts are git, cmake, python3, ninja, xz, and wget — ninja is a real prerequisite here, not an optional extra. On Windows, 7-Zip is additionally required (winget install -e --id 7zip.7zip); it gates west sdk install, not bootstrap.ps1.

Install the toolchain​

Linux (Debian / Ubuntu)​

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

macOS (Homebrew)​

brew install git cmake python ninja xz wget
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
winget install -e --id 7zip.7zip
pip install west

7-Zip is what unpacks the Zephyr SDK archive, so it gates west sdk install — bootstrap.ps1 runs fine without it. Installing Python 3.12 here also clears Zephyr's own 3.12 build floor, which the bootstrap script never checks.

Windows (WSL2)​

wsl --install -d Ubuntu

Then use the Linux instructions inside the Ubuntu shell.

Install the tan CLI​

tan is the SDK's sole user-facing command-line front door — scaffolding, validating, generating, host preflight, serial console, diagnostics, and building / flashing / sizing / bundling / cleaning / Renode-booting. It ships from its own repo (alplabai/tan-cli) on its own version line — the released version is 0.5.1 — so you install it separately from the SDK bootstrap, and you install it first, because the bootstrap step itself is a tan verb.

tan is a Python program, released as self-contained PyInstaller --onedir freezes. The install script drops a ready-to-run freeze on your PATH: there is no Rust toolchain, no rustup, and no Python interpreter to provide.

curl -fsSL https://raw.githubusercontent.com/alplabai/tan-cli/main/install.sh | sh
Windows PowerShell
irm https://raw.githubusercontent.com/alplabai/tan-cli/main/install.ps1 | iex

From a source checkout instead: pip install ./python.

Installing tan never pulls in alp-studio or the VS Code extension.

Zephyr SDK (for real silicon)​

For builds against actual hardware you also need the Zephyr SDK cross-toolchains, pinned at 1.0.1 by metadata/toolchains.json. Neither tan bootstrap nor bootstrap.sh installs them; run west sdk install from the workspace once after bootstrapping (see the sequence below). native_sim builds use only the host compiler and don't require the Zephyr SDK.

This is the one place west is still a customer-facing command: tan sdk install / tan sdk switch are not ported yet.

Intel Mac: no Zephyr SDK target

The pinned Zephyr SDK ships a macos-aarch64 host archive only — there is no macos-x86_64. On an Intel Mac the west sdk install step therefore has nothing to install, and real-silicon Zephyr builds need a Linux host instead. native_sim and the bootstrap step itself are unaffected.

Clone and bootstrap​

The canonical first-install sequence — tan first, then the SDK, then the toolchain:

git clone https://github.com/alplabai/alp-sdk
cd alp-sdk

curl -fsSL https://raw.githubusercontent.com/alplabai/tan-cli/main/install.sh | sh
# Windows PowerShell: irm https://raw.githubusercontent.com/alplabai/tan-cli/main/install.ps1 | iex

tan bootstrap --sdk-root "$PWD"
tan doctor

( cd .. && west sdk install --gnu-toolchains arm-zephyr-eabi --no-hosttools \
    --install-dir "$PWD/zephyr-sdk" )
export ZEPHYR_SDK_INSTALL_DIR="$PWD/../zephyr-sdk"

tan init --name my-app --destination .. --sdk-root "$PWD"
cd ../my-app
tan build

Every customer-facing step leads with tan; west appears exactly once, for the one-time SDK toolchain install.

The SDK also ships the bootstrap scripts directly, if you'd rather run them yourself:

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

scripts/bootstrap.sh makes the alp-sdk checkout's parent directory the west workspace (west init -l <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 SDK-side alp_cli package — into a workspace venv; your system Python is never touched. Because that install is editable, a later git pull in the alp-sdk checkout updates it in place. The script also prints OS-specific apt / brew commands for the optional native libraries the Yocto backends need.

It enforces the 3.10 host Python floor (prerequisites.pythonMinVersion) and stops there — Zephyr's own 3.12 build floor (zephyr.pythonMinVersion) is not checked by any bootstrap script, so a 3.10 / 3.11 host bootstraps cleanly and then fails inside Zephyr's CMake at west build time.

Bootstrap does not give you a command to run

There is no alp binary installed anywhere — pyproject.toml registers only alp-mcp. alp_cli is an SDK-side Python package, not a user command; tan does not shell out to it — since v0.5.0-rc1 tan is itself a Python program and carries its own implementations. Install tan before you build anything.

The resulting layout — alp-sdk is the manifest repo, so the topdir is its parent:

<parent>/                     # west topdir
├── alp-sdk/                  # this repo — the workspace manifest
├── .west/
├── .venv/                    # hermetic west + Zephyr Python deps
├── zephyr/                   # v4.4.1
└── modules/                  # HALs + extras
This layout changed in v0.10.1

Bootstrap used to init the workspace from the plain upstream Zephyr manifest into a zephyrproject/ sibling. That left alp-sdk as a non-manifest project, so west never discovered its extension commands and every west alp-* command failed with "unknown command" (#769). Bootstrap now inits from alp-sdk's own west.yml, which both fixes the commands and moves the topdir to the checkout's parent. If you bootstrapped before v0.10.1, re-run scripts/bootstrap.sh on a fresh clone and update your ZEPHYR_BASE — the old ../zephyrproject/zephyr path no longer applies.

Two guards keep that honest. A reuse-guard only reuses an existing $ZEPHYR_BASE workspace when it's a v4.4.x tree and its manifest repo is this very checkout — a compatible-but-foreign workspace is refused (and ZEPHYR_BASE unset) rather than silently producing the broken layout. A post-init legibility guard then asserts west alp-migrate actually resolves, so a bad workspace fails at bootstrap time instead of at your first build.

The script is idempotent (re-running skips completed work). It takes no target directory — the destination derives from the script's own location. 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:

git clone https://github.com/alplabai/alp-sdk
cd alp-sdk
pwsh scripts\bootstrap.ps1
& ..\.venv\Scripts\Activate.ps1
$env:ZEPHYR_BASE = "$PWD\..\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.

As of v0.11.0 bootstrap.ps1 produces the same layout as bootstrap.sh — west init -l <alp-sdk>, so alp-sdk is the manifest repo, the topdir is its parent, and the surviving alp-* extension commands register. Both guards described above now run on native Windows too, including the post-init legibility guard that fails the bootstrap outright if west alp-migrate doesn't resolve.

Bootstrapped on Windows before v0.11.0? Your layout is stale

Through v0.10.1 the #769 fix had landed in bootstrap.sh only, so bootstrap.ps1 initialised from the upstream Zephyr manifest into a zephyrproject\ sibling — which left alp-sdk a non-manifest project and every west alp-* command an "unknown command".

Re-run pwsh scripts\bootstrap.ps1 on a fresh clone and update ZEPHYR_BASE: the old ..\zephyrproject\zephyr path no longer applies, and the old workspace is not reused (the reuse-guard refuses a workspace whose manifest isn't this checkout, rather than silently rebuilding the broken layout).

Manual west init (alternative)​

If you'd rather drive west directly — this works on every host, and produces the same topdir shape with west choosing the topdir instead of it being wherever you happened to clone:

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

After this the workspace contains:

alp-workspace/           # west topdir
├── zephyr/              # Zephyr v4.4.1 (pinned by the SDK's west.yml)
├── modules/             # standard Zephyr modules
└── alp-sdk/             # this repo — the workspace manifest

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

Initialising from alp-sdk's manifest is what surfaces the surviving west alp-* extension commands — west alp-migrate (board.yaml schema migration), west alp-lock (dependency lockfile), west alp-quality (quality-task registry) and west alp-emit (the generated-artefact subset): west reads them from the manifest's self.west-commands, not from zephyr/module.yml. Consumers who instead include alp-sdk as a project in their own west.yml should add the same west-commands: scripts/west-commands.yml line under their projects.alp-sdk entry, or the commands won't register. Building is not among them — that surface belongs to tan (above).

The SDK's west.yml disables four optional project groups by default (extras-tier1, extras-cpp, extras-lwrb-nanopb, vendor-sdks); enable one with west update --group-filter +<group>.

How tan runs your commands​

Everything runs inside the one frozen Python program — tan does not shell out to python -m alp_cli for any verb:

  • build / flash / size / image / clean / renode — tan's own build executor. Per ADR 0020, alp-sdk is plans-only for this surface: tan runs west / bitbake / cmake per slice itself.
  • model, monitor, faultdecode, new-som — native Python inside tan.
  • generate — renders in-process from tan.planner. Spawning the SDK's scripts/alp_project.py instead is an opt-in escape hatch behind TAN_GENERATE_EXECUTOR=subprocess.

There is no tan emit verb. The equivalent is tan generate --target <target>; see the tan CLI reference for the target catalogue.

Verify​

Once bootstrapped and with tan installed, confirm the host is build-ready, then build + run the GPIO example on native_sim:

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

alp-sdk's own contribution to that pipeline is inspectable without tan — it emits plans, it never builds:

PYTHONPATH=scripts python3 -m alp_orchestrate --input board.yaml --emit build-plan
PYTHONPATH=scripts python3 -m alp_orchestrate --input board.yaml --emit system-manifest

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

note
tan doctor now catches a mis-initialised workspace

tan doctor is a host-environment preflight — Python / west / CMake / Ninja / the Zephyr pin / the workspace venv / ZEPHYR_BASE. It infers the topdir from ZEPHYR_BASE's parent and checks a .west/ directory exists beside it.

As of v0.11.0 its west-workspace check goes further: it reads the workspace's [manifest] path out of .west/config and FAILs when the manifest repo isn't this alp-sdk checkout, naming #769 and telling you to re-bootstrap. Through v0.10.1 a bare .west/ directory was enough to PASS — which reported healthy on exactly the layout that leaves the west alp-* commands unknown. If the manifest path can't be read at all, the check WARNs rather than passing silently.

Install the alplabai.alp-sdk extension for:

  • Schema-aware board.yaml editing (autocomplete on SKUs, board presets, libraries, and the declarative 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 tan generate target set
  • 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/           # 80+ opt-in chip drivers (Tier 0 stable + the §D ecosystem set)
├── vendors/         # per-SoM HAL bindings (alif, renesas-rzv2n, nxp-imx93, deepx-dxm1)
├── metadata/        # schemas, templates, e1m_modules/<MPN>.yaml, boards/, socs/, libraries/, library-profiles/
├── scripts/         # board.yaml orchestrator, validators, soc_caps + ABI generators
├── alp.lock         # dependency lock (west alp-lock)
├── 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
└── west.yml         # the workspace manifest (pins Zephyr; registers west alp-*)

Next steps​

Questions about this page? Discuss in Community Forum