seL4 setup

seL4 Development Environment Setup Guide

Table of Contents

1. Overview
2. Prerequisites
3. Initial VM Access
4. Environment Setup
5. Clone and Build seL4
6. Testing
7. Multi-Platform Builds
8. Troubleshooting
9. Quick Reference

Overview

This guide will help you set up a complete seL4 development environment on both local machines (using WSL) and remote VMs. By the end, you'll be able to:

-Build the seL4 microkernel from source

-Run comprehensive test suites

-Test on multiple platforms (x86, ARM)

• Use QEMU for emulation and testing

Expected Time: 1-2 hours for first-time setup

Prerequisites

Required

Linux Environment: WSL2 (Windows), native Linux, or macOS

• VM Access: SSH key and credentials (provided by project lead)
• Internet Connection: For downloading packages and repositories
• Disk Space: At least 15GB free

Recommended

VS Code: With Remote-SSH and WSL extensions

• Git: Basic familiarity with version control
• Terminal: Basic command-line knowledge

Phase 1: Initial VM Access

Step 1.1: Test SSH Connection

Test connection to VM
ssh -i /path/to/your/private-key.pem username@VM_IP_ADDRESS

Expected Result:

• Login banner appears
• Shell prompt: username@hostname:~$

If Connection Fails:

• Verify VM IP address
• Check SSH key permissions: chmod 600 /path/to/key.pem
• Contact team lead for firewall/network issues
• Share your public IP: curl ifconfig.me

Step 1.2: Initial Environment Check

Once connected, verify the system:

# Check OS version  
cat /etc/os-release  
# Check available disk space  
df -h  
# Check memory  
free -h  
# Check current directory

pwd   
ls -la   
# Look for existing seL4 installations   
find \~ -name "sel4\*""-o -name "seL4\*" 2>/dev/null

What to verify:

• Ubuntu/Debian-based system (Ubuntu 20.04+ recommended)
• At least 10GB free disk space
• At least 4GB RAM
• Clean home directory

Phase 2: Environment Setup

Step 2.1: Update System Packages

Update package lists sudo apt update # Upgrade existing packages sudo apt upgrade -y

Step 2.2: Install Development Tools

Install essential build tools  
sudo apt install -y \  
build-essential \  
git \  
cmake \  
ninja-build \  
python3 \  
python3-pip \  
curl \  
wget \  
vim \  
nano \  
libxml2-utils \  
ncurses-dev \

device-tree-compiler \ u-boot-tools   
# Install QEMU emulators sudo apt install -y qemu-system-x86 qemu-system-arm qemu-system-misc   
# Install cross-compilation toolchains sudo apt install -y gcc-arm-linux-gnueabi g++arm-linux-gnueabi gcc-aarch64-linux-gnu g++aarch64-linux-gnu

Step 2.3: Install Python Dependencies

Install seL4-specific Python packages pip3 install --user --break-system-packages \ sel4-deps \ cmake \ ninja \ ply \ jinja2 \ jsonschema \ pyelftools

Step 2.4: Configure Git

Set your Git identity (use your actual details)  
git config --global user.email "your.email@organization.com"  
git config --global user.name "Your Name"

Verify configuration git config --global --list

Step 2.5: Install repo Tool

The repo tool manages multiple Git repositories:

Create binary directory  
mkdir -p ~/.bin  
# Download repo  
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/rep  
# Make executable  
chmod a+x ~/.bin/redo  
# Add to PATH  
echo 'export PATH="\${HOME}/.bin:${PATH}'' >> ~/.bashrc  
source ~/.bashrc  
# Verify installation  
repo version

Step 2.6: Create Verification Script

Save this script to check your setup:

# Create verification script
cat << 'EOF' > ~/verify_setup.sh
#!/bin/bash
echo ""
echo "seL4 Environment Verification"
echo ""
check_tool() {
if command -v $1 && /dev/null; then
    echo "$1: $(command -v $1)"
else
    echo "$1: NOT FOUND"
fi
}
echo -e "\n[Build Tools]"
check_tool git
check_tool cmake
check_tool ninja
check_tool gcc

check_tool python3   
check_tool repo   
echo -e "\n[QEMU Emulators]"   
check_tool qemu-system-x86_64   
check_tool qemu-system-arm   
echo -e "\n[Cross Compilers]"   
check_tool arm-linux-gnueabi-gcc   
check_tool aarch64-linux-gnu-gcc   
echo -e "\n[Python Packages]"   
python3 -c "import sel4deps" 2>/dev/null && echo " sel4-deps" || echo "s   
python3 -c "import jinja2" 2>/dev/null && echo "jinja2" || echo " jinja2"   
echo -e "\n[System Resources]"   
echo "Disk Space:"   
df -h / | tail -n 1   
echo "Memory:"   
free -h | grep Mem   
echo -e "\n==============   
echo "Verification Complete"   
echo "="   
EOF   
# Make executable and run   
chmod  $+\mathrm{x}\sim /$  verify_setup.sh   
./verify_setup.sh

Phase 3: Clone and Build seL4

Step 3.1: Create Project Directory

Create workspace  
mkdir -p ~/spar-project  
cd ~/spar-project

Step 3.2: Clone sel4test Repository

Create sel4test directory  
mkdir sel4test  
cd sel4test  
# Initialize repository  
repo init -u https://github.com/seL4/sel4test-manifest.git  
# Sync (downloads all source code - takes 2-5 minutes)  
repo sync  
# Verify directory structure  
ls -la

Expected directories:

kernel/ -seL4 kernel source  
projects/ -Test suite and libraries  
tools/ -Build tools  
init-build.sh -Build initialization script

Step 3.3: Build for x86 Platform (pc99)

Ensure you're in the sel4test directory  
cd ~/spar-project/sel4test  
# Initialize build for x86 simulation  
./init-build.sh -DPLATFORM=pc99 -DSIMULATION=TRUE  
# Build (takes 5-10 minutes on first run)  
ninja  
# Verify build success  
ls -la images/

Expected output file:

images/sel4test-driver-image-x86_64-pc99

Phase 4: Testing

Step 4.1: Run Tests in QEMU

Run simulation ./simulate

Expected output (at the end):

Test suite passed. 123 tests passed. 57 tests disabled. All is well in the universe

QEMU Controls:

• Exit: Press Ctrl+A, then press X
• Switch console: Ctrl+A, then C

Step 4.2: Manual QEMU Execution (Alternative)

Run QEMU manually if simulate script doesn't work qemu-system-x86_64 \  
-nographic \  
-m 512 \  
-kernel images/ Sel4test-driver-image-x86_64-pc99

Phase 5: Multi-Platform Builds

Step 5.1: Build for ARM (Sabre Platform)

cd \~/spar-project/sel4test   
#IMPORTANT: Complete clean before switching platforms rm -rf build.ninja .ninja\* CMakeCache.txt CMakeFiles/ staging/ # Or use git clean (removes ALL untracked files) git clean -xdf   
# Initialize for ARM ./init-build.sh -DPLATFORM=sabre -DSIMULATION  $\equiv$  TRUE

Build  
ninja  
# Test  
./simulate

Step 5.2: Other Supported Platforms

# x86 32-bit
./init-build.sh -DPLATFORM=pc99 -DARCH=ia32 -DSIMULATION=TRUE
# Raspberry Pi 3 (AArch64)
./init-build.sh -DPLATFORM=bcm2837 -DAARCH64=TRUE -DSIMULATION=TRUE
# Always clean between platform switches!
rm -rf build.ninja .ninja* CMakeCache.txt CMakeFiles/ staging/

Step 5.3: Separate Build Directories (Recommended)

For testing multiple platforms without cleaning:

cd \~/spar-project   
# Create separate directories   
mkdir sel4test-x86   
mkdir sel4test-arm   
# Clone into each   
cd sel4test-x86   
repo init -u https://github.com/seL4/sel4test-manifest.git   
repo sync   
./init-build.sh -DPLATFORM=pc99 -DSIMULATION  $\equiv$  TRUE   
ninja   
cd ./sel4test-arm   
repo init -u https://github.com/seL4/sel4test-manifest.git   
repo sync   
./init-build.sh -DPLATFORM=sabre -DSIMULATION  $\equiv$  TRUE   
ninja

Phase 6: Troubleshooting

Issue 1: SSH Connection Timeout

Problem: ssh: connect to host X.X.X.X port 22: Connection timed out

Solutions:

• Verify VM is running (contact team lead)
• Check your IP is whitelisted
• Verify you're on the correct network/VPN
• Test with: ping VM_IP_ADDRESS

Issue 2: Permission Denied (SSH)

Problem: Permission denied (publickey)

Solutions:

Fix key permissions  
chmod 600 /path/to/private-key.pem  
# Verify key is correct  
ssh -v -i /path/tokey.pem username@VM_IP

Issue 3: Toolchain Error When Switching Platforms

Problem: Config changes have resulted in a different toolchain file

Solution:

Complete clean required  
cd ~/spar-project/sel4test  
git clean -xdf  
# Then rebuild  
./init-build.sh -DPLATFORM=sabre -DSIMULATION=TRUE  
ninja

Issue 4: Build Fails with Missing Dependencies

Problem: ninja: error: 'xxx', needed by 'yyy', missing

Solutions:

Re-run repo sync   
repo sync   
# Clean and rebuild   
rm -rf build.ninja .ninja\* CMakeCache.txt CMakeFiles/ staging/ ./init-build.sh -DPLATFORM=pc99 -DSIMULATION  $\equiv$  TRUE ninja

Issue 5: No Space Left on Device

Problem: Build fails with disk space error

Solutions:

# Check disk usage  
df -h  
# Clean package cache  
sudo apt clean  
sudo apt autoremove  
# Remove old build artifacts  
cd ~/spar-project  
rm -rf sel4test/staging sel4test/build*

Issue 6: QEMU Doesn't Start

Problem: ./simulate fails or QEMU crashes

Solutions:

Verify QEMU installation  
which qemu-system-x86_64

Reinstall if missing sudo apt install -y qemu-system-x86 qemu-system-arm # Check image exists ls -la images/sel4test-driver-image\*

Issue 7: Python Import Errors

Problem: ModuleNotFoundError: No module named 'aenum'

Solution:

Install missing Python packages pip3 install --user aenum pyelftools orderedset # Verify installation python3 -c "import aenum; print('OK')"

Quick Reference

Essential Commands

Connect to VM  
ssh -i /path/to/key.pem username@VM_IP  
# Verify environment  
~/verify_setup.sh  
# Build x86  
cd ~/spar-project/sel4test  
./init-build.sh -DPLATFORM=pc99 -DSIMULATION=TRUE  
ninja  
./simulate  
# Build ARM  
rm -rf build.ninja .ninja* CMakeCache.txt CMakeFiles/ staging/  
./init-build.sh -DPLATFORM=sabre -DSIMULATION=TRUE  
ninja  
./simulate

# Clean build  
rm -rf build.ninja .ninja* CMakeCache.txt CMakeFiles/ staging/# OR complete clean:  
git clean -xdf  
# Exit QEMU  
Ctrl+A, then X  
# Exit VM  
exit

Important File Locations

~/spar-project/sel4test/  
kernel/ -seL4 kernel source  
src/ -Implementation  
include/ -Header files  
projects/  
sel4test/ -Test framework  
seL4_libs/ -Libraries  
tools/ -Build tools  
images/ -Build output  
init-build.sh -Build script

Platform Options

Platform	Command Flag	Architecture	Use Case
pc99	-DPLATFORM=pc99	x86_64	Standard PC
pc99(32-bit)	-DPLATFORM=pc99 -DARCH=ia32	x86	Legacy PC
sabre	-DPLATFORM=sabre	ARM Cortex-A	i.MX6 boards
bcm2837	-DPLATFORM=bcm2837 -DAARCH64=TRUE	AArch64	Raspberry Pi 3

Expected Build Times

Task	First Time	Subsequent
repo sync	2-5 min	30-60 sec
CMake configure	30-60 sec	10-20 sec
ninja build	5-10 min	1-2 min
QEMU test run	2-3 min	2-3 min

Note: Times vary based on system specifications and network speed.

Success Checklist

Before considering setup complete:

hat-; Can connect to VM via SSH   
hat-; All tools verified (ae" in verify_setup.sh)   
hat-; sel4test repository cloned   
hat-; x86 build successful   
hat-; All 123 tests pass in QEMU   
hat-; Understand clean build process   
hat-; Can switch between platforms   
hat-; Documentation reviewed

Next Steps

After successful setup:

1. Explore the code:

cd \~/spar-project/ Sel4test   
find kernel/src -name "*.c" | head -n 10   
cat projects/ Sel4test/apps/ sel4test-tests/src/tests/trivial.c

2. Read documentation:

Official docs: https://docs.sol4.systems/

• Tutorials: https://docssel4.systems/Tutorials/
  o API reference: https://docs.sol4.systems/APIDoc/

3. Try building a simple application:

Follow seL4 tutorials
Experiment with test modifications

4. Join the community:

• Discourse forum: https://sel4/discourse.group/
  o GitHub: https://github.com/seL4

Tips for Success

1. Always clean between platform switches

git clean -xdf # Most thorough

2. Use screen for long builds

screen -S build  
ninja  
# Ctrl+A, D to detach  
screen -r build # Reattach later

3. Save successful configurations

cp CMakeCache.txt CMakeCache.txt.backup

4. Document custom changes

• Keep notes of modifications
  Use Git branches for experiments

5. Stay updated

repo sync # Pull latest changes