Repo Tool Reference

Overview

The repo tool is the primary interface for managing recipe sources, building packages, and installing them into the filesystem. It replaces the older repo.sh script with a faster, more feature-rich Rust implementation.

The repo tool is built from src/bin/repo.rs and is also available as make r.*, make f.*, etc. targets.

Usage

repo <command> [flags] <recipe1> <recipe2> ...

Commands

fetch

Download recipe source code.

repo fetch coreutils bash gcc

Respects COOKBOOK_OFFLINE=true to prevent network access if sources are already available.

Behavior

Downloads sources from Git, tarballs, or other configured locations
Extracts archives to recipes/*/source/ directories
Skips downloads if sources already exist (unless clean is run first)
Can operate in offline mode if sources are pre-fetched

cook

Build recipe packages.

repo cook kernel drivers init

Build Process

Fetches sources if not already present
Runs the recipe’s build script
Compiles sources in recipes/*/source/
Stages outputs to recipes/*/target/$(TARGET)/stage/
Creates package archives in repo/$(TARGET)/
Publishes packages to the repository

Features

TUI Mode: Shows real-time build progress with colored output (default when not in CI)
Parallel Building: Builds dependencies concurrently
Build Logs: Saves logs to build/logs/$(TARGET)/ when enabled
Dependency Resolution: Automatically builds required dependencies
Package Caching: Reuses previously built packages when possible

unfetch

Delete recipe source code.

repo unfetch rust llvm

Removes the source/ directory for specified recipes.

clean

Delete recipe build artifacts.

repo clean gcc relibc

Removes:

recipes/*/target/ directory (all architectures)
Build cache and intermediate files

Does not remove source code. Use unfetch for that.

clean-target

Delete recipe artifacts for one target only.

repo clean-target kernel

Removes only recipes/*/target/$(TARGET)/, preserving other architectures.

push

Extract packages into the sysroot (filesystem).

repo push orbital netsurf cosmic-term

--sysroot

path

default:"./sysroot"

Target directory for package installation

Extracts package archives from repo/$(TARGET)/ into the sysroot.

Do not push packages while QEMU is running with the disk image mounted, as this may cause corruption.

find

Find the path to recipe directories.

repo find coreutils bash

Outputs:

recipes/core/coreutils
recipes/core/bash

cook-tree

Show the build dependency tree.

repo cook-tree gcc

Outputs:

gcc
├── binutils
├── relibc
│   ├── llvm
│   └── kernel
└── gcc-core

Build summary: 5 need build, 1 may rebuild, with total of 5 recipes

push-tree

Show the package installation tree with sizes.

repo push-tree netsurf

Outputs:

netsurf (2.1 MB)
├── libcurl (856 KB)
│   └── openssl (1.4 MB)
├── libpng (421 KB)
└── libjpeg (612 KB)

Estimated image size: 5.4 MB of 5 packages

Common Flags

—cookbook

Specify the recipes directory.

repo cook --cookbook=/path/to/recipes kernel

--cookbook

path

default:"$PWD/recipes"

Path to the recipes directory

—repo

Specify the package repository directory.

repo cook --repo=/path/to/repo gcc

--repo

path

default:"$PWD/repo"

Path to the package output directory

—sysroot

Specify the installation target directory.

repo push --sysroot=/mnt/redox coreutils

--sysroot

path

default:"$PWD/sysroot or /"

Target directory for push command. Defaults to / on Redox, ./sysroot elsewhere.

—with-package-deps

Include package (runtime) dependencies.

repo cook --with-package-deps netsurf

Builds the recipe plus all packages it needs at runtime (not just build dependencies).

—all

Apply command to all recipes.

repo clean --all
repo unfetch --all

Use with caution, especially with clean and unfetch. Cannot be combined with explicit recipe names.

—category

Apply command to all recipes in a category.

repo cook --category=core
repo clean --category=drivers

--category

string

Category subdirectory name (e.g., core, games, drivers)

—filesystem

Use an installer TOML config to determine which recipes to build.

repo cook --filesystem=config/desktop.toml --with-package-deps

--filesystem

path

Path to filesystem configuration TOML file

Builds all packages specified in the configuration, respecting build rules (source/binary/ignore).

—repo-binary

Override recipes to use binary packages.

repo cook --repo-binary --filesystem=config/server.toml

Forces all recipes to use pre-built binary packages from the repository instead of building from source.

Environment Variables

These environment variables control the repo tool’s behavior:

CI

Disable TUI when set.

CI=1 repo cook kernel

any

default:"unset"

If set to any value, disables the interactive TUI and uses plain text output

COOKBOOK_LOGS

Control log file creation.

COOKBOOK_LOGS=true repo cook gcc

COOKBOOK_LOGS

true|false

default:"!CI"

Whether to write build logs to files. Defaults to true unless CI is set.

COOKBOOK_OFFLINE

Prevent network access.

COOKBOOK_OFFLINE=true repo cook kernel

COOKBOOK_OFFLINE

true|false

default:"false"

Prevent internet access if possible. Ignored when using the fetch command.

COOKBOOK_NONSTOP

Continue building after failures.

COOKBOOK_NONSTOP=true repo cook --all

COOKBOOK_NONSTOP

true|false

default:"false"

Keep running even if a recipe build fails. Useful for CI builds.

COOKBOOK_COMPRESSED

Build compressed packages.

COOKBOOK_COMPRESSED=true repo cook netsurf

COOKBOOK_COMPRESSED

true|false

default:"false"

Build packages in compressed (tar.gz) format instead of pkgar format

COOKBOOK_VERBOSE

Print build results.

COOKBOOK_VERBOSE=false repo cook --all

COOKBOOK_VERBOSE

true|false

default:"true"

Print success/error messages for each recipe build

COOKBOOK_CLEAN_BUILD

Remove build directory before building.

COOKBOOK_CLEAN_BUILD=true repo cook gcc

COOKBOOK_CLEAN_BUILD

true|false

default:"false"

Remove the build directory before starting compilation

COOKBOOK_CLEAN_TARGET

Remove target directory after building.

COOKBOOK_CLEAN_TARGET=true repo cook kernel

COOKBOOK_CLEAN_TARGET

true|false

default:"false"

Remove the target/stage directory after building the package

COOKBOOK_WRITE_FILETREE

Write stage file tree.

COOKBOOK_WRITE_FILETREE=true repo cook bash

COOKBOOK_WRITE_FILETREE

true|false

default:"false"

Write a text file listing all staged files

COOKBOOK_MAKE_JOBS

Override build parallelism.

COOKBOOK_MAKE_JOBS=8 repo cook llvm

COOKBOOK_MAKE_JOBS

number

default:"nproc"

Number of parallel build jobs. Defaults to number of CPU cores.

COOKBOOK_WEB

Generate package metadata for web.

COOKBOOK_WEB=true repo cook gcc

COOKBOOK_WEB

true|false

default:"false"

Generate web-friendly package metadata files

COOKBOOK_HOST_SYSROOT

Set host sysroot for cross-compilation.

COOKBOOK_HOST_SYSROOT=/path/to/sysroot repo cook host:binutils

COOKBOOK_HOST_SYSROOT

path

Path to host system sysroot for cross-compiler recipes

COOKBOOK_CROSS_TARGET

Set cross-compilation target.

COOKBOOK_CROSS_TARGET=x86_64-unknown-redox repo cook host:gcc

COOKBOOK_CROSS_TARGET

string

Target triple for cross-compilation

COOKBOOK_APPSTREAM

Build AppStream metadata.

COOKBOOK_APPSTREAM=true repo cook --all

COOKBOOK_APPSTREAM

true|false

default:"false"

Generate AppStream metadata for packages (set by REPO_APPSTREAM=1)

COOKBOOK_NOSTRIP

Disable binary stripping.

COOKBOOK_NOSTRIP=true repo cook kernel

COOKBOOK_NOSTRIP

true|false

default:"false"

Don’t strip debug symbols from binaries (set by REPO_DEBUG=1)

COOKBOOK_DEBUG

Enable debug builds.

COOKBOOK_DEBUG=true repo cook relibc

COOKBOOK_DEBUG

true|false

default:"false"

Build with debug symbols and less optimization (set by REPO_DEBUG=1)

TUI Mode

When CI is not set and the terminal supports it, repo cook displays an interactive TUI:

Features

Live Log Viewing: Shows real-time build output for active recipes
Progress Tracking: Displays fetch and cook queues
Color Coding: Green for success, red for failures, yellow for active
Automatic Scrolling: Follows log output automatically
Keyboard Controls:
- Arrow keys: Scroll logs
- Page Up/Down: Fast scroll
- Home/End: Jump to top/bottom
- Tab: Switch between fetch/cook logs

Failure Handling

When a build fails in TUI mode:

The TUI exits and returns to the shell
Full error context is printed to stderr
Logs are saved to build/logs/$(TARGET)/$(RECIPE).log
Exit code indicates failure

With COOKBOOK_NONSTOP=true:

Failed recipes are skipped
Building continues with remaining recipes
All failures are logged

Recipe Selection

The tool supports multiple ways to specify recipes:

By Name

repo cook coreutils bash gcc

By Wildcard Pattern

Not directly supported. Use --category or --all instead.

By Category

repo cook --category=core

Builds all recipes in recipes/core/.

By Filesystem Config

repo cook --filesystem=config/desktop.toml --with-package-deps

Builds all recipes listed in the TOML configuration.

With Dependencies

repo cook --with-package-deps netsurf

Builds the recipe plus all its runtime dependencies.

Dependency Resolution

Build Dependencies

Automatically included when cooking recipes. These are specified in recipe.toml files.

Package Dependencies

Included only when using --with-package-deps flag. These are runtime dependencies.

Dependency Types

Dependency Types in recipe.toml

dependencies: Build-time dependencies (always included)
build_dependencies: Build tools needed during compilation
host_dependencies: Dependencies for cross-compiler recipes
package_dependencies: Runtime dependencies (only with --with-package-deps)

Build Modes

Source Mode

Builds packages from source code (default).

repo cook gcc

Binary Mode

Uses pre-built binary packages from the repository.

repo cook --repo-binary --filesystem=config/desktop.toml

Binary mode is much faster but requires packages to be available in the binary repository.

Local Mode

Forces building from local source, ignoring binary packages.

[packages]
gcc = "local"

Specified in filesystem configuration files.

Ignore Mode

Skips building certain packages.

[packages]
debug-tools = "ignore"

Exit Codes

Success

All operations completed successfully

Error

One or more recipes failed to build, or invalid arguments provided

Examples

Build a single recipe

repo cook coreutils

Build with dependencies

repo cook --with-package-deps orbital

Clean and rebuild

repo clean gcc && repo cook gcc

Build entire desktop system

repo cook --filesystem=config/desktop.toml --with-package-deps

Build in offline mode

COOKBOOK_OFFLINE=true repo cook kernel

Build all recipes in a category

repo cook --category=games

Show dependencies before building

repo cook-tree netsurf
repo push-tree netsurf

Build with verbose logging

COOKBOOK_VERBOSE=true COOKBOOK_LOGS=true repo cook --all

Make Commands

Makefile targets that wrap the repo tool

Configuration Options

Build system configuration variables

Build Commands

Porting

Support

​Overview

​Usage

​Commands

​fetch

​Behavior

​cook

​Features

​unfetch

​clean

​clean-target

​push

​find

​cook-tree

​push-tree

​Common Flags

​—cookbook

​—repo

​—sysroot

​—with-package-deps

​—all

​—category

​—filesystem

​—repo-binary

​Environment Variables

​CI

​COOKBOOK_LOGS

​COOKBOOK_OFFLINE

​COOKBOOK_NONSTOP

​COOKBOOK_COMPRESSED

​COOKBOOK_VERBOSE

​COOKBOOK_CLEAN_BUILD

​COOKBOOK_CLEAN_TARGET

​COOKBOOK_WRITE_FILETREE

​COOKBOOK_MAKE_JOBS

​COOKBOOK_WEB

​COOKBOOK_HOST_SYSROOT

​COOKBOOK_CROSS_TARGET

​COOKBOOK_APPSTREAM

​COOKBOOK_NOSTRIP

​COOKBOOK_DEBUG

​TUI Mode

​Features

​Failure Handling

​Recipe Selection

​By Name

​By Wildcard Pattern

​By Category

​By Filesystem Config

​With Dependencies

​Dependency Resolution

​Build Dependencies

​Package Dependencies

​Dependency Types

​Build Modes

​Source Mode

​Binary Mode

​Local Mode

​Ignore Mode

​Exit Codes

​Examples

​Build a single recipe

​Build with dependencies

​Clean and rebuild

​Build entire desktop system

​Build in offline mode

​Build all recipes in a category

​Show dependencies before building

​Build with verbose logging

​See Also

Make Commands

Configuration Options

Build docs developers (and LLMs) love

Overview

Usage

Commands

fetch

Behavior

cook

Features

unfetch

clean

clean-target

push

find

cook-tree

push-tree

Common Flags

—cookbook

—repo

—sysroot

—with-package-deps

—all

—category

—filesystem

—repo-binary

Environment Variables

CI

COOKBOOK_LOGS

COOKBOOK_OFFLINE

COOKBOOK_NONSTOP

COOKBOOK_COMPRESSED

COOKBOOK_VERBOSE

COOKBOOK_CLEAN_BUILD

COOKBOOK_CLEAN_TARGET

COOKBOOK_WRITE_FILETREE

COOKBOOK_MAKE_JOBS

COOKBOOK_WEB

COOKBOOK_HOST_SYSROOT

COOKBOOK_CROSS_TARGET

COOKBOOK_APPSTREAM

COOKBOOK_NOSTRIP

COOKBOOK_DEBUG

TUI Mode

Features

Failure Handling

Recipe Selection

By Name

By Wildcard Pattern

By Category

By Filesystem Config

With Dependencies

Dependency Resolution

Build Dependencies

Package Dependencies

Dependency Types

Build Modes

Source Mode

Binary Mode

Local Mode

Ignore Mode

Exit Codes

Examples

Build a single recipe

Build with dependencies

Clean and rebuild

Build entire desktop system

Build in offline mode

Build all recipes in a category

Show dependencies before building

Build with verbose logging

See Also