Building Redox

Congrats on making it this far! Now you will build Redox. This process is mainly for creating images targeting x86-64 machines (Intel/AMD). The process is similar when targeting i586, ARM64 and RISC-V.

Redox build system is using Rootless Podman. Podman is used to avoid bugs from different build environments (operating systems). You can find out more about Podman on the Official Podman documentation.

Podman Build Overview

Podman is a container manager that creates containers to execute a Linux distribution image. In our case, we are creating an Debian image, with a Rust installation and all the dependencies needed to build the system and programs.

New Working Directory

📝 Note: If you have cloned our official repository, go to Existing Working Directory.

1. Open a terminal and ensure you have the curl program installed. You can use apt, dnf or apk depending on your operating system.

   which curl || sudo apt-get install curl
   

2. Create a new directory and run podman_bootstrap.sh inside of it. This will clone the repository, install Podman and extra software such as Rust, Git and QEMU. It's a good practice to check the content of the script before launching it.

   mkdir -p ~/tryredox && cd $_
   

   curl -sf https://gitlab.redox-os.org/redox-os/redox/raw/master/podman_bootstrap.sh -o podman_bootstrap.sh
   

   time bash -e podman_bootstrap.sh
   

   The installation may take about 15 minutes on good network condition. You may be asked for some question and sudo prompt along the installation.

3. Update your path to include cargo and the Rust compiler.

   source ~/.cargo/env
   

4. Navigate to the redox directory.

   cd ~/tryredox/redox
   

5. Create a configuration file and take a moment to read our Build Configuration Settings. The build configuration is written to .config, and we recommend to start with REPO_BINARY=1 to speed up image build by downloading prebuilt programs instead of compiling them.

   nano .config
   

   REPO_BINARY=1
   

6. Build the system. The time needed in the first execution depends on computer, system, and network performance/condition.

   time make all
   

Existing Working Directory

If you already have the build system, simply perform the following steps:

1. Change to your working directory

   cd ~/tryredox/redox
   

2. Update the build system and wipe all compiled binaries

   make clean pull
   

3. Install Podman. If your Linux distribution is not supported, check the installation instructions to determine which dependencies are needed. Or, run the following in your redox base` directory:

   ./podman_bootstrap.sh -d
   

4. Make sure the configuration for Podman Build stays enabled

   nano .config
   

   PODMAN_BUILD?=1
   

5. Build the Redox image.

   make all
   

Run in a virtual machine

You can immediately run the new image (build/x86_64/desktop/harddrive.img) in a virtual machine with the following command:

make qemu

The emulator will display the Redox GUI (Orbital). See Using the emulation for general instructions and Trying out Redox for things to try.

Run without a GUI

To run the virtual machine without a GUI, use:

make qemu gpu=no

If you want to capture the terminal output, read the Debug Methods section.

💡 Tip: if you encounter problems running the virtual machine, try turning off various virtualization features with make qemu kvm=no or make qemu iommu=no. These same arguments can also be used with build.sh.

QEMU Tap For Network Testing

Expose Redox to other computers in the same local network. Configure QEMU with a "TAP" which will allow other computers to test Redox client/server/networking capabilities.

Please join the chat if this is something you are interested in pursuing.

Using build.sh script

build.sh is a shell script for quickly invoking make for a specified variant, CPU architecture, and output file. It is created for quick one-off commands to build everything without changing settings from .config file.

💡 Tip: for doing Redox development, such settings should usually be configured in the .config file (see the Configuration Settings page). But for users who are just trying things out, the build.sh script can be used to run make for you.

You can also provide qemu option to run the virtual machine:

./build.sh -a i586 -c demo qemu

This will build build/i586/demo/harddrive.img (if it doesn't already exist) and run it in the QEMU emulator.

Example 1

The following builds the server variant of Redox for the i586 (32-bit Intel/AMD) CPU architecture (defined in config/i586/server.toml):

./build.sh -a i586 -c server live

The resulting image is build/i586/server/livedisk.iso, which can be used to install Redox from a USB device.

Example 2

The following builds the desktop variant of Redox for the aarch64 (64-bit ARM) CPU architecture (defined in config/aarch64/desktop.toml).

./build.sh -f config/aarch64/desktop.toml qemu

The resulting image is build/aarch64/desktop/harddrive.img, which is then run in the QEMU emulator upon completion of the build.

More options

Details of build.sh and other settings are described in the Configuration Settings page.

💡 Tip: The script's underlying make command doesn't keep any record of the build settings used between build.sh runs. If you are going to use build.sh repeatedly, it's recommended that you do so consistently.

Next Step

• The Build System Reference page to know our build system organization, the Makefile commands and how it works.
• The Testing on Real Hardware section contains guide for creating a bootable image into real hardware.
• The Advanced Podman Build contains more information about how the podman build works and how manual installation can be performed.
• The build process fetches files from the Redox Gitlab server. If this happens, first check for typos in the git URL. If that doesn't solve the problem, try again later, and if it continues to happen, you can let us know through the chat.

Contributor Note

If you intend to contribute to Redox or its subprojects, please read the CONTRIBUTING document to understand how the Redox build system works, and how to set up your repository fork appropriately.

If you encounter any bugs, errors, obstructions, or other annoying things, please join the chat or report the issue to the build system repository or a proper repository for the component. Thanks!