Recipe Format Reference

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:

Runs ./configure --host=${TARGET} --prefix=/usr ${configureflags}
Runs make -j${COOKBOOK_MAKE_JOBS}
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.

Build Commands

Porting

Support

​Overview

​Recipe Structure

​Source Section

​Git Source

​Tar Source

​Path Source

​Shared Source

​No Source

​Build Section

​Template Field

​None Template

​Remote Template

​Cargo Template

​Configure Template

​CMake Template

​Meson Template

​Custom Template

​Build Dependencies

​Package Section

​Optional Packages

​Build Script Environment

​Directory Variables

​Tool Variables

​Target Variables

​Compiler Variables

​Helper Functions

​DYNAMIC_INIT

​DYNAMIC_STATIC_INIT

​cookbook_cargo

​cookbook_configure

​cookbook_meson

​Complete Examples

​Minimal Rust Package

​Library with Dependencies

​Complex Build Script

​Meta Package

​Package Naming

​Regular Packages

​Optional Packages

​Host Packages

​Validation

​Best Practices

Always Use Checksums

Pin Git Revisions

Minimal Dependencies

Use Standard Templates

​See Also

Build docs developers (and LLMs) love

Overview

Recipe Structure

Source Section

Git Source

Tar Source

Path Source

Shared Source

No Source

Build Section

Template Field

None Template

Remote Template

Cargo Template

Configure Template

CMake Template

Meson Template

Custom Template

Build Dependencies

Package Section

Optional Packages

Build Script Environment

Directory Variables

Tool Variables

Target Variables

Compiler Variables

Helper Functions

DYNAMIC_INIT

DYNAMIC_STATIC_INIT

cookbook_cargo

cookbook_configure

cookbook_meson

Complete Examples

Minimal Rust Package

Library with Dependencies

Complex Build Script

Meta Package

Package Naming

Regular Packages

Optional Packages

Host Packages

Validation

Best Practices

See Also