Skip to main content
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

1

Download the bootstrap script

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

Run the bootstrap script

time bash -e podman_bootstrap.sh
3

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

1

Check for duplicates

Search existing issues to avoid creating duplicates.
2

File the issue

Create your issue following the Filing Issues guidelines.
3

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

When making local changes to recipe sources:
1

Disable automatic updates

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

Make your changes

Edit the recipe source files as needed.
3

Build and test

make r.recipe-name

​
Build System Commands

​
Basic Commands

make all

​
Recipe Management

Find recipe for one or more targets:
make find.target-name
Fetch source or binary for a recipe:
make f.recipe-name
Fetch multiple recipes (comma-separated):
make f.recipe1,recipe2,recipe3
Build a specific recipe:
make r.recipe-name
Build multiple recipes:
make r.recipe1,recipe2,recipe3
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 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
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

1

Review your changes

Ensure your changes are complete and follow the Best Practices.
2

Format your code

cargo fmt
3

Test your changes

See the Testing Guide for comprehensive testing instructions.
4

Create the MR

Follow the Creating Proper Pull Requests guide.
5

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:
1

Linting Stage

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

Test Stage

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

​
Common Workflows

1

Check for existing recipe

make find.app-name
Always verify a recipe doesn’t already exist to avoid duplication.
2

Create recipe

See Application Porting.
3

Build and test

make r.new-recipe
1

Identify the component

Use the debug tools and documentation to locate the issue.
2

Make the fix

Edit the relevant source files.
3

Clean and rebuild

make cr.component-name
4

Test the fix

See the Testing Guide and Debugging Guide.
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

Build docs developers (and LLMs) love

Get started for freeTalk to us