Development Workflow

Git workflow and development process for Redox OS

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

Recipe 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
   

System Components

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

1. Make your changes

   Edit the source files for the system component.

2. Update initfs

   See How to update initfs.

3. Rebuild

   make rebuild
   

Kernel/Core

For kernel and core system changes:

1. Clean previous builds

   make c.kernel
   
2. Make changes and rebuild

   make r.kernel
   
3. Update initfs if needed

   See How to update initfs.

Build System Commands

Basic Commands

Build Everything

make all

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

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

Porting a New Application

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
   

Fixing a Bug

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.

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