Why another system builder?

rsdk is yet another evolution of Radxa's system builder. The primary goal is to move away from debos for following reasons:

1. (Previously) Lack of ARM64 support.
2. We use pagefile to workaround dkms build failure, which requires KVM to be available.
3. Go templates leave much to be desired.
4. Provided actions are becoming limiting to achieve our desired result.

Beyond those, our system has grown into 100+ repositories, interconnected by various CI/CD workflows. From an operational standpoint we also need a tool to centrally manage them, with the added bonus that customers can use the very same tool to reproduce our setup for their own use.

Finally, we want to have a short answer to the commonly asked question "where can I download the SDK for X". So far, our answer has always been a brief explanation of the system design, because of its complexity. We want to have something that matches customer's expectation more closely, where there is only a single entry to all related Radxa source code.

Thus, rsdk is born.

Run rsdk with Visual Studio Code & devcontainer

First, please install the required dependencies:

sudo apt-get update
sudo apt-get install git qemu-user-static binfmt-support

Then follow Visual Studio Code's documentation to:

1. Install Visual Studio Code
2. Setup devcontainer

Then clone the project with git:

git clone --recurse-submodules https://github.com/RadxaOS-SDK/rsdk.git

Open the project in Visual Studio Code. A notification will pop up on the corner asking if you want to reopen in devcontainer. Click yes and wait for the container to be set up.

This can be combined with VS Code remote development extension to run rsdk in other systems.

Common issues

1. devcontainer setup paused with You might be rate limited by GitHub. message

   You might be rate limited by GitHub. Please follow the instruction listed in the output.

2. Failed to launch devcontainer.

   Please edit .devcintainer/devcontainer.json, and adjust runArgs property.

Run rsdk with devcontainer alone

This is similar to how we build system images in the CI pipelines.

First, please install the required dependencies:

sudo apt-get update
sudo apt-get install git qemu-user-static binfmt-support
sudo apt-get install npm docker.io
sudo usermod -a -G docker $USER

If you were not in the docker group before, you will need to log out and log back in.

For SSH, simple disconnect the current session and reconnect.

Then clone the project with git and install devcontainer:

git clone --recurse-submodules https://github.com/RadxaOS-SDK/rsdk.git
cd rsdk
npm install @devcontainers/cli
export PATH="$PWD/src/bin:$PWD/node_modules/.bin:$PATH"
rsdk devcon up
rsdk devcon

You are now inside the rsdk's devcontainer shell.

Common issues

1. devcontainer setup paused with You might be rate limited by GitHub. message

   You might be rate limited by GitHub. Please follow the instruction listed in the output.

2. Failed to launch devcontainer.

   Please edit .devcintainer/devcontainer.json, and adjust runArgs property.

Run rsdk using released Debian package

To be released.

Run rsdk natively

To run rsdk natively, you will ideally need an Ubuntu system, as it is the base system used in Dev Container.

Please first install devenv on your system.

Optionally you can setup direnv, then run direnv allow within the project folder to enable it.

You can then run devenv shell to enter the development shell. This shell will manipulate your PATH to have the development dependency available.

If you have direnv setup, you don't have to run the above command when you enter the project directory to use the SDK. However, the direnv shell lacks starship integration as well as rsdk auto completion, as it only saves the environmental variables.

There are some additional system configurations and packages that are currently not managed by devenv. They are mostly covered by install_native_dependency function in rsdk-setup.

Basic usage

rsdk comes with bash-completion to assist its CLI usage.

After typing rsdk into your terminal, if there is no subcommand suggestion after you press Tab key twice, you should run rsdk shell to enter the development environment.

From there, you can use autocompletion to query the supported command list.

Running a command with --help argument will display its help text.

Use TUI to run guided tasks

rsdk command is the common CLI entry point.

When it is run without any argument, rsdk-tui will be run instead.

1. Start TUI Wizard by running rsdk in the terminal.

2. Select the task you want to run.
   You can use arrow key to navigate, use Enter key to select, and use Escape key to leave current window.
   In this example, we will choose Build system image:

┌─────────────────┤ RSDK ├──────────────────┐
│ Please select a task:                     │
│                                           │
│            Build system image             │
│            =========                      │
│            About                          │
│                                           │
│         <Ok>             <Cancel>         │
│                                           │
└───────────────────────────────────────────┘

3. Select the product you want to build.
   You can use the space bar to select the product, and the chosen product will have asterisk symbol placed in the parentheses.
   Enter key does not select the product when used alone!
   In this example, we will choose rock-5b-6_1:

┌─────────────────┤ RSDK ├──────────────────┐
│ Please select a product:                  │
│                                           │
│  ( ) radxa-e25                        ▒   │
│  (*) rock-5b-6_1                      ▒   │
│  ( ) rock-5b                          ▒   │
│                                           │
│         <Ok>             <Cancel>         │
│                                           │
└───────────────────────────────────────────┘

4. Select Yes to start the build process.
   rsdk-tui will then run the associated CLI commands to complete the task:

┌─────────────────┤ RSDK ├──────────────────┐
│                                           │
│ Are you sure to build for 'rock-5b-6_1'?  │
│                                           │
│                                           │
│          <Yes>             <No>           │
│                                           │
└───────────────────────────────────────────┘

Advanced build should use rsdk-build command instead.

Migrating from old toolchain

rbuild

rsdk build is the rbuild replacement. It uses the same argument ordering, and support similar input values.

When no suite or edition is supplied, rsdk build will use the value defined in src/share/rsdk/configs/products.json instead of bullseye cli.

Not all rbuild options are supported by rsdk build. Please check the command help for more details.

.rbuild-config file is now replaced by devenv.local.nix, and option names are adjusted. You can check devenv.local.nix.example for syntax.

rbuild json

This subcommand is replaced by configuration files under src/share/rsdk/configs.

rbuild shrink-image

This subcommand is no longer needed, as now image shrinking is no longer a root operation, and comes standard.

rbuild write-image

rsdk write-image is the rbuild write-image replacement. It uses the same argument ordering.

Build customization

rsdk uses devenv to manage its development envrionronment, but itself is not nix based. nix has good support generating NixOS images, but here we are dealing with a Debian system, and some parts are currently missing.

We currently uses bdebstrap, which is a YAML frontend for mmdebstrap. mmdebstrap is the recommended tool for building RISC-V systems compared to traditional debootstrap.

YAML itself is not a templating language, so it cannot dynamically generate different configurations for different builds. We use jsonnet for this purpose.

Lastly, mmdebstrap does not handle disk image generation. We again use jsonnet to dynamically generate a guestfish script to handle this task.

All of those tools are glued by bash to provide a frontend, known as rsdk-build.

Depending on your goal, you would need the knowledge of some of the above tools.

Rootfs customization

rootfs.jsonnet is the entry point for rootfs template. It collects the various inputs and passes them to different modules.

Module loading order matters, as that will determine *-hooks's execution order. The safest way is to only edit the customize-hooks field in rootfs.jsonnet and only adding new entries after the existing ones.

You can also edit the packages field in rootfs.jsonnet to add additional packages to the system. customize-hooks will be run after packages are installed in the rootfs.

Disk image customization

image.jsonnet is the template for the deployment script. It is generally not necessary to change this part.

rsdk

rsdk command is the common CLI entry point.

When it is run without any argument, it will run rsdk-tui instead.

Build RadxaOS image

When no suite or edition options is supplied, rsdk-build will use the product-specific default values, which are defined in src/share/rsdk/configs/products.json as the first element of the respective array.
Using ROCK 3C as an example, if you want to build a CLI image for RadxaOS Bullseye, you can run the following command:

rsdk build rock-3c bullseye cli

RadxaOS output path

you can find the generated RadxaOS image as out/${product}_${suite}_${edition}/output.img.

rsdk-shell

It is recommended to run rsdk shell first to set up the work environment before running other commands.
However, most commands should run without issue.
Some enhancements (for example, bash completion and shell prompt) may not be available outside of rsdk shell by default.