Configuration Settings

The Redox build system applies configuration settings from various places to determine the final Redox image. Most of these settings ultimately come from the build system's environment variables (or similarly-named Make variables) and the contents of the chosen filesystem configuration file.

• Environment Variables
  • .config
  • Cookbook Environment Variables
    • cookbook.toml
  • Changing the QEMU Properties
  • Command Line
  • mk/config.mk
    • build.sh
• Filesystem Configuration
  • CPU Architecture Codenames
  • Filesystem Size
  • Filesystem Customization
    • Creating a custom filesystem configuration
    • Adding a package to the filesystem configuration
  • Binary Packages
    • REPO_BINARY
  • Local Recipe Changes
• Advanced Cookbook Options
  • Cookbook TUI Mode
  • Cookbook Offline Mode
  • Cookbook Logs
  • Cookbook Verbosity
  • Cookbook Compressed Packages
  • Cookbook Clean Build
  • Cookbook Clean Target
  • Cookbook Web Generator

Environment Variables

The default values for the build system's Makefile variables are mostly defined in the mk directory—particularly in mk/config.mk. Local changes from the default values, however, should be applied in the .config file, or temporarily on the make command line.

The build system uses GNU Make and Cookbook to coordinate the build system in order. The build system reference and porting application guide have more information about Cookbook.

Three important Makefile variables of interest are ARCH, CONFIG_NAME, and BOARD, as they specify the system to be built. These, and other important environment variables, can be seen in the following table:

The Redox image that is built is typically named build/$ARCH/$CONFIG_NAME/harddrive.img or build/$ARCH/$CONFIG/livedisk.iso.

.config

The purpose of the .config file is to allow default configuration settings to be changed without explicitly setting those changes in every make command (or modifying the contents of the mk directory). The file is also included in the .gitignore list to ensure it won't be committed by accident.

To permanently override the settings in the mk/config.mk section, add a .config file to the redox base directory (i.e., where make commands are run) and set the overriding values in that file.

For example, the following configuration specifies the desktop-minimal image variant will be built for the i586 CPU architecture. These settings will be applied implicitly to all subsequent make commands:

ARCH?=i586
CONFIG_NAME?=desktop-minimal

📝 Note: Comments are supported using the # character 📝 Note: Any QEMU option can be inserted 📝 Note: if podman_bootstrap.sh was run previously, the .config file may already exist. 💡 Tip: when adding environment variables in the .config file, don't forget the ? symbol at the end of variable names. This allows the variable to be overridden on the command line or in the environment. In particular, PODMAN_BUILD?=1 must include the question mark to function correctly.

Cookbook Environment Variables

Cookbook (the build system) has environment variables that can be tuned for more customization. To set these environment variables, write export KEY=VALUE to .config. Note that these are environment, not Makefile variables, so the export keyword is necessary.

Each Cookbook configuration defaults to environment variables:

📝 Note: REPO_OFFLINE=1 and REPO_NONSTOP=1 are the recommended ways to set options instead of export COOKBOOK_OFFLINE=true and export COOKBOOK_NONSTOP=true 💡 Tip: Running Cookbook with CI=1 COOKBOOK_LOGS=true COOKBOOK_VERBOSE=false will hide successful build logs in the terminal

cookbook.toml

Cookbook also has a configuration file. This file is rarely used because .config should be sufficient. Any configuration in this file will override configuration from .config or environment variables. The cookbook.toml configuration below can be used as a template:

The cookbook.toml file mainly configures Cookbook options ([cook]) and mirrors ([mirror]). Mirrors are used to replace the main code and binary source URLs used in Cookbook recipes, useful for a quick way to use alternative sources when the main server is offline or slow.

# These options have defaults set below
#[cook]
#jobs = <nproc>
#nonstop = false
#offline = false
#tui = true
#logs = true
#verbose = true
#web = false
#compressed = false

[mirrors]
# The uncommented option below is the default if [mirrors] is not set
# see the list of GNU FTP mirrors at: https://www.gnu.org/prep/ftp.en.html
"ftp.gnu.org/gnu" = "mirrors.ocf.berkeley.edu/gnu"
# "github.com/foo/bar" = "github.com/baz/bar"

💡 Tip: Mirrors option can also be used to override precompiled Redox packages source URL.

Changing the QEMU Properties

To change the CPU core and RAM memory quantities used when running the Redox image in QEMU, add the following environment variables to your .config file:

QEMU_SMP?=<number-of-cpu-threads>
QEMU_MEM?=<number-of-memory-in-mib>

There's also an option to customize the QEMU machine and CPU type, which is influenced by how ARCH and BOARD is set. Read the QEMU documentation for more information:

QEMU_MACHINE?=<qemu-machine>
QEMU_CPU?=<qemu-cpu-type>

There is more options that can be customized, these are defined in mk/qemu.mk:

audio?=<no|ac97|hda>
disk?=<ata|nvme|usb|virtio|cdrom|sdcard>
net?=<e1000|rtl8139|virtio|usb-net|redir>
netboot?=<yes|no>
kvm?=<yes|no>
bridge?=...
gpu?=<no|vga|ramfb|multi|virtio|virtio-sdl|virtio-gl>
uefi?=<yes|no>
gdb?=<yes|nonblock|no>

Command Line

The default settings in mk/config.mk can be overridden by explicitly setting them on the make command line.

For example, the following command builds the demo image variant and loads it into QEMU:

make CONFIG_NAME=demo qemu

Some environment variables can also be set for the lifetime of the current shell by setting them at the command line:

export ARCH=i586; make all

Overriding settings in this way is only temporary, however. Additionally, for those using the Podman Build, some settings may be ignored when using this method. For best results, use .config.

mk/config.mk

The Redox build system uses several Makefiles, most of which are in the mk directory. Most settings of interest have have been grouped together in mk/config.mk.

Feel free to open mk/config.mk in your favorite editor and have a look through it; just be sure not to apply any changes:

nano mk/config.mk

The mk/config.mk file should never be modified directly, especially if you are contributing to the Redox project, as doing so could create conflicts in the make pull command.

To apply lasting changes to environment variables, please refer to the .config section. To apply changes only temporarily, see the Command Line section.

build.sh

The build.sh script allows you to easily set ARCH, FILESYSTEM_CONFIG and CONFIG_NAME when running make. If you are not changing the values very often, it is recommended that you set the values in .config rather than use build.sh. But if you are testing against different CPU architectures or configurations, this script can help minimize effort, errors and confusion.

./build.sh [-a <ARCH>] [-c <CONFIG_NAME>] [-f <FILESYSTEM_CONFIG>] <TARGET> ...

The TARGET parameter may be any valid make target, although the recommended target is qemu. Additional variable settings may also be included, such as gpu=no

The default value of FILESYSTEM_CONFIG is constructed from ARCH and CONFIG_NAME: config/$ARCH/$CONFIG_NAME.toml.

The default values for ARCH and CONFIG_NAME are x86_64 and desktop, respectively. These produce a default FILESYSTEM_CONFIG value of config/x86_64/desktop.toml.

Filesystem Configuration

The packages to be included in the final Redox image are determined by the chosen filesystem configuration file, which is a .toml file (e.g., config/x86_64/desktop.toml). Open desktop.toml and have a look through it:

nano config/x86_64/desktop.toml

For each supported CPU architecture, there are some filesystem configurations to choose from. For x86_64, there are desktop, demo and server configurations, as well as a few others. For i586, there are also some stripped down configurations for embedded devices or legacy systems with minimal RAM. Feel free to browse the config/x86_64 directory for more examples.

For more details on the filesystem configuration, and how to add additional packages to the build image, please see the Including Programs in Redox page.

Feel free to create your own filesystem configuration.

CPU Architecture Codenames

The Redox build system supports cross-compilation to other CPU architectures. The CPU architecture that Redox is built for (specified by the ARCH environment variable) usually determines the filesystem configuration file that will be used by the build system.

See the currently supported CPU architectures by Redox below:

The filesystem configurations for a given CPU architecture can be found in the config folder's correspondingly named sub-directory (e.g. config/x86_64).

Filesystem Size

The filesystem size is the total amount of storage space allocated for the filesystem that is built into the image, including all programs. It is specified in Megabytes (MB). The typical size is 512MB, although some configs (e.g., demo) are larger. The filesystem must be large enough to accommodate the packages included in the filesystem. For a livedisk system, the filesystem must not exceed the size of your system's RAM, and must also leave room for the package's installation and system execution.

The filesystem size is normally set from the filesystem configuration file, e.g. config/x86_64/demo.toml.

[general]
...
filesystem_size = 768
...

To change this, it is recommended that you create your own filesystem configuration and apply changes there. However, this can be temporarily overridden on the make command line, e.g.:

make FILESYSTEM_SIZE=512 image qemu

⚠️ Warning: setting the filesystem_size value too low will produce an error resembling the following:

thread 'main' panicked at src/lib.rs:94:53:
called `Result::unwrap()` on an `Err` value: Error(Path("/tmp/redox_installer_759506/include/openssl/.pkgar.srtp.h"), State { next_error: Some(Os { code: 28, kind: StorageFull, message: "No space left on device" }), backtrace: InternalBacktrace { backtrace: None } })

Filesystem Customization

The Redox image can be customized by tweaking the configuration files at config/$ARCH/*.toml. However, it is recommended that you create your own configuration file and apply changes there. (The configuration files at config/$ARCH can override the data type values from the filesystem templates at config)

Creating a custom filesystem configuration

The following items describe the process for creating a custom filesystem configuration file (my-desktop.toml):

1. Create the my-desktop.toml file from an existing filesystem configuration:

   cp config/$ARCH/desktop.toml config/$ARCH/my_desktop.toml
   

2. Add the following to the .config file to set the new configuration as the build system's default:

   CONFIG_NAME?=my_desktop
   

Many filesystem configuration settings can be adjusted. See the templates in the config folder for reference.

💡 Tip: files named with the prefix "my-" in the redox repo are git-ignored. Be sure to follow this convention for all custom filesystem configurations to avoid accidentally committing them to the Redox project.

Adding a package to the filesystem configuration

In the following example, the acid package is added to the my_desktop.toml configuration:

1. Open the my-desktop.toml file:

   nano config/$ARCH/my-desktop.toml
   

2. Add the acid package to the [packages] section:

   [packages]
   acid = {}
   

3. Build the acid package and update the Redox image:

   make rp.acid
   

Done! The acid package is now included in your Redox image.

Binary Packages

By default, the Redox build system builds all packages from source (i.e., recipes). If you want to use pre-compiled packages from our build server, however, there's a TOML option for it.

This is useful for some purposes, such as producing development builds, confirming package status from the Redox package server, and reducing image build time with large programs.

1. Open the my-desktop.toml file:

   nano config/$ARCH/my-desktop.toml
   

2. Add the binary package below the [packages] section:

   [packages]
   ...
   new-package = "binary"
   ...
   

3. Download and add the binary package on your Redox image:

   make image
   

4. Open QEMU to verify your binary package:

   make qemu
   

REPO_BINARY

In the previous example, the build system's default behavior was overridden by explicitly setting a package to use a pre-built binary. To configure the build system to download pre-built packages by default, however, we can set the REPO_BINARY environment variable (REPO_BINARY?=1).

When REPO_BINARY is enabled, the Redox image is made to use pre-built binaries for all packages assigned to {}; when REPO_BINARY is disabled, however, those same packages are compiled from source (i.e., recipes).

For example:

[packages]
...
package-name1 = {} # use the REPO_BINARY setting ("source" if 0; "binary" if 1)
package-name2 = "binary" # pre-built package
package-name3 = "source" # source-based recipe
...

Local Recipe Changes

By default every time a recipe build is triggered, Cookbook will update the recipe source. Cookbook will check the tarball BLAKE3 hash from the recipe configuration (recipe.toml), or pull from the origin remote when the recipe source is a Git repository. This will also remove local changes that are not saved in a branch.

To preserve and use local changes and skip updating the source for a specific recipe, change the recipe type to "local" in the filesystem configuration, for example:

[packages]
...
package-name = "local"
...

An old way for preserving and using local changes by commenting out the [source] section at the top of the file of a recipe.toml is also working but less recommended as it's prone to merge conflicts when pulling Redox repository:

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

Advanced Cookbook Options

This section has details of the Cookbook Environment Variables options.

Cookbook TUI Mode

Cookbook has a TUI mode which is enabled by default. This mode speedup the build process because it allows the source fetch and compilation to be done in parallel. When the CI environment variable is set the TUI mode will be disabled, which is desired for builds under Continuous Integration (CI).

Cookbook Offline Mode

Cookbook also has a mode where it will reduce Internet activity by adding REPO_OFFLINE=1 into .config. This mode is useful when you are in places where the Internet connection is slow or absent, or when you want a fixed build system state or faster incremental compilation.

In this mode, Cookbook will not update the source of any recipe or a package binary if also set with REPO_BINARY=1. It also adds the --offline option to some Cargo build methods inside recipes where it is supported. When Cookbook or Cargo must access the Internet because sources do not exist locally it will throw an error instead.

To temporarily allow Cookbook and Cargo to have Internet activity and update sources, run make f.package-name (single recipe source fetch) or make fetch (to fetch all enabled recipe sources), as these commands will ignore the REPO_OFFLINE environment variable.

Cookbook Logs

When export COOKBOOK_LOGS=true is set, all build logs will be written into the build/logs/$TARGET directory. This is enabled by default when TUI mode is enabled because build logs are captured anyway. When logs are enabled it can alter the build script and maybe hide some essential progress bar. Which is why when CI=1, logs are disabled.

Under the hood when the TUI mode or log capture is enabled, Cookbook will try to provide pseudo-terminal support and pipe them as-is to the terminal, then strip colors before saving them to logs.

Cookbook Verbosity

When export COOKBOOK_VERBOSE=false is set, it disables certain debug logs and disables the GNU Bash's set -x command, if combined with CI=1 COOKBOOK_LOGS=true, it will hide success build logs to the terminal.

Usually you want to combine CI=1 COOKBOOK_LOGS=true COOKBOOK_VERBOSE=false because it will not replace build logs that are doing the build instead of caching it and creating a minimally distracting build output on terminal.

Cookbook Compressed Packages

When export COOKBOOK_COMPRESSED=true is set, it will package software with compression turned on. Under the hood it's compressing with the LZMA2 algorithm which is quick to decompress but slow to compress.

It is not enabled by default because it uses considerable CPU time to compress and storage saving is negligible compared to Cookbook Clean Target.

Cookbook Clean Build

When export COOKBOOK_CLEAN_BUILD=true is set, it will always remove the build directory before building. This is intended for build servers where build consistency matters and avoid a build failure due to a stale build directory. It has the side effect of disabling incremental compilation thus generally avoided for local development.

Cookbook Clean Target

When export COOKBOOK_CLEAN_TARGET=true is set, it will remove the build, stage, and sysroot directories after a build success. This is intended to save storage space for local development that frequently jumps between recipes.

Unlike COOKBOOK_CLEAN_BUILD, it allows inspection of build directory and allows incremental compilation if build is failing. It does not allow visualization of the build and stage directories but creates stage.files which contains tree of files in the stage directory before deletion.

Cookbook Web Generator

When export COOKBOOK_WEB=true is set, it will create a web directory containing HTML files for published repo. It contains much more information including the published file tree and dependents, intended for easy browsing.