Getting Started

Get up and running with the Sol3 SDK in 10 minutes. In this guide we will:

  • Configure a local development environment

  • Build and run tests locally

  • Build an example application for local development (x64)

  • Build an example application image for remote deployment (arm64)

  • Deploy and run an example application to an HDK

1. Initial One-Time Setup

See also

System Requirements - Before starting, ensure you have Docker and the devcontainer CLI installed. See System Requirements for setup instructions.

SSH Setup - Most SDK workflows require SSH access to the HDK. See SSH Setup for HDK to configure network and passwordless SSH access.

These steps assume the following ENV variables have been set in your local environment:

  1. GITHUB_USERNAME: The username of the GitHub account with access to the sol3-sdk.

  2. GITHUB_PAT: Your GitHub Personal Access Token.

# Ensure that you're logged in to the sol3_sdk github container registry.
echo $GITHUB_PAT | docker login ghcr.io/space-ng/sol3-sdk -u $GITHUB_USERNAME --password-stdin

# Ensure QEMU binaries are installed and registered with binfmt_misc
docker run --privileged --rm tonistiigi/binfmt --install all

2. Build Locally

Clone the repo, start the devcontainer, and build locally.

# Clone the SDK, bootstrap a new project.
git clone git@github.com:space-ng/sol3-sdk.git sol3-sdk
./sol3-sdk/scripts/sol3_new_project my-project
cd my-project

# Start development container and enter interactive shell.
# The first time you run this may take some time.
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash

# Inside devcontainer: install the x64 sysroot (one-time), then
# configure, build, test, and run the example.
sol3_setup_sysroot x64
cmake --preset x64
cmake --build --preset x64
ctest --preset x64
sol3_activate_sysroot x64 ./out/build/x64/bin/example_app

Note

sol3_setup_sysroot x64 populates /opt/sysroots/x64, which the x64 toolchain requires; the devcontainer does not ship it pre-populated. Run it once per devcontainer. ctest --preset x64 applies the sysroot environment automatically; only direct binary runs need sol3_activate_sysroot.

3. Deploy Containerized Application to Hardware

Now that the build is working on your machine, build a deployable application image and deploy it to the HDK unit:

# Build ARM64 application image
sol3_build_app_image example_app arm64 --cmake-preset arm64

# Deploy to HDK (requires SSH setup - see SSH Setup guide)
sol3_deploy_app_image example-app-arm64:latest sol3-hdk

# SSH to HDK and run the application
ssh sol3-hdk
docker run --rm -v /run/sol3:/run/sol3 -v /dev:/dev --privileged localhost:5000/example-app-arm64:latest