Redox OS: Build System Deployment and Usage Guide

This guide provides comprehensive instructions for deploying and using the Redox OS build system. Redox OS is an open-source operating system written in Rust, focusing on safety, efficiency, and performance.

1. Prerequisites

To build Redox OS, you will need a Linux-based system. The recommended way to build Redox is using podman or docker.

Software Requirements:

• Podman or Docker: For containerized builds.
  • Podman Installation Guide
  • Docker Installation Guide
• Git: For cloning the repository.
  • sudo apt install git (Debian/Ubuntu)
  • sudo dnf install git (Fedora)
• Rust Toolchain (Optional, for host development): If you plan to contribute to the build system itself or other Rust components on your host machine.
  • Install rustup: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • Ensure cargo is in your PATH.

Hardware Requirements:

• RAM: At least 8GB recommended.
• Disk Space: At least 50GB of free disk space for the build artifacts.
• CPU: A multi-core processor is highly recommended for faster build times.

2. Installation

The Redox OS build system is primarily designed to be run within a container.

1. Clone the Redox OS repository:

   git clone https://gitlab.redox-os.org/redox-os/redox.git
   cd redox
   

2. Initialize and Update Submodules: The Redox OS build system relies on various submodules for its components.

   git submodule update --init --recursive
   

3. Configuration

The Redox build system uses environment variables and configuration within its build scripts. Most configuration is handled automatically by the cookbook utility within the container.

Key Configuration Concepts:

• COOKBOOK_SYSROOT: This environment variable points to the sysroot of the Redox OS build. It's crucial for cross-compilation and dynamic linking.
• COOKBOOK_DYNAMIC: Set to 1 when building dynamically linked binaries.
• COOKBOOK_CONFIGURE_FLAGS, COOKBOOK_CMAKE_FLAGS, COOKBOOK_MESON_FLAGS: These arrays hold standard configuration flags for different build systems (Autotools, CMake, Meson) used by various packages within Redox. They are dynamically populated based on whether a dynamic or static build is performed (see SHARED_PRESCRIPT in src/cook/script.rs).
• Mirrors: The build system can use mirrors for fetching sources. This is configured internally via translate_mirror in src/config.rs and src/cook/fs.rs.

No manual configuration is typically required for a standard build. The build process handles these settings automatically.

4. Build & Run

The recommended way to build and run Redox OS is using the provided podman or docker scripts.

Build Redox OS

1. Build using Podman (Recommended):

   ./podman.sh
   

   This command will:

   • Pull or build the necessary redox-builder container image.
   • Mount the Redox OS source directory into the container.
   • Execute the build process inside the container.
   • The build output will be located in the build/ directory.

2. Build using Docker (Alternative):

   ./docker.sh
   

   This command performs the same actions as ./podman.sh but uses Docker instead.

Run Redox OS

After a successful build, a disk image will be created (e.g., build/harddrive.img). You can run this image in a virtual machine.

1. Run in QEMU (within the container):

   ./podman.sh qemu
   

   or

   ./docker.sh qemu
   

   This will launch QEMU with the built Redox OS image.

2. Run in QEMU (manually on host): If you want to run QEMU directly on your host machine (assuming QEMU is installed), you can find the generated image and run it.

   # After a successful build, the image is in build/harddrive.img
   qemu-system-x86_64 -drive file=build/harddrive.img,format=raw -m 4G -cpu host -smp 4 -vga std -display sdl
   

   (Adjust QEMU parameters as needed for your system and desired configuration.)

Development Workflow

For developing and testing individual packages within Redox, the cookbook utility is used. This is typically invoked within the builder container.

Example: Building a specific package (e.g., relibc)

# Enter the builder container (using podman as an example)
podman run -it --rm -v "$(pwd)":/redox redox-builder bash

# Inside the container, navigate to the redox directory
cd /redox

# Build a specific package (e.g., relibc)
./cookbook.sh relibc

5. Deployment

Redox OS is an operating system, not an application to be deployed on existing platforms. Deployment means running it on a virtual machine or real hardware.

Virtual Machine Deployment

As shown in the "Run Redox OS" section, you can run the generated harddrive.img in virtual machine software like QEMU, VirtualBox, or VMware.

• QEMU: The most common and supported method.
  • qemu-system-x86_64 -drive file=build/harddrive.img,format=raw -m 4G -cpu host -smp 4 -vga std -display sdl
• VirtualBox/VMware: Create a new virtual machine and attach build/harddrive.img as a raw disk image. Refer to your VM software's documentation for specific steps.

Real Hardware Deployment

Running Redox OS on real hardware is an advanced topic and requires careful consideration of hardware compatibility.

1. Check Hardware Compatibility: Refer to the Redox Book's Hardware Compatibility section.

2. Flash to USB Drive: You can flash the build/harddrive.img to a USB drive using tools like dd (use with extreme caution as incorrect usage can erase your system drive).

   # Identify your USB drive (e.g., /dev/sdX, BE VERY CAREFUL!)
   lsblk
   
   # Flash the image
   sudo dd if=build/harddrive.img of=/dev/sdX bs=4M status=progress
   

   Replace /dev/sdX with the correct device name for your USB drive.

6. Troubleshooting

Common Issues and Solutions

• "Error: permission denied" when running ./podman.sh or ./docker.sh:

  • Ensure the scripts are executable: chmod +x podman.sh docker.sh
  • Ensure your user has permissions to run podman or docker commands. You might need to add your user to the docker group (sudo usermod -aG docker $USER) and then log out and back in.

• Build fails inside the container with "No space left on device":

  • The build process requires significant disk space. Ensure your host machine has enough free space where the Redox repository is located and where Podman/Docker stores its images/volumes.
  • Clean up old Docker/Podman images and containers: docker system prune or podman system prune.

• git submodule update --init --recursive fails or reports issues:

  • Check your internet connection.
  • Ensure Git is correctly installed and configured.
  • Try running git submodule deinit -f . and then git submodule update --init --recursive again.

• podman.sh or docker.sh fails to pull the redox-builder image:

  • Verify your internet connection.
  • Check if the container registry is accessible.
  • Ensure Podman/Docker is correctly configured and running.

• QEMU fails to start or shows a black screen:

  • Ensure the build process completed successfully and build/harddrive.img exists and is not empty.
  • Check QEMU installation and its dependencies on your host system.
  • Try different QEMU parameters (e.g., -vga std, -vga cirrus).
  • Increase allocated RAM (-m).

• Build takes a very long time:

  • Redox OS is a full operating system; a complete build can take several hours, especially on less powerful hardware.
  • Ensure your system meets the recommended hardware requirements.
  • Ensure you have enough CPU cores allocated to the container (Podman/Docker typically uses all available by default, but check your configuration).

• Specific package build failure:

  • The build logs inside the container will provide details. Look for error messages related to cargo, make, cmake, or meson.
  • If you're modifying a package, ensure your changes are compatible with the Redox environment and its toolchain.
  • Consult the Redox Chat and Support for assistance with specific build errors.