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 Configuration
  • 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
  • Cookbook Offline Mode

Environment Variables

The default values for the build system's environment 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 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 Configuration

In addition to .config, cookbook.toml is a configuration file that is used by Cookbook and has more customization. Any configuration in this file will override configuration from .config or environment variables. The cookbook.toml configuration below can be used as a template:

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

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

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

Each Cookbook configuration defaults to environment variables which are:

📝 Note: REPO_OFFLINE=1 and REPO_NONSTOP=1 are the recommended ways to set options instead of COOKBOOK_OFFLINE=true and COOKBOOK_NONSTOP=true 📝 Note: .config cannot be used to save COOKBOOK_* options as those are not Makefile variables, so you need to use cookbook.toml to make options persist 💡 Tip: Running Cookbook with CI=1 COOKBOOK_LOGS=true COOKBOOK_NONSTOP=true COOKBOOK_VERBOSE=false will hide successful build logs in the terminal 💡 Tip: Mirrors option can also be used to override binary builds source URL.

Changing the QEMU CPU Core and Memory Quantity

For example, 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-threads>
QEMU_MEM?=<number-in-mb>

Command Line

The default settings in mk/config.mk can be manually 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/your-cpu/*.toml. However, it is recommended that you create your own configuration file and apply changes there. (The configuration files at config/your-cpu 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/your-cpu-arch/desktop.toml config/your-cpu-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/your-cpu/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/your-cpu/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"

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 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.