Recipe Format Reference

Complete specification of the recipe.toml format for Redox OS packages

Overview

Recipes are TOML files that define how to download, build, and package software for Redox OS. Each recipe is stored in recipes/<category>/<package>/recipe.toml.

Recipe Structure

A recipe consists of up to four main sections:

[source]      # How to obtain source code
[build]       # How to compile the source
[package]     # Runtime metadata and dependencies
[[optional-packages]]  # Additional packages from same source

Source Section

Defines where and how to download the source code.

Git Source

Clone from a Git repository:

[source]
git = "https://gitlab.redox-os.org/redox-os/ion.git"
branch = "master"
rev = "abc123..."
upstream = "https://github.com/original/repo.git"
shallow_clone = true
patches = ["fix.patch"]
script = "./autogen.sh"

Fields:

git · string · required

URL to the Git repository

branch · string

Git branch to track (recommended for reproducibility)

rev · string

Specific Git commit SHA (recommended for reproducible builds)

upstream · string

URL to upstream repository for reference

shallow_clone · boolean

Use treeless clone for faster downloads (default: true if rev specified)

patches · array

List of patch files to apply after cloning

script · string

Shell script to run after cloning and patching

Tar Source

Download from a tarball:

[source]
tar = "https://www.kernel.org/pub/software/scm/git/git-2.13.1.tar.xz"
blake3 = "bc78271bffd60c5b8b938d8c08fd74dc2de8d21fbaf8f8e0e3155436d9263f17"
patches = ["git.patch"]
script = "./bootstrap.sh"

Fields:

tar · string · required

URL to the tarball (supports .tar.gz, .tar.xz, .tar.bz2, .zip)

blake3 · string

BLAKE3 checksum of the tarball (strongly recommended for reproducibility)

patches · array

List of patch files to apply after extraction

script · string

Shell script to run after extraction and patching

Path Source

Use a local directory:

[source]
path = "/path/to/source"

Path sources are primarily for testing. Production recipes should use Git or tar sources.

Shared Source

Reuse another package’s source:

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

Useful when building multiple packages from a single source tree.

No Source

For meta-packages with no source code:

# No [source] section

[package]
dependencies = ["pkg1", "pkg2"]

Build Section

Defines how to compile the source code.

Template Field

All build sections must specify a template:

[build]
template = "cargo"  # or "configure", "cmake", "meson", "custom", "none", "remote"

None Template

No build process (meta-packages):

[build]
template = "none"

Remote Template

Download pre-built binary package:

[build]
template = "remote"

The build system automatically downloads packages from the official Redox package repository.

Cargo Template

For Rust projects using Cargo:

[build]
template = "cargo"
cargopath = "subdir/Cargo.toml"
cargoflags = [
    "--features", "redox,extra",
    "--no-default-features"
]
cargopackages = ["pkg1", "pkg2"]
cargoexamples = ["example1"]

Fields:

cargopath · string

Path to Cargo.toml relative to source root (default: “Cargo.toml”)

cargoflags · array

Additional flags passed to cargo build

cargopackages · array

Specific packages to build from a workspace

cargoexamples · array

Example binaries to build and install

Example from coreutils:

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

[build]
template = "cargo"

Configure Template

For autotools-based projects:

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

Fields:

configureflags · array

Flags passed to the ./configure script

The configure template automatically:

1. Runs ./configure --host=${TARGET} --prefix=/usr ${configureflags}
2. Runs make -j${COOKBOOK_MAKE_JOBS}
3. Runs make DESTDIR=${COOKBOOK_STAGE} install

CMake Template

For CMake-based projects:

[build]
template = "cmake"
cmakeflags = [
    "-DBUILD_SHARED_LIBS=ON",
    "-DENABLE_TESTING=OFF"
]

Fields:

cmakeflags · array

Flags passed to the cmake command

Meson Template

For Meson build system:

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

Fields:

mesonflags · array

Flags passed to the meson setup command

Custom Template

For projects requiring custom build logic:

[build]
template = "custom"
script = """
# Your custom build script here
DYNAMIC_INIT
rsync -av --delete "${COOKBOOK_SOURCE}/" ./
./configure --host="${TARGET}"
make -j"${COOKBOOK_MAKE_JOBS}"
make DESTDIR="${COOKBOOK_STAGE}" install
"""

Fields:

script · string · required

Shell script executed in the build directory

Example from zstd:

[source]
tar = "https://github.com/facebook/zstd/releases/download/v1.5.7/zstd-1.5.7.tar.gz"
patches = ["01_redox.patch"]

[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"
"""

Build Dependencies

Libraries and tools required at build time:

[build]
template = "cargo"
dependencies = [
    "openssl3",
    "zlib",
    "libxml2"
]
dev-dependencies = [
    "pkg-config",
    "cmake"
]

Fields:

dependencies · array

Runtime libraries and build tools required during compilation

dev-dependencies · array

Additional development tools (compilers, build systems, etc.)

Package Section

Metadata about the resulting package.

[package]
dependencies = ["ca-certificates", "libssl"]
version = "1.2.3"
description = "A cool package for Redox OS"

Fields:

dependencies · array

Packages required at runtime

version · string

Package version (auto-detected from source if possible)

description · string

Brief description of the package

Example from git:

[source]
tar = "https://www.kernel.org/pub/software/scm/git/git-2.13.1.tar.xz"
blake3 = "bc78271bffd60c5b8b938d8c08fd74dc2de8d21fbaf8f8e0e3155436d9263f17"
patches = ["git.patch"]

[build]
dependencies = [
    "curl",
    "expat",
    "nghttp2",
    "openssl3",
    "zlib"
]
template = "custom"
script = """
# ... build script ...
"""

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

Optional Packages

Create additional packages from the same source:

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

[[optional-packages]]
name = "docs"
dependencies = []
files = [
    "/usr/share/doc/**",
    "/usr/share/man/**"
]

Fields:

name · string · required

Suffix for the package name (creates package-name-suffix)

dependencies · array

Additional dependencies for this optional package

files · array

File patterns to include (supports glob patterns)

Build Script Environment

Available environment variables in custom build scripts:

Directory Variables

Variable	Description
COOKBOOK_SOURCE	Extracted source directory
COOKBOOK_STAGE	Staging directory for installation (DESTDIR)
COOKBOOK_SYSROOT	Sysroot with all dependencies
COOKBOOK_BUILD	Build directory (usually same as pwd)

Tool Variables

Variable	Description
COOKBOOK_CARGO	Path to cargo
COOKBOOK_MAKE	Path to make
COOKBOOK_MAKE_JOBS	Number of parallel jobs
COOKBOOK_CONFIGURE	Path to configure script

Target Variables

Variable	Description	Example
TARGET	Rust target triple	x86_64-unknown-redox
GNU_TARGET	GNU-style target	x86_64-redox
ARCH	Target architecture	x86_64

Compiler Variables

Variable	Description
CC	C compiler
CXX	C++ compiler
AR	Archiver
RANLIB	ranlib tool
STRIP	Strip tool
CFLAGS	C compiler flags
CXXFLAGS	C++ compiler flags
LDFLAGS	Linker flags
PKG_CONFIG	pkg-config tool
PKG_CONFIG_PATH	pkg-config search path

Helper Functions

The Cookbook provides helper functions in build scripts:

DYNAMIC_INIT

Initialize for dynamic linking:

DYNAMIC_INIT
# Sets up LDFLAGS and other variables for dynamic linking

DYNAMIC_STATIC_INIT

Support both static and dynamic linking:

DYNAMIC_STATIC_INIT
# Configures build for static or dynamic based on COOKBOOK_DYNAMIC

cookbook_cargo

Standard Cargo build and install:

cookbook_cargo
# Equivalent to: cargo build + cargo install to COOKBOOK_STAGE

cookbook_configure

Standard configure, make, install:

cookbook_configure
# Runs: ./configure, make, make install

cookbook_meson

Standard Meson build:

cookbook_meson -Doption=value
# Sets up and compiles with Meson

Complete Examples

Minimal Rust Package

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

[build]
template = "cargo"

Library with Dependencies

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

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

Complex Build Script

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

[build]
template = "custom"
script = """
mkdir -pv "${COOKBOOK_STAGE}/usr/bin"

# Build multiple packages
for package in audiod ipcd ptyd; do
    "${COOKBOOK_CARGO}" build \
        --manifest-path "${COOKBOOK_SOURCE}/${package}/Cargo.toml" \
        --release
    cp -v \
        "target/${TARGET}/release/${package}" \
        "${COOKBOOK_STAGE}/usr/bin/${package}"
done
"""

Meta Package

[build]
template = "none"

[package]
dependencies = [
    "gcc13",
    "binutils",
    "make"
]
description = "Build toolchain meta-package"

Package Naming

Regular Packages

Package name is the directory name:

recipes/libs/zlib/recipe.toml → package "zlib"

Optional Packages

Optional packages append the name:

[[optional-packages]]
name = "dev"

Creates package zlib-dev.

Host Packages

Packages for the host system use -host suffix internally:

make host/package → builds package-host

Validation

The recipe system validates:

Well-formed TOML syntax

Required fields present

Valid template names

Dependency packages exist

Best Practices

Always Use Checksums

Specify blake3 for all tarball sources to ensure reproducible builds.

Pin Git Revisions

Specify branch and rev for Git sources to enable reproducible builds.

Minimal Dependencies

Only list dependencies actually required - extras slow down builds.

Use Standard Templates

Prefer cargo, configure, cmake, or meson over custom when possible.

See Also

• Application Porting Guide - How to port software
• Cookbook System - Build system architecture
• Build System Reference - Full build system guide