Skip to content

docs(dragon/q6a): add rsdk-image container as second environment setup method #1795

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Milir-Radxa merged 2 commits into from
Jun 4, 2026
Merged

docs(dragon/q6a): add rsdk-image container as second environment setup method #1795

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c2ac84f
docs(dragon/q6a): add rsdk-image container as second environment setu…
tangzz-radxa Jun 3, 2026
7cd9008
docs(dragon/q6a): flatten TabItem content to bullets to avoid TOC dup…
tangzz-radxa Jun 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 122 additions & 31 deletions docs/common/radxa-os/build-system/_radxa_os.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,60 +2,145 @@ import { Image } from "@site/src/utils/docs";

## 使用前提

我们需要提前将 Visual Studio Code 和 Docker 环境搭建好，然后使用 Dev Container 来运行 RadxaOS SDK（rsdk）的编译环境。
Radxa OS 的开发环境提供两种搭建方式：**方式一**基于 Dev Container（推荐用于二次开发），**方式二**基于 `rsdk-image` 预制容器（推荐用于纯构建）。两种方式最终使用相同的 `rsdk` 工具来编译 Radxa OS，可以按需选择。

:::info 参考教程

可以按照下方教程完成 RadxaOS SDK（rsdk）开发的环境搭建。
可以按照下方教程完成 Docker / Visual Studio Code / Dev Containers 等基础组件的安装。

- [环境搭建](./install-env)
:::

## 下载 rsdk 源码
- 硬件准备：x86_64 架构的 PC
- 通用依赖：Docker
- 方式一额外需要：Visual Studio Code + Dev Containers 扩展插件
- 方式二额外需要：apt 可用、能访问 Radxa 的 `radxa-deb` 软件源

使用 `git clone` 命令克隆 RadxaOS SDK（rsdk）源码。
## 选择环境搭建方式

<NewCodeBlock tip="Linux-Host$" type="host">
<Tabs queryString="setup-method">
<TabItem value="devcontainer" label="方式一：DevContainer">

```bash
git clone --recurse-submodules <git_repo_url>
```
- **下载 rsdk 源码**

</NewCodeBlock>
使用 `git clone` 命令克隆 RadxaOS SDK（rsdk）源码。

其中 `<git_repo_url>` 需要替换成：{props.git_url}
<NewCodeBlock tip="Linux-Host$" type="host">

## 启动开发环境
```bash
git clone --recurse-submodules <git_repo_url>
```

使用 Visual Studio Code 打开 Radxa OS SDK（rsdk）源码目录：一般 `Dev Container` 拓展会自动识别文件夹下的配置文件，会提示你是否重新打开容器开发环境。
</NewCodeBlock>

:::tip
首次启动开发环境时，Dev Containers 会自动下载并安装依赖，需要耐心等待一段时间。
:::
其中 `<git_repo_url>` 需要替换成：{props.git_url}

- **启动开发环境**

使用 Visual Studio Code 打开 Radxa OS SDK（rsdk）源码目录：一般 `Dev Container` 拓展会自动识别文件夹下的配置文件，会提示你是否重新打开容器开发环境。

:::tip
首次启动开发环境时，Dev Containers 会自动下载并安装依赖，需要耐心等待一段时间。
:::

①：点击左下角的 `Remote` 选项

②：选择 `Reopen in Container` 选项

<div style={{ textAlign: "center" }}>
<img
src="/img/common/radxa-os/low-level-dev/vscode-dev-container-reopen.webp"
style={{ width: "100%", maxWidth: "1200px" }}
/>
</div>

等待容器自动连接和初始化环境，可以点击右下角选择在终端显示日志。

<div style={{ textAlign: "center" }}>
<img
src="/img/common/radxa-os/low-level-dev/vscode-dev-container-log.webp"
style={{ width: "100%", maxWidth: "1200px" }}
/>
</div>

</TabItem>
<TabItem value="rsdk-image" label="方式二：rsdk-image 容器">

- **关于 rsdk-image**

`rsdk-image` 是 Radxa 官方提供的预制 Docker 镜像，内置了 `rsdk` 命令行工具，无需在本地安装 Nix 或自行构建 deb 包即可快速使用 `rsdk`。该方式**不需要** Visual Studio Code 和 Dev Containers，仅依赖 Docker 与 Radxa 的 `radxa-deb` 软件源，适合只需要构建系统镜像、不打算修改 rsdk 本身的用户。

- **安装 rsdk-image**

- **方式 A：通过 apt 源安装**

添加 Radxa `radxa-deb` 软件源（`rsdk-image` 当前发布在 testing 源中）：

<NewCodeBlock tip="Linux@host$" type="host">

①：点击左下角的 `Remote` 选项
```bash
sudo tee /etc/apt/sources.list.d/70-radxa.list <<< "deb [trusted=yes] https://mirrors.hust.edu.cn/radxa-deb/rsdk-test/ rsdk-test main"
sudo apt update
```

②：选择 `Reopen in Container` 选项
</NewCodeBlock>

<div style={{ textAlign: "center" }}>
<img
src="/img/common/radxa-os/low-level-dev/vscode-dev-container-reopen.webp"
style={{ width: "100%", maxWidth: "1200px" }}
/>
</div>
安装 `rsdk-image` deb 包：

等待容器自动连接和初始化环境，可以点击右下角选择在终端显示日志。
<NewCodeBlock tip="Linux@host$" type="host">

<div style={{ textAlign: "center" }}>
<img
src="/img/common/radxa-os/low-level-dev/vscode-dev-container-log.webp"
style={{ width: "100%", maxWidth: "1200px" }}
/>
</div>
```bash
sudo apt install rsdk-image
```

</NewCodeBlock>

- **方式 B：手动下载 deb 安装**

访问 [`radxa-pkg/rsdk-image` Releases](https://github.com/radxa-pkg/rsdk-image/releases) 下载最新的 `rsdk-image_*_amd64.deb`，然后本地安装：

<NewCodeBlock tip="Linux@host$" type="host">

```bash
sudo apt install ./rsdk-image_*_amd64.deb
```

</NewCodeBlock>

- **运行 rsdk-image**

使用 `rsdk-image` 命令启动一个预配置好的容器环境：

<NewCodeBlock tip="Linux@host$" type="host">

```bash
rsdk-image --name rsdk
```

</NewCodeBlock>

- `--name` 参数为容器名称，可以自定义。
- 如果容器已经存在，会直接进入容器；如果需要重建容器，请先执行 `docker rm -f rsdk` 删除旧容器。
- 也可以传入需要执行的命令：`rsdk-image --name rsdk -- <command>`。

进入容器后，使用方式一中克隆的 rsdk 源码，或在容器内重新克隆：

<NewCodeBlock tip="Linux@host$" type="host">

```bash
git clone --recurse-submodules <git_repo_url>
```

</NewCodeBlock>

其中 `<git_repo_url>` 需要替换成：{props.git_url}

</TabItem>
</Tabs>

## 编译 Radxa OS

启动开发环境后，使用 `rsdk` 命令运行 TUI 界面。
完成环境搭建后，使用 `rsdk` 命令运行 TUI 界面：

<NewCodeBlock tip="Linux-Host$" type="host">

Expand Down Expand Up @@ -109,3 +194,9 @@ rsdk
:::info 瑞莎 Cubie A7A / A7Z / A7S 构建系统选项
选择 `Build system image` 后，在主板型号列表中选择 `radxa-a733` 选项。
:::

## 常见问题

- 构建过程中如遇 `rm: cannot remove ... rootfs/boot/efi: Device or resource busy`，说明 `out/<board>/rootfs/boot/efi` 被挂载，请先执行 `sudo umount -l out/<board>/rootfs/boot/efi` 卸载后再删除 `out` 目录下的构建产物。
- 方式一相关：Dev Container 设置暂停并提示 `You might be rate limited by GitHub`；启动开发容器失败时可编辑 `.devcontainer/devcontainer.json` 调整 `runArgs`。
- 方式二相关：`rsdk-image` 容器无法启动时，先执行 `docker rm -f rsdk` 删除旧容器再重试。
155 changes: 123 additions & 32 deletions ...cusaurus-plugin-content-docs/current/common/radxa-os/build-system/_radxa_os.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,61 +2,146 @@ import { Image } from "@site/src/utils/docs";

## Prerequisites

You need to have Visual Studio Code and Docker environment set up in advance, then use Dev Container to run the RadxaOS SDK (rsdk) compilation environment.
Radxa OS development environment offers two setup methods: **Method 1** is based on Dev Container (recommended for secondary development), and **Method 2** is based on the `rsdk-image` prebuilt container (recommended for build-only use). Both methods use the same `rsdk` tool to compile Radxa OS. Choose the one that fits your needs.

:::info Reference Tutorial

You can follow the tutorial below to complete the environment setup for RadxaOS SDK (rsdk) development.
You can follow the tutorial below to install Docker / Visual Studio Code / Dev Containers and other base components.

- [Environment Setup](./install-env)
:::

## Download rsdk Source Code
- Hardware: x86_64 PC
- Common dependencies: Docker
- Method 1 additional requirements: Visual Studio Code + Dev Containers extension
- Method 2 additional requirements: `apt` available, and network access to the Radxa `radxa-deb` repository

Use the `git clone` command to clone the RadxaOS SDK (rsdk) source code.
## Choose Your Setup Method

<NewCodeBlock tip="Linux@host$" type="host">
<Tabs queryString="setup-method">
<TabItem value="devcontainer" label="Method 1: DevContainer">

```bash
git clone --recurse-submodules <git_repo_url>
```
- **Download rsdk source code**

</NewCodeBlock>
Use the `git clone` command to clone the RadxaOS SDK (rsdk) source code.

Replace `<git_repo_url>` with: {props.git_url}
<NewCodeBlock tip="Linux@host$" type="host">

## Start Development Environment
```bash
git clone --recurse-submodules <git_repo_url>
```

Open the Radxa OS SDK (rsdk) source code directory with Visual Studio Code: The `Dev Container` extension will usually automatically detect the configuration file in the folder and prompt you to reopen in the container development environment.
</NewCodeBlock>

:::tip
When starting the development environment for the first time, Dev Containers will automatically download and install dependencies. Please be patient as this may take some time.
:::
Replace `<git_repo_url>` with: {props.git_url}

- **Start development environment**

Open the Radxa OS SDK (rsdk) source code directory with Visual Studio Code: The `Dev Container` extension will usually automatically detect the configuration file in the folder and prompt you to reopen in the container development environment.

:::tip
When starting the development environment for the first time, Dev Containers will automatically download and install dependencies. Please be patient as this may take some time.
:::

1. Click the `Remote` option in the bottom-left corner
2. Select the `Reopen in Container` option

<div style={{ textAlign: "center" }}>
<img
src="/en/img/common/radxa-os/low-level-dev/vscode-dev-container-reopen.webp"
style={{ width: "100%", maxWidth: "1200px" }}
/>
</div>

Wait for the container to automatically connect and initialize the environment. You can click the bottom right corner to select to display logs in the terminal.

<div style={{ textAlign: "center" }}>
<img
src="/en/img/common/radxa-os/low-level-dev/vscode-dev-container-log.webp"
style={{ width: "100%", maxWidth: "1200px" }}
/>
</div>

</TabItem>
<TabItem value="rsdk-image" label="Method 2: rsdk-image Container">

- **About rsdk-image**

`rsdk-image` is a prebuilt Docker image provided by Radxa. It comes with the `rsdk` command-line tool pre-installed, so you do not need to install Nix or build the deb package locally. This method **does not require** Visual Studio Code or Dev Containers; it only depends on Docker and access to the Radxa `radxa-deb` repository. It is suitable for users who only need to build system images and do not plan to modify `rsdk` itself.

- **Install rsdk-image**

- **Option A: Install via apt repository**

Add the Radxa `radxa-deb` repository (`rsdk-image` is currently published in the testing repository):

<NewCodeBlock tip="Linux@host$" type="host">

```bash
sudo tee /etc/apt/sources.list.d/70-radxa.list <<< "deb [trusted=yes] https://mirrors.hust.edu.cn/radxa-deb/rsdk-test/ rsdk-test main"
sudo apt update
```

1. Click the `Remote` option in the bottom-left corner
2. Select the `Reopen in Container` option
</NewCodeBlock>

<div style={{ textAlign: "center" }}>
<img
src="/en/img/common/radxa-os/low-level-dev/vscode-dev-container-reopen.webp"
style={{ width: "100%", maxWidth: "1200px" }}
/>
</div>
Install the `rsdk-image` deb package:

Wait for the container to automatically connect and initialize the environment. You can click the bottom right corner to select to display logs in the terminal.
<NewCodeBlock tip="Linux@host$" type="host">

<div style={{ textAlign: "center" }}>
<img
src="/en/img/common/radxa-os/low-level-dev/vscode-dev-container-log.webp"
style={{ width: "100%", maxWidth: "1200px" }}
/>
</div>
```bash
sudo apt install rsdk-image
```

</NewCodeBlock>

- **Option B: Install via manual deb download**

Visit [`radxa-pkg/rsdk-image` Releases](https://github.com/radxa-pkg/rsdk-image/releases) to download the latest `rsdk-image_*_amd64.deb`, then install it locally:

<NewCodeBlock tip="Linux@host$" type="host">

```bash
sudo apt install ./rsdk-image_*_amd64.deb
```

</NewCodeBlock>

- **Run rsdk-image**

Use the `rsdk-image` command to launch a preconfigured container environment:

<NewCodeBlock tip="Linux@host$" type="host">

```bash
rsdk-image --name rsdk
```

</NewCodeBlock>

- The `--name` parameter specifies the container name and can be customized.
- If the container already exists, you will enter it directly. To rebuild the container, first run `docker rm -f rsdk` to remove the existing one.
- You can also pass a command to execute inside the container: `rsdk-image --name rsdk -- <command>`.

After entering the container, use the rsdk source cloned in Method 1, or clone it again inside the container:

<NewCodeBlock tip="Linux@host$" type="host">

```bash
git clone --recurse-submodules <git_repo_url>
```

</NewCodeBlock>

Replace `<git_repo_url>` with: {props.git_url}

</TabItem>
</Tabs>

## Compile Radxa OS

After starting the development environment, use the `rsdk` command to run the TUI interface.
After completing the environment setup, use the `rsdk` command to run the TUI interface:

<NewCodeBlock tip="PC@host$" type="host">
<NewCodeBlock tip="Linux@host$" type="host">

```bash
rsdk
Expand Down Expand Up @@ -108,3 +193,9 @@ After compilation is complete, a folder corresponding to the board model and sys
:::info Radxa Cubie A7A / A7Z / A7S Build System Options
After selecting `Build system image`, choose the `radxa-a733` option from the board model list.
:::

## FAQ

- During the build, if you encounter `rm: cannot remove ... rootfs/boot/efi: Device or resource busy`, it means `out/<board>/rootfs/boot/efi` is mounted. Run `sudo umount -l out/<board>/rootfs/boot/efi` to unmount it before removing the build artifacts in the `out` directory.
- Method 1 related: Dev Container setup paused with the message `You might be rate limited by GitHub`; if the development container fails to start, edit `.devcontainer/devcontainer.json` and adjust `runArgs`.
- Method 2 related: if the `rsdk-image` container fails to start, run `docker rm -f rsdk` to remove the existing container and try again.
Loading