Recipe System Guide

Overview

The Redox OS recipe system, called Cookbook, is a package management and build system that handles compilation, installation, and dependency resolution for all userspace software. It’s similar to ports systems on BSD or package build systems like Gentoo’s Portage.

What is a Recipe?

A recipe is a specification for building and installing a software package. Each recipe contains:

Source

Where to fetch the source code (Git, tarball, etc.)

Dependencies

Build and runtime dependencies on other recipes

Build Instructions

How to configure, compile, and install the software

Patches

Modifications needed for Redox OS compatibility

Recipe Location

Recipes are stored in the recipes/ directory with this structure:

recipes/
├── core/              # Core system components
│   ├── kernel/       # Kernel recipe
│   ├── relibc/       # C library recipe
│   └── ...
├── drivers/          # Device drivers
├── gnu/              # GNU utilities
├── games/            # Games and entertainment
├── other/            # Third-party software
└── wip/              # Work in progress recipes

Recipe Structure

Each recipe is a directory containing:

recipes/other/nano/
├── recipe.toml       # Recipe definition (required)
├── source/           # Downloaded source code
├── target/           # Build artifacts
│   └── $(TARGET)/
│       ├── build/    # Build directory
│       ├── stage/    # Installation staging
│       └── sysroot/  # Dependencies
└── *.patch           # Patch files (optional)

Recipe Definition (recipe.toml)

The recipe.toml file defines how to build a package:

Basic Recipe Example

recipes/other/nano/recipe.toml

[source]
git = "https://git.savannah.gnu.org/git/nano.git"
rev = "v7.2"

[build]
template = "configure"
script = """
autoreconf -fi
./configure --host=${TARGET} --prefix=/usr
make -j${MAKE_JOBS}
"""

[build.dependencies]
ncurses = {}

Recipe Sections

[source]
[build]
[package]

Defines where to get the source code:

# Git repository
[source]
git = "https://github.com/redox-os/relibc.git"
branch = "master"

# Or specific revision
[source]
git = "https://github.com/user/project.git"
rev = "abc123def456"

# Tarball
[source]
tar = "https://example.com/package-1.2.3.tar.gz"
blake3 = "sha256hash..."

# Multiple Git sources
[source]
git = [
    { name = "main", url = "https://github.com/user/main.git", rev = "v1.0" },
    { name = "submodule", url = "https://github.com/user/sub.git", rev = "v0.5" }
]

Build instructions and template:

[build]
# Use a predefined build template
template = "configure"  # or "cargo", "custom", "make", "cmake"

# Custom build script
script = """
export CC=${TARGET}-gcc
./configure --host=${TARGET} --prefix=/usr
make -j${MAKE_JOBS}
make DESTDIR=${COOKBOOK_SYSROOT} install
"""

# Build dependencies
[build.dependencies]
gcc = {}
make = {}
pkgconf = {}

# Package runtime dependencies  
[build.dependencies.runtime]
relibc = {}

Package metadata:

[package]
name = "nano"
version = "7.2"
description = "Text editor"

[package.dependencies]
ncurses = {}
relibc = {}

Build Templates

Cookbook provides templates for common build systems:

Configure Template

For autotools-based projects:

[build]
template = "configure"
script = """
autoreconf -fi
./configure \
    --host=${TARGET} \
    --prefix=/usr \
    --disable-shared \
    --enable-static
make -j${MAKE_JOBS}
make DESTDIR=${COOKBOOK_SYSROOT} install
"""

Cargo Template

For Rust projects:

[build]
template = "cargo"

# Cookbook automatically runs:
# cargo build --release --target=${TARGET}

CMake Template

For CMake-based projects:

[build]
template = "cmake"
script = """
mkdir build && cd build
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=${COOKBOOK_ROOT}/cmake/${TARGET}.cmake \
    -DCMAKE_INSTALL_PREFIX=/usr
make -j${MAKE_JOBS}
make DESTDIR=${COOKBOOK_SYSROOT} install
"""

Custom Template

For unique build systems:

[build]
template = "custom"
script = """
# Your custom build commands
python3 setup.py build
python3 setup.py install --root=${COOKBOOK_SYSROOT} --prefix=/usr
"""

Build Variables

These variables are available in build scripts:

TARGET

string

Target triple (e.g., x86_64-unknown-redox)

COOKBOOK_ROOT

string

Root directory of the cookbook system

COOKBOOK_SYSROOT

string

Installation destination directory

COOKBOOK_RECIPE

string

Path to current recipe directory

COOKBOOK_SOURCE

string

Source code directory

COOKBOOK_BUILD

string

Build directory

COOKBOOK_STAGE

string

Staging directory for installation

MAKE_JOBS

integer

Number of parallel jobs for make

HOST

string

Host system triple

Recipe Commands

The build system provides shorthand commands for working with recipes:

Basic Commands

r.PACKAGE - Build Recipe

Build (cook) a recipe and its dependencies:

make r.nano

Build multiple recipes:

make r.gcc,binutils,newlib

c.PACKAGE - Clean Recipe

Clean build artifacts:

make c.kernel

Clean specific recipe including sysroot:

make c.relibc

f.PACKAGE - Fetch Source

Download source code without building:

make f.mesa

u.PACKAGE - Unfetch Source

Remove downloaded sources:

make u.gcc

Combined Commands

# Clean then build
make cr.relibc

Query Commands

# Find recipe location
make find.orbital

# Show build tree (dependencies)
make rt.mesa

# Show push tree (installation order)
make pt.desktop

Working with Recipes

Building a Single Package

Find the Recipe

make find.nano
# Output: recipes/other/nano

Check Dependencies

make rt.nano
# Shows dependency tree

Build the Recipe

make r.nano

Install to Image

make p.nano

Modifying an Existing Recipe

Edit Recipe

Modify the recipe.toml file:

nano recipes/other/nano/recipe.toml

Clean and Rebuild

make cr.nano

Test in Image

# Push to mounted image
make mount
make p.nano
make unmount

# Test in QEMU
make qemu

Creating a New Recipe

Create Recipe Directory

mkdir -p recipes/other/mypackage
cd recipes/other/mypackage

Create recipe.toml

recipe.toml

[source]
git = "https://github.com/user/mypackage.git"
branch = "main"

[build]
template = "configure"
script = """
./configure --host=${TARGET} --prefix=/usr
make -j${MAKE_JOBS}
make DESTDIR=${COOKBOOK_SYSROOT} install
"""

[build.dependencies]
gcc = {}
relibc = {}

Test Build

make r.mypackage

Add to Configuration

Add to your TOML config:

config/mycustom.toml

[packages]
mypackage = {}

Dependencies

Build Dependencies

Required to build the package:

[build.dependencies]
gcc = {}
make = {}
pkgconf = {}

Runtime Dependencies

Required to run the package:

[build.dependencies.runtime]
ncurses = {}
relibc = {}

Dependency Chains

Cookbook automatically resolves dependency chains:

Patches

Patches modify source code for Redox compatibility:

Applying Patches

Place .patch files in the recipe directory:

recipes/other/nano/
├── recipe.toml
├── 01-fix-build.patch
└── 02-add-feature.patch

Cookbook automatically applies patches in alphabetical order.

Creating Patches

cd recipes/other/nano/source

# Make your changes
vim src/nano.c

# Create patch
git diff > ../fix-issue.patch

Patch Format

Use unified diff format:

fix-issue.patch

--- a/src/nano.c
+++ b/src/nano.c
@@ -100,7 +100,7 @@
 int main(int argc, char **argv) {
-    // Old code
+    // New code
     return 0;
 }

Repository Operations

Building All Packages

# Build all packages in configuration
make repo

# Or implicitly through:
make all

Cleaning Repository

# Clean all built packages
make repo_clean

# Clean and remove sources
make fetch_clean

# Complete clean
make distclean

Offline Builds

Build without internet access:

# Fetch all sources first
make fetch

# Enable offline mode
echo 'REPO_OFFLINE=1' >> .config

# Build offline
make all

Advanced Topics

Binary Packages

Use pre-built packages:

.config

REPO_BINARY=1

Cookbook will download pre-built packages from:

https://static.redox-os.org/pkg

Debug Builds

Enable debug symbols:

.config

REPO_DEBUG=1

This sets these environment variables:

COOKBOOK_NOSTRIP=true
COOKBOOK_DEBUG=true

Continuing on Errors

Don’t stop on recipe failures:

.config

REPO_NONSTOP=1

Useful for CI or finding all broken recipes.

AppStream Metadata

Generate application metadata:

.config

REPO_APPSTREAM=1

Cross-Compilation

Recipes support multiple architectures:

# Build for different architecture
make r.nano ARCH=aarch64

# Build tree shows arch-specific deps
make rt.nano ARCH=riscv64gc

Recipe Best Practices

Use Templates

Prefer built-in templates (cargo, configure, etc.) over custom scripts when possible.

Minimize Patches

Try to upstream changes rather than maintaining patches. Keep patches small and well-documented.

Specify Dependencies

Explicitly list all dependencies, including transitive ones that might be needed.

Test Incrementally

Test recipes in isolation before adding to system configuration.

Document Changes

Add comments explaining non-obvious build steps or workarounds.

Version Pinning

Use specific Git revisions or tags rather than branches for reproducibility.

Troubleshooting Recipes

Build fails

Check logs:

# Enable verbose output
make r.package COOKBOOK_VERBOSE=1

# Check build directory
ls -la recipes/other/package/target/$(TARGET)/build/

Missing dependencies

Verify dependency tree:

make rt.package

# Check if dependencies are built
make r.dependency

Patch fails to apply

Check source version:

cd recipes/other/package/source
git log --oneline

# Regenerate patch
git diff > ../new.patch

Cross-compilation errors

Check toolchain:

# Verify target is set
echo $TARGET

# Check compiler
${TARGET}-gcc --version

# Rebuild toolchain
make prefix

Recipe Repository

Browse available recipes:

Core recipes: recipes/core/
Drivers: recipes/drivers/
GNU tools: recipes/gnu/
Applications: recipes/other/
Games: recipes/games/

Online recipe browser: recipes.redox-os.org

Next Steps

Configuration

Learn about configuration files

Build System Overview

Understand the complete build system

Get Started

Build System

Architecture

Components

Development

Hardware

​Overview

​What is a Recipe?

Source

Dependencies

Build Instructions

Patches

​Recipe Location

​Recipe Structure

​Recipe Definition (recipe.toml)

​Basic Recipe Example

​Recipe Sections

​Build Templates

​Configure Template

​Cargo Template

​CMake Template

​Custom Template

​Build Variables

​Recipe Commands

​Basic Commands

​Combined Commands

​Query Commands

​Working with Recipes

​Building a Single Package

​Modifying an Existing Recipe

​Creating a New Recipe

​Dependencies

​Build Dependencies

​Runtime Dependencies

​Dependency Chains

​Patches

​Applying Patches

​Creating Patches

​Patch Format

​Repository Operations

​Building All Packages

​Cleaning Repository

​Offline Builds

​Advanced Topics

​Binary Packages

​Debug Builds

​Continuing on Errors

​AppStream Metadata

​Cross-Compilation

​Recipe Best Practices

​Troubleshooting Recipes

​Recipe Repository

​Next Steps

Configuration

Build System Overview

Build docs developers (and LLMs) love

Overview

What is a Recipe?

Recipe Location

Recipe Structure

Recipe Definition (recipe.toml)

Basic Recipe Example

Recipe Sections

Build Templates

Configure Template

Cargo Template

CMake Template

Custom Template

Build Variables

Recipe Commands

Basic Commands

Combined Commands

Query Commands

Working with Recipes

Building a Single Package

Modifying an Existing Recipe

Creating a New Recipe

Dependencies

Build Dependencies

Runtime Dependencies

Dependency Chains

Patches

Applying Patches

Creating Patches

Patch Format

Repository Operations

Building All Packages

Cleaning Repository

Offline Builds

Advanced Topics

Binary Packages

Debug Builds

Continuing on Errors

AppStream Metadata

Cross-Compilation

Recipe Best Practices

Troubleshooting Recipes

Recipe Repository

Next Steps