Application Porting Guide

Overview

Porting applications to Redox OS involves creating recipes in the Cookbook system. A recipe is a TOML file that describes how to download, build, and package software for Redox.

Always verify if a recipe for your program or library already exists before porting to avoid recipe duplication or breaking the build system.

Before You Start

Prerequisites

Build system setup and up-to-date (see Build System Reference)
Familiarity with the target application’s build system
Understanding of POSIX/Linux APIs

Common Porting Issues

If a program can’t build or work, something may be missing in relibc, such as a POSIX/Linux function or there may be a bug.

Recipe Structure

Every recipe is stored in recipes/<category>/<package-name>/recipe.toml. The recipe consists of three main sections:

1. Source Section

Defines where to download the source code from.

2. Build Section

Specifies how to compile the application.

3. Package Section

Describes runtime dependencies and metadata.

Creating a Basic Recipe

Simple Rust Application

For Rust applications hosted on GitLab:

[source]
git = "https://gitlab.redox-os.org/redox-os/coreutils.git"

[build]
template = "cargo"

This minimal recipe:

Clones the git repository
Builds using cargo build --release
Installs binaries to /usr/bin

Application with Tarball Source

For applications distributed as tarballs:

[source]
tar = "https://www.cairographics.org/releases/cairo-1.18.4.tar.xz"
blake3 = "b9fa14e02f85ec4e72396c62236c98502d04dbbdf8daf01ab9557a1c7aa7106e"
patches = ["redox.patch"]

[build]
dependencies = [
    "expat",
    "freetype2",
    "pixman",
    "zlib"
]
template = "custom"
script = """
DYNAMIC_INIT
CFLAGS="${CFLAGS} -DCAIRO_NO_MUTEX=1"
cookbook_meson \
    -Dxlib-xcb=enabled \
    -Dtests=disabled
"""

Always specify blake3 checksums for reproducible builds.

Build Templates

The Cookbook provides several build templates for common build systems.

Cargo Template

For Rust projects:

[build]
template = "cargo"
cargoflags = ["--features", "extra-features"]
cargopackages = ["package1", "package2"]

Options:

cargopath - Path to Cargo.toml if not in root
cargoflags - Additional flags for cargo build
cargopackages - Specific packages to build from workspace
cargoexamples - Example binaries to build

Configure Template

For autotools-based projects:

[build]
template = "configure"
configureflags = [
    "--disable-nls",
    "--enable-static"
]

Example from the dash recipe:

[source]
git = "https://gitlab.redox-os.org/redox-os/dash.git"
branch = "redox"

[build]
template = "custom"
script = """
DYNAMIC_INIT
rsync -av --delete "${COOKBOOK_SOURCE}/" ./
./autogen.sh
./configure \
    --host="${TARGET}" \
    --prefix="" \
    --enable-static \
    cross_compiling=yes
sed -i'' -e 's|#define HAVE_GETRLIMIT 1|/* #undef HAVE_GETRLIMIT */|g' config.h
COOKBOOK_CONFIGURE="true"
COOKBOOK_CONFIGURE_FLAGS=()
cookbook_configure
"""

CMake Template

For CMake-based projects:

[build]
template = "cmake"
cmakeflags = [
    "-DBUILD_TESTING=OFF",
    "-DENABLE_FEATURE=ON"
]

Meson Template

For Meson-based projects:

[build]
template = "meson"
mesonflags = [
    "-Dtests=disabled",
    "-Ddocs=false"
]

Custom Template

For projects requiring custom build scripts:

[build]
template = "custom"
script = """
DYNAMIC_STATIC_INIT
rsync -av --delete "${COOKBOOK_SOURCE}/" ./
export CPPFLAGS="$CPPFLAGS -fPIC"
${COOKBOOK_MAKE}
${COOKBOOK_MAKE} install DESTDIR="${COOKBOOK_STAGE}" prefix="/usr"
"""

Dependencies

Build Dependencies

Libraries and tools needed during compilation:

[build]
dependencies = [
    "curl",
    "expat",
    "openssl3",
    "zlib"
]

Development Dependencies

Additional dependencies for building (optional):

[build]
dev-dependencies = [
    "cmake",
    "pkg-config"
]

Runtime Dependencies

Packages required at runtime:

[package]
dependencies = [
    "ca-certificates",
    "libssl"
]

Advanced Features

Applying Patches

Store patches in the same directory as recipe.toml:

[source]
tar = "https://example.com/app-1.0.tar.gz"
blake3 = "abc123..."
patches = [
    "01_redox.patch",
    "02_fix_build.patch"
]

Git Sources with Specific Revisions

[source]
git = "https://gitlab.redox-os.org/redox-os/acid.git"
branch = "master"
rev = "06344744d3d55a5ac9a62a6059cb363d40699bbc"
shallow_clone = true

Specify branch and rev for reproducible builds.

Using Another Package’s Source

Reuse source from another recipe:

[source]
same_as = "../main-package"

Optional Packages

Create multiple packages from one recipe:

[[optional-packages]]
name = "dev"
dependencies = ["main-package"]
files = [
    "/usr/include/**",
    "/usr/lib/*.a"
]

Build Script Variables

The Cookbook provides several environment variables in build scripts:

Variable	Description
`COOKBOOK_SOURCE`	Path to extracted source code
`COOKBOOK_STAGE`	Installation staging directory
`COOKBOOK_SYSROOT`	Sysroot with dependencies
`COOKBOOK_CARGO`	Path to cargo binary
`COOKBOOK_MAKE`	Path to make binary
`COOKBOOK_MAKE_JOBS`	Number of parallel jobs
`TARGET`	Target triple (e.g., `x86_64-unknown-redox`)
`GNU_TARGET`	GNU-style target triple

Helper Functions

DYNAMIC_INIT - Initialize for dynamic linking
DYNAMIC_STATIC_INIT - Initialize for static/dynamic linking
cookbook_cargo - Standard cargo build and install
cookbook_configure - Standard configure, make, install
cookbook_meson - Standard meson build

Testing Your Recipe

Build a Single Recipe

make r.recipe-name

Build with Dependencies

make r.recipe-name.tar

Clean and Rebuild

make cr.recipe-name

Update Recipe Source

make u.recipe-name

Local Development

For local changes, configure recipes to skip automatic updates. See Local Recipe Changes.

Add to .config/<target>/repo.toml:

[packages]
my-recipe = "local"

This prevents the build system from updating your local changes.

Common Patterns

Meta Packages

Packages with no source, only dependencies:

[package]
dependencies = [
    "package1",
    "package2",
    "package3"
]

Complex Build Example

From the base recipe:

[source]
git = "https://gitlab.redox-os.org/redox-os/base.git"

[build]
template = "custom"
script = """
mkdir -pv "${COOKBOOK_STAGE}/usr/bin"
for package in audiod ipcd ptyd; do
    "${COOKBOOK_CARGO}" build \
        --manifest-path "${COOKBOOK_SOURCE}/${package}/Cargo.toml" \
        ${build_flags}
    cp -v \
        "target/${TARGET}/${build_type}/${package}" \
        "${COOKBOOK_STAGE}/usr/bin/${package}"
done
"""

Troubleshooting

Build Failures

Check relibc for missing POSIX functions
Verify all dependencies are listed
Check if patches apply cleanly
Review build logs in build/<target>/<recipe>/

Missing Functions

If you encounter undefined references, the function may need to be implemented in:

relibc - C library
libredox - Redox system library

Debug Build

Enable verbose output:

make VERBOSE=1 r.recipe-name

Recipe Categories

Organize recipes by category:

archives/ - Compression tools
core/ - Essential system components
dev/ - Development tools
games/ - Games and entertainment
graphics/ - Graphics applications
gui/ - GUI applications
libs/ - Libraries
net/ - Network applications
shells/ - Command shells
text/ - Text editors and processors

Best Practices

Use Checksums

Always specify blake3 for tarball sources to ensure reproducible builds.

Minimal Dependencies

Only list necessary dependencies to reduce build complexity.

Upstream First

Contribute Redox support upstream when possible instead of maintaining patches.

Test Thoroughly

Build and test your recipe before submitting.

Contributing Recipes

Once your recipe is working:

Test thoroughly on QEMU or real hardware
Create a merge request to the Redox repository
Post the MR link in the MRs Matrix room

Read the full Contributing Guide for merge request guidelines.

Build Commands

Porting

Support

​Overview

​Before You Start

​Prerequisites

​Common Porting Issues

​Recipe Structure

​1. Source Section

​2. Build Section

​3. Package Section

​Creating a Basic Recipe

​Simple Rust Application

​Application with Tarball Source

​Build Templates

​Cargo Template

​Configure Template

​CMake Template

​Meson Template

​Custom Template

​Dependencies

​Build Dependencies

​Development Dependencies

​Runtime Dependencies

​Advanced Features

​Applying Patches

​Git Sources with Specific Revisions

​Using Another Package’s Source

​Optional Packages

​Build Script Variables

​Helper Functions

​Testing Your Recipe

​Build a Single Recipe

​Build with Dependencies

​Clean and Rebuild

​Update Recipe Source

​Local Development

​Common Patterns

​Meta Packages

​Complex Build Example

​Troubleshooting

​Build Failures

​Missing Functions

​Debug Build

​Recipe Categories

​Best Practices

Use Checksums

Minimal Dependencies

Upstream First

Test Thoroughly

​Contributing Recipes

​See Also

Build docs developers (and LLMs) love

Overview

Before You Start

Prerequisites

Common Porting Issues

Recipe Structure

1. Source Section

2. Build Section

3. Package Section

Creating a Basic Recipe

Simple Rust Application

Application with Tarball Source

Build Templates

Cargo Template

Configure Template

CMake Template

Meson Template

Custom Template

Dependencies

Build Dependencies

Development Dependencies

Runtime Dependencies

Advanced Features

Applying Patches

Git Sources with Specific Revisions

Using Another Package’s Source

Optional Packages

Build Script Variables

Helper Functions

Testing Your Recipe

Build a Single Recipe

Build with Dependencies

Clean and Rebuild

Update Recipe Source

Local Development

Common Patterns

Meta Packages

Complex Build Example

Troubleshooting

Build Failures

Missing Functions

Debug Build

Recipe Categories

Best Practices

Contributing Recipes

See Also