Setup Arch Linux RISC V Development Environment

This documentation aims to help you set up an Arch Linux RISC-V (riscv64gc) development environment powered by usermode QEMU and systemd-nspawn.

Currently, the documentation contains instructions for Arch Linux, Debian and Ubuntu.

If you are using a native RISC-V board, you should skip these steps, and scroll down to the bottom of this page. The following instruction is for x86_64, etc. users.

0. CAUTION

We (distro packagers) decided to modify GCC spec to get rid of just way too many atomic symbol missing error. AFAIK debian does the same thing in the same way.

So, you may notice that some program compiles without -latomic flag, but that's not the case if you switch to some other distros. I wrote another blog post explaining this in detail.

In short: For GCC you should add -latomic if you use std::atomic<T> where sizeof(T) is lower than 4. Also apply to those __atomic_compare_exchange_2() stuff. Clang is not affected.

This is resolved by the GCC upstream in version 13 or higher.

1. Prepare the Container

1.1 Install Packages

If you are using Ubuntu/Debian as the host OS, skip to "For Debian and Ubuntu".

For Arch Linux

Add [archlinuxcn] Repo Source

We need to install some packages from [archlinuxcn] later.

Append these two lines to /etc/pacman.conf:

[archlinuxcn]
Server = https://repo.archlinuxcn.org/$arch

There is also a list of public mirrors available.

After doing so, you need to trust the archlinuxcn maintainers' PGP keys to install packages from it:

$ sudo pacman -Sy && sudo pacman -S archlinuxcn-keyring

Install Packages

$ sudo pacman -S qemu-user-static qemu-user-static-binfmt

where qemu-user-static-binfmt is for registering QEMU interpreter to execute RISC-V ELF files. Other necessary packages like zstd and systemd-nspawn are listed in the dependency tree of base meta package, so they will also be installed by the provided command, hence there's no need to install them explicitly.

For Debian and Ubuntu

$ sudo apt install zstd qemu-user-static systemd-container

where zstd is for decompressing the Arch Linux RISC-V rootfs compressed tarball, and systemd-container is for the systemd-nspawn command, which we'll use later to spawn a container from the rootfs.

1.2 Download rootfs

$ curl -O https://archriscv.felixc.at/images/archriscv-20220727.tar.zst

If you have poor connectivity upon reaching archriscv.felixc.at, you can also download the rootfs from mirror sites. They are listed at https://archriscv.felixc.at/.

root user's password is sifive, but probably you don't need it if you are creating a container with this rootfs to chroot into it later.

1.3 Decompress rootfs

Arch Linux

$ mkdir archriscv
$ sudo bsdtar -xf archriscv-20220727.tar.zst -C archriscv

Debian and Ubuntu

$ mkdir archriscv
$ sudo tar -I zstd -xf archriscv-20220727.tar.zst -C archriscv

tar may spit out some warnings, which turn out to be harmless and we can safely ignore them.

2. Start and Setup a Container

$ sudo systemd-nspawn -D ./archriscv -a -U

where -D provides the root directory for the container, -a for preventing processes with PID 1 from not reaping zombie children, -U for preventing processes in container from using the same UID range as those used outside the container.

2.1 Check Architecture

# uname -m
riscv64

2.2 System Upgrade

# pacman -Syu

2.3 (Optional) Install Packages

For example, if you want to install vim:

# pacman -S vim

2.4 (Optional) Set Default Editor

# echo 'export EDITOR=vim' >> ~/.bashrc && source ~/.bashrc

2.5 (Optional) Create a Regular User for Development

# useradd -m <username>

where -m means to create a home directory for the user to be added.

Use visudo if you'd like to grant sudo privilege for this user, and append this line under ## User privilege specification:

<username> ALL=(ALL) NOPASSWD: ALL

2.6 (Optional) Switch to a Regular User

# exec su username
$ cd ~
$ pwd
/home/<username>
$ echo 'export EDITOR=vim' >> ~/.bashrc && source ~/.bashrc

3. Compile and Run a Program

This guide is about compile & run a program manually. If you want to start your development from a git repo or so, jump to 3.2 Compile for instructions on how to install git and other packages needed by your toolchain. If you are trying to create or modify an Arch Linux package (i.e. dealing with a PKGBUILD), you may refer to related ArchWiki pages.

3.1 Coding

Run vim hello.c and type:

#include <stdio.h>

int main(int argc, char *argv[]) {
    printf("Hello RISC-V!\n");
    return 0;
}

Exit with esc and :wqEnter, as this S/O answer suggested :-P

3.2 Compilation

First of all, update your local packages repo data from remote package sources (like sudo apt-get update):

$ sudo pacman -Sy

You should run this prior to any attempt to install a package, unless you are sure that your local copy of package info is up-to-date.

Then, install your development toolchain:

$ sudo pacman -S gcc cmake foo bar bah

Compile your code:

$ gcc -o hello hello.c

3.3 Checking for File Format

$ file hello
hello: ELF 64-bit LSB pie executable, UCB RISC-V, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-riscv64-lp64d.so.1, BuildID[sha1]=4a75c57e4e99654dca0d6dc91689dffbbe7dc581, for GNU/Linux 4.15.0, not stripped

3.4 Running the Program

$ ./hello
Hello RISC-V!

---

For native RISC-V board users:

Edit your /etc/pacman.conf with the following settings:

[core]
Server = https://archriscv.felixc.at/repo/$repo

[extra]
Server = https://archriscv.felixc.at/repo/$repo

[community]
Server = https://archriscv.felixc.at/repo/$repo

[unsupported]
Server = https://archriscv.felixc.at/repo/$repo

Finally, add the packager's public key to your keyring:

$ pacman-key --recv-keys "B5971F2C5C10A9A08C60030F786C63F330D7CB92"  # Always grab the latest key ID from https://archlinux.org/people/developers/#felixonmars