Development Workflow

This guide covers the development workflow for contributing to Redox OS, including setting up the build system, making changes, and submitting merge requests.

Setting Up the Build System

Prerequisites

You need to have curl installed on your system.

Download and Bootstrap

Download the bootstrap script

curl -sf https://gitlab.redox-os.org/redox-os/redox/raw/master/podman_bootstrap.sh -o podman_bootstrap.sh

Run the bootstrap script

time bash -e podman_bootstrap.sh

Build default recipes

make all

If your operating system does not use SELinux, set USE_SELINUX=0:

make all USE_SELINUX=0

Git Workflow

Creating Issues

Check for duplicates

Search existing issues to avoid creating duplicates.

File the issue

Create your issue following the Filing Issues guidelines.

Share in chat

Post the issue link in the Dev or Support rooms of the chat. This ensures developers see your issue and prevents it from being forgotten.

Making Changes

Recipe Changes
System Components
Kernel/Core

When making local changes to recipe sources:

Disable automatic updates

For one or multiple recipes, see Local Recipe Changes.For all recipes, enable Cookbook Offline Mode.

Make your changes

Edit the recipe source files as needed.

Build and test

make r.recipe-name

Changes to system components, drivers, or RedoxFS require manual initfs updates:

Make your changes

Edit the source files for the system component.

Update initfs

See How to update initfs.

Rebuild

make rebuild

For kernel and core system changes:

Clean previous builds

make c.kernel

Make changes and rebuild

make r.kernel

Update initfs if needed

See How to update initfs.

Build System Commands

Basic Commands

make all

make rebuild

make live

make clean

make distclean

Recipe Management

Find Recipe

Find recipe for one or more targets:

make find.target-name

Fetch Recipe

Fetch source or binary for a recipe:

make f.recipe-name

Fetch multiple recipes (comma-separated):

make f.recipe1,recipe2,recipe3

Cook (Build) Recipe

Build a specific recipe:

make r.recipe-name

Build multiple recipes:

make r.recipe1,recipe2,recipe3

Clean Recipe

Clean a specific recipe:

make c.recipe-name

Clean multiple recipes:

make c.recipe1,recipe2,recipe3

Special case for relibc (cleans both recipe and sysroot):

make c.relibc

Push Recipe

Push compiled package into existing image:

DO NOT RUN THIS WHILE QEMU IS RUNNING - the disk might corrupt.

make p.recipe-name

Push with package dependencies:

make pp.recipe-name

Combined Commands

Clean and rebuild:

make cr.recipe-name

Unfetch, clean, and rebuild:

make ucr.recipe-name

Clean, rebuild, and push:

make crp.recipe-name

View Recipe Trees

# List all recipes in cook-tree fashion
make repo-tree

# List all recipes in push-tree fashion
make image-tree

# Show what to cook for a specific recipe
make rt.recipe-name

# Show what to push for a specific recipe
make pt.recipe-name

# Show what to push with dependencies
make ppt.recipe-name

Updating Your Fork

# Pull latest changes
git pull

# Remove fstools tag to rebuild if needed
rm -f $(FSTOOLS_TAG)

# Or use the make target
make pull

Code Style

Rust Formatting

Run rustfmt on your changes before committing:

cargo fmt

The CI system will check formatting automatically. You can test locally:

cargo fmt -- --check

Creating Merge Requests

Review your changes

Ensure your changes are complete and follow the Best Practices.

Format your code

cargo fmt

Test your changes

See the Testing Guide for comprehensive testing instructions.

Create the MR

Follow the Creating Proper Pull Requests guide.

Share in MRs room

Post your MR link in the MRs Matrix room to ensure it gets reviewed.

For quick reviews: Keep MRs small and focused. If you have a large MR taking too long to review, try splitting it into smaller ones (but ensure nothing breaks).

Development Environment

Setting Up the Environment

Enter a development environment with proper paths:

make env

This sets up the PATH with the prefix toolchain and opens a bash shell.

View Environment Variables

make setenv

This displays the current build configuration variables:

ARCH - Target architecture
BOARD - Target board
CONFIG_NAME - Configuration name
BUILD - Build directory

Visual Studio Code Configuration

For VS Code setup, see Visual Studio Code Configuration.

Configuration Files

Redox uses TOML configuration files for different build targets:

config/x86_64/desktop.toml - Desktop configuration
config/x86_64/server.toml - Server configuration
config/x86_64/demo.toml - Demo configuration
config/tests.toml - Testing configuration

Switch configurations using:

make all CONFIG_NAME=desktop

Continuous Integration

The CI system automatically runs on merge requests targeting master:

Linting Stage

rustfmt: Checks code formatting
cargo-test: Runs unit tests

Test Stage

img: Builds system images
pkg: Tests packaging for multiple architectures (x86_64, i586, aarch64, riscv64gc)

Common Workflows

Porting a New Application

Check for existing recipe

make find.app-name

Always verify a recipe doesn’t already exist to avoid duplication.

Create recipe

See Application Porting.

Build and test

make r.new-recipe

Fixing a Bug

Identify the component

Use the debug tools and documentation to locate the issue.

Make the fix

Edit the relevant source files.

Clean and rebuild

make cr.component-name

Test the fix

See the Testing Guide and Debugging Guide.

Iterative Development

For rapid iteration on a single component:

# Make changes, then:
make cr.component && make qemu

# Or push to running image (requires mounting):
make rp.component

Getting Help

If you encounter issues during development:

Developer FAQ

Common questions and solutions

Chat Rooms

Ask in Matrix or Discord

File an Issue

Report bugs or ask for help

Build System Reference

Complete build system documentation

Next Steps

Debugging Guide

Learn how to debug Redox OS

Testing Guide

Learn how to test your changes

Get Started

Build System

Architecture

Components

Development

Hardware

Development Workflow

Setting Up the Build System

Prerequisites

Download and Bootstrap

Git Workflow

Creating Issues

Making Changes

Build System Commands

Basic Commands

Recipe Management

View Recipe Trees

Updating Your Fork

Code Style

Rust Formatting

Creating Merge Requests

Development Environment

Setting Up the Environment

View Environment Variables

Visual Studio Code Configuration

Configuration Files

Continuous Integration

Common Workflows

Getting Help

Developer FAQ

Chat Rooms

File an Issue

Build System Reference

Next Steps

Debugging Guide

Testing Guide

​Setting Up the Build System

​Prerequisites

​Download and Bootstrap

​Git Workflow

​Creating Issues

​Making Changes

​Build System Commands

​Basic Commands

​Recipe Management

​View Recipe Trees

​Updating Your Fork

​Code Style

​Rust Formatting

​Creating Merge Requests

​Development Environment

​Setting Up the Environment

​View Environment Variables

​Visual Studio Code Configuration

​Configuration Files

​Continuous Integration

​Common Workflows

​Getting Help

Developer FAQ

Chat Rooms

File an Issue

Build System Reference

​Next Steps

Debugging Guide

Testing Guide

Setting Up the Build System

Prerequisites

Download and Bootstrap

Git Workflow

Creating Issues

Making Changes

Build System Commands

Basic Commands

Recipe Management

View Recipe Trees

Updating Your Fork

Code Style

Rust Formatting

Creating Merge Requests

Development Environment

Setting Up the Environment

View Environment Variables

Visual Studio Code Configuration

Configuration Files

Continuous Integration

Common Workflows

Getting Help

Next Steps