Introduction

This is the Redox OS book, which will go through (almost) everything about Redox: design, philosophy, how it works, how you can contribute, how to deploy Redox, and much more.

Please note that this book is work-in-progress.

If you want to skip straight to trying out Redox, see the Getting started page.

If you want to contribute to Redox, read the following guides: CONTRIBUTING and Developing for Redox.

Conventions

Notices

The following notices are commonly used throughout the book to convey noteworthy information:

What is Redox?

Redox OS is a general-purpose operating system written in Rust. Our aim is to provide a fully functioning Unix-like microkernel-based operating system, that is secure, reliable and free.

We have modest compatibility with POSIX, allowing Redox to run many programs without porting.

We take inspiration from Plan 9, Minix, seL4, Linux, OpenBSD and FreeBSD. Redox aims to synthesize years of research and hard won experience into a system that feels modern and familiar.

This book is written in a way that you doesn't require any prior knowledge of Rust or OS development.

Introducing Redox OS

Redox OS is microkernel-based operating system, with a large number of supported programs and components, to create a full-featured user and application environment. In this chapter, we will discuss the goals, philosophy and scope of Redox.

Our Goals

Redox is an attempt to make a complete, fully-functioning, general-purpose operating system with a focus on safety, freedom, stabillity, correctness, and pragmatism.

We want to be able to use it, without obstructions, as a complete alternative to Linux/BSD in our computers. It should be able to run most Linux/BSD programs with minimal modifications.

We're aiming towards a complete, stable, and safe Rust ecosystem. This is a design choice, which hopefully improves correctness and security (see the Why Rust page).

We want to improve the security design when compared to other Unix-like operating systems by using safe defaults and limiting insecure configurations where possible.

The non-goals of Redox

We are not a Linux/BSD clone, or POSIX-compliant, nor crazy scientists, who wish to redesign everything. Generally, we stick to well-tested and proven correct designs. If it ain't broken don't fix it.

This means that a large number of programs and libraries will be compatible with Redox. Some things that do not align with our design decisions will have to be ported.

The key here is the trade off between correctness and compatibility. Ideally, you should be able to achieve both, but unfortunately, you can't always do so.

Our Philosophy

Redox OS is predominately MIT X11-style licensed, including all software, documentation, and fonts. There are only a few exceptions to this, which are all licensed under other compatible open-source licenses.

The MIT X11-style license has the following properties:

• It gives you, the user of the software, complete and unrestrained access to the software, such that you may inspect, modify, and redistribute your changes
  • Inspection Anyone may inspect the software for security vulnerabilities
  • Modification Anyone may modify the software to fix security vulnerabilities
  • Redistribution Anyone may redistribute the software to patch the security vulnerabilities
• It is compatible with GPL licenses - Projects licensed as GPL can be distributed with Redox OS
• It allows for the incorporation of GPL-incompatible free software, such as OpenZFS, which is CDDL licensed

The license does not restrict the software that may run on Redox, however -- and thanks to the microkernel architecture, even traditionally tightly-coupled components such as drivers can be distributed separately, so maintainers are free to choose whatever license they like for their projects.

Redox intends to be free forever, because we aim to be a foundational piece in creating secure and resilient systems.

Why a New OS?

The essential goal of the Redox project is to build a robust, reliable and safe general-purpose operating system. To that end, the following key design choices have been made.

Written in Rust

Wherever possible, Redox code is written in Rust. Rust enforces a set of rules and checks on the use, sharing and deallocation of memory references. This almost entirely eliminates the potential for memory leaks, buffer overruns, use after free, and other memory errors that arise during development. The vast majority of security vulnerabilities in operating systems originate from memory errors. The Rust compiler prevents this type of error before the developer attempts to add it to the code base.

Benefits

The following items summarize the Rust benefits:

• Memory-Safety

  All memory allocations are verified by the compiler to prevent bugs.

• Thread-Safety

  Concurrent code in programs is immune to data races.

• NULL-Safety

  NULLs can't cause undefined behavior.

Microkernel Architecture

The Microkernel Architecture moves as much components as possible out of the operating system kernel. Drivers, subsystems and other operating system functionality run as independent processes on user-space (daemons). The kernel's main responsibility is the coordination of these processes, and the management of system resources to the processes.

Most kernels, other than some real-time operating systems, use an event-handler design. Hardware interrupts and application system calls, each one trigger an event invoking the appropriate handler. The kernel runs in supervisor-mode, with access to all the system's resources. In Monolithic Kernels, the operating system's entire response to an event must be completed in supervisor mode. An error in the kernel, or even a misbehaving piece of hardware, can cause the system to enter a state where it is unable to respond to any event. And because of the large amount of code in the kernel, the potential for vulnerabilities while in supervisor mode is vastly greater than for a microkernel design.

In Redox, drivers and many system services can run in user-mode, similar to user programs, and the system can restrict them so they can only access the resources that they require for their designated purpose. If a driver fails or panics, it can be ignored or restarted with no impact on the rest of the system. A misbehaving piece of hardware might impact system performance or cause the loss of a service, but the kernel will continue to function and to provide whatever services remain available.

Thus Redox is an unique opportunity to show the microkernel potential for the mainstream operating systems universe.

Benefits

The following items summarize the microkernel benefits:

• True modularity

  You can enable/disable/update most system components without a system restart, similar to but safer than some modules on monolithic kernels and livepatching.

• Bug isolation

  Most system components run in user-space on a microkernel system. Because of this some types of bugs in most system components won't crash or damage the system or kernel.

• Restartless design

  A mature microkernel changes very little (except for bug fixes), so you won't need to restart your system very often to update it.

  Since most of the system components are in userspace they can be restarted/updated on-the-fly, reducing the downtime of servers a lot.

• Easy to develop and debug

  Most of the system components run in userspace, simplifying the testing and debugging.

You can read more about the above benefits on the Microkernels page.

Advanced Filesystem

Redox provides an advanced filesystem, RedoxFS. It includes many of the features in ZFS, but in a more modular design.

More details on RedoxFS can be found on the RedoxFS page.

Unix-like Tools and API

Redox provides a Unix-like command interface, with many everyday tools written in Rust but with familiar names and options. As well, Redox system services include a programming interface that is a subset of the POSIX API, via relibc. This means that many Linux/POSIX programs can run on Redox with only recompilation. While the Redox team has a strong preference for having essential programs written in Rust, we are agnostic about the programming language for programs of the user's choice. This means an easy migration path for systems and programs previously developed for a Unix-like platform.

Redox Use Cases

Redox is a general-purpose operating system that can be used in many situations. Some of the key use cases for Redox are as follows.

Server

Redox has the potential to be a secure server platform for cloud services and web hosting. The improved safety and reliability that Redox can provide, as it matures, makes it an excellent fit for the server world. Work remains to be done on support for important server technologies such as databases and web servers, as well as compatibility with high-end server hardware.

Redox has plans underway for virtualization support. Although running an instance of Linux in a container on Redox will lose some of the benefits of Redox, it can limit the scope of vulnerabilities. Redox-on-Redox and Linux-on-Redox virtualization have the potential to be much more secure than Linux-on-Linux. These capabilities are still a ways off, but are among the goals of the Redox team.

Desktop

The development of Redox for the desktop is well underway. Although support for accelerated graphics is limited at this time, Redox does include a graphical user interface, and support on Rust-written GUI libraries like winit, Iced and Slint.

A demo version of Redox is available with several games and programs to try. However, the most important objective for desktop is to host the development of Redox. We are working through issues with some of our build tools, and other developer tools such as editors have not been tested under daily use, but we continue to make this a priority.

Due to a fairly limited list of currently supported hardware, once self-hosted development is available the development can be done inside of Redox with more quick testing. We are adding more hardware compatibility as quickly as we can, and we hope to be able to support the development on a wide array of desktops and notebooks in the near future.

Infrastructure

Redox's modular architecture make it ideal for many telecom infrastructure applications, such as routers, telecom components, edge servers, etc., especially as more functionality is added to these devices. There are no specific plans for remote management yet, but Redox's potential for security and reliability make it ideal for this type of application.

Embedded and IoT

For embedded systems with complex user interfaces and broad feature sets, Redox has the potential to be an ideal fit. As everyday appliances become Internet-connected devices with sensors, microphones and cameras, they have the potential for attacks that violate the privacy of consumers in the sanctity of their homes. Redox can provide a full-featured, reliable operating system while limiting the likelihood of attacks. At this time, Redox does not yet have touchscreen support, video capture, or support for sensors and buttons, but these are well-understood technologies and can be added as it becomes a priority.

Mission-Critical Applications

Although there are no current plans to create a version of Redox for mission-critical applications such as satellites or air safety systems, it's not beyond the realm of possibility. As tools for correctness proofs of Rust software improve, it may be possible to create a version of Redox that is proven correct, within some practical limits.

How Redox Compares to Other Operating Systems

We share quite a lot with other operating systems.

System Calls

The Redox userspace API is Unix-like. For example, we have the open, pipe, pipe2, lseek, read, write, brk, execv POSIX functions, and so on. Currently, we implement userspace analogues of most Unix-like system calls (on monolithic kernels). The kernel syscall interface itself is unstable and may not be similar at all, but is closely related to the higher-level POSIX APIs built on top of them, at the moment.

However, Redox does not necessarily implement them as system calls directly. Much of the machinery for these functions (typically the man(2) functions) is provided in userspace through an interface library, relibc.

For example, the open POSIX function is called SYS_OPEN on relibc.

"Everything is a File"

In a model largely inspired by Plan 9, in Redox, resources can be socket-like or file-like, providing a more unified system API. Resources are named using paths, similar to what you would find in Linux or another Unix system. But when referring to a resource that is being managed by a particular resource manager, you can address it using a scheme-rooted path. We will explain this later, in the Schemes and Resources page.

The kernel

Redox's kernel is a microkernel. The architecture is largely inspired by MINIX and seL4.

In contrast to Linux or BSD, Redox has around 50,000 lines of kernel code, a number that is often decreasing. Most system services are provided in userspace, either in an interface library, or as daemons.

Having vastly smaller amount of code in the kernel makes it easier to find and fix bugs/security issues in an efficient way. Andrew Tanenbaum (author of MINIX) stated that for every 1,000 lines of properly written C code, there is a bug. This means that for a monolithic kernel with nearly 25,000,000 lines of C code, there could be nearly 25,000 bugs. A microkernel with only 50,000 lines of C code would mean that around 50 bugs exist (Tanenbaum Law).

It should be noted that in a microkernel the high amount of code (present in a monolithic kernel) is not removed, it's just moved to user-space daemons to make it less dangerous.

The main idea is to have system components and drivers that would be inside a monolithic kernel exist in user-space and follow the Principle of Least Authority (POLA). This is where every individual component is:

• Completely isolated in memory as separated user processes (daemons)
  • The failure of one component does not crash other components
  • Foreign and untrusted code does not expose the entire system
  • Bugs and malware cannot spread to other components
• Has restricted communication with other components
• Doesn't have Admin/Super-User privileges
  • Bugs are moved to user-space which reduces their power

All of this increases the reliability of the system significantly. This is important for users that want minimal issues with their computers or mission-critical applications.

Why Rust?

Why we wrote an operating system in Rust? Why even write in Rust?

Rust has enormous advantages, because for operating systems, security and stability matters a lot.

Since operating systems are such an integrated part of computing, they are the most important piece of software.

There have been numerous bugs and vulnerabilities in Linux, BSD, glibc, Bash, X11, etc. throughout time, simply due to the lack of memory allocation and type safety. Rust does this right, by enforcing memory safety statically.

Design does matter, but so does implementation. Rust attempts to avoid these unexpected memory unsafe conditions (which are a major source of security critical bugs). Design is a very transparent source of issues. You know what is going on, you know what was intended and what was not.

The basic design of the kernel/user-space separation is fairly similar to Unix-like systems, at this point. The idea is roughly the same: you separate kernel and user-space, through strict enforcement by the kernel, which manages system resources.

However, we have an advantage: enforced memory and type safety. This is Rust's strong side, a large number of "unexpected bugs" (for example, undefined behavior) are eliminated at compile-time.

The design of Linux and BSD is secure. The implementation is not. Many bugs in Linux originate in unsafe conditions (which Rust effectively eliminates) like buffer overflows, not the overall design.

We hope that using Rust we will produce a more secure and stable operating system in the end.

Unsafes

unsafe is a way to tell Rust that "I know what I'm doing!", which is often necessary when writing low-level code, providing safe abstractions. You cannot write a kernel without unsafe.

In that light, a kernel cannot be 100% verified by the Rust compiler, however the unsafe parts have to be marked with an unsafe, which keeps the unsafe parts segregated from the safe code. We seek to eliminate the unsafes where we can, and when we use unsafes, we are extremely careful.

This contrasts with kernels written in C, which cannot make guarantees about security without costly formal analysis.

You can find out more about how unsafe works in the relevant section of the Rust book.

Benefits

The following sections explain the Rust benefits.

Less likely to have bugs

The restrictive syntax and compiler requirements to build the code reduce the probability of bugs a lot.

Less vulnerable to data corruption

The Rust compiler helps the programmer to avoid memory errors and race conditions, which reduces the probability of data corruption bugs.

No need for C/C++ exploit mitigations

The microkernel design written in Rust protects against memory defects that one might see in software written in C/C++.

By isolating the system components from the kernel, the attack surface is very limited.

Improved security and reliability without significant performance impact

As the kernel is small, it uses less memory to do its work. The limited kernel code size helps us work towards a bug-free status (KISS).

Rust's safe and fast language design, combined with the small kernel code size, helps ensure a reliable, performant and easy to maintain core.

Thread-safety

The C/C++ support for thread-safety is quite fragile. As such, it is very easy to write a program that looks safe to run across multiple threads, but which introduces subtle bugs or security holes. If one thread accesses a piece of state at the same time that another thread is changing it, the whole program can exhibit some truly confusing and bizarre bugs.

You can see this example of a serious class of security bugs that thread-safety fixes.

In Rust, this kind of bug is easy to avoid: the same type system that keeps us from writing memory unsafety prevents us from writing dangerous concurrent access patterns

Rust-written Drivers

Drivers written in Rust are likely to have fewer bugs and are therefore more stable and secure.

Side Projects

Redox is a complete Rust operating system. In addition to the Redox kernel, our team is developing several side projects, including:

• RedoxFS - Redox file system inspired by ZFS.
• Ion - The Redox shell.
• Orbital - The desktop environment/display server of Redox.
• pkgutils - Redox package manager, with a command-line frontend and library.
• relibc - Redox C library.
• audiod - Redox audio server.
• bootloader - Redox boot loader.
• init - Redox init system.
• installer - Redox buildsystem builder.
• netstack - Redox network stack.
• redoxer - A tool to run/test Rust programs inside of a Redox VM.
• sodium - A Vi-like editor.
• games - A collection of mini-games for Redox (alike BSD-games).
• OrbTK - Cross-platform Rust-written GUI toolkit (in maintenance mode).
• and a few other exciting projects you can explore on the redox-os group.

We also have some in-house tools, which are collections of small, useful command-line programs:

• extrautils - Extra utilities such as reminders, calendars, spellcheck, and so on.
• binutils - Utilities for working with binary files.

We also actively contribute to third-party projects that are heavily used in Redox.

• uutils/coreutils - Cross-platform Rust rewrite of the GNU Coreutils.
• smoltcp - The TCP/IP stack used by Redox.

What tools are fitting for the Redox distribution?

The necessary tools for a usable system, we offer variants with fewer programs.

The listed tools fall into three categories:

1. Critical, which are needed for a full functioning and usable system.
2. Ecosystem-friendly, which are there for establishing consistency within the ecosystem.
3. Fun, which are "nice" to have and are inherently simple.

The first category should be obvious: an OS without certain core tools is a useless OS. The second category contains the tools which are likely to be non-default in the future, but nonetheless are in the official distribution right now, for the charm. The third category is there for convenience: namely for making sure that the Redox infrastructure is consistent and integrated.

Influences

This page explains how Redox was influenced by other operating systems.

(The list is ordered by influence level)

Minix

The most influential Unix-like system with a microkernel. It has advanced features such as system modularity, kernel panic resistence, driver reincarnation, protection against bad drivers and secure interfaces for process comunication.

Redox is largely influenced by Minix - it has a similar architecture but with a feature set written in Rust.

• How Minix influenced the Redox design

seL4

The most performant and simplest microkernel of the world.

Redox follow the same principle, trying to make the kernel-space small as possible (moving components to user-space and reducing the number of system calls, passing the complexity to user-space) and keeping the overall performance good (reducing the context switch cost).

Plan 9

This Bell Labs OS brings the concept of "Everything is a File" to the highest level, doing all the system communication from the filesystem.

• Drew DeVault explains the Plan 9
• Plan 9's influence on Redox

Linux

The most advanced monolithic kernel and biggest open-source project of the world. It brought several improvements and optimizations to the Unix-like world.

Redox tries to implement the Linux performance improvements in a microkernel design.

BSD

This Unix family included several improvements on Unix systems and the open-source variants of BSD added many improvements to the original system (like Linux did).

• FreeBSD - The Capsicum (a capability-based system) and jails (a sandbox technology) influenced the Redox namespaces implementation.

• OpenBSD - The system call, filesystem, display server and audio server sandbox and others influenced the Redox security.

Hardware Support

There are billions of devices with hundreds of models and architectures in the world. We try to write drivers for the most used devices to support more people. Support depends on the specific hardware, since some drivers are device-specific and others are architecture-specific.

Have a look at the HARDWARE.md document to see all tested computers.

CPU

• Intel - 64-bit (x86_64) and 32-bit (i686) from Pentium II and after with limitations.
• AMD - 64-bit (AMD64) and 32-bit.
• ARM - 64-bit (Aarch64) with limitations.

Why CPUs older than i686 aren't supported?

• i686 (essentially Pentium II) introduced a wide range of features that are critical for the Redox kernel.
• It would be possible to go all the way back to i486, but that would make us lose nice functions like fxsave/fxrstor and we would need to build userspace without any SSE code.
• i386 has no atomics (at all) which makes it not likely as a target.

Hardware Interfaces

• ACPI
• PCI
• USB

(Support for USB devices using hubs soon)

Video

• VGA - (BIOS)
• GOP (UEFI)
• LLVMpipe (OpenGL CPU emulation)

(Intel/AMD and others in the future)

Sound

• Intel chipsets
• Realtek chipsets
• PC speaker

(Sound Blaster soon)

Storage

• IDE (PATA)
• SATA (AHCI)
• NVMe

(USB soon)

Input

• PS/2 keyboards, mouse and touchpad
• USB keyboards, mouse and touchpad

Internet

• Intel Gigabit ethernet
• Intel 10 Gigabit ethernet
• Realtek ethernet

(Wi-Fi and Atheros ethernet soon)

I have a low-end computer, would Redox work on it?

A CPU is the most complex machine of the world: even the oldest processors are powerful for some tasks but not for others.

The main problem with old computers is the amount of RAM available (they were sold in a era where RAM chips were expensive) and the lack of SSE/AVX extensions (programs use them to speed up the algorithms). Because of this some modern programs may not work or require a lot of RAM to perform complex tasks.

Redox itself will work normally if the processor architecture is supported by the system, but the performance and stability may vary per program.

Important Programs

This page covers important programs and libraries supported by Redox.

Redox is designed to be source-compatible with most Unix, Linux and POSIX-compliant applications, only requiring compilation.

Currently, most GUI applications require porting, as we don't support X11 or Wayland yet.

Some important software that Redox supports:

• GCC
• LLVM
• FFMPEG
• OpenSSL
• Mesa3D
• SDL2
• Git
• RustPython
• GNU Bash

You can see all Redox components and ported programs on the build server list.

Getting started

Redox is still at experimental/alpha stage, but there are many things that you can do with it, and it's fun to try it out. You can start by downloading and running the latest release. Read the instructions for running in a virtual machine or running on real hardware.

The Building Redox page has information about configuring your system to build Redox, which is necessary if you want to contribute to the development. The Advanced Podman Build page gives a look under the hood of the build process to help you maintain your build environment.

By reading the Build System page you can have a complete understanding of the build system.

Running Redox in a Virtual Machine

• VirtualBox Instructions
• QEMU Instructions

Download the bootable images

This section will guide you to download the Redox images.

(You need to use the harddrive.img image variant for QEMU or VirtualBox)

Stable Releases

The bootable images for the 0.9.0 release are located on the build server release folder. To try Redox using a virtual machine such as QEMU or VirtualBox, download the demo variant, check the SHA256 sum to ensure it has downloaded correctly.

sha256sum $HOME/Downloads/redox_demo_x86_64_*_harddrive.img.zst

If you have more than one demo image in the Downloads directory, you may need to replace the * symbol with the date of your file.

If the demo variant doesn't boot on your computer, try the desktop and server variants.

Even if the desktop and server variants doesn't work, use the daily images below.

Daily Images

If you want to test the latest Redox changes you can use our bootable images created each day by opening the build server images and downloading your preferred variant. Once the download is complete, check the SHA256 sum.

(Sometimes our daily images can be one week old or more because of breaking changes)

Decompression

The Redox images are compressed using the Zstd algorithm, to decompress follow the steps below:

Linux

GUI

1. Install GNOME File Roller or KDE Ark (both can be installed from Flathub)
2. Open the Redox image and click on the "Extract" button

If you are using the GNOME Nautilus or KDE Dolphin file manager, right-click the file and select the option to extract the file.

Terminal

Install the Zstd tool and run:

zstd -d $HOME/Downloads/redox_*_x86_64_*_harddrive.img.zst

Windows

GUI

1. Install 7-Zip
2. Right-click the Redox image, hover the 7-Zip section and click on the option to extract the file or open the file on 7-Zip and extract

VirtualBox Instructions

To run Redox in a VirtualBox virtual machine you need to do the following steps:

1. Create a VM with 2048 MB of RAM memory (or less if using a simpler Redox image variant) and 32MB of VRAM (video memory)
2. Enable Nested Paging
3. Change the keyboard and mouse interface to PS/2
4. Change the audio controller to Intel HDA
5. Disable USB support
6. Go to the network settings of the VM and change the NIC model to 82540EM
7. Go to the storage settings of the VM, create an IDE controller and add the Redox bootable image on it
8. Start the VM!

If you want to install Redox on the VM create a VDI disk of 5GB (or less if you are using a simplier Redox image variant).

Command for the pre-installed image

If you want to do this using the command-line, run the following commands:

1. VBoxManage createvm --name Redox --register
   

2. VBoxManage modifyvm Redox --memory 2048 --vram 32 --nic1 nat --nictype1 82540EM \
   --cableconnected1 on --usb off --keyboard ps2 --mouse ps2 --audiocontroller hda \
   --audioout on --nestedpaging on
   

3. VBoxManage convertfromraw $HOME/Downloads/redox_demo_x86_64_*_harddrive.img harddrive.vdi
   

4. VBoxManage storagectl Redox --name SATA --add sata --bootable on --portcount 1
   

5. VBoxManage storageattach Redox --storagectl SATA --port 0 --device 0 --type hdd --medium harddrive.vdi
   

6. VBoxManage startvm Redox
   

Command for the Live ISO image

If you want to use the Live ISO run the following commands:

1. VBoxManage createvm --name Redox --register
   

2. VBoxManage modifyvm Redox --memory 2048 --vram 32 --nic1 nat --nictype1 82540EM \
   --cableconnected1 on --usb off --keyboard ps2 --mouse ps2 --audiocontroller hda \
   --audioout on --nestedpaging on
   

3. VBoxManage storagectl Redox --name SATA --add sata --bootable on --portcount 1
   

4. VBoxManage storageattach Redox --storagectl SATA --port 0 --device 0 --type dvddrive --medium $HOME/Downloads/redox_demo_x86_64_*_livedisk.iso
   

5. VBoxManage startvm Redox
   

QEMU Instructions

Linux

You can then run the image in your preferred emulator. If you don't have an emulator installed, use the following command (Pop!_OS/Ubuntu/Debian) to install QEMU:

sudo apt-get install qemu-system-x86

This command will run QEMU with various Redox-compatible features enabled:

SDL_VIDEO_X11_DGAMOUSE=0 qemu-system-x86_64 -d cpu_reset,guest_errors -smp 4 -m 2048 \
    -chardev stdio,id=debug,signal=off,mux=on,"" -serial chardev:debug -mon chardev=debug \
    -machine q35 -device ich9-intel-hda -device hda-duplex -netdev user,id=net0 \
    -device e1000,netdev=net0 -device nec-usb-xhci,id=xhci -enable-kvm -cpu host \
    -drive file=`echo $HOME/Downloads/redox_demo_x86_64_*_harddrive.img`,format=raw

💡 Tip: if you encounter an error with the file name, verify that the name passed into the previous command (i.e., $HOME/Downloads/redox_demo_x86_64_*_harddrive.img) matches the file you downloaded.

MacOSX Instructions (Intel)

To install QEMU on MacOSX, use the following command:

brew install qemu

📝 Note: The brew command is part of the Homebrew package manager for macOS.

This command will run QEMU with various Redox-compatible features enabled:

SDL_VIDEO_X11_DGAMOUSE=0 qemu-system-x86_64 -d cpu_reset,guest_errors -smp 4 -m 2048 \
    -chardev stdio,id=debug,signal=off,mux=on,"" -serial chardev:debug -mon chardev=debug \
    -machine q35 -device ich9-intel-hda -device hda-duplex -netdev user,id=net0 \
    -device e1000,netdev=net0 -device nec-usb-xhci,id=xhci -cpu max \
    -drive file=`echo $HOME/Downloads/redox_demo_x86_64_*_harddrive.img`,format=raw

💡 Tip: if you encounter an error with the file name, verify that the name passed into the previous command (i.e., $HOME/Downloads/redox_demo_x86_64_*_harddrive.img) matches the file you downloaded.

Windows

To install QEMU on Windows, follow the instructions here. The installation of QEMU will probably not update your command path, so the necessary QEMU command needs to be specified using its full path. Or, you can add the installation folder to your PATH environment variable if you will be using it regularly.

Following the instructions for Linux above, download the same redox_demo image. Then, in a Command window, cd to the location of the downloaded Redox image and run the following very long command:

"C:\Program Files\qemu\qemu-system-x86_64.exe" -d cpu_reset,guest_errors -smp 4 -m 2048 -chardev stdio,id=debug,signal=off,mux=on,"" -serial chardev:debug -mon chardev=debug -machine q35 -device ich9-intel-hda -device hda-duplex -netdev user,id=net0 -device e1000,netdev=net0 -device nec-usb-xhci,id=xhci -drive file=redox_demo_x86_64_2022-11-23_638_harddrive.img,format=raw

💡 Tip: if you get a filename error, change redox_demo_x86_64_*_harddrive.img to the name of the file you downloaded.

💡 Tip: if necessary, change "C:\Program Files\qemu\qemu-system-x86_64.exe" to reflect where QEMU was installed. The quotes are needed if the path contains spaces.

Using the QEMU emulation

As the system boots, it will ask you for a screen resolution to use, for example 1024x768. After selecting a screen size, the system will complete the boot, start the Orbital GUI, and display a Redox login screen. Login as user user with no password. The password for root is password. Use Ctrl+Alt+G to toggle the mouse behavior if you need to zoom out or exit the emulation. If your emulated cursor is out of alignment with your mouse position, type Ctrl+Alt+G to regain full cursor control, then click on your emulated cursor. Ctrl+Alt+F toggles between full screen and window views.

See Trying Out Redox for things to try.

If you want to try Redox in server mode, add -nographic -vga none to the command line above. You may wish to switch to the redox_server edition. There are also i686 editions available, although these are not part of the release.

Running Redox on Real Hardware

(You need to use the *livedisk.iso image variant for real hardware)

Since version 0.8.0, Redox can now be installed on certain hard drives and internal SSDs, including some vintage systems. USB devices are not yet supported during run-time, although they can be used for installation and livedisk boot. Check the release notes for additional details on supported hardware. Systems with unsupported devices can still use the livedisk method described below. Ensure you backup your data before trying Redox on your hardware.

Hardware support is limited at the moment, so your milage may vary. Only USB input devices (HID) work. There is a PS/2 driver, which works with the keyboards and touchpads in many (but not all) laptops. For networking, the Realtek and Intel ethernet controllers are currently supported.

On some computers, hardware incompatibilities, e.g. disk driver issues, can slow down Redox performance. This is not reflective of Redox in general, so if you find that Redox is slow on your computer, please try it on a different model for a better experience.

The current ISO image uses a bootloader to load the filesystem into memory (livedisk) and emulates a hard drive. You can use the system in this mode without installing. Although its use of memory is inefficient, it is fully functional and does not require changes to your device. The ISO image is a great way to try out Redox on real hardware.

Creating a Bootable USB Drive

Download an Compressed ISO Image

You can obtain a livedisk ISO image either by downloading the latest release, or by building one. The demo ISO is recommended for most laptops. After downloading completes, check the SHA256 sum:

sha256sum $HOME/Downloads/redox_demo_x86_64_*_livedisk.iso.zst

If you have more than one demo image in the Downloads directory, you may need to replace the * symbol with the date of your file.

If the demo variant doesn't boot on your computer, try the desktop and server variants.

If even the desktop and server variants don't work, use the daily images below.

Daily Images

If you want to test the latest Redox changes you can use our bootable images created each day by opening the build server images and downloading your preferred variant.

(Sometimes our daily images can be one week old or more because of breaking changes) Once the download is complete, check the SHA256 sum.

Decompress the ISO Image

Downloaded Redox images are compressed using the Zstd algorithm. To decompress an image, follow the appropriate steps below for your system:

Linux (GUI)

1. Install GNOME File Roller or KDE Ark (both can be installed from Flathub)
2. Open the Redox image and click on the "Extract" button

If you are using the GNOME Nautilus or KDE Dolphin file manager, right-click the file and select the option to extract the file.

Linux (Terminal)

Install the Zstd tool and run:

zstd -d $HOME/Downloads/redox_*_x86_64_*_livedisk.iso.zst

Windows (GUI)

1. Install 7-Zip
2. Right-click the Redox image, hover the 7-Zip section and click on the option to extract the file or open the file on 7-Zip and extract

Flash the ISO Image

Linux Instructions

We recommend using the Popsicle tool to flash ISO images to USB devices on Linux. To flash an image, follow the steps below:

1. Open the Releases section to open the Popsicle releases page and download the .AppImage file.
2. Open your file manager, click with the right-button of your mouse on the .AppImage file and open the "Properties", find the "Permissions" section and mark it as executable.
3. Open the Popsicle .AppImage file, select the downloaded Redox image and your USB device.
4. Confirm the flash process and wait until the progress bar reach 100%. If the flashing process completes with no errors, the flash was successful.

You can now restart your Linux machine and boot into Redox.

Windows Instructions

We recommend using the balenaEtcher tool on Windows to flash your USB device, follow the steps below:

1. Open the balenaEtcher website, click on the "Download Etcher" button and download the "Etcher for Windows" asset.
2. Install and open balenaEtcher, select the ISO image of Redox, select the USB device and click on "Flash!"
3. Confirm the permission to erase the data of your device and wait until the progress bar reach 100%

Now you can now restart your Windows system and boot into Redox.

Booting the System

Some computers don't come with USB booting enabled, to enable it press the keyboard key to open your UEFI or BIOS setup and allow the booting from USB devices (the name varies from firmware to firmware).

If you don't know the keyboard keys to open your UEFI/BIOS setup or boot menu, press the Esc or F keys (from 1 until 12), if you press the wrong key or got the wrong timing, don't stop your operating system boot process to try again, as it could corrupt your data.

Once the ISO image boots, the system will display the Orbital GUI. Log in as the user named user with no password. The password for root is password.

See Trying Out Redox for things to try.

To switch between Orbital and the console, use the following keys:

• F1: Display the console log messages
• F2: Open a text-only terminal
• F3: Return to the Orbital GUI

If you want to be able to boot Redox from your HDD or SSD, follow the Installation instructions.

Redox isn't currently going to replace your existing operating system, but testing is important to help us fix bugs and add features: boot Redox on your computer, and see what works.

Installing Redox on a Drive

Once you have downloaded or built your ISO image, you can install it to your internal HDD or SSD. Please back up your system before attempting to install. Note that at this time (Release 0.8.0), you can't install onto a USB device, or use a USB device for your Redox filesystem, but you can install from it.

After starting your livedisk system from a USB device or from CD/DVD, log in as the user named user with an empty password. Open a terminal window and type:

sudo redox_installer_tui

If Redox recognizes your device, it will prompt you to select a device to install on. Choose carefully, as it will erase all the data on that device. Note that if your device is not recognized, it may offer you the option to install on disk/live (the in-memory livedisk). Don't do this, as it will crash Redox.

You will be prompted for a redoxfs password. This is for a encrypted filesystem. Leave the password empty and press Enter if an encrypted filesystem is not required.

Once the installation completes, power off your computer, remove the USB device, power on your computer and you are ready to start using Redox!

Trying Out Redox

There are several programs, games, demos and other things to try on Redox. Most of these are not included in the regular Redox build, so you will need to run the demo variant from the list of available Redox images. Currently, Redox does not have Wi-Fi support, so if you need Wi-Fi for some of the things you want to do, you are best to use an Ethernet cable or run Redox in a virtual machine. Most of the suggestions below do not require Internet access.

On the demo variant, click on the Redox symbol in the bottom left corner of the screen. This brings up a menu, which, for the demo variant, includes some games. Feel free to give them a try!

Many of the available commands are in the folders /usr/bin and /ui/bin, which are included in your command path. Open a Terminal window and type ls /usr/bin (or ls /scheme/file/usr/bin) to see some of the available commands.

💡 Note: some of the games listed below are installed in the /usr/games directory, which is not detected in the terminal shell by default. To run these games from the terminal, you may have to specify the path of their executables.

Programs

FFMPEG

The most advanced multimedia library of the world.

• Run the following command to play an audio file:

ffplay music-name.mp3

(Change the audio format according to your file)

• Run the following command to play a video file:

ffplay video-name.mp4

(Change the video format according to your file)

COSMIC Files

An advanced file manager written in Rust, similar to GNOME Nautilus or Files.

COSMIC Editor

An advanced text editor written in Rust, similar to KDE KWrite.

Git

Git is a tool used for source code management.

• Run the following command to download a Git repository:

git clone repository-link

(Replace the "repository-link" part with your repository URL)

RustPython

RustPython is a Python 3.11+ interpreter written in Rust.

• Run the following command to run your Python script:

rustpython script-name.py

(The PyPI dependency manager is supported)

Periodic Table

The Periodic Table /ui/bin/periodictable is a demonstration of the OrbTk user interface toolkit.

Sodium

Sodium is Redox's Vi-like editor. To try it out, run the sodium command from a terminal.

A short list of the Sodium defaults:

For a more extensive list, run :help from within Sodium.

Rusthello

Rusthello is an advanced Reversi AI, made by HenryTheCat. It is highly concurrent, so this acts as a demonstration of Redox's multithreading capabilities. It supports various AIs, such as brute force, minimax, local optimizations, and hybrid AIs.

In a Terminal window, type rusthello.

Then you will get prompted for various things, such as difficulty, AI setup, and so on. When this is done, Rusthello interactively starts the battle between you and an AI or an AI and an AI.

Games

Freedoom

Freedoom is a first-person shooter in the form of content for a Doom engine. For Redox, we have included the PrBoom engine to run Freedoom. You can read more about Freedoom on the Freedoom website. PrBoom can be found on the PrBoom website.

Freedoom can be run by selecting its entry from the "Games" section of the Orbital system menu, or by running either /usr/games/freedoom1 or /usr/games/freedoom2 from a terminal.

Hit Esc and use the arrow keys to select Options->Setup->Key Bindings for keyboard help.

Neverball and Nevergolf

Neverball and Nevergolf are 3D pinball and golf games, respectively. Both can be run from the Orbital system menu, under "Games".

Sopwith

Sopwith is a game which allows players to pilot a small, virtual plane. The original game was written in 1984 and used PC graphics, but it is now presented to users using the SDL library. To play it, run the sopwith command from a terminal.

Syobon Action

Syobon Action is 2D side-scrolling platformer that you won't enjoy. To play it, run syobonaction from a terminal window. It's recommended that you read the GitHub page so you don't blame us.

Terminal Games Written in Rust

Also check out some games that have been written in Rust, and use the Terminal Window for simple graphics. In a Terminal window, enter one of the following commands:

• baduk - Baduk/Go
• dem - Democracy
• flappy - Flappy Bird clone
• ice - Ice Sliding Puzzle
• minesweeper - Minesweeper but it wraps
• reblox - Tetris-like falling blocks
• redoku - Sudoku
• snake - Snake

Building Redox

Congrats on making it this far! Now you will build Redox. This process is for x86-64 machines (Intel/AMD). There are also similar processes for i686 and AArch64/ARM64.

The build process fetches files from the Redox Gitlab server. From time to time, errors may occur which may result in you being asked to provide a username and password during the build process. If this happens, first check for typos in the git URL. If that doesn't solve the problem and you don't have a Redox GitLab login, try again later, and if it continues to happen, you can let us know through the chat.

To avoid bugs from different build environments (operating systems) we are using Rootless Podman for major parts of the build. Podman is invoked automatically and transparently within the Makefiles.

The TL;DR version is here. More details are available in the Advanced Podman Build page.

You can find out more about Podman on the Podman documentation.

(Don't forget to read the Build System page to know our build system organization and how it works)

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.

The build process is performed in your normal working directory, e.g., ~/tryredox/redox. Compilation of the Redox components is performed in the container, but the final Redox image (build/$ARCH/$CONFIG/harddrive.img or build/$ARCH/$CONFIG/livedisk.iso) is constructed using FUSE running directly on your host machine.

Setting PODMAN_BUILD to 1 in .config, on the make command line (e.g., make PODMAN_BUILD=1 all) or in the environment (e.g., export PODMAN_BUILD=1; make all) will enable Podman.

First, a base image called redox_base will be constructed, with all the necessary packages for the build system. A "home" directory will also be created in build/podman. This is the home directory of your container alter ego, poduser. It will contain the rustup install, and the .bashrc. This takes some time, but is only done when necessary. The tag file build/container.tag is also created at this time to prevent unnecessary image builds.

Then, various make commands are executed in containers built from the base image. The files are constructed in your working directory tree, just as they would for a non-Podman build. In fact, if all necessary packages are installed on your host system, you can switch Podman on and off relatively seamlessly, although there is no benefit of doing so.

The build process is using Podman's keep-id feature, which allows your regular User ID to be mapped to poduser in the container. The first time a container is built, it takes some time to set up this mapping. After the first container is built, new containers can be built almost instantly.

TL;DR - New or Existing Working Directory

New Working Directory

If you have already read the Building Redox instructions, but you wish to use Podman Build, follow these steps:

1. Ensure you have the curl program installed. e.g., for Pop!_OS/Ubuntu/Debian:

   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 and install Podman.

   mkdir -p ~/tryredox
   

   cd ~/tryredox
   

   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
   

   You may be asked which QEMU installation you want. Please select full.

   You may be asked which Podman container runtime you want to use, crun or runc. Choose crun, but runc will also work.

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

   source ~/.cargo/env
   

4. Navigate to the redox directory.

   cd ~/tryredox/redox
   

5. Build the system. This will take some time.

   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 binaries

   make pull clean
   

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

   nano .config
   

   PODMAN_BUILD?=1
   

   📝 Note: the initial container setup for the Podman build can take 15 minutes or more, but it is comparable in speed to native build after that.

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

📝 Note: if you are building the system using build.sh to change the CPU architecture or filesystem contents, you can also provide the qemu option to run the virtual machine:

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

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

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 within a LAN. 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.

Building A Redox Bootable Image

Read the Testing on Real Hardware section.

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. You can use ./bootstrap.sh -d in the redox folder to install the prerequisite packages if you have already done a git clone of the sources.

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!

build.sh

build.sh is a shell script for quickly invoking make for a specified variant, CPU architecture, and output 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.

Example 1

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

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

The resulting image is build/i686/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.

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

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

Native Build

This page explains how to build Redox in your operating system's native environment. Keep in mind that it's possible to encounter issues with the native build that don't occur with the Podman build, so this method is only recommended where Podman cannot be used.

📝 Note: be sure to read the Build System page for an explanation of the build system's organization and functionality.

Supported Unix-like Distributions and Podman Build

The following Unix-like systems are supported:

• Pop_OS!
• Ubuntu
• Debian
• Fedora
• Arch Linux
• OpenSUSE
• Gentoo (basic support)
• FreeBSD
• MacOSX (require workarounds)
• Nix (under development)
• Solus (basic support, not maintained)

If you encounter a weird or difficult-to-fix problem, test the Podman Build to determine if the problem occurs there as well.

Preparing the Build

Bootstrap Prerequisites and Fetch Sources

On supported Linux distributions, build system preparation can be performed automatically via the build system's bootstrap script:

1. Ensure you have the curl program installed. e.g., for Pop!_OS/Ubuntu/Debian:

   which curl || sudo apt-get install curl
   

2. Create a new directory and run the native_bootstrap.sh script in it.

   mkdir -p ~/tryredox
   

   cd ~/tryredox
   

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

   time bash -e native_bootstrap.sh
   

   You will be asked to confirm some steps: answer with y or 1.

   For an explanation of what the native_bootstrap.sh script does, read this section.

   Note that curl -sf operates silently, so if there are errors, you may get an empty or incorrect version of native_bootstrap.sh. Check for typos in the command and try again. If you continue to have problems, join the chat and let us know.

   Please be patient. The bootstrapping process can take anywhere from 5 minutes to an hour depending on the hardware and network it's being run on.

3. After bootstrapping is completed, update the PATH environment variable for the current shell:

   source ~/.cargo/env
   

Setting Configuration Values

The build system uses several configuration files, which contain settings that you may wish to change. These are detailed in the Configuration Settings page. By default the build system cross-compile to the x86_64 CPU architecture, using the desktop configuration (at config/x86_64/desktop.toml). Set the desired ARCH and CONFIG_FILE in .config.

The build.sh script also allows the user to specify the CPU architecture and filesystem contents to be used in the build, although these settings be re-specified every time the script is run.

Compiling Redox

At this point we have:

• Downloaded the sources
• Tweaked the settings to our liking
• Probably added our recipe to the filesystem

We are ready to build the Redox operating system image. Skip ahead to Configuration Settings if you want to build for a different CPU architecture or with different filesystem contents.

Build all system components and programs

To build all the components and packages to be included in the filesystem.

cd ~/tryredox/redox

time make all

This will build the target build/x86_64/desktop/harddrive.img, which can be run in a virtual machine.

Give it a while. Redox is big. Read the make all (first run) section for an explanation of what the make all command does.

💡 Tip: the filesystem parts are merged into the final system image using the FUSE library. The bootstrap.sh script installs libfuse automatically. If you encounter problems with the final Redox image, verify libfuse is installed and that you are able to use it.

From Nothing To Hello World

This page describes the quickest way to test a program on Redox. This tutorial doesn't build Redox from source.

In this example we will use a "Hello World" program written in Rust.

1. Create the tryredox folder.

   mkdir -p ~/tryredox
   

2. Navigate to the tryredox folder.

   cd ~/tryredox
   

3. Download the script to bootstrap Podman and download the Redox build system.

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

4. Execute the downloaded script.

   time bash -e podman_bootstrap.sh
   

5. Enable the Rust toolchain in the current shell.

   source ~/.cargo/env
   

6. Navigate to the Redox build system directory.

   cd ~/tryredox/redox
   

7. Create the .config file and add the REPO_BINARY environment variable to enable the binary-mode.

   echo "REPO_BINARY?=1 \n CONFIG_NAME?=my_config" >> .config
   

8. Create the hello-world recipe folder.

   mkdir cookbook/recipes/other/hello-world
   

9. Create the source folder for the recipe.

   mkdir cookbook/recipes/other/hello-world/source
   

10. Navigate to the recipe's source folder.

    cd cookbook/recipes/other/hello-world/source
    

11. Initialize a Cargo project with the "Hello World" string.

    cargo init --name="hello-world"
    

12. Create the hello-world recipe configuration.

    cd ~/tryredox/redox
    

    nano cookbook/recipes/other/hello-world/recipe.toml
    

13. Add the following to the recipe configuration:

    [build]
    template = "cargo"
    

14. Create the my_config filesystem configuration.

    cp config/x86_64/desktop.toml config/x86_64/my_config.toml
    

15. Open the my_config filesystem configuration file (i.e., config/x86_64/my_config.toml) and add the hello-world package to it.

    [packages]
    # Add the item below
    hello-world = "source"
    

16. Build the Hello World program and the Redox image.

    time make prefix r.hello-world image
    

17. Start the Redox virtual machine without a GUI.

    make qemu gpu=no
    

18. At the Redox login screen, write "user" for the user name and press Enter.

19. Run the "Hello World" program.

    helloworld
    

20. Shut down the Redox virtual machine.

    sudo shutdown
    

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

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.

Three important variables of interest are ARCH, CONFIG_NAME, and FILESYSTEM_CONFIG, 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 i686 CPU architecture. These settings will be applied implictly to all subsequent make commands:

ARCH?=i686
CONFIG_NAME?=desktop-minimal

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

📝 Note: if podman_bootstrap.sh was run previously, the .config file may already exist.

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>
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=i686; 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 i686, 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.

Architecture Names

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 create a new Redox image:

   make r.acid image
   

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

Binary Packages

By default, the Redox build system builds all packages from source (i.e., recipes). If you want to use pre-built 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
...

Package Management

Redox package management is similar to that of the major Linux distributions, except that many of Redox's (Rust-written) packages use static linking by default, rather than dynamic linking.

Static linking provides a few advantages over dynamic linking:

• Better Security

  Static linking can improve system security by running each program's library code in isolated memory locations. This is true even when identical versions of a vulnerable library are being used by multiple programs at once.

  To steal sensitive data from statically linked programs, an attacker would need to inject code directly into each program's memory address space, rather than the address space of a shared library. This increases the cost of the attack.

• Better Performance

  When a program is built with static linking, its library references are resolved before execution. Thus, there's no need for processing on the dynamic linker.

  This means a statically linked program will open faster than its dynamically linked equivalent, provided both are loaded entirely from disk.

• Simpler Dependency Management

  When a dynamically linked program depends on multiple versions of the same library, naming conflicts can arise from the identical object or symbol names within those versions. This issue can necessitate isolating the library files, often by giving them unique names or placing them in separate /lib directories, to ensure the proper version is used in each case.

  With static linking, however, there's no need for run-time dependency management, as library dependencies are included within the executable binaries.

  Rust programs aren't affected by this problem because of Cargo.

📝 Note: Rust programs are statically linked by default.

Format

What is "pkgar" ?

Short for "package archive", pkgar is a file format, library, and command-line executable for creating and extracting cryptographically secure collections of files, primarily for use in package management on Redox OS.

The technical details are still in development, so we think it is good to instead review the goals of pkgar and some examples that demonstrate its design principles.

pkgar has the following goals:

• Atomic - Updates are done atomically if possible
• Economical - Transfer of data must only occur when hashes change, allowing for network and data usage to be minimized
• Fast - Encryption and hashing algorithms are chosen for performance, and packages can potentially be extracted in parallel
• Minimal - Unlike other formats such as tar, the metadata included in a pkgar file is only what is required to extract the package
• Relocatable - Packages can be installed to any directory, by any user, provided the user can verify the package signature and has access to that directory.
• Secure - Packages are always cryptographically secure, and verification of all contents must occur before installation of a package completes.

To demonstrate how the format's design achieves these goals, let's look at some examples.

Example 1: Newly installed package

In this example, a package is installed that has never been installed on the system, from a remote repository. We assume that the repository's public key is already installed on disk, and that the URL to the package's pkgar is known.

First, a small, fixed-size header portion of the pkgar is downloaded. This is currently 136 bytes in size. It contains a NaCL signature, NaCL public key, BLAKE3 hash of the entry metadata, and 64-bit count of entry metadata structs.

Before this header can be used, it is verified. The public key must match the one installed on disk. The signature of the struct must verify against the public key. If this is true, the hash and entry count are considered valid.

The entry metadata can now be downloaded to a temporary file. During the download, the BLAKE3 hash is calculated. If this hash matches the hash in the header, the metadata is considered valid and is moved atomically to the correct location for future use. Both the header and metadata are stored in this file.

Each entry metadata struct contains a BLAKE3 hash of the entry data, a 64-bit offset of the file data in the data portion of the pkgar, a 64-bit size of the file data, a 32-bit mode identifying Unix permissions, and up to a 256-byte relative path for the file.

For each entry, before downloading the file data, the path can be validated for install permissions. The file data is downloaded to a temporary file, with no read, write, or execute permissions. While the download is happening, the BLAKE3 hash is calculated. If this hash matches, the file data is considered valid.

After downloading all entries, the temporary files have their permissions set as indicated by the mode in the metadata. They are then moved atomically to the correct location. At this point, the package is successfully installed.

Example 2: Updated package

In this example, a package is updated, and only one file changes. This is to demonstrate the capabilities of pkgar to minimize disk writes and network traffic.

First, the header is downloaded. The header is verified as before. Since a file has changed, the metadata hash will have changed. The metadata will be downloaded and verified. Both header and metadata will be atomically updated on disk.

The entry metadata will be compared to the previous entry metadata. The hash for one specific file will have changed. Only the contents for that file will be downloaded to a temporary file, and verified. Once that is complete, it will be atomically updated on disk. The package update is successfully completed, and only the header, entry metadata, and the files that have changed were downloaded and written.

Example 3: Package verification

In this example, a package is verified against the metadata saved on disk. It is possible to reconstruct a package from an installed system, for example, in order to install that package from a live disk.

First, the header is verified as before. The entry metadata is then verified. If there is a mismatch, an error is thrown and the package could be reinstalled.

The entry metadata will be compared to the files on disk. The mode of each file will be compared to the metadata mode. Then the hash of the file data will be compared to the hash in the metadata. If there is a mismatch, again, an error is thrown and the package could be reinstalled.

It would be possible to perform this process while copying the package to a new target. This allows the installation of a package from a live disk to a new install without having to store the entire package contents.

Conclusion

As the examples show, the design of pkgar is meant to provide the best possible package management experience on Redox OS. At no point should invalid data be installed on disk in accessible files, and installation should be incredibly fast and efficient.

Work still continues on determining the repository format.

The source for pkgar is fairly lightweight, we highly recommend reading it and contributing to the pkgar repository.

If you have questions, feel free to ask us on the Chat page.

Downloading packages with pkg

pkg is the Redox package manager installing binary packages to a running system. If you want to build packages, or include binary packages during the build, please see the Including Programs in Redox page.

Due to limited device support, you may get better results in an virtual machine than on real hardware.

The most commonly used pkg commands are show below:

• Install a package:

  sudo pkg install <package-name>
  

• Upgrade all installed packages:

  sudo pkg upgrade
  

• List package contents:

  pkg list <package-name>
  

• Get a file signature:

  pkg sign <package-name>
  

• Download a package:

  pkg fetch <package-name>
  

• Clean an extracted package:

  pkg clean <package-name>
  

• Create a package:

  pkg create <package-name>
  

• Extract a package:

  pkg extract <package-name>
  

• Get detailed information about one of the above options:

  pkg help <pkg-command>
  

📝 Note: Some pkg commands must be run with sudo because they manipulate the contents of protected folders: /usr/bin and /pkg.

The available packages can be found on the build server list.

Tasks

This page covers the commands used for common and specific tasks on Redox.

• Hardware
• System
• Networking
• User
• Files and Folders
• Media
• Graphics

Hardware

Show CPU information

cat /scheme/sys/cpu

System

Show system information

uname -a

Show memory (RAM) usage

free -h

Show the storage usage

df -h

Shutdown the computer

sudo shutdown

Show all running processes

ps

Show system-wide common programs

ls /bin

Show all schemes

ls /scheme

Show the system log

cat /scheme/sys/log

Or

dmesg

Networking

Show system DNS name

hostname

Show all network addresses of your system

hostname -I

Ping a website or IP

ping (website-link/ip-address)

Show website information

whois https://website-name.com

Download a GitHub repository on the current directory

git clone https://github.com/user-name/repository-name.git

Download a Git repository

git clone https://website-name.com/repository-name

Download a Git repository to the specified directory

git clone https://website-name.com/repository-name folder-name

Download a file with wget

wget https://website-name.com/file-name

Resume an incomplete download

wget -c https://website-name.com/file-name

Download from multiple links in a text file

wget -i file.txt

Download an entire website and convert it to work locally (offline)

wget --recursive --page-requisites --html-extension --convert-links --no-parent https://website-name.com

Download a file with curl

curl -O https://website-name.com

Download files from multiple websites at once

curl -O https://website-name.com/file-name -O https://website2-name.com/file-name

Host a website with Simple HTTP Server

• Point the program to the website folder
• The Home page of the website should be available on the root of the folder
• The Home page should be named as index.html

simple-http-server -i -p 80 folder-name

This command will use the port 80 (the certified port for HTTP servers), you can change as you wish.

User

Clean the terminal content

clear

Exit the terminal session, current shell or root privileges

exit

Current user on the shell

whoami

Show the default terminal shell

echo $SHELL

Show your current terminal shell

echo $0

Show your installed terminal shells (active on $PATH)

cat /etc/shells

Change your default terminal shell permanently (common path is /usr/bin)

chsh -s /path/of/your/shell

Add an abbreviation for a command on the Ion shell

alias name='command'

Change the user password

passwd user-name

Show the commands history

history

Show the commands with the name specified in history

history name

Change the ownership of a file, folder, device and mounted-partition (recursively)

sudo chown -R user-name:group-name directory-name

Or

chown user-name file-name

Show system-wide configuration files

ls /etc

Show the user configuration files of programs

ls ~/.local/share ~/.config

Print a text on terminal

echo text

Show the directories in the $PATH environment variable

echo $PATH

Show the dependencies (shared libraries) used by a program

ldd program-name

Add a new directory on the $PATH environment variable of the Ion shell

TODO

Restore the shell variables to default values

reset

Measure the time spent by a program to run a command

time command

Run a executable file on the current directory

./

Run a non-executable shell script

sh script-name

Or

bash script-name

Files and Folders

Show files and folders in the current directory

ls

Print some text file

cat file-name

Edit a text file

kibi file-name

Save your changes by pressing Ctrl+S

Show the current directory

pwd

Change the active directory to the specified folder

cd folder-name

Change to the previous directory

cd -

Change to the upper directory

cd ..

Change the current directory to the user folder

cd ~

Show files and folders (including the hidden ones)

ls -A

Show the files, folders and subfolders

ls *

Show advanced information about the files/folders of the directory

ls -l

Create a new folder

mkdir folder-name

Copy a file

cp -v file-name destination-folder

Copy a folder

cp -v folder-name destination-folder

Move a folder

mv folder-name destination-folder

Remove a file

rm file-name

Remove a folder

(Use with caution if you called the command with su, sudo or doas)

rm -rf folder-name

Add text in a text file

echo "text" >> directory/file

Search for files

find . -type f -name file-name

(Run with sudo or su if these directories are under root permissions)

Search for folders

find . -type d -name folder-name

(Run with sudo or su if the directories are under root permissions)

Show files/folders in a tree

tree

Media

Play a video

ffplay video-name

Play a music

ffplay music-name

Show an image

image-viewer image-name

Graphics

Show the OpenGL driver information

glxinfo | grep OpenGL

Questions, Feedback, Reporting Issues

• Most questions are answered in the Website FAQ.
• Technical questions are answered in the Developer FAQ.

Join the Redox Chat. It is the best method to chat with the Redox Team.

You can find historical questions in our Discourse Forum.

If you would like to report issues, send a message on the Support room of the chat or create an issue here and click in the New Issue button.

System Design

This chapter will discuss the design of Redox.

Microkernels

The Redox kernel is a microkernel. Microkernels stand out in their design by providing minimal abstractions in kernel-space. Microkernels focus on user-space, unlike Monolithic kernels which focus on kernel-space.

The basic philosophy of microkernels is that any component which can run in user-space should run in user-space. Kernel-space should only be utilized for the most essential components (e.g., system calls, process separation, resource management, IPC, thread management, etc).

The kernel's main task is to act as a medium for communication and segregation of processes. The kernel should provide minimal abstraction over the hardware (that is, drivers, which can and should run in user-space).

Microkernels are more secure and less prone to crashes than monolithic kernels. This is because most kernel components are moved to user-space and use different memory address spaces, and thus can't do damage to the system. Furthermore, microkernels are extremely maintainable, due to their small code size the number of bugs in the kernel is reduced a lot.

As anything else, microkernels do also have disadvantages.

Advantages of microkernels

There are quite a lot of advantages (and disadvantages) with microkernels, a few of which will be covered here.

Better Modularity and Configuration

Monolithic kernels are, well, monolithic. They do not allow fine-grained control as microkernels. This is due to many essential components being "hard-coded" into the kernel, and thus requiring modifications to the kernel itself (e.g., device drivers).

Microkernels are very modular by nature. You can replace, reload, modify, change, and remove modules, on runtime, without even touching the kernel.

Modern monolithic kernels try to solve this issue using kernel modules but still often require the system to reboot.

Better Security

Microkernels are undoubtedly more secure than monolithic kernels. The minimality principle of microkernels is a direct consequence of the principle of least privilege, according to which all components should have only the privileges absolutely needed to provide the needed functionality.

Many security-critical bugs in monolithic kernels come from services and drivers running unrestricted in kernel mode, without any form of protection.

In other words: in monolithic kernels, drivers can do whatever they want, without restrictions, when running in kernel mode.

Better Stability

When compared to microkernels, Monolithic kernels tend to be crash-prone. A buggy driver in a Monolithic kernel can crash the whole system because the driver code is running on the same memory address space of the kernel, thus the kernel process can't continue to run (to avoid memory corruption) and crash (kernel panic).

While in a microkernel the drivers run in different memory address spaces (separation of concerns) which allows the system to handle any crash safely.

In Linux we often see errors with drivers dereferencing bad pointers which ultimately results in kernel panics.

There is very good documentation in the MINIX documentation about how this can be addressed by a microkernel.

Sane Debugging

In microkernels the kernel components (drivers, filesystems, etc) are moved to user-space, thus bugs on them don't crash the kernel.

This is very important to debug in real hardware, because if a kernel panic happens, the log can't be saved to find the root of the bug.

In monolithic kernels, a bug in kernel component will cause a kernel panic and lock the system (if it happens in real hardware, you can't debug without serial output support)

(Buggy drivers are the main cause of kernel panics)

Disadvantages of microkernels

Small Performance Overhead

Any modern operating system needs basic security mechanisms such as memory isolation and virtualization. Furthermore any process (including the kernel) has its own stack and variables stored in registers. On context switch, that is each time a system call is invoked or any other inter-process communication (IPC) is done, some tasks have to be done, including:

• Saving caller registers, especially the program counter (caller: process invoking syscall or IPC)
• Reprogramming the MMU's page table (aka TLB)
• Putting CPU in another mode (kernel mode and user mode, also known as ring 0 and ring 3)
• Restoring callee registers (callee: process invoked by syscall or IPC)

These are not inherently slower on microkernels, but microkernels need to perform these operations more frequently. Many of the system functionality is performed by user-space processes, requiring additional context switches.

The performance difference between monolithic and microkernels has been marginalized over time, making their performance comparable. This is partly due to a smaller surface area which can be easier to optimize.

• Context Switch Documentation
• Microkernels Performance Paper

We are working on exciting performance optimizations to minimize the overhead of extra context switches.

Versus monolithic kernels

Monolithic kernels provide a lot more abstractions than microkernels.

The above illustration from Wikimedia, by Wooptoo, License: Public domain) shows how they differ.

Documentation about the kernel/user-space separation

• Dual Mode Operations in OS
• User Mode and Kernel Mode Switching

Documentation about microkernels

• OSDev Technical Wiki
• Message Passing Documentation
• Minix Documentation
• Minix Features
• Minix Reliability
• GNU Hurd Documentation
• Fuchsia Documentation
• HelenOS FAQ
• Minix Paper
• seL4 Whitepaper
• Tanenbaum-Torvalds Debate

A Note On The Current State

Redox has less than 40,000 Rust lines of kernel code. For comparison Minix has around 6,000 C lines of kernel code.

(The above comparison can't be used to argue that Minix is more stable or safe than Redox due to a less amount of source code lines, because Redox is more advanced than Minix in features, thus more lines of code are expected and a 1:1 comparison can't be made)

We would like to move more parts of Redox to user-space to get an even more stable and secure kernel.

Boot Process

Boot Loader

The boot loader source can be found in cookbook/recipes/bootloader/source after a successful build or in the Boot Loader repository.

BIOS Boot

The first code to be executed on x86 systems using BIOS is the boot sector, called stage 1, which is written in Assembly, and can be found in asm/x86-unknown-none/stage1.asm. This loads the stage 2 bootloader from disk, which is also written in Assembly. This stage switches to 32-bit mode and finally loads the Rust-written boot loader, called stage 3. These three boot loader stages are combined in one executable written to the first megabyte of the storage device. At this point, the bootloader follows the same common boot process on all boot methods, which can be seen in a later section.

UEFI Boot

Redox only supports UEFI for 64bit machines. On startup the UEFI firmware loads and executes PE32+ UEFI programs typically located at /EFI/BOOT/BOOTX64.efi (OSDev Wiki). In case this is our bootloader, the first code that is executed is pub extern "C" fn main() in src/os/uefi/mod.rs. At this point, the bootloader follows the same common boot process on all boot methods, which can be seen in a later section.

Common boot process

The bootloader initializes the memory map and the display mode, both of which rely on firmware mechanisms that are not acccessible after control is switched to the kernel. The bootloader then finds the RedoxFS partition on the disk and loads the kernel, bootstrap, and initfs into memory. It maps the kernel to its expected virtual address, and jumps to its entry function.

Kernel

The Redox kernel performs (fairly significant) architecture-specific initialization in the kstart function before jumping to the kmain function. At this point, the user-space bootstrap, a specially prepared executable that limits the required kernel parsing, sets up the initfs scheme, and loads and executes the init program.

Init

Redox has a multi-staged init process, designed to allow for the loading of disk drivers in a modular and configurable fashion. This is commonly referred to as an init RAMdisk.

RAMdisk Init

The ramdisk init has the job of loading the drivers required to access the root filesystem and then transfer control to the filesystem init. This contains drivers for ACPI, for the framebuffer, and for IDE, SATA, and NVMe disks. After loading all disk drivers, the RedoxFS driver is executed with the UUID of the partition where the kernel and other boot files were located. It then searches every driver for this partition, and if it is found, mounts it and then allows init to continue.

Filesystem Init

The filesystem init continues the loading of drivers for all other functionality. This includes audio, networking, and anything not required for disk access. After this, the login prompt is shown.

If Orbital is enabled, the display server is launched.

Login

After the init processes have set up drivers and daemons, it is possible for the user to log in to the system. The login program accepts an username, with a default user called user, prints the /etc/motd file, and then executes the user's login shell, usually ion. At this point, the user will now be able to access the shell

Graphical overview

Here is an overview of the initialization process with scheme creation and usage. For simplicity's sake, we do not depict all scheme interaction but at least the major ones. this is currently out of date, but still informative

Boot process documentation

• Boot process documentation

Redox kernel

System calls are generally simple, and have a similar ABI compared to regular function calls. On x86-64, it simply uses the syscall instruction, causing a mode switch from user-mode (ring 3) to kernel-mode (ring 0), and when the system call handler is finished, its mode switches back, as if the syscall instruction was a regular call instruction, using sysretq.

• System calls documentation

System Services in User Space

As any microkernel-based operating system, most kernel components are moved to user-space and adapted to work on it.

Monolithic kernels in general have hundreds of system calls due to the high number of kernel components (system calls are interfaces for these components), not to mention the number of sub-syscalls provided by ioctl and e.g. procfs/sysfs. Microkernels on the other hand, only have dozens of them.

This happens because the non-core kernel components are moved to user-space, thereby relying on IPC instead, which we will later explain.

User-space bootstrap is the first program launched by the kernel, and has a simple design. The kernel loads the initfs blob, containing both the bootstrap executable itself and the initfs image, that was passed from the boot loader. It creates an address space containing it, and jumps to a bootloader-provided offset. Bootstrap allocates a stack (in an Assembly stub), mprotects itself, and does the remaining steps to exec the init daemon. It also sets up the initfs scheme daemon.

The system calls used for IPC, are almost exclusively file-based. The kernel therefore has to know what schemes to forward certain system calls to. All file syscalls are marked with either SYS_CLASS_PATH or SYS_CLASS_FILE. The kernel associates paths with schemes by checking their scheme prefix against the scheme's name, in the former case, and in the latter case, the kernel simply remembers which scheme opened file descriptors originated from. Most IPC in general is done using schemes, with the exception of regular pipes like Linux has, which uses pipe2, read, write, close. Any scheme can also of course setup its own custom pipe-like IPC that also uses the aforementioned syscalls, like shm and chan from ipcd.

Schemes are implemented as a regular Rust trait in the kernel. Some builtin kernel schemes exist, which just implement that trait. Userspace schemes are provided via the UserScheme trait implementor, which relies on messages being sent between the kernel and the scheme daemon. This channel is created by scheme daemons when opening :SCHEME_NAME, which is parsed to the root scheme "" with path "SCHEME_NAME". Messages are sent by reading from and writing to that root scheme file descriptor.

So all file-based syscalls on files owned by user-space, will send a message to that scheme daemon, and when the result is sent back, the kernel will return that result back to the process doing the syscall.

Communication between user-space and the kernel, is generally fast, even though the current syscall handler implementation is somewhat unoptimized. Systems with Meltdown mitigations would be an exception, although such mitigations are not yet implemented.

• Kernel and User-Space Separation Policy

Communication

This page explains how a program communicates with the system components.

Context

• A scheme is a system service
• SQE means "Submission Queue Entry"
• CQE means "Completion Queue Entry"
• POSIX and Linux functions are implemented by relibc using Redox services provided by schemes, they work with the appropriate schemes to implement the function. It might involve opening a scheme, maybe writing to a scheme, or maybe calling mmap on the scheme after opening (this is pretty common).
• relibc and redox-rt talk to the scheme via a system call - open, read, write, mmap, etc.
• A system component (userspace daemon) uses the Scheme API (from the redox-scheme library) to implement the system service. The Scheme API also is doing system calls like open, read and write, but the message format for reading and writing is a special format. The latest version of the Scheme API reads SQE messages and writes CQE messages. SQE is basically the parameters to the system call that the caller originally did, packaged into a message. CQE is the response that the daemon sends back.
• The kernel is responsible for creating the SQE messages, and for unpacking the CQE messages.

Example

• The program calls some POSIX or Linux function from relibc
• relibc/redox-rt convert it to system calls
• The kernel converts the system calls to SQE
• The userspace daemon calls read on a "scheme socket" and gets an SQE message
• The userspace daemon calls write on the scheme socket and sends a CQE message
• The kernel converts the CQE message to the result of the system call
• relibc/redox-rt gets the result from the system call and uses that to calculate the result of the POSIX or Linux function call

Memory Management

TODO.

• Memory management documentation

Scheduling on Redox

The Redox kernel uses a scheduling algorithm called Round Robin.

The kernel registers a function called an interrupt handler that the CPU calls periodically. This function keeps track of how many times it is called, and will schedule the next process ready for scheduling every 10 "ticks".

• Scheduling documentation

Drivers

On Redox the device drivers are user-space daemons, being a common Unix process they have their own namespace with restricted schemes.

In other words, a driver on Redox can't damage other system interfaces, while on Monolithic kernels a driver could wipe your data because the driver run on the same memory address space of the filesystem (thus same privilege level).

You can find the driver documentation on the repository README and drivers code.

• Drivers repository

RedoxFS

This is the default filesystem of Redox OS, inspired by ZFS and adapted to a microkernel architecture.

Redox had a read-only ZFS driver but it was abandoned because of the monolithic nature of ZFS that created problems with the Redox microkernel design.

(It's a replacement for TFS)

Current features:

• Compatible with Redox and Linux (FUSE)
• Copy-on-write
• Data/metadata checksums
• Transparent encryption
• Standard Unix file attributes
• File/directory size limit up to 193TiB (212TB)
• File/directory quantity limit up to 4 billion per 193TiB (2^32 - 1 = 4294967295)
• Disk encryption fully supported by the Redox bootloader, letting it load the kernel off an encrypted partition.
• MIT licensed

Being MIT licensed, RedoxFS can be bundled on GPL-licensed operating systems (Linux, for example).

Graphics and Windowing

Drivers

VESA (vesad)

vesad is not really a driver, it writes to a framebuffer given by firmware (via UEFI or BIOS software interrupts).

Because we don't have GPU drivers yet, we rely on what firmware gives to us.

GPUs

On Linux/BSDs, the GPU communication with the kernel is done by the DRM system (Direct Rendering Manager, libdrm library), that Mesa3D drivers use to work (Mesa3D implement OpenGL/Vulkan drivers, DRM expose the hardware interfaces).

Said this, in Redox a "DRM driver" needs to be an user-space driver which use the system calls/schemes to communicate with the hardware.

The last step is to implement the Redox backend in our Mesa3D fork/recipe to use these user-space drivers.

Software Rendering

We don't have GPU drivers yet but LLVMpipe (OpenGL CPU emulation) is working.

Orbital

The Orbital desktop environment provides a display server, window manager and compositor.

Comparison with X11/Wayland

This display server is more simple than X11 and Wayland making the porting task more quick and easy, it's not advanced like X11 and Wayland yet but enough to port most Linux/BSD programs.

Compared to Wayland, Orbital has one server implementation, while Wayland provide protocols for compositors.

Features

• Custom Resolutions
• App Launcher (bottom bar)
• File Manager
• Text Editor
• Calculator
• Terminal Emulator

If you hold the Super key (generally the key with a Windows logo) it will show all keyboard shortcuts in a pop-up.

Libraries

The programs using these libraries can work on Orbital.

• winit
• softbuffer
• Slint (through winit and softbuffer)
• Iced (through winit and softbuffer)
• egui (winit or SDL2 can be used)
• SDL1.2
• SDL2
• Mesa3D's OSMesa

Security

In Orbital a GUI program cannot read input events or the content (framebuffer) from windows of other GUI programs, like Wayland.

Clients

Apps (or 'clients') create a window and draw to it by using the orbclient client.

Client Examples

If you wish to see examples of client apps that use orbclient to "talk" to Orbital and create windows and draw to them, then you can find some in orbclient/examples folder.

Porting

If you want to port a program to Orbital, see below:

• If the program is written in Rust probably it works on Orbital because the winit crate is used in most places, but there are programs that access X11 or Wayland directly. You need to port these programs to winit and merge on upstream.

• If the program is written in C or C++ and access X11 or Wayland directly, it must be ported to the Orbital library.

Security

This page covers the current Redox security design.

• The namespaces and capability-based system are implemented by the kernel but some parts can be moved to user-space.
• A namespace is a list of schemes, if you run ls :, it will show the schemes on the current namespace.
• Each process has a namespace.
• Capabilities are customized file descriptors that carry specific actions.
• All programs are statically-linked to their libraries, except for big libraries to save memory and storage space

Sandbox

The sandbox system duplicates the system resources for each program, it allows them to be completely isolated from the main system. Flatpak and Snap use a sandbox security system on Linux, Redox will do the same on its packages.

Redox allows sandbox by limiting a program's capabilities:

• Only a certain number of schemes in the program's namespace is allowed, or no scheme at all. That way new file descriptors can't be opened.
• All functionality is forced to occur via file descriptors (WIP).

Static Linking

Static linking increase the system security because each program use a different library code, even if the same version of a vulnerable library is used.

The attacker would need to inject code on each program's memory address space to steal sensitive data and not the shared library's memory address space, it increases the cost of the attack.

Rust programs use static linking by default.

Features

• Desktop
• Mobile
• External References

This page contains an operating system comparison table for common/important features.

Desktop

Mobile

External References

• Rust OS Comparison - A table comparing some Rust-written operating systems.

Schemes and Resources

An essential design choice made for Redox is to refer to resources using scheme-rooted paths. This gives Redox the ability to:

• Treat resources (files, devices, etc.) in a consistent manner
• Provide resource-specific behaviors with a common interface
• Allow management of names and namespaces to provide sandboxing and other security features
• Enable device drivers and other system resource management to communicate with each other using the same mechanisms available to user programs

Scheme-rooted Paths

Scheme-rooted paths are the way that resources are identified on Redox.

What is a Resource

A resource is anything that a program might wish to access, usually referenced by some name.

What is a Scheme

A scheme identifies the starting point for finding a resource.

What is a Scheme-rooted Path

A scheme-rooted path takes the following form, with text in bold being literal.

/scheme/scheme-name/resource-name

scheme-name is the name of the kind of resource, and it also identifies the name used by the manager daemon for that kind.

resource-name is the specific resource of that kind. Typically in Redox, the resource-name is a path with elements separated by slashes, but the resource manager is free to interpret the resource-name how it chooses, allowing other formats to be used if required.

Differences from Unix

Unix systems have some special file types, such as "block special file" or "character special file". These special files use major/minor numbers to identify the driver and the specific resource within the driver. There are also pseudo-filesystems, for example procfs that provide access to resources using paths.

Redox's scheme-rooted paths provide a consistent approach to resource naming, compared with Unix.

Regular Files

For Redox, a path that does not begin with /scheme/ is a reference to the the root filesystem, which is managed by the file scheme. Thus /home/user/.bashrc is interpreted as /scheme/file/home/user/.bashrc.

In this case, the scheme is file and the resource is home/user/.bashrc within that scheme.

This makes paths for regular files feel as natural as Unix file paths.

Resources

A resource is any "thing" that can be referred to using a path. It can be a physical device, a logical pseudodevice, a file on a file system, a service that has a name, or an element of a dataset.

The client program accesses a resource by opening it, using the resource name in scheme-rooted path format. The first part of the path is the name of the scheme, and the rest of the path is interpreted by the scheme provider, assigning whatever meaning is appropriate for the resources included under that scheme.

Some schemes, such as /scheme/pty/ simply allocate sequentially numbered resources and do not need the complexity of a slash-separated path.

Resource Examples

Some examples of resources are:

• Files within a filesystem - /path/to/file is interpreted as /scheme/file/path/to/file. Other filesystems can be referenced as /scheme/otherfs/path/to/file.
• Pseudo-terminals - /scheme/pty/n where n is a number, refers to a particular pseudo-terminal.
• Display - /scheme/display.vesa/n where n is a number, refers to the VESA virtual display - Virtual display 1 is the system log, display 2 is the text UI, and display 3 is the graphical display used by Orbital.
• Networking - /scheme/udp/a.b.c.d/p is the UDP socket with IPv4 address a.b.c.d, port number p.

Schemes

The scheme, which takes its name from URI schemes, identifies the type of resource, and identifies the manager daemon responsible for that resource.

Within Redox, a scheme may be thought of in a few ways. It is all of these things:

• The type of a resource, such as "file", "NVMe drive", "TCP connection", etc. (Note that these are not valid scheme names, they are just given by way of example.)
• The starting point for locating the resource, i.e. it is the root of the path to the resource, which the system can then use in establishing a connection to the resource.
• A uniquely named service that is provided by some driver or daemon program, with the full path identifying a specific resource accessed via that service.

Scheme Daemons

A scheme is typically provided by a daemon. A daemon is a program that runs as a process in userspace; it is typically started by the system during boot. When the process starts, it registers with kernel using the name of the scheme that it manages.

Kernel vs. Userspace Schemes

A userspace scheme is implemented by a scheme daemon, described above. A kernel scheme is implemented within the kernel, and manages critical resources not easily managed with a userspace daemon. When possible, schemes should be implemented in userspace.

Accessing Resources

In order to provide "virtual file" behavior, schemes generally implement file-like operations. However, it is up to the scheme provider to determine what each file-like operation means. For example, seek to an SSD driver scheme might simply add to a file offset, but to a floppy disk controller scheme, it might cause the physical movement of disk read-write heads.

Typical scheme operations include:

• open - Create a handle (file descriptor) to a resource provided by the scheme. e.g. File::create("/scheme/tcp/127.0.0.1/3000") in a regular program would be converted by the kernel into open("127.0.0.1/3000") and sent to the "tcp" scheme provider. The "tcp" scheme provider would parse the name, establish a connection to Internet address "127.0.0.1", port "3000", and return a handle that represents that connection.
• read - get some data from the thing represented by the handle, normally consuming that data so the next read will return new data.
• write - send some data to the thing represented by the handle to be saved, sent or written.
• seek - change the logical location where the next read or write will occur. This may or may not cause some action by the scheme provider.

Schemes may choose to provide other standard operations, such as mkdir, but the meaning of the operation is up to the scheme. mkdir might create a directory entry, or it might create some type of substructure or container relevant to that particular scheme.

Some schemes implement fmap, which creates a memory-mapped area that is shared between the scheme resource and the scheme user. It allows direct memory operations on the resource, rather than reading and writing to a file descriptor. The most common use case for fmap is for a device driver to access the physical addresses of a memory-mapped device, using the memory: kernel scheme. It is also used for frame buffers in the graphics subsystem.

TODO: add F-operations.

TODO: explain file-like vs. socket-like schemes.

Userspace Schemes

Redox creates user-space schemes during initialization, starting various daemon-style programs, each of which can provide one or more schemes.

Kernel Schemes

The kernel provides a small number of schemes in order to support userspace.

Scheme List

This section has all Redox schemes in a list format to improve organization, coordination and focus.

Userspace

• disk.*
• disk.live
• disk.usb-{id}+{port}-scsi
• logging
• initfs
• file
• network
• ip
• tcp
• udp
• icmp
• netcfg
• dns
• display.vesa
• display.virtio-gpu
• orbital
• pty
• audiorw
• audio
• usb.*
• pcspkr
• acpi
• input
• escalate
• chan
• shm
• log
• rand
• zero
• null

Kernel

• namespace
• user
• debug
• event
• irq
• pipe
• proc
• thisproc
• sys
• kernel.acpi
• memory
• time
• itimer
• serio

"Everything is a file"

Unix has a concept of using file paths to represent "special files" that have some meaning beyond a regular file. For example, a device file is a reference to a device resource that looks like a file path.

With the "Everything is a file" concept provided by Unix-like systems, all sorts of devices, processes, and kernel parameters can be accessed as files in a regular filesystem. If you are on a Linux computer, you should try to cd to /proc, and see what's going on there.

Redox extends this concept to a much more powerful one. Since each "scheme provider" is free to interpret the path in its own way, new schemes can be created as needed for each type of resource. This way USB devices don't end up in a "filesystem", but a protocol-based scheme like EHCI. It is not necessary for the file system software to understand the meaning of a particular path, or to give a special file some special properties that then become a fixed file system convention.

Redox schemes are flexible enough to be used in many circumstances, with each scheme provider having full flexibility to define its own path conventions and meanings, and only the programs that wish to take advantage of those meanings need to understand them.

Redox does not go as far as Plan 9, in that there are not separate paths for data and control of resources. In this case, Redox is more like Unix, where resources can potentially have a control interface.

Documentation about this design

• Drew DeVault - In praise of Plan 9
• Plan 9 documentation
• Plan 9 wiki
• 9P documentation

Stiching It All Together

The "path, scheme, resource" model is simply a unified interface for efficient inter-process communication. Paths are simply resource descriptors. Schemes are simply resource types, provided by scheme managers.

A diagram would look like this:

Scheme Operation

A kernel scheme is implemented directly in the kernel. A userspace scheme is typically implemented by a daemon.

A scheme is created in the root scheme and listens for requests using the event scheme.

Root Scheme

The root scheme is a special scheme provided by the kernel. It acts as the container for all other scheme names. The root scheme is currently referenced as ":", so when creating a new scheme, the scheme provider calls File::create(":myscheme"). The file descriptor that is returned by this operation is a message passing channel between the scheme provider and the kernel. File operations performed by a regular program are translated by the kernel into message packets that the scheme provider reads and responds to, using this file descriptor.

Event Scheme

The event scheme is a special scheme provided by the kernel that allows a scheme provider or other program to listen for events occurring on a file descriptor. A more detailed explanation of the event scheme can be found on the Event Scheme page.

Note that very simple scheme providers do not use the event scheme. However, if a scheme can receive requests or events from more than one source, the event scheme makes it easy for the daemon (scheme provider) to block until something (an event) happens, do some work, then block again until the next event.

Daemons and Userspace Scheme Providers

A daemon is a program, normally started during system initialization. It runs with root permissions. It is intended to run continuously, handling requests and other relevant events. On some operating systems, daemons are automatically restarted if they exit unexpectedly. Redox does not currently do this but is likely to do so in the future.

On Redox, a userspace scheme provider is a typically a daemon, although it doesn't have to be. The scheme provider informs the kernel that it will provide the scheme by creating it, e.g. File::create(":myscheme") will create the scheme myscheme. Notice that the name used to create the scheme starts with ":", indicating that it is a new entry in the root scheme. Since it is created in the root scheme, the kernel knows that it is a new scheme, as named schemes are the only thing that can exist in the root scheme. In future, the scheme will register in a namespace using a different path format.

Namespaces

At the time a regular program is started, it becomes a process, and it exists in a namespace. The namespace is a container for all the schemes, files and directories that a process can access. When a process starts another program, the namespace is inherited, so a new process can only access the schemes, files and directories that its parent process had available. If a parent process wants to limit (sandbox) a child process, it would do so as part of creating the child process.

Currently, Redox starts all processes in the "root" namespace. This will be changed in the future, sandboxing all user programs so most schemes and system resources are hidden.

Redox also provides a null namespace. A process that exists in the null namespace cannot open files or schemes by name, and can only use file descriptors that are already open. This is a security mechanism, mostly used to by daemons running with root permission to prevent themselves from being hijacked into opening things they should not be accessing. A daemon will typically open its scheme and any resources it needs during its initialization, then it will ask the kernel to place it in the null namespace so no further resources can be opened.

Providing a Scheme

To provide a scheme, a program performs the following steps:

1. Create the scheme, obtaining a file descriptor - File::create(":myscheme")
2. Open a file descriptor for each resource that is required to provide the scheme's services, e.g. File::open("/scheme/irq/{irq-name}")
3. Open a file descriptor for a timer if needed - File::open("/scheme/time/{timer_type}")
4. Open a file descriptor for the event scheme (if needed) - File::open("/scheme/event")
5. Move to the null namespace to prevent any additional resources from being accessed - setrens(0,0)
6. Write to the event file descriptor to register each of the file descriptors the provider will listen to, including the scheme file descriptor - event_fd.write(&Event{fd, ...})

Then, in a loop:

1. Block, waiting for an event to read. For simple schemes, the scheme provider would not use this mechanism, it would simply do a blocking read of its scheme file descriptor.
2. Read the event to determine (based on the file descriptor included in the event) if it is a timer, a resource event, or a scheme request.
3. If it's a resource event, e.g. indicating a device interrupt, perform the necessary actions such as reading from the device and queuing the data for the scheme.
4. If it's a scheme event, read a request packet from the scheme file descriptor and call the "handler". The request packet will indicate if it's an open, read, write, etc. on the scheme:

   • An open will include the name of the item to be opened. This can be parsed by the scheme provider to determine the exact resource the requestor wants to access. The scheme will allocate a handle for the resource, with a numbered descriptor. Descriptor numbers are in the range 0 to usize::MAX - 4096, leaving the upper 4096 values as internal error codes. These descriptors are used by the scheme provider to look up the handle data structure it uses internally for the resource. The descriptors are typically allocated sequentially, but a scheme provider could return a pointer to the handle data structure if it so chooses.

     📝 Note: the descriptor returned from an open request is not the same as the file descriptor returned to the client program. The kernel maps between the client's (process id, fd number) and the scheme provider's (process id, handle number).

   • A read or write, etc., will be handled by the scheme, using the handle number to look up the information associated with the resource. The operation will be performed, or queued to be performed. If the request can be handled immediately, a response is sent back on the scheme file descriptor, matched to the original request.

5. After all requests have been handled, loop through every handle to determine if any queued requests are now complete. A response is sent back on the scheme file descriptor for each completed request, matched to that request.
6. Set a timer if appropriate, to enable handling of device timeouts, etc. This is performed as a write operation on the timer file descriptor.

Kernel Actions

The kernel performs the following actions in support of the scheme:

• Any special resources required by a scheme provider are accessed as file operations on some other scheme. The kernel handles access to resources as it would for any other scheme.
• Regular file operations from user programs are converted by the kernel to request messages to the schemes. The kernel maps the user program's file descriptor to a scheme and a handle id provided by the scheme during the open operation, and places them in a packet.
• If the user program is performing a blocking read or write, the user program is suspended.
• The kernel sends event packets on the scheme provider's event file descriptor, waking the blocked scheme provider. Each event packet indicates whether it is the scheme or some other resource, using the file descriptor obtained by the scheme provider during its initialization.
• When the scheme provider reads from its scheme file descriptor, it receives the packets the kernel created describing the client request and handles them as described above.
• When the scheme provider sends a response packet, the kernel maps the response to a return value from the user program's file operation.
• When a blocking read or write is completed, the user program is marked ready to run, and the kernel will place it in the run queue.

Event Scheme

The event scheme is a special scheme that is central to the operation of device drivers, schemes and other programs that receive events from multiple sources. It's like a "clearing house" for activity on multiple file descriptors. The daemon or client program performs a read operation on the event scheme, blocking until an event happens. It then examines the event to determine what file descriptor is active, and performs a non-blocking read of the active file descriptor. In this way, a program can have many sources to read from, and rather than blocking on one of those sources while another might be active, the program blocks only on the event scheme, and is unblocked if any one of the other sources become active.

The event scheme is conceptually similar to Linux's epoll mechanism.

What is a Blocking Read

For a regular program doing a regular read of a regular file, the program calls read, providing an input buffer, and when the read call returns, the data has been placed into the input buffer. Behind the scenes, the system receives the read request and suspends the program, meaning that the program is put aside while it waits for something to happen. This is very convenient if the program has nothing to do while it waits for the read to complete. However, if the thing the program is reading from might take a long time, such as a slow device, a network connection or input from the user, and there are other things for the program to do, such as updating the screen, performing a blocking read can prevent handling these other activities in a timely manner.

Non-blocking Read

To allow reading from multiple sources without getting stuck waiting for any particular one, a program can open a path using the O_NONBLOCK flag. If data is ready to be read, the system immediately copies the data to the input buffer and returns normally. However, if data is not ready to be read, the read operation returns an error of type EAGAIN, which indicates that the program should try again later.

Now your program can scan many file descriptors, checking if any of them have data available to read. However, if none have any data, you want your program to block until there is something to do. This is where the event scheme comes in.

Using the Event Scheme

The purpose of the event scheme is to allow the daemon or client program to receive a message on the event_file, to inform it that some other file descriptor is ready to be read. The daemon reads from the event_file to determine which other file descriptor is ready. If no other descriptor is ready, the read of the event_file will block, causing the daemon to be suspended until the event scheme indicates some other file descriptor is ready.

Before setting up the event scheme, you should open all the other resources you will be working with, but set them to be non-blocking. E.g. if you are a scheme provider, open your scheme in non-blocking mode,

#![allow(unused)]
fn main() {
let mut scheme_file = OpenOptions::new()
            .create(true)
            .read(true)
            .write(true)
            .custom_flags(syscall::O_NONBLOCK as i32)
            .open(":myscheme")
            .expect("mydaemon: failed to create myscheme: scheme");
}

The first step in using the event scheme is to open a connection to it. Each program will have a connection to the event scheme that is unique, so no path name is required, only the name of the scheme itself.

#![allow(unused)]
fn main() {
let event_file = File::open("/scheme/event");
// you actually need to open it read/write
}

Next, write messages to the event scheme, one message per file descriptor that the event scheme should monitor. A message is in the form of a syscall::data::Event struct.

#![allow(unused)]
fn main() {
use syscall::data::Event;
let _ = event_file.write(&Event{ id: scheme_file.as_raw_fd(), ... });
// write one message per file descriptor
}

Note that timers in Redox are also handled via a scheme, so if you will be using a timer, you will need to open the timer scheme, and include that file descriptor among the ones your event_file should listen to.

Once your setup of the event scheme is complete, you begin your main loop:

1. Perform a blocking read on the event file descriptor. event_file.read(&mut event_buf);
2. When an event, such as data becoming available on a file descriptor, occurs, the read operation on the event_file will complete.
3. Look at the event_buf to see which file descriptor is active.
4. Perform a non-blocking read on that file descriptor.
5. Perform the appropriate processing.
6. If you are using a timer, write to the timer file descriptor to tell it when you want an event.
7. Repeat.

Non-blocking Write

Sometimes write operations can take time, such as sending a message synchronously or writing to a device with a limited buffer. The event scheme allows you to listen for write file descriptors to become unblocked. If a single file descriptor is opened in read-write mode, your program will need to register with the event scheme twice, once for reading and once for writing.

Implementing Non-blocking Reads in a Scheme

If your scheme supports non-blocking reads by clients, you will need to include some machinery to work with the event scheme on your client's behalf:

1. Wait for an event that indicates activity on your scheme. event_file.read(&mut event_buf);
2. Read a packet from your scheme file descriptor containing the request from the client program. scheme_file.read(&mut packet) The packet contains the details of which file descriptor is being read, and where the data should be copied to.
3. If the client is performing a read that would block, then queue the client request and return the EAGAIN error, writing the error response to your scheme file descriptor.
4. When data is available to read, send an event by writing a special packet to your scheme, indicating the handle id that is active:

   
   #![allow(unused)]
   fn main() {
   scheme_file.write(&Packet { a: syscall::number::SYS_FEVENT, b: handle_id, ... });
   }
   

5. When routing this response back to the client, the kernel will recognize it as an event message, and post the event on the client's event_fd, if one exists.
6. The scheme provider does not know whether the client has actually set up an event_fd. The scheme provider must send the event "just in case".
7. If an event has already been sent, but the client has not yet performed a read, the scheme should not send additional events. In correctly coded clients, extra events should not cause problems, but an effort should be made to not send unnecessary events. Be wary, however, as race conditions can occur where you think an extra event is not required but it actually is.

An Example

Enough theory! Time for an example.

We will implement a scheme which holds a vector. The scheme will push elements to the vector when it receives writes, and pop them when it is read. Let's call it vec.

The complete source for this example can be found at redox-os/vec_scheme_example.

TODO: the example has not been saved to the repo.

Setup

In order to build and run this example in a Redox environment, you'll need to be set up to compile the OS from source. The process for getting a program included in a local Redox build is laid out in the Including Programs in Redox page. Pause here and follow the helloworld example in that guide if you want to get this example running.

This example assumes that vec was used as the name of the crate instead of helloworld. The crate should therefore be located at cookbook/recipes/vec/source

Modify the Cargo.toml for the vec crate so that it looks something like this:

[package]
name = "vec"
version = "0.1.0"
edition = "2018"

[[bin]]
name = "vec_scheme"
path = "src/scheme.rs"

[[bin]]
name = "vec"
path = "src/client.rs"

[dependencies]
redox_syscall = "^0.2.6"

Notice that there are two binaries here. We'll need another program to interact with our scheme, since CLI tools like cat use more operations than we strictly need to implement for our scheme. The client uses only the standard library.

The Scheme Daemon

Create src/scheme.rs in the crate. Start by useing a couple of symbols.

#![allow(unused)]
fn main() {
use std::cmp::min;
use std::fs::File;
use std::io::{Read, Write};

use syscall::Packet;
use syscall::scheme::SchemeMut;
use syscall::error::Result;
}

We start by defining our mutable scheme struct, which will implement the SchemeMut trait and hold the state of the scheme.

#![allow(unused)]
fn main() {
struct VecScheme {
    vec: Vec<u8>,
}

impl VecScheme {
    fn new() -> VecScheme {
        VecScheme {
            vec: Vec::new(),
        }
    }
}
}

Before implementing the scheme operations on our scheme struct, let's breifly discuss the way that this struct will be used. Our program (vec_scheme) will create the vec scheme by opening the corresponding scheme handler in the root scheme (:vec). Let's implement a main() that intializes our scheme struct and registers the new scheme:

fn main() {
    let mut scheme = VecScheme::new();

    let mut handler = File::create(":vec")
        .expect("Failed to create the vec scheme");
}

When other programs open/read/write/etc against our scheme, the Redox kernel will make those requests available to our program via this scheme handler. Our scheme will read that data, handle the requests, and send responses back to the kernel by writing to the scheme handler. The kernel will then pass the results of operations back to the caller.

fn main() {
    // ...

    let mut packet = Packet::default();

    loop {
        // Wait for the kernel to send us requests
        let read_bytes = handler.read(&mut packet)
            .expect("vec: failed to read event from vec scheme handler");

        if read_bytes == 0 {
            // Exit cleanly
            break;
        }

        // Scheme::handle passes off the info from the packet to the individual
        // scheme methods and writes back to it any information returned by
        // those methods.
        scheme.handle(&mut packet);

        handler.write(&packet)
            .expect("vec: failed to write response to vec scheme handler");
    }
}

Now let's deal with the specific operations on our scheme. The scheme.handle(...) call dispatches requests to these methods, so that we don't need to worry about the gory details of the Packet struct.

In most Unix systems (Redox included!), a program needs to open a file before it can do very much with it. Since our scheme is just a "virtual filesystem", programs call open with the path to the "file" they want to interact with when they want to start a conversation with our scheme.

For our vec scheme, let's push whatever path we're given to the vec:

#![allow(unused)]
fn main() {
impl SchemeMut for VecScheme {
    fn open(&mut self, path: &str, _flags: usize, _uid: u32, _gid: u32) -> Result<usize> {
        self.vec.extend_from_slice(path.as_bytes());
        Ok(0)
    }
}
}

Say a program calls open("vec:/hello"). That call will work its way through the kernel and end up being dispatched to this function through our Scheme::handle call.

The usize we return here will be passed back to us as the id parameter of the other scheme operations. This way we can keep track of different open files. In this case, we won't make a distinction between two different programs talking to us and simply return zero.

Similarly, when a process opens a file, the kernel returns a number (the file descriptor) that the process can use to read and write to that file. Now let's implement the read and write operations for VecScheme:

#![allow(unused)]
fn main() {
impl SchemeMut for VecScheme {
    // ...

    // Fill up buf with the contents of self.vec, starting from self.buf[0].
    // Note that this reverses the contents of the Vec.
    fn read(&mut self, _id: usize, buf: &mut [u8]) -> Result<usize> {
        let num_written = min(buf.len(), self.vec.len());

        for b in buf {
            if let Some(x) = self.vec.pop() {
                *b = x;
            } else {
                break;
            }
        }

        Ok(num_written)
    }

    // Simply push any bytes we are given to self.vec
    fn write(&mut self, _id: usize, buf: &[u8]) -> Result<usize> {
        for i in buf {
            self.vec.push(*i);
        }

        Ok(buf.len())
    }
}
}

Note that each of the methods of the SchemeMut trait provide a default implementation. These will all return errors since they are essentially unimplemented. There's one more method we need to implement in order to prevent errors for users of our scheme:

#![allow(unused)]
fn main() {
impl SchemeMut for VecScheme {
    // ...

    fn close(&mut self, _id: usize) -> Result<usize> {
        Ok(0)
    }
}
}

Most languages' standard libraries call close automatically when a file object is destroyed, and Rust is no exception.

To see all the possible operations on schemes, check out the API docs.

TODO: there is no scheme documentation at this link.

A Simple Client

As mentioned earlier, we need to create a very simple client in order to use our scheme, since some command line tools (like cat) use operations other than open, read, write, and close. Put this code into src/client.rs:

use std::fs::File;
use std::io::{Read, Write};

fn main() {
    let mut vec_file = File::open("/scheme/vec/hi")
        .expect("Failed to open vec file");

    vec_file.write(b" Hello")
        .expect("Failed to write to vec");

    let mut read_into = String::new();
    vec_file.read_to_string(&mut read_into)
        .expect("Failed to read from vec");

    println!("{}", read_into); // olleH ih/
}

We simply open some "file" in our scheme, write some bytes to it, read some bytes from it, and then spit those bytes out on stdout. Remember, it doesn't matter what path we use, since all our scheme does is add that path to the vec. In this sense, the vec scheme implements a global vector.

Running the Scheme

Since we've already set up the program to build and run in QEMU, simply run:

make r.scheme-name image qemu

We'll need multiple terminal windows open in the QEMU window for this step. Notice that both binaries we defined in our Cargo.toml can now be found in /usr/bin (vec_scheme and vec). In one terminal window, run sudo vec_scheme. A program needs to run as root in order to register a new scheme. In another terminal, run vec and observe the output.

Exercises for the Reader

• Make the vec scheme print out something whenever it gets events. For example, print out the user and group IDs of the user who tries to open a file in the scheme.
• Create a unique vec for each opened file in your scheme. You might find a hashmap useful for this.
• Write a scheme that can run code for your favorite esoteric programming language.

Programs and Libraries

• Redox is a general-purpose operating system, thus it can run any program.

Some programs are interpreted by a runtime for the program's language, such as a script running in the GNU Bash shell or a Python program. Others are compiled into CPU instructions that run on a particular operating system (Redox) and specific hardware (e.g. x86 compatible CPU in 64-bit mode).

• In Redox, the binaries use the standard ELF ("Executable and Linkable Format") format.

Programs could directly invoke Redox system calls, but most call library functions that are higher-level are more easy to use. You link your program with the libraries it needs.

• Most C/C++ programs call functions in a C Standard Library (libc) such as fopen.
• Redox includes a Rust implementation of the C Standard Library called relibc. This is how programs such as Git and Python can run on Redox. relibc has some POSIX compatibility.
• Rust programs implicitly or explicitly call functions in the Rust Standard Library.
• The Rust libstd includes an implementation of its system-dependent parts (such as file access and setting environment variables) for Redox, in src/libstd/sys/redox. Most of libstd works in Redox, so many terminal-based Rust programs can be compiled for Redox.

The Redox Cookbook package system includes recipes (software ports) for compiling C, C++ and Rust programs into Redox binaries.

The porting of programs on Redox is done case-by-case, if a program just need small patches, the programmer can modify the Rust crate source code or add .patch files on the recipe folder, but if big or dirty patches are needed, Redox create a fork of it on GitLab and rebase for a while in the redox branch of the fork (some Redox forks use branches for different versions).

• OS Internals Documentation
• ELF Documentation

Components of Redox

Redox is made up of several discrete components.

Core

• bootloader - Kernel bootstrap
• kernel - System manager
• bootstrap - User-space bootstrap
• init
• initfs
• drivers - Device drivers
• redoxfS - Filesystem
• audiod - Audio daemon
• netstack - TCP/UDP stack
• ps2d - PS/2 driver
• relibc - Redox C library
• randd
• zerod
• ion - Shell
• orbital - Desktop environment

Orbital

• orbterm - Terminal
• orbdata - Images, fonts, etc.
• orbaudio - Audio
• orbutils - Bunch of applications
• orblogin - Login prompt
• orbfont - Font rendering library
• orbclient - Display client
• orbimage - Image rendering library
• orbtk - Cross-platform Rust GUI toolkit, similar to GTK

Default Programs

• sodium - Text editor
• orbutils
  • background - Wallpaper program
  • browser
  • calculator - Math program
  • character map - Characters list
  • editor - Text Editor
  • file manager
  • launcher - Program menu
  • viewer - Image viewer

GUI

The desktop environment of Redox (Orbital) is provided by a set of programs that run in user-space.

• Orbital - The display server and window manager sets up the orbital: scheme, manages the display, and handles requests for window creation, redraws, and event polling.

• Launcher - The launcher multi-purpose program that scans the applications in the /apps/ directory and provides the following services:

  • Called Without Arguments - A taskbar that displays icons for each application
  • Called With Arguments - An application chooser that opens a file in a matching program.
    • If one application is found that matches, it will be opened automatically
    • If more than one application is found, a chooser will be shown

Programs

The following are GUI utilities that can be found in the /apps/ directory.

• Calculator - A calculator that provides similar functionality to the calc program.
• Editor - A simple editor that is similar to Notepad.
• File Browser - A file browser that displays icons, names, sizes, and details for files. It uses the launcher command to open files when they are clicked.
• Image Viewer - A simple image viewer.
• Sodium - A vi-like editor that provides syntax highlighting.
• Terminal Emulator - An ANSI terminal emulator that launches the Ion shell by default.

Ion

Ion is a terminal shell and library for shells/command execution in Redox, it's used by default. Ion has it's own manual, which you can find on the Ion Manual.

1. The default shell in Redox

What is a terminal shell?

A terminal shell is a layer around the operating system kernel and libraries, that allows users to interact with the operating system. That means a shell can be used on any operating system (Ion runs on both Linux and Redox) or implementation of a standard library as long as the provided API is the same. Shells can either be graphical (GUI) or command-line (CLI).

Text shells

Text shells are programs that provide interactive user interface with an operating system. A shell reads from users as they type and performs operations according to the input. This is similar to read-eval-print loop (REPL) found in many programming languages (e.g. Python).

Typical Unix shells

Probably the most famous shell is GNU Bash, which can be found in the majority of Linux distributions, and also in MacOSX. On the other hand, FreeBSD uses tcsh by default.

There are many more shell implementations, but these two form the base of two fundamentally different sets:

• Bourne shell syntax (bash, sh, zsh)
• C shell syntax (csh, tcsh)

Of course these two groups are not exhaustive; it is worth mentioning at least the fish shell and xonsh. These shells are trying to abandon some features of old-school shell to make the language safer and more sane.

Fancy features

Writing commands without any help from the shell would be very exhausting and impossible to use for everyday work. Therefore, most shells (including Ion of course!) include features such as command history, autocompletion based on history or man pages, shortcuts to speed-up typing, etc.

2. A scripting language

Ion can also be used to write simple scripts for common tasks or system configuration after startup. It is not meant as a fully-featured programming language, but more like a glue to connect other programs together.

Relation to terminals

Early terminals were devices used to communicate with large computer systems like IBM mainframes. Nowadays Unix-like operating systems usually implement so called virtual terminals (tty stands for teletypewriter ... whoa!) and terminal emulators (e.g. xterm, gnome-terminal).

Terminals are used to read input from a keyboard and display textual output of the shell and other programs running inside it. This means that a terminal converts key strokes into control codes that are further used by the shell. The shell provides the user with a command line prompt (for instance: user name and working directory), line editing capabilities (Ctrl + a,e,u,k...), history, and the ability to run other programs (ls, uname, vim, etc.) according to user's input.

TODO: In Linux we have device files like /dev/tty, how is this concept handled in Redox?

Shell

When Ion is called without "-c", it starts a main loop, which can be found inside Shell.execute().

#![allow(unused)]
fn main() {
        self.print_prompt();
        while let Some(command) = readln() {
            let command = command.trim();
            if !command.is_empty() {
                self.on_command(command, &commands);
            }
            self.update_variables();
            self.print_prompt();
        }
}

self.print_prompt(); is used to print the shell prompt.

The readln() function is the input reader. The code can be found in crates/ion/src/input_editor.

The documentation about trim() can be found on the libstd documentation. If the command is not empty, the on_command method will be called. Then, the shell will update variables, and reprint the prompt.

#![allow(unused)]
fn main() {
fn on_command(&mut self, command_string: &str, commands: &HashMap<&str, Command>) {
    self.history.add(command_string.to_string(), &self.variables);

    let mut pipelines = parse(command_string);

    // Execute commands
    for pipeline in pipelines.drain(..) {
        if self.flow_control.collecting_block {
            // TODO move this logic into "end" command
            if pipeline.jobs[0].command == "end" {
                self.flow_control.collecting_block = false;
                let block_jobs: Vec<Pipeline> = self.flow_control
                                               .current_block
                                               .pipelines
                                               .drain(..)
                                               .collect();
                match self.flow_control.current_statement.clone() {
                    Statement::For(ref var, ref vals) => {
                        let variable = var.clone();
                        let values = vals.clone();
                        for value in values {
                            self.variables.set_var(&variable, &value);
                            for pipeline in &block_jobs {
                                self.run_pipeline(&pipeline, commands);
                            }
                        }
                    },
                    Statement::Function(ref name, ref args) => {
                        self.functions.insert(name.clone(), Function { name: name.clone(), pipelines: block_jobs.clone(), args: args.clone() });
                    },
                    _ => {}
                }
                self.flow_control.current_statement = Statement::Default;
            } else {
                self.flow_control.current_block.pipelines.push(pipeline);
            }
        } else {
            if self.flow_control.skipping() && !is_flow_control_command(&pipeline.jobs[0].command) {
                continue;
            }
            self.run_pipeline(&pipeline, commands);
        }
    }
}
}

First, on_command adds the commands to the shell history with self.history.add(command_string.to_string(), &self.variables);.

Then the script will be parsed. The parser code is in crates/ion/src/peg.rs. The parse will return a set of pipelines, with each pipeline containing a set of jobs. Each job represents a single command with its arguments. You can take a look in crates/ion/src/peg.rs.

#![allow(unused)]
fn main() {
pub struct Pipeline {
    pub jobs: Vec<Job>,
    pub stdout: Option<Redirection>,
    pub stdin: Option<Redirection>,
}
pub struct Job {
    pub command: String,
    pub args: Vec<String>,
    pub background: bool,
}
}

What Happens Next:

• If the current block is a collecting block (a for loop or a function declaration) and the current command is ended, we close the block:
  • If the block is a for loop we run the loop.
  • If the block is a function declaration we push the function to the functions list.
• If the current block is a collecting block but the current command is not ended, we add the current command to the block.
• If the current block is not a collecting block, we simply execute the current command.

The code blocks are defined in crates/ion/src/flow_control.rs.

pub struct CodeBlock {
    pub pipelines: Vec<Pipeline>,
}

The function code can be found in crates/ion/src/functions.rs.

The execution of pipeline content will be executed in run_pipeline().

The Command class inside crates/ion/src/main.rs maps each command with a description and a method to be executed. For example:

#![allow(unused)]
fn main() {
commands.insert("cd",
                Command {
                    name: "cd",
                    help: "Change the current directory\n    cd <path>",
                    main: box |args: &[String], shell: &mut Shell| -> i32 {
                        shell.directory_stack.cd(args, &shell.variables)
                    },
                });
}

cd is described by "Change the current directory\n cd <path>", and when called the method shell.directory_stack.cd(args, &shell.variables) will be used. You can see its code in crates/ion/src/directory_stack.rs.

System Tools

coreutils

Coreutils is a collection of basic command line utilities included with Redox (or with Linux, BSD, etc.). This includes programs like ls, cp, cat and various other tools necessary for basic command line interaction.

Redox use the Rust implementation of the GNU Coreutils, uutils.

Available programs:

• ls - Show the files and folders of the current directory.
• cp - Copy and paste some file or folder.
• cat - Show the output of some text file.
• chmod - Change the permissions of some file or directory.
• clear - Clean the terminal output.
• dd - Copies and converts a file.
• df - Show the disk partitions information.
• du - Shows disk usage on file systems.
• env - Displays and modifies environment variables.
• free - Show the RAM usage.
• kill - Kill a process.
• ln - Creates a link to a file.
• mkdir - Create a directory.
• ps - Show all running processes.
• reset - Restart the terminal to allow the command-line input.
• shutdown - Shutdown the system.
• sort - Sort, merge, or sequence check text files.
• stat - Returns data about an inode.
• tail - Copy the last part of a file.
• tee - Duplicate the standard output.
• test - Evaluate expression.
• time - Count the time that some command takes to finish it's operation.
• touch - Update the timestamp of some file or folder.
• uname - Show the system information, like kernel version and architecture type.
• uptime - Show how much time your system is running.
• which - Show the path where some program is located.

userutils

Userutils contains the utilities for dealing with users and groups in Redox OS.

They are heavily influenced by Unix and are, when needed, tailored to specific Redox use cases.

These implementations strive to be as simple as possible drawing particular inspiration by BSD systems. They are indeed small, by choice.

Available programs:

• getty - Used by init(8) to open and initialize the TTY line, read a login name and invoke login(1).
• id - Displays user identity.
• login - Allows users to login into the system
• passwd - Allows users to modify their passwords.
• su - Allows users to substitute identity.
• sudo - Enables users to execute a command as another user.
• useradd - Add a user
• usermod - Modify user information
• userdel - Delete a user
• groupadd - Add a user group
• groupmod - Modify group information
• groupdel - Remove a user group

extrautils

Some additional command line tools are included in extrautils, such as less, grep, and dmesg.

Available programs:

• calc - Do math operations.
• cur - Move terminal cursor keys using vi keybindings.
• dmesg - Show the kernel message buffer.
• grep - Search all text matches in some text file.
• gunzip - Decompress tar.gz archives.
• gzip - Compress files into tar.gz archives.
• info - Read Markdown files with help pages.
• keymap - Change the keyboard map.
• less - Show the text file content one page at a time.
• man - Show the program manual.
• mdless - Pager with Markdown support.
• mtxt - Various text conversions, like lowercase to uppercase.
• rem - Countdown tool.
• resize - Print the size of the terminal in the form of shell commands to export the COLUMNS and LINES environment variables.
• screenfetch - Show system information.
• tar - Manipulate tar archives.
• unzip - Manipulate zip archives.
• watch - Repeat a command every 2 seconds.

binutils

Binutils contains utilities for manipulating binary files.

Available programs:

• hex - Filter and show files in hexadecimal format.
• hexdump - Filter and show files in hexadecimal format (better output formatting).
• strings - Find printable strings in files.

contain

This program provides containers (namespaces) on Redox.

• Repository

acid

The general-purpose test suite of Redox to detect crashes, regressions and race conditions.

• Repository

resist

The POSIX test suite of Redox to see how much % the system is compliant to the POSIX specification (more means better compatibility).

• Repository

The Build Process

This chapter will cover the advanced build process of Redox.

Advanced Podman Build

To make the Redox build process more consistent across platforms, we are using Rootless Podman for major parts of the build. The basics of using Podman are described in the Building Redox page. This chapter provides a detailed discussion, including tips, tricks and troubleshooting, as well as some extra detail for those who might want to leverage or improve Redox's use of Podman.

(Don't forget to read the Build System page to know our build system organization and how it works)

Build Environment

• Environment and command line Variables, other than ARCH, CONFIG_NAME and FILESYSTEM_CONFIG, are not passed to the part of make that is done in Podman. You must set any other configuration variables, e.g. REPO_BINARY, in .config and not on the command line or on your environment.

• If you are building your own software to add in Redox, and you need to install additional packages using apt-get for the build, follow the Adding Packages to the Build section.

Installation

Most of the packages required for the build are installed in the container as part of the build process. However, some packages need to be installed on the host computer. You may also need to install an emulator such as QEMU. For most Linux distributions, this is done for you in the podman_bootstrap.sh script.

Note that the Redox filesystem parts are merged using FUSE. podman_bootstrap.sh installs libfuse for most platforms, if it is not already included. If you have problems with the final image of Redox, verify if libfuse is installed and you are able to use it.

Ubuntu

sudo apt-get install git make curl podman fuse fuse-overlayfs slirp4netns

Debian

sudo apt-get install git make curl podman fuse fuse-overlayfs slirp4netns

Arch Linux

sudo pacman -S --needed git make curl podman fuse3 fuse-overlayfs slirp4netns

Fedora

sudo dnf install git-all make curl podman fuse3 fuse-overlayfs slirp4netns

OpenSUSE

sudo zypper install git make curl podman fuse fuse-overlayfs slipr4netns

Pop!_OS

sudo apt-get install git make curl podman fuse fuse-overlayfs slirp4netns

FreeBSD

sudo pkg install git gmake curl fusefs-libs3 podman

MacOSX

• Homebrew

sudo brew install git make curl osxfuse podman fuse-overlayfs slirp4netns

• MacPorts

sudo port install git gmake curl osxfuse podman

NixOS

Before building Redox with NixOS, you must have configured Podman on your system. Just follow the instructions of the NixOS wiki:

{ pkgs, ... }:
{
  # Enable common container config files in /etc/containers
  virtualisation.containers.enable = true;
  virtualisation = {
    podman = {
      enable = true;

      # Create a `docker` alias for podman, to use it as a drop-in replacement
      dockerCompat = true;

      # Required for containers under podman-compose to be able to talk to each other.
      defaultNetwork.settings.dns_enabled = true;
    };
  };

  # Useful other development tools
  environment.systemPackages = with pkgs; [
    dive # look into docker image layers
    podman-tui # status of containers in the terminal
    docker-compose # start group of containers for dev
    podman-compose # start group of containers for dev
  ];
}
        

You will then have to configure your user to be able to use Podman:

users.extraUsers.${user-name} = {
  subUidRanges = [{ startUid = 100000; count = 65536; }];
  subGidRanges = [{ startGid = 100000; count = 65536; }];
};

The last step is to activate the development shell:

nix develop --no-warn-dirty --command $SHELL

build/container.tag

The building of the image is controlled by the tag file build/container.tag. If you run make all with PODMAN_BUILD=1, the file build/container.tag will be created after the image is built. This file tells make that it can skip updating the image after the first time.

Many targets in the Makefiles mk/*.mk include build/container.tag as a dependency. If the tag file is missing, building any of those targets may trigger an image to be created, which can take some time.

When you move to a new working directory, if you want to save a few minutes, and you are confident that your image is correct and your poduser home directory build/podman/poduser is valid, you can do

make container_touch

This will create the file build/container.tag without rebuilding the image. However, it will fail if the image does not exist. If it fails, just do a normal make, it will create the container when needed.

Cleaning Up

To remove the base image, any lingering containers, poduser's home directory, including the Rust installation, and build/container.tag, run:

make container_clean

• To verify that everything has been removed

podman ps -a

• Show any remaining images or containers

podman images

• Remove all images and containers. You still may need to remove build/container.tag if you did not do make container_clean.

podman system reset

In some rare instances, poduser's home directory can have bad file permissions, and you may need to run:

sudo chown -R `id -un`:`id -gn` build/podman

Where `id -un` is your User ID and `id -gn` is your effective Group ID. Be sure to make container_clean after that.

Note:

• make clean does not run make container_clean and will not remove the container image.
• If you already did make container_clean, doing make clean could trigger an image build and a Rust install in the container. It invokes cargo clean on various components, which it must run in a container, since the build is designed to not require Cargo on your host machine. If you have Cargo installed on the host and in your PATH, you can use make PODMAN_BUILD=0 clean to clean without building a container.

Debugging Your Build Process

If you are developing your own components and wish to do one-time debugging to determine what library you are missing in the Podman Build environment, the following instructions can help. Note that your changes will not be persistent. After debugging, you must Add your Libraries to the Build. With PODMAN_BUILD=1, run the following command:

• This will start a bash shell in the Podman container environment, as a normal user without root privileges.

make container_shell

• Within that environment, you can build the Redox components with:

make repo

• If you need to change ARCH or CONFIG_NAME, run:

./build.sh -a ARCH -c CONFIG_NAME repo

• If you need root privileges, while you are still running the above bash shell, go to a separate Terminal or Console window on the host, and type:

cd ~/tryredox/redox

make container_su

You will then be running Bash with root privilege in the container, and you can use apt-get or whatever tools you need, and it will affect the environment of the user-level container_shell above. Do not precede the commands with sudo as you are already root. And remember that you are in an Ubuntu instance.

Note: Your changes will not persist once both shells have been exited.

Type exit on both shells once you have determined how to solve your problem.

Adding Packages to the Build

This method can be used if you want to make changes/testing inside the Debian container with make env.

The default Containerfile, podman/redox-base-containerfile, imports all required packages for a normal Redox build.

However, you cannot easily add packages after the base image is created. You must add them to your own Containerfile and rebuild the container image.

Copy podman/redox-base-containerfile and add to the list of packages in the initial apt-get.

cp podman/redox-base-containerfile podman/my-containerfile

nano podman/my-containerfile

...
        xxd \
        rsync \
        MY_PACKAGE \
...

Make sure you include the continuation character \ at the end of each line except after the last package.

Then, edit .config, and change the variable CONTAINERFILE to point to your Containerfile, e.g.

CONTAINERFILE?=podman/my-containerfile

If your Containerfile is newer than build/container.tag, a new image will be created. You can force the image to be rebuilt with make container_clean.

If you feel the need to have more than one image, you can change the variable IMAGE_TAG in mk/podman.mk to give the image a different name.

If you just want to install the packages temporarily, run make env, open a new terminal tab/windows, run make container_su and use apt install on this tab/window.

Summary of Podman-related Make Targets, Variables and Podman Commands

• PODMAN_BUILD - If set to 1 in .config, or in the environment, or on the make command line, much of the build process takes place in Podman.

• CONTAINERFILE- The name of the containerfile used to build the image. This file includes the apt-get command that installs all the necessary packages into the image. If you need to add packages to the build, edit your own containerfile and change this variable to point to it.

• make build/container.tag - If no container image has been built, build one. It's not necessary to do this, it will be done when needed.

• make container_touch - If a container image already exists and poduser's home directory is valid, but there is no tag file, create the tag file so a new image is not built.

• make container_clean - Remove the container image, poduser's home directory and the tag file.

• make container_shell - Start an interactive Podman bash shell in the same environment used by make; for debugging the apt-get commands used during image build.

• make env - Start an interactive bash shell with the prefix tools in your PATH. Automatically determines if this should be a Podman shell or a host shell, depending on the value of PODMAN_BUILD.

• make repo or ./build.sh -a ARCH -c CONFIG repo - Used while in a Podman shell to build all the Redox component packages. make all will not complete successfully, since part of the build process must take place on the host.

• podman exec --user=0 -it CONTAINER bash - Use this command in combination with make container_shell or make env to get root access to the Podman build environment, so you can temporarily add packages to the environment. CONTAINER is the name of the active container as shown by podman ps. For temporary, debugging purposes only.

• podman system reset - Use this command when make container_clean is not sufficient to solve problems caused by errors in the container image. It will remove all images, use with caution. If you are using Podman for any other purpose, those images will be deleted as well.

Gory Details

If you are interested in how we are able to use your working directory for builds in Podman, the following configuration details may be interesting.

We are using Rootless Podman's --userns keep-id feature. Because Podman is being run Rootless, the container's root user is actually mapped to your User ID on the host. Without the keep-id option, a regular user in the container maps to a phantom user outside the container. With the keep-id option, a user in the container that has the same User ID as your host User ID, will have the same permissions as you.

During the creation of the base image, Podman invokes Buildah to build the image. Buildah does not allow User IDs to be shared between the host and the container in the same way that Podman does. So the base image is created without keep-id, then the first container created from the image, having keep-id enabled, triggers a remapping. Once that remapping is done, it is reused for each subsequent container.

The working directory is made available in the container by mounting it as a volume. The Podman option:

--volume "`pwd`":$(CONTAINER_WORKDIR):Z

takes the directory that make was started in as the host working directory, and mounts it at the location $CONTAINER_WORKDIR, normally set to /mnt/redox. The :Z at the end of the name indicates that the mounted directory should not be shared between simultaneous container instances. It is optional on some Linux distros, and not optional on others.

For our invocation of Podman, we set the PATH environment variable as an option to podman run. This is to avoid the need for our make command to run .bashrc, which would add extra complexity. The ARCH, CONFIG_NAME and FILESYSTEM_CONFIG variables are passed in the environment to allow you to override the values in mk/config.mk or .config, e.g. by setting them on your make command line or by using build.sh.

We also set PODMAN_BUILD=0 in the environment, to ensure that the instance of make running in the container knows not to invoke Podman. This overrides the value set in .config.

In the Containerfile, we use as few RUN commands as possible, as Podman commits the image after each command. And we avoid using ENTRYPOINT to allow us to specify the podman run command as a list of arguments, rather than just a string to be processed by the entrypoint shell.

Containers in our build process are run with --rm to ensure the container is discarded after each use. This prevents a proliferation of used containers. However, when you use make container_clean, you may notice multiple items being deleted. These are the partial images created as each RUN command is executed while building.

Container images and container data is normally stored in the directory $HOME/.local/share/containers/storage. The following command removes that directory in its entirety. However, the contents of any volume are left alone:

podman system reset

Advanced Build

In this section, we provide the gory details that may be handy to know if you are contributing to or developing for Redox.

(Don't forget to read the Build System page to know our build system organization and how it works)

Setup Your Environment

Although it's recommended to read the Building Redox or Podman Build pages instead of the process described here, advanced users may accomplish the same as the native_bootstrap.sh script with the following steps, which are provided by way of example for Pop!_OS/Ubuntu/Debian. For other platforms, have a look at the native_bootstrap.sh file to help determine what packages to install for your Unix-like system.

The steps to perform are:

• Clone The Repository
• Install The Necessary Packages
• Install Rust
• Adjust Your Configuration Settings
• Build the system

Clone The Repository

• Create a directory and clone the repository

mkdir -p ~/tryredox

cd ~/tryredox

git clone https://gitlab.redox-os.org/redox-os/redox.git --origin upstream --recursive

cd redox

make pull

Please be patient, this can take minutes to hours depending on the hardware and network you're using.

In addition to installing the various packages needed for building Redox, native_bootstrap.sh and podman_bootstrap.sh both clone the repository, so if you used either script, you have completed Step 1.

Install The Necessary Packages and Emulator

If you cloned the sources before running native_bootstrap.sh, you can use:

cd ~/tryredox/redox

./native_bootstrap.sh -d

If you can't use native_bootstrap.sh script, you can attempt to install the necessary packages below.

Pop!_OS/Ubuntu/Debian Users

Install the build system dependencies:

sudo apt-get install ant autoconf automake autopoint bison \
build-essential clang cmake curl dos2unix doxygen file flex \
fuse3 g++ genisoimage git gperf intltool libexpat-dev libfuse-dev \
libgmp-dev libhtml-parser-perl libjpeg-dev libmpfr-dev libpng-dev \
libsdl1.2-dev libsdl2-ttf-dev libtool llvm lua5.4 m4 make meson nasm \
ninja-build patch perl pkg-config po4a protobuf-compiler python3 \
python3-mako rsync scons texinfo unzip wget xdg-utils xxd zip zstd

• If you want to use QEMU, run:

sudo apt-get install qemu-system-x86 qemu-kvm

• If you want to use VirtualBox, run:

sudo apt-get install virtualbox

Fedora Users

Install the build system dependencies:

sudo dnf install autoconf vim bison flex genisoimage gperf \
glibc-devel.i686 expat expat-devel fuse-devel fuse3-devel gmp-devel \
libpng-devel perl perl-HTML-Parser libtool libjpeg-turbo-devel
SDL2_ttf-devel sdl12-compat-devel m4 nasm po4a syslinux \
texinfo ninja-build meson waf python3-mako make gcc gcc-c++ \
openssl patch automake perl-Pod-Html perl-FindBin gperf curl \
gettext-devel perl-Pod-Xhtml pkgconf-pkg-config cmake llvm zip \
unzip lua luajit make clang doxygen ant protobuf-compiler zstd

• If you want to use QEMU, run:

sudo dnf install qemu-system-x86 qemu-kvm

• If you want to use VirtualBox, install from the VirtualBox Linux Downloads page.

Arch Linux Users

Install the build system dependencies:

pacman -S --needed cmake fuse git gperf perl-html-parser nasm \
wget texinfo bison flex po4a autoconf curl file patch automake \
scons waf expat gmp libtool libpng libjpeg-turbo sdl12-compat \
m4 pkgconf po4a syslinux meson python python-mako make xdg-utils \
zip unzip llvm clang perl doxygen lua ant protobuf

• If you want to use QEMU, run:

sudo pacman -S qemu

• If you want to use VirtualBox, run:

sudo pacman -S virtualbox

OpenSUSE Users

Install the build system dependencies:

sudo zypper install gcc gcc-c++ glibc-devel-32bit nasm make fuse-devel \
cmake openssl automake gettext-tools libtool po4a patch flex gperf autoconf \
bison curl wget file libexpat-devel gmp-devel libpng16-devel libjpeg8-devel \
perl perl-HTML-Parser m4 patch scons pkgconf syslinux-utils ninja meson python-Mako \
xdg-utils zip unzip llvm clang doxygen lua54 ant protobuf

• If you want to use QEMU, run:

sudo zypper install qemu-x86 qemu-kvm

Gentoo Users

Install the build system dependencies:

sudo emerge dev-lang/nasm dev-vcs/git sys-fs/fuse

• If you want to use QEMU, run:

sudo emerge app-emulation/qemu

• If you want to use VirtualBox, install from the VirtualBox Linux Downloads page.

FreeBSD Users

Install the build system dependencies:

sudo pkg install coreutils findutils gcc nasm pkgconf fusefs-libs3 \
cmake gmake wget openssl texinfo python automake gettext bison gperf \
autoconf curl file flex expat2 gmp png libjpeg-turbo sdl12 sdl2_ttf \
perl5.36 p5-HTML-Parser libtool m4 po4a syslinux ninja meson xdg-utils \
zip unzip llvm doxygen patch automake scons lua54 py-protobuf-compiler

• If you want to use QEMU, run:

sudo pkg install qemu qemu-system-x86_64

• If you want to use VirtualBox, run:

sudo pkg install virtualbox

MacOS Users

The MacOSX require workarounds because the Redox toolchain don't support ARM64 as host and MacOSX don't allow FUSE to work while SIP is enabled.

This is what you can do:

• Install QEMU and create a x86-64 VM for a Linux distribution
• Install VirtualBox and create a VM for a Linux distribution (only works with Apple computers using Intel CPUs)
• Install UTM and create a x86-64 VM for a Linux distribution
• Disable SIP (Not recommended, only if you know what you are doing)
• Install a Linux distribution

MacPorts

Install the build system dependencies:

sudo port install coreutils findutils gcc49 gcc-4.9 nasm pkgconfig \
osxfuse x86_64-elf-gcc cmake ninja po4a findutils texinfo autoconf \
openssl3 openssl11 bison curl wget file flex gperf expat gmp libpng \
jpeg libsdl12 libsdl2_ttf libtool m4 ninja meson python311 py37-mako \
xdg-utils zip unzip llvm-16 clang-16 perl5.24 p5-html-parser doxygen \
gpatch automake scons gmake lua protobuf-c

• If you want to use QEMU, run:

sudo port install qemu qemu-system-x86_64

• If you want to use VirtualBox, run:

sudo port install virtualbox

If you have some problem, try to install this Perl module:

cpan install HTML::Entities

Homebrew

Install the build system dependencies:

brew install automake bison gettext libtool make nasm gcc@7 \
gcc-7 pkg-config cmake ninja po4a macfuse findutils texinfo \
openssl@1.1 openssl@3.0 autoconf curl wget flex gperf expat \
gmp libpng jpeg sdl12-compat sdl2_ttf perl libtool m4 ninja \
meson python@3.11 zip unzip llvm doxygen gpatch automake scons \
lua ant protobuf redox-os/gcc_cross_compilers/x86_64-elf-gcc x86_64-elf-gcc

• If you want to use QEMU, run:

brew install qemu qemu-system-x86_64

• If you want to use VirtualBox, run:

brew install virtualbox

If you have some problem, try to install this Perl module:

cpan install HTML::Entities

Install Rust Stable And Nightly

Install Rust, make the nightly version your default toolchain, then list the installed toolchains:

curl https://sh.rustup.rs -sSf | sh

then

source ~/.cargo/env

rustup default nightly

rustup toolchain list

cargo install --force --version 0.1.1 cargo-config

NOTE: ~/.cargo/bin has been added to your PATH environment variable for the running session.

The . "$HOME/.cargo/env command (equivalent to source ~/.cargo/env) have been added to your shell start-up file, ~/.bashrc, but you may wish to add it elsewhere or modify it according to your own environment.

Prefix

The tools that build Redox are specific to each CPU architecture. These tools are located in the directory prefix, in a subdirectory named for the architecture, e.g. prefix/x86_64-unknown-redox. If you have problems with these tools, you can remove the subdirectory or even the whole prefix directory, which will cause the tools to be re-downloaded or rebuilt. The variable PREFIX_BINARY in mk/config.mk controls whether they are downloaded or built.

Cookbook

The Cookbook system is an essential part of the Redox build system. Each Redox component package is built and managed by the Cookbook toolset. The variable REPO_BINARY in mk/config.mk controls if the recipes are compiled from sources or use binary packages from Redox CI server, read the section REPO_BINARY for more details. See the Including Programs in Redox page for examples of using the Cookbook toolset. If you will be developing recipes to include in Redox, it is worthwhile to have a look at the tools in the cookbook directory.

Creating a Build Environment Shell

If you are working on specific components of the system, and will be using some of the tools in the cookbook directory and bypassing make, you may wish to create a build environment shell. This shell includes the prefix tools in your PATH. You can do this with:

make env

This command also works with a Podman Build, creating a shell in Podman and setting PATH to include the necessary build tools.

Updating The Sources

If you want to update the build system or if some of the recipes have changed, you can update those parts of the system with make pull. However, this will not update the sources of the recipes.

cd ~/tryredox/redox

make pull

If you want to update the source for the recipes, use make rebuild, or remove the file $(BUILD)/fetch.tag and run make fetch.

Changing the Filesystem Size and Contents

You can modify the size and contents of the filesystem for emulation and livedisk as described in the Configuration Settings page.

Next Steps

Once this is all set up, we can finally build! See the Compiling Redox section.

Working with i686

The build system supports building for multiple CPU architectures in the same directory tree. Building for i686 or aarch64 only requires that you set the ARCH Make variable to the correct value. Normally, you would do this in the .config section, but you can also do this temporarily with the make ARCH=i686 command, in the shell environment (export ARCH=i686) or with the build.sh script.

First Time Build

Bootstrap Pre-Requisites And Download Sources

Follow the instructions for running bootstrap.sh to setup your environment on the Building Redox or Native Build pages.

Install QEMU

The i386 emulator is not installed by bootstrap.sh. You can add it like this:
(Pop!_OS/Ubuntu/Debian)

sudo apt-get install qemu-system-i386

Configuration Values

Before your first build, be sure to set the ARCH variable in .config to your architecture type, in this case i686. You can change several other configurable settings, such as the filesystem contents, etc. See Configuration Settings.

Add packages to the filesystem.

You can add programs to the filesystem by following the instructions here.

Advanced Users

For more details on the build process, please read Advanced Build.

Compiling Redox

Now we have:

• Downloaded the sources
• Set the ARCH environment variable to i686
• Selected a filesystem configuration, e.g. desktop
• Tweaked the settings to our liking
• Probably added our recipes to the filesystem

We are ready to build a Redox image.

Building an image for emulation

cd ~/tryredox/redox

This command will create the image, e.g. build/i686/desktop/harddrive.img, which you can run with an emulator. See Running Redox.

time make all

Building A Bootable Redox Image

cd ~/tryredox/redox

• The following command will create the file build/i686/desktop/livedisk.iso, which can be copied to a USB device or CD for testing or installation. See Running Redox on real hardware.

time make live

Give it a while. Redox is big.

Cleaning Previous Build Cycles

Cleaning Intended For Rebuilding Core Packages And Entire System

When you need to rebuild core-packages like relibc, gcc and related tools, clean the entire previous build cycle with:

cd ~/tryredox/redox/

rm -rf prefix/i686-unknown-redox/relibc-install/ cookbook/recipes/gcc/{build,sysroot,stage*} build/i686/*/{harddrive.img,livedisk.iso}

Cleaning Intended For Only Rebuilding Non-Core Package(s)

If you're only rebuilding a non-core package, you can partially clean the previous build cycle just enough to force the rebuilding of the Non-Core Package:

cd ~/tryredox/redox/

rm build/i686/*/{fetch.tag,harddrive.img}

Running Redox

Running The Redox Desktop

To open QEMU, run:

make qemu

This should open up a QEMU window, booting to Redox.

If it does not work, disable KVM with:

make qemu kvm=no

or:

make qemu iommu=no

If this doesn't work either, you should go open an issue.

Running The Redox Console Only

We disable to GUI desktop by passing the gpu=no option. The following disables the graphics support and welcomes you with the Redox console:

make qemu gpu=no 

It's useful to run the console in order to capture the output from the non-GUI programs.

It helps to debug applications and share the console captured logs with other developers in the Redox community.

QEMU Tap For Network Testing

Expose Redox to other computers within a LAN. Configure QEMU with a "TAP" which will allow other computers to test Redox client/server/networking capabilities.

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

Note

If you encounter any bugs, errors, obstructions, or other annoying things, please send a message in the chat or report the issue on GitLab. Thanks!

ARM64

The build system supports building for multiple CPU architectures in the same directory tree. Building for i686 or aarch64 only requires that you set the ARCH environment variable to the correct value. Normally, you would do this in .config, but you can also do this temporarily with the make ARCH=aarch64 command, in the shell environment (export ARCH=aarch64) or with the build.sh script.

(ARM64 has limited support)

First Time Build

Bootstrap Pre-Requisites and Download Sources

Follow the instructions for running bootstrap.sh to setup your environment, read the Building Redox page or the Podman Build page.

Install QEMU

The ARM64 emulator is not installed by bootstrap.sh. You can add it like this:

(Pop!_OS/Ubuntu/Debian)

sudo apt-get install qemu-system-aarch64

Install Additional Tools To Build And Run ARM 64-bit Redox OS Image

sudo apt-get install u-boot-tools qemu-system-arm qemu-efi

Configuration Values

Before your first build, be sure to set the ARCH variable in .config to your CPU architecture type, in this case aarch64. You can change several other configurable settings, such as the filesystem contents, etc. See Configuration Settings.

Add packages to the filesystem.

You can add programs to the filesystem by following the instructions on the Including Programs in Redox page.

Advanced Users

For more details on the build process, please read the Advanced Build page.

Compiling Redox

Now we have:

• Downloaded the sources
• Set the ARCH to aarch64
• Selected a filesystem config, e.g. desktop
• Tweaked the settings to our liking
• Probably added our recipe to the filesystem

We are ready to build the a Redox image.

Building an image for emulation

cd ~/tryredox/redox

This command will create the image, e.g. build/aarch64/desktop/harddrive.img, which you can run with an emulator. See the Running Redox page.

time make all

Give it a while. Redox is big.

Read the make all (first run) section to know what the command above does.

Cleaning Previous Build Cycles

Cleaning Intended For Rebuilding Core Packages And Entire System

When you need to rebuild core-packages like relibc, gcc and related tools, clean the entire previous build cycle with:

cd ~/tryredox/redox/

rm -rf prefix/aarch64-unknown-redox/relibc-install/ cookbook/recipes/gcc/{build,sysroot,stage*} build/aarch64/*/{harddrive.img,livedisk.iso}

Cleaning Intended For Only Rebuilding Non-Core Package(s)

If you're only rebuilding a non-core package, you can partially clean the previous build cycle just enough to force the rebuilding of the Non-Core Package:

cd ~/tryredox/redox/

rm build/aarch64/*/{fetch.tag,harddrive.img}

Running Redox

To open QEMU, run:

make qemu kvm=no gpu=no

This should boot to Redox. The desktop GUI will be disabled, but you will be prompted to login to the Redox console.

QEMU Tap For Network Testing

Expose Redox to other computers within a LAN. Configure QEMU with a "TAP" which will allow other computers to test Redox client/server/networking capabilities.

Join the Chat if this is something you are interested in pursuing.

Note

If you encounter any bugs, errors, obstructions, or other annoying things, please send a message in the Chat or report the issue on GitLab. Thanks!

Raspberry Pi

Build and run device-specific images

Most ARM motherboards do not use the default image for booting, which requires us to do some extra steps with building images.

Raspberry Pi 3 Model B+

It is easy to port Raspberry Pi 3 Model B+ (raspi3b+) since the bootloader of Raspberry Pi family uses the similar filesystem (FAT32) for booting.

In order to build a RasPi3B+ image:

• Add BOARD?=raspi3bp and CONFIG_NAME?=minimalto .config
• Run make all
• Download the firmware

cd ~/tryredox

git clone https://gitlab.redox-os.org/Ivan/redox_firmware.git

Run in QEMU

Assume that we are using the server-minimal configuration and built the image successfully, run:

• Add two additional dtb files to EFI system partition:

DISK=build/aarch64/server-minimal/harddrive.img
MOUNT_DIR=/mnt/efi_boot
DTB_DIR=$MOUNT_DIR/dtb/broadcom
WORKPLACE=/home/redox/tryredox
DTS=$WORKPLACE/redox_firmware/platform/raspberry_pi/rpi3/bcm2837-rpi-3-b-plus.dts

mkdir -p $MOUNT_DIR

mount -o loop,offset=$((2048*512)) $DISK $MOUNT_DIR

mkdir -p $DTB_DIR

dtc -I dts -O dtb $DTS > $DTB_DIR/bcm2837-rpi-3-b.dtb

cp $DTB_DIR/bcm2837-rpi-3-b.dtb $DTB_DIR/bcm2837-rpi-3-b-plus.dtb

sync

umount $MOUNT_DIR

• Run make qemu_raspi live=no

Booting from USB

Assume that we are using the server-minimal configuration and access serial console using GPIOs 14 and 15 (pins 8 and 10 on the 40-pin header). Do the following:

• Run make live
• Download the firmware from official repository

cd ~/tryredox

git clone --depth=1 https://github.com/raspberrypi/firmware.git

• Copy all required firmware to EFI system partition

DISK=build/aarch64/server-minimal/livedisk.iso
MOUNT_DIR=/mnt/efi_boot
DTB_DIR=$MOUNT_DIR/dtb/broadcom
WORKPLACE=/home/redox/tryredox
DTS=$WORKPLACE/redox_firmware/platform/raspberry_pi/rpi3/bcm2837-rpi-3-b-plus.dts
UBOOT=$WORKPLACE/redox_firmware/platform/raspberry_pi/rpi3/u-boot-rpi-3-b-plus.bin
CONFIG_TXT=$WORKPLACE/redox_firmware/platform/raspberry_pi/rpi3/config.txt
FW_DIR=$WORKPLACE/firmware/boot

mkdir -p $MOUNT_DIR

mount -o loop,offset=$((2048*512)) $DISK $MOUNT_DIR

cp -rf $FW_DIR/* $MOUNT_DIR

mkdir -p $DTB_DIR

dtc -I dts -O dtb $DTS > $DTB_DIR/bcm2837-rpi-3-b.dtb

cp $DTB_DIR/bcm2837-rpi-3-b.dtb $DTB_DIR/bcm2837-rpi-3-b-plus.dtb

cp $UBOOT $MOUNT_DIR/u-boot.bin

cp $CONFIG_TXT $MOUNT_DIR

sync

umount $MOUNT_DIR

• Run:

dd if=build/aarch64/server-minimal/livedisk.iso of=/dev/sdX

(/dev/sdX is your USB device.)

Booting from SD Card

This process is similar to that of "Booting from USB", but has some differences:

• Use harddrive.img instead of livedisk.iso
• After dd command, try to make the EFI system partition of the SD card become a hybrid MBR. See this post for more details

root@dev-pc:/home/ivan/code/os/redox# gdisk /dev/sdc
GPT fdisk (gdisk) version 1.0.8

Partition table scan:
  MBR: protective
  BSD: not present
  APM: not present
  GPT: present

Found valid GPT with protective MBR; using GPT.

Command (? for help): r

Recovery/transformation command (? for help): p
Disk /dev/sdc: 61067264 sectors, 29.1 GiB
Model: MassStorageClass
Sector size (logical/physical): 512/512 bytes
Disk identifier (GUID): B37FD04D-B67D-48AA-900B-884F0E3B2EAD
Partition table holds up to 128 entries
Main partition table begins at sector 2 and ends at sector 33
First usable sector is 34, last usable sector is 524254
Partitions will be aligned on 2-sector boundaries
Total free space is 2015 sectors (1007.5 KiB)

Number  Start (sector)    End (sector)  Size       Code  Name
   1              34            2047   1007.0 KiB  EF02  BIOS
   2            2048          264191   128.0 MiB   EF00  EFI
   3          264192          522239   126.0 MiB   8300  REDOX

Recovery/transformation command (? for help): h

WARNING! Hybrid MBRs are flaky and dangerous! If you decide not to use one,
just hit the Enter key at the below prompt and your MBR partition table will
be untouched.

Type from one to three GPT partition numbers, separated by spaces, to be
added to the hybrid MBR, in sequence: 2
Place EFI GPT (0xEE) partition first in MBR (good for GRUB)? (Y/N): n

Creating entry for GPT partition #2 (MBR partition #1)
Enter an MBR hex code (default EF): 0c
Set the bootable flag? (Y/N): n

Unused partition space(s) found. Use one to protect more partitions? (Y/N): n

Recovery/transformation command (? for help): o

Disk size is 61067264 sectors (29.1 GiB)
MBR disk identifier: 0x00000000
MBR partitions:

Number  Boot  Start Sector   End Sector   Status      Code
   1                  2048       264191   primary     0x0C
   2                     1         2047   primary     0xEE

Recovery/transformation command (? for help): w
Warning! Secondary header is placed too early on the disk! Do you want to
correct this problem? (Y/N): y
Have moved second header and partition table to correct location.

Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!!

Do you want to proceed? (Y/N): y
OK; writing new GUID partition table (GPT) to /dev/sdc.
The operation has completed successfully.
root@dev-pc:/home/ivan/code/os/redox#

Troubleshooting the Build

This page covers all troubleshooting methods and tips for our build system.

(You must read the Build System page before)

• Setup
  • Podman
    • Manual Configuration
  • Native Build
  • Git
• Building the System
  • .config and mk/config.mk
  • Prefix
  • Filesystem Configuration
  • Fetch
  • Cookbook
  • Create the Image with FUSE
• Solving Compilation Problems
  • Environment Leakage
  • Update Your Build System
  • Update Relibc
  • Fix Breaking Changes
  • Update Your Branch
  • Update Crates
  • Verify The Dependency Tree
• Debug Methods
  • Recipes
    • Rust
• Kill A Frozen Redox VM
• Kernel Panic
  • QEMU
  • Real Hardware

Setup

When you run podman_bootstrap.sh or native_bootstrap.sh, the Linux tools and libraries required to support the toolchain and build all recipes are installed. Then the redox project is downloaded from the Redox GitLab server. The redox project does not contain the system component sources, it only contains the build system. The cookbook subproject, which contains recipes for all the packages to be included in Redox, is also copied as part of the download.

Podman

If your build appears to be missing libraries, have a look at the Debugging Your Podman Build Process section. If your Podman environment becomes broken, you can use podman system reset and rm -rf build/podman. In some cases, you may need to run the sudo rm -rf build/podman command.

Manual Configuration

If you have problems setting Podman to rootless mode, do the following steps:

(These commands were taken from the official Podman rootless wiki and Shortcomings of Rootless Podman, thus it could be broken/wrong in the future, read the wiki to see if the commands match, we will try to update the method to work with everyone)

• Install the podman, crun, slirp4netns and fuse-overlayfs packages on your system.
• podman ps -a - This command will show all your Podman containers, if you want to remove all of them, run podman system reset
• Follow this step if necessary (if the Podman of your distribution use cgroups V2), you will need to edit the containers.conf file at /etc/containers or your user folder at ~/.config/containers, change the line runtime = "runc" to runtime = "crun"
• Execute the cat /etc/subuid and cat /etc/subgid commands to see user/group IDs (UIDs/GIDs) available for Podman.

If you don't want to edit the file, you can use this command:

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 your-user

You can use the values 100000-165535 for your user, just edit the two text files, we recommend sudo nano /etc/subuid and sudo nano /etc/subgid, when you finish, press Ctrl+X to save the changes.

• After the change on the UID/GID values, execute this command:

podman system migrate

• If you have a network problem on the container, this command will allow connections on the port 443 (without root):

sudo sysctl net.ipv4.ip_unprivileged_port_start=443

• Hopefully, you have a working Podman build now.

(If you still have problems with Podman, read the Troubleshooting chapter or join us on the chat)

Let us know if you have improvements for Podman troubleshooting on the chat.

Native Build

Not all Linux distributions are supported by native_bootstrap.sh, so if you have frequent compilation problems try the podman_bootstrap.sh script for Podman builds.

If you want to support your Unix-like system without Podman, you can try to install the Debian/Ubuntu package equivalents for your system from your package manager/software store, you can see them on the ubuntu() function of the native_bootstrap.sh script.

The native_bootstrap.sh script and redox-base-containerfile covers the build system packages needed by the recipes at the demo.toml filesystem configuration.

(Note that some systems may have build environment problems hard and time consuming to fix, on these systems Podman will fix most headaches)

Git

If you did not use podman_bootstrap.sh or native_bootstrap.sh to setup your environment, you can download the sources with:

git clone https://gitlab.redox-os.org/redox-os/redox.git --origin upstream --recursive

• If the cookbook project or other components are missing, ensure that you used the --recursive flag when doing git clone.
• Ensure that all the libraries and packages required by Redox are installed by running ./bootstrap.sh -d or, if you will be using the Podman build run the ./podman_bootstrap.sh -d command.

Building The System

When you run make all, the following steps occur.

.config and mk/config.mk

• make scans .config and mk/config.mk for settings, such as the CPU architecture, configuration name, and whether to use Podman during the build process. Read through the Configuration Settings page to make sure you have the settings that are best for you.

Prefix

The Redox toolchain, referred to as prefix because it is prefixed with the CPU architecture name, is downloaded and/or built. Modified versions of cargo, rustc, gcc and many other tools are created. They are placed in the prefix directory.

If you have a problem with the toolchain, try rm -rf prefix, and everything will be reinstalled the next time you run make all or make rebuild.

Filesystem Configuration

The list of Redox recipes to be built is read from the filesystem configuration file, which is specified in .config or mk/config.mk. If your recipe is not being included in the build, verify if you have set the CONFIG_NAME or FILESYSTEM_CONFIG in the .config file.

Fetch

Each recipe source is downloaded using git or curl, according to the [source] section of the recipe.toml file. Source is placed at cookbook/recipes/recipe-name/source.

(Some recipes still use the old recipe.sh format, they need to be converted to TOML)

If you are doing work on a recipe, you may want to comment out the [source] section of the recipe. To discard your changes to the source for a recipe, or to update to the latest version, uncomment the [source] section of the recipe, and use make uc.recipe-name in the recipe directory to remove both the source and any compiled code.

After all recipes are fetched, a tag file is created as build/$ARCH/$CONFIG_NAME/fetch.tag, e.g. build/x86_64/desktop/fetch.tag. If this file is present, fetching is skipped. You can remove it manually, or use make rebuild, if you want to force refetching.

Cookbook

Each recipe is built according to the recipe.toml file. The recipe binaries or library objects are placed in the target directory, in a subdirectory named based on the CPU architecture. These tasks are done by various Redox-specific shell scripts and commands, including repo.sh, cook.sh and Cargo. These commands make assumptions about $PATH and $PWD, so they might not work if you are using them outside the build process.

If you have a problem with a recipe you are building, try the make c.recipe-name command. A common problem when building on unsupported systems is that certain recipes will fail to build due to missing dependencies. Try using the Podman Build or manually installing the recipe dependencies.

After all recipes are cooked, a tag file is created as build/$ARCH/$CONFIG_NAME/repo.tag. If this file is present, cooking is skipped. You can remove it manually, or use make rebuild, which will force refetching and rebuilding.

Create the Image with FUSE

To build the final Redox image, redox_installer uses FUSE, creating a virtual filesystem and copying the recipe packages into it. This is done outside of Podman, even if you are using Podman Build.

On some Linux distributions, FUSE may not be permitted for some users, or bootstrap.sh might not install it correctly. Investigate whether you can address your FUSE issues, or join the chat if you need advice.

Solving Compilation Problems

• Verify your Rust version (run make env and cargo --version, then exit), make sure you have the latest version of Rust nightly!.

  • rustup.rs is recommended for managing Rust versions. If you already have it, run the rustup command.

• Verify if your make and nasm are up-to-date.

• Verify if the build system is using the latest commit by running the git branch -v command.

• Verify if the submodules are using the latest pinned commit, to do this run:

cd submodule-name

git branch -v

• Verify if the recipe source is using the latest commit of the default branch, to do this run:

cd cookbook/recipes/some-category/recipe-name/source

git branch -v

• Run make clean pull fetch to remove all your compiled binaries and update all sources.
• Sometimes there are merge requests that briefly break the build, so check the Chat if anyone else is experiencing your problems.
• Sometimes both the source and the binary of some recipe is wrong, run make ucr.recipe-name and verify if it fix the problem.

Environment Leakage

Environment leakage is when some program or library is not fully cross-compiled to Redox, thus its dependency chain has Linux references that don't work on Redox.

It usually happens when the program or library get objects from outside the Redox build system PATH.

• The Redox build system PATH only read at /usr/bin and /bin to use the host system build tools
• The program build system must use the host system build tools and the Cookbook recipe dependencies, not the host system libraries.
• The most common way to detect this is to install the *-dev dependency package equivalent to the program recipe dependency, for example:

The program named "my-program" needs to use the OpenSSL library, thus you add the openssl recipe on the recipe.toml of the program, but the program don't detect the OpenSSL source code.

Then you install the libssl-dev package on your Ubuntu system and rebuild the program with the make cr.my-program command, then it finish the build process successfully.

But when you try to open the executable of the program inside of Redox, it doesn't work. Because it contain Linux references.

To fix this problem you need to find where the program build system get the OpenSSL source code and patch it with ${COOKBOOK_SYSROOT} environment variable (where the openssl recipe contents were copied)

Update Your Build System

Sometimes your build system can be outdated because you forgot to run make pull before other commands, read this section to learn the complete way to update the build system.

Update Relibc

An outdated relibc copy can contain bugs (already fixed on recent versions) or missing APIs, read this section to learn how to update it.

Fix Breaking Changes

• Build System

Sometimes build system breaking changes are merged (you need to monitor the Dev room in our chat to know if some MRs containing breaking changes were merged) and you need to cleanup most of your build system files to avoid conflicts with the new configuration, the make distclean pull all command should work in most cases because it wipe sources and binaries that can cause conflicts after the build system update.

If the method above doesn't work you need to download a new copy of the build system by running the podman_bootstrap.sh or native_bootstrap.sh scripts or using the following commands:

git clone https://gitlab.redox-os.org/redox-os/redox.git --origin upstream --recursive

cd redox

make all

• Recipes

Some types of recipe errors can be backwards-incompatible build system, system component or relibc changes after the make pull rebuild command execution. Run the following tests to verify if the recipe error is an isolated problem or a breaking change:

• Rebuild the recipe binaries

make cr.recipe-name

Check if the compilation or runtime error continues after this command, if the error continues run the following test:

• Wipe the recipe sources and binaries and rebuild

make ucr.recipe-name

Check if the compilation or runtime error continues after this command, if the error continues run the following test:

• Update relibc and rebuild the recipe

touch relibc

make prefix cr.recipe-name

Check if the compilation or runtime error continues after this command, if the error continues run the following test:

• Reconfigure the Redox toolchain and rebuild the recipe

rm -rf prefix

make prefix cr.recipe-name

Check if the compilation or runtime error continues after this command, if the error continues run the following test:

• Wipe the build system binaries, update the build system configuration and build the system (download the Redox toolchain, build the build system tools and recipe sources)

make clean all

Check if the compilation or runtime error continues after this command, if the error continues it very probably doesn't happen because of breaking changes but there's not common exception for source breaking changes in the following test:

• Wipe the build system sources and binaries, update the build system configuration and build the system (download the Redox toolchain, build the build system tools, download the recipe sources and build them)

make distclean all

Check if the compilation or runtime error continues after this command, if the error continues it doesn't happen because of breaking changes

Update Your Branch

If you are doing local changes on the build system, probably you left your branch active on the folder (instead of master branch).

New branches don't sync automatically with master, thus if the master branch receive new commits, you wouldn't use them because your branch is outdated.

To fix this, run:

git checkout master

git pull

git checkout your-branch

git merge master

Or

git checkout master

git pull

git merge your-branch master

If you want an anonymous merge, read the Anonymous Commits section.

Update Crates

Sometimes a Rust program use an old crate version lacking Redox support, read this section to learn how to update them.

Verify The Dependency Tree

Some crates take a long time to do a new release (years in some cases), thus these releases will hold old versions of other crates, versions where the Redox support is not available (causing errors during the program compilation).

The redox_syscall crate is the most affected by this, some crates hold a very old version of it and will require patches (cargo update -p alone doesn't work).

To identify which crates are using old versions of Redox crates you will need to verify the dependency tree of the program, inside the program source directory, run:

cargo tree --target=x86_64-unknown-redox

This command will draw the dependency tree and you will need to find the crate name on the tree.

If you don't want to find it, you can use the grep tool with a pipe to see all crate versions used in the tree, sadly grep don't preserve the tree hierarchy, thus it's only useful to see versions and if some patched crate works (if the patched crate works all crate matches will report the most recent version).

To do this, run:

cargo tree --target=x86_64-unknown-redox | grep crate-name

Debug Methods

• Use the dmesg command to read the kernel and user-space daemons log.

• You can start the QEMU with the make qemu gpu=no command to easily copy the terminal text.

• Use the following command for advanced logging:

make some-command 2>&1 | tee file-name.log

• You can write to the debug: scheme, which will output on the console, but you must be root. This is useful if you are debugging an app where you need to use Orbital but still want to capture messages.

• Currently, the build system strips function names and other symbols from programs, as support for symbols is not implemented on Redox.

Recipes

You will see the available debug methods for recipes on this section.

• If you change the recipe build mode (release to debug or the opposite) while debugging, don't forget to rebuild with make cr.recipe-name because the build system may not detect the changes.

Rust

Rust programs can carry assertions, checking and symbols, but they are disabled by default.

• COOKBOOK_DEBUG - This environment variable will build the Rust program with assertions, checking and symbols.
• COOKBOOK_NOSTRIP - This environment variable will package the recipe with symbols.

(Debugging with symbols inside of Redox is not supported yet)

To enable them you can use these commands or scripts:

• Enable the COOKBOOK_DEBUG environment variable for one command and build a recipe:

COOKBOOK_DEBUG=true make r.recipe-name

• Enable the COOKBOOK_DEBUG environment variable for multiple commands and build a recipe:

export COOKBOOK_DEBUG=true

make r.recipe-name

• Enable the COOKBOOK_DEBUG and COOKBOOK_NOSTRIP environment variables for one command and build a recipe:

COOKBOOK_DEBUG=true COOKBOOK_NOSTRIP=true make r.recipe-name

• Enable the COOKBOOK_DEBUG and COOKBOOK_NOSTRIP environment variables for multiple commands and build a recipe:

export COOKBOOK_DEBUG=true

export COOKBOOK_NOSTRIP=true

make r.recipe-name

• Enable the COOKBOOK_DEBUG environment variable inside the recipe.toml:

template = "custom"
script = """
COOKBOOK_DEBUG=true
cookbook_cargo
"""

• Enable the COOKBOOK_DEBUG and COOKBOOK_NOSTRIP environment variables inside the recipe.toml:

template = "custom"
script = """
COOKBOOK_DEBUG=true
COOKBOOK_NOSTRIP=true
cookbook_cargo
"""

• Backtrace

A backtrace helps you to detect bugs that happen with not expected input parameters, you can trace back through the callers to see where the bad data is coming from.

You can see how to use it below:

• Start QEMU with logging:

make qemu 2>&1 | tee file-name.log

• Enable this environment variable globally (on Redox):

export RUST_BACKTRACE=full

• Run the program and repeat the bug (capturing a backtrace in the log file)

• Close QEMU

• Open the log file, copy the backtrace and paste in an empty text file

• Run the backtrace.sh script in the redox directory (on Linux):

scripts/backtrace.sh -r recipe-name -b your-backtrace.txt

It will print the file and line number for each entry in the backtrace.

(This is the most simple example command, use the -h option of the backtrace.sh script to see more combinations)

Kill A Frozen Redox VM

Sometimes Redox can freeze or rarely get a kernel panic, to kill the QEMU process run this command:

pkill qemu-system

Kernel Panic

A kernel panic is when some bug avoid the safe execution of the kernel code, thus the system needs to be restarted to avoid data corruption.

We use the following kernel panic message format:

KERNEL PANIC: panicked at some-path/file-name.rs:line-number:character-position:
the panic description goes here

• You can use the following command to search it in a big log:

grep -nw "KERNEL PANIC" --include "file-name.log"

QEMU

If you get a kernel panic in QEMU, copy the terminal text or capture a screenshot and send to us on Matrix or create an issue on GitLab.

Real Hardware

If you get a kernel panic in real hardware, capture a photo and send to us on Matrix or create an issue on GitLab.

Build System

The build system downloads and creates several files that you may want to know about. There are also several make commands mentioned below, and a few extras that you may find useful. Here's a quick summary. All file paths are relative to your redox base directory.

• Build System Organization
  • Root Folder
  • GNU Make Configuration
  • Podman Configuration
  • Filesystem Configuration
  • Cookbook
  • Build System Files
• GNU Make Commands
  • Build System
  • Recipes
  • QEMU/VirtualBox
• Environment Variables
• Scripts
• Component Separation
• Crates
  • Current Projects With Crates
  • Manual Patching
• Pinned Commits
  • Current Pinned Submodules
  • Manual Submodule Update
• Git Auto-checkout
  • Submodules
• Update The Build System
• Update Relibc
• Fix Breaking Changes
  • All Recipes
  • One Recipe
• Configuration
  • Format
  • Filesystem Customization
• Cross-Compilation
• Build Phases

Build System Organization

Root Folder

• podman_bootstrap.sh - The script used to configure the Podman build
• native_bootstrap.sh - The script used to configure the Native build
• Makefile - The main Makefile of the build system, it loads all the other Makefiles.
• .config - Where you override your build system settings. It is loaded by the Makefile (it is ignored by git).

GNU Make Configuration

• mk/config.mk - The build system settings are here. You can override these settings in your .config, don't change them here to avoid conflicts in the make pull command.
• mk/*.mk - The rest of the Makefiles. You should not need to change them.

Podman Configuration

• podman/redox-base-containerfile - The file used to create the image used by the Podman build. The installation of Ubuntu packages needed for the build is done here. See the Adding Packages to the Build section if you need to add additional Ubuntu packages.

Filesystem Configuration

• config - This folder contains all filesystem configurations.
• config/*.toml - Filesystem templates used by the CPU target configurations (a template can use other template to reduce duplication)
• config/your-cpu-arch/your-config.toml - The filesystem configuration of the QEMU image to be built, e.g. config/x86_64/desktop.toml
• config/your-cpu-arch/server.toml - The variant with system components (without Orbital) and some important tools. Aimed for servers, low-end computers, testers and developers.

(Try this config if you have boot problems on QEMU or real hardware).

• config/your-cpu-arch/desktop.toml - The variant with system components, the Orbital desktop environment and some important programs (this is the default configuration of the build system). Aimed for end-users, gamers, testers and developers.
• config/your-cpu-arch/dev.toml - The variant with development tools included. Aimed for developers.
• config/your-cpu-arch/demo.toml - The variant with a complete system and optional programs and games. Aimed for end-users, gamers, testers and developers.
• config/your-cpu-arch/desktop-minimal.toml - The minimal desktop variant for low-end computers and embedded hardware. Aimed for servers, low-end computers, embedded hardware and developers.
• config/your-cpu-arch/minimal.toml - The variant without network support and Orbital. Aimed for low-end computers, embedded hardware, testers and developers.
• config/your-cpu-arch/minimal-net.toml - The variant without Orbital and tools. Aimed for low-end computers, embedded hardware, testers and developers.
• config/your-cpu-arch/resist.toml - The variant with the resist POSIX test suite. Aimed for developers.
• config/your-cpu-arch/acid.toml - The variant with the acid general-purpose test suite. Aimed for developers.
• config/your-cpu-arch/ci.toml - The continuous integration variant, recipes added here become packages on the build server. Aimed for packagers and developers.
• config/your-cpu-arch/jeremy.toml - The build of Jeremy Soller (creator/BDFL of Redox) with the recipes that he is testing at the moment.

Cookbook

• prefix/* - Tools used by the Cookbook system. They are normally downloaded during the first system build.

(If you are having a problem with the build system, you can remove the prefix directory and it will be recreated during the next build)

• cookbook/* - Part of the Cookbook system, these scripts and tools will build your recipes.
• cookbook/repo - Contains all packaged recipes.
• cookbook/recipes/recipe-name - A recipe (software port) directory (represented as recipe-name), this directory holds the recipe.toml file.
• cookbook/recipes/recipe-name/recipe.toml - The recipe configuration file, this configuration contains instructions for downloading Git repositories or tarballs, then creating executables or other files to include in the Redox filesystem. Note that a recipe can contain dependencies that cause other recipes to be built, even if the dependencies are not otherwise part of your Redox build.

(To learn more about the recipe system read the Porting Applications using Recipes page)

• cookbook/recipes/recipe-name/recipe.sh - The old recipe configuration format (can't be used as dependency of a recipe with a TOML syntax).
• cookbook/recipes/recipe-name/source.tar - The tarball of the recipe (renamed).
• cookbook/recipes/recipe-name/source - The directory where the recipe source is extracted or downloaded.
• cookbook/recipes/recipe-name/target - The directory where the recipe binaries are stored.
• cookbook/recipes/recipe-name/target/${TARGET} - The directory for the recipes binaries of the CPU architecture (${TARGET} is the environment variable of your CPU architecture).
• cookbook/recipes/recipe-name/target/${TARGET}/build - The directory where the recipe build system run its commands.
• cookbook/recipes/recipe-name/target/${TARGET}/stage - The directory where recipe binaries go before the packaging, after make all, make rebuild and make image the installer will extract the recipe package on the QEMU image, generally at /usr/bin or /usr/lib in a Redox filesystem hierarchy.
• cookbook/recipes/recipe-name/target/${TARGET}/sysroot - The folder where recipe build dependencies (libraries) goes, for example: library-name/src/example.c
• cookbook/recipes/recipe-name/target/${TARGET}/stage.pkgar - Redox package file.
• cookbook/recipes/recipe-name/target/${TARGET}/stage.sig - Signature for the tar package format.
• cookbook/recipes/recipe-name/target/${TARGET}/stage.tar.gz - Legacy tar package format, produced for compatibility reasons as we are working to make the package manager use the pkgar format.
• cookbook/recipes/recipe-name/target/${TARGET}/stage.toml - Contains the runtime dependencies of the package and is part of both package formats.

Build System Files

• build - The directory where the build system will place the final image. Usually build/$(ARCH)/$(CONFIG_NAME), e.g. build/x86_64/desktop
• build/your-cpu-arch/your-config/harddrive.img - The Redox image file, to be used by QEMU or VirtualBox for virtual machine execution on a Unix-like host.
• build/your-cpu-arch/your-config/livedisk.iso - The Redox bootable image file, to be used on real hardware for testing and possible installation.
• build/your-cpu-arch/your-config/fetch.tag - An empty file that, if present, tells the build system that the downloading of recipe sources is done.
• build/your-cpu-arch/your-config/repo.tag - An empty file that, if present, tells the build system that all recipes required for the Redox image have been successfully built. The build system will not check for changes to your code when this file is present. Use make rebuild to force the build system to check for changes.
• build/podman - The directory where Podman Build places the container user's home directory, including the container's Rust installation. Use make container_clean to remove it. In some situations, you may need to remove this directory manually, possibly with root privileges.
• build/container.tag - An empty file, created during the first Podman build, so a Podman build knows when a reusable Podman image is available. Use make container_clean to force a rebuild of the Podman image on your next make rebuild run.

GNU Make Commands

You can combine make commands, but order is significant. For example, make r.games image will build the games recipe and create a new Redox image, but make image r.games will make the Redox image before the recipe building, thus the new recipe binary will not be included on your Redox filesystem.

Build System

• make pull - Update the source code of the build system without building.
• make all - Builds the entire system, checking for changes and only building as required. Only use this for the first build. If the system was successfully built previously, this command may report Nothing to be done for 'all', even if some recipes have changed. Use make rebuild instead.
• make rebuild - Update all binaries from recipes with source code changes (it don't detect changes on the Redox toolchain), it should be your normal make target.
• make prefix - Download the Rust/GCC forks and build relibc (it update the relibc binary with source code changes after the make pull, touch relibc and make prefix commands).
• make fstools - Build the image builder (installer), Cookbook and RedoxFS (after touch installer or touch redoxfs).
• make fstools_clean - Clean the image builder, Cookbook and RedoxFS binaries.
• make fetch - Update recipe sources, according to each recipe, without building them. Only the recipes that are included in your (CONFIG_NAME).toml are downloaded. Does nothing if $(BUILD)/fetch.tag is present. You won't need this.
• make clean - Clean all recipe binaries (Note that make clean may require some tools to be built).
• make unfetch - Clean all recipe sources.
• make distclean - Clean all recipe sources and binaries (please backup or submit your source changes before the execution of this command).
• make repo - Package the recipe binaries, according to each recipe. Does nothing if $(BUILD)/repo.tag is present. You won't need this.
• make live - Creates a bootable image, build/livedisk.iso. Recipes are not usually rebuilt.
• make popsicle - Flash the Redox bootable image on your USB device using the Popsicle tool (the program executable must be present on your shell $PATH environment variable, you can get the executable by extracting the AppImage, installing from the package manager or building from source)
• make env - Creates a shell with the build environment initialized. If you are using Podman Build, the shell will be inside the container, and you can use it to debug build issues such as missing packages.
• make container_shell - Open the GNU Bash shell of the Podman container as the active shell of your terminal, it's logged as the podman user without root privileges.
• make container_su - Open the GNU Bash shell of the Podman container as the active shell of your terminal, it's logged as the root user.
• make container_clean - This will discard images and other files created by Podman.
• make container_touch - If you have removed the file build/container.tag, but the container image is still usable, this will recreate the container.tag file and avoid rebuilding the container image.
• make container_kill - If you have started a build using Podman Build, and you want to stop it, Ctrl-C may not be sufficient. Use this command to terminate the most recently created container.

Recipes

• make f.recipe-name - Download the recipe source.

• make r.recipe-name - Build a single recipe, checking if the recipe source has changed, and creating the executable, etc. e.g. make r.games (you can't use this command to replace the make all, make fstools and make prefix commands because it don't trigger them, make sure to run them before to avoid errors)

  The package is built even if it is not in your filesystem configuration.

  (This command will continue where you stopped the build process, it's useful to save time if you had a compilation error and patched a crate)

• make c.recipe-name - Clean the recipe binaries.

• make u.recipe-name - Clean the recipe source code (please backup or submit your source changes before the execution of this command).

• make cr.recipe-name - A shortcut for make c.recipe r.recipe

• make ucr.recipe-name - A shortcut for make u.recipe c.recipe r.recipe (please backup or submit your source changes before the execution of this command).

QEMU/VirtualBox

• make qemu - If a build/harddrive.img file exists, QEMU will run using that image. If you want to force a rebuild first, use make rebuild qemu. Sometimes make qemu will detect changes and rebuild, but this is not typical. If you are interested in a particular combination of QEMU command line options, have a look through mk/qemu.mk.
• make qemu gpu=no - Start QEMU without a GUI (Orbital is disabled).
• make qemu gpu=virtio - Start QEMU with the VirtIO GPU driver.
• make qemu kvm=no - Start QEMU without the Linux KVM acceleration.
• make qemu iommu=no - Start QEMU without IOMMU.
• make qemu audio=no - Disable all sound drivers.
• make qemu usb=no - Disable all USB drivers.
• make qemu uefi=yes - Enable the UEFI boot loader (it supports more screen resolutions).
• make qemu live=yes - Fully load the Redox image to RAM.
• make qemu disk=nvme - Boot Redox from a NVMe interface (SSD emulation).
• make qemu disk=usb - Boot Redox from a virtual USB device.
• make qemu disk=cdrom - Boot Redox from a virtual CD-ROM disk.
• make qemu option1=string option2=string - Cumulative QEMU options is supported.
• make image - Builds a new QEMU image, build/harddrive.img, without checking if any recipes have changed. It can save you some time if you are just updating one recipe with make r.recipe-name.
• make gdb - Connects gdb to the Redox image in QEMU. Join us on the chat if you want to use this.
• make mount - Mounts the Redox image as a filesystem at $(BUILD)/filesystem. Do not use this if QEMU is running, and remember to use make unmount as soon as you are done. This is not recommended, but if you need to get a large file onto or off of your Redox image, this is available as a workaround.
• make unmount - Unmounts the Redox image filesystem. Use this as soon as you are done with make mount, and do not start QEMU until this is done.
• make virtualbox - The same as make qemu, but for VirtualBox (it requires the VirtualBox service to be running, run systemctl status vboxdrv.service to verify or akmods; systemctl restart vboxdrv.service to enable on systems using systemd).

Environment Variables

• $(BUILD) - Represents the build folder.
• $(ARCH) - Represents the CPU architecture folder at build
• ${TARGET} - Represents the CPU architecture folder at the cookbook/recipes/recipe-name/target folder
• $(CONFIG_NAME) - Represents your filesystem configuration folder at build/your-cpu-arch

We recommend that you use these variables with the " symbol to clean any spaces on the path, spaces are interpreted as command separators and will break the commands.

Example:

"${VARIABLE_NAME}"

If you have a folder inside the variable folder you can call it with:

"${VARIABLE_NAME}"/folder-name

Or

"${VARIABLE_NAME}/folder-name"

Scripts

You can use these scripts to perform actions not implemented as make commands in the build system.

• To run a script use the following command:

scripts/script-name.sh input-text

The "input-text" is the word used by the script.

Changelog

• scripts/changelog.sh - Show the changelog of all Redox components.

Recipe Files

Show all files installed by a recipe.

scripts/find-recipe.sh recipe-name

Recipe Categories

Run make options on some recipe category.

scripts/category.sh -x category-name

Where x is your make option, it can be f, r, c, u, cr, ucr, uc or ucf

Include Recipes

Create a list with recipe-name = {} #TODO for quick testing of WIP recipes.

scripts/include-recipes.sh "TODO.text"

You will insert the text after the #TODO in the text part, it can be found on the recipe.toml file of the recipe.

If you want to add recipes to the ci.toml filesystem configuration to be available on the package build server, the recipe names must be sorted in alphabetical order, to do this from the output of this script use the following command:

scripts/include-recipes.sh "TODO.text" | sort

Recipe Analysis

Show the folders and files on the stage and sysroot folders of some recipe (to identify packaging issues or violations).

scripts/show-package.sh recipe-name

Recipe Commit Hash

Show the current Git branch and commit of the recipe source.

scripts/commit-hash.sh recipe-name

Package Size

Show the package size of the recipes (stage.pkgar and stage.tar.gz), it must be used by package maintainers to enforce the library linking size policy.

scripts/pkg-size.sh recipe-name

Recipe Location

Show the location of the written recipe.

scripts/recipe-path.sh recipe-name

Recipe Match

Search some text inside the recipe.toml of some recipe.

scripts/recipe-match.sh recipe-name

Print Recipe

Show the content of the recipe configuration.

(Require bat and ripgrep installed, run cargo install bat ripgrep to install)

scripts/print-recipe.sh recipe-name

Recipe Executables

List the recipe executables to find duplicates and conflicts.

• By default the script will only verify duplicates, if the -a option is used it will print the executable names of all compiled recipes
• The -arm64 option will show the ARM64 recipe executables
• The -i686 option will show the i686 recipe executables

scripts/executables.sh

Cargo Update

Download the recipe source and run cargo update

scripts/cargo-update.sh recipe-name

Dual Boot

• scripts/dual-boot.sh - Install Redox in the free space of your storage device and add a boot entry (if you are using the systemd-boot boot loader).

Ventoy

• scripts/ventoy.sh - Create and copy the Redox bootable image to an Ventoy-formatted device.

Recipe Debugging (Rust)

• scripts/backtrace.sh - Allow the user to copy a Rust backtrace from Redox and retrieve the symbols (use the -h option to show the "Usage" message).

Component Separation

• relibc - The cross-compiled recipes will link to the relibc of this folder (build system submodule)
• redoxfs - The FUSE driver of RedoxFS (build system submodule, to run on Linux)
• cookbook/recipes/relibc - The relibc recipe to be installed inside of Redox for static or dynamic linking of binaries (for native compilation)
• cookbook/recipes/redoxfs - The RedoxFS user-space daemon that run inside of Redox (recipe)

Crates

Some Redox projects have crates on crates.io, thus they use a version-based development, if some change is sent to their repository they need to release a new version on crates.io, it will have some delay.

Current Projects With Crates

• libredox
• redox_syscall
• redox-path
• redox-scheme
• redoxfs
• redoxer
• redox_installer
• redox-kprofiling
• redox-users
• redox-buffer-pool
• redox_log
• redox_termios
• redox-daemon
• redox_event
• redox_event_update
• redox_pkgutils
• redox_uefi
• redox_uefi_alloc
• redox_dmi
• redox_hwio
• redox_intelflash
• redox_liner
• redox_uefi_std
• ralloc
• orbclient
• orbclient_window_shortcuts
• orbfont
• orbimage
• orbterm
• orbutils
• slint_orbclient
• ralloc_shim
• ransid
• gitrepoman
• pkgar
• pkgar-core
• pkgar-repo
• termion
• reagent
• gdb-protocol
• orbtk
• orbtk_orbclient
• orbtk-render
• orbtk-shell
• orbtk-tinyskia

Manual Patching

If you don't want to wait a new release on crates.io, you can patch the crate temporarily by fetching the version you need from GitLab and changing the crate version in Cargo.toml to crate-name = { path = "path/to/crate" }

Pinned Commits

The build system pin the last working commit of the submodules, if some submodule is broken because of some commit, the pinned commit avoid the fetch of this broken commit, thus pinned commits increase the development stability (broken changes aren't passed for developers and testers).

(When you run make pull the build system update the submodule folders based on the last pinned commit)

Current Pinned Submodules

• cookbook
• installer
• redoxfs
• relibc
• rust

Manual Submodule Update

Whenever a fix or new feature is merged on the submodules, the upstream build system must update the commit hash, to workaround this you can run git pull on the folder of the submodule directly, example:

make pull

cd submodule-folder-name

git checkout master

git pull

cd ..

Git Auto-checkout

The make rebuild and make r.recipe commands will Git checkout (change the active branch) of the recipe source to master (only recipes that fetch Git repositories are affected, thus all Redox components).

If you are working in a separated branch on the recipe source you can't build your changes, to avoid this comment out the [source] and git = fields from your recipe.toml :

#[source]
#git = "some-repository-link"

Submodules

The make pull command will Git checkout the submodules active branches to master and pin a commit in HEAD, if you are working on the build system submodules don't run this command, to keep the build system using your changes.

To update the build system while you have out-of-tree changes in some submodule, run these commands:

• This command will only update the root build system files

git pull

• Now you need to manually update each submodule folder without your changes

cd submodule-name

git checkout master

git pull

cd ..

Update The Build System

This is the recommended way to update your build system/recipe sources and binaries.

make pull rebuild

If the make pull command download new commits of the relibc submodule, you will need to run the commands of the Update relibc section.

Update Relibc

An outdated relibc copy can contain bugs (already fixed on recent commits) or missing APIs, to update the relibc sources and build it, run:

make pull

touch relibc

make prefix

Fix Breaking Changes

To learn how to fix breaking changes before and after build system updates read this section.

All recipes

To pass the new relibc changes for all recipes (programs are the most common case) you will need to rebuild all recipes, unfortunately it's not possible to use make rebuild because it can't detect the relibc changes to trigger a complete rebuild.

To clean all recipe binaries and trigger a complete rebuild, run:

make clean all

One Recipe

To pass the new relibc changes to one recipe, run:

make cr.recipe-name

Configuration

You can find the global settings on the Configuration Settings page.

Format

The Redox configuration files use the TOML format, it has a very easy syntax and is very flexbile.

You can see what the format supports on the TOML website.

Filesystem Customization

Read the Filesystem Customization section.

Cross-Compilation

The Redox build system is an example of cross-compilation. The Redox toolchain runs on Linux, and produces Redox executables. Anything that is installed with your package manager is just part of the toolchain and does not go on Redox.

In the background, the make all command downloads the Redox toolchain to build all recipes (patched forks of rustc, GCC and LLVM).

If you are using Podman, the podman_bootstrap.sh script will download an Ubuntu container and make all will install the Redox toolchain, all recipes will be compiled in the container.

The recipes produce Redox-specific executables. At the end of the build process, these executables are installed inside the QEMU image.

The relibc (Redox C Library) provides the Redox system calls to any software.

• OSDev article about cross-compilation

Build Phases

Every build system command/script has phases, read this page to know them.

• Build Phases

Build Phases

Every build system command and script has phases, this page documents them.

• native_bootstrap.sh
• podman_bootstrap.sh
• make all (first run)
• make all (second run)
• make all (Podman, first run)
• make prefix
• make prefix (after "touch relibc")
• make rebuild
• make r.recipe
• make qemu

native_bootstrap.sh

This is the script used to do the initial configuration of the build system, see its phases below:

• Install the Rust toolchain (using rustup.rs) and add cargo to the shell PATH.
• Install the packages (based on your Unix-like distribution) of the development tools to build all recipes.
• Download the build system sources (if you run without the -d option - ./native_bootstrap.sh -d)
• Show a message with the commands to build the Redox system.

podman_bootstrap.sh

This script is the alternative to native_bootstrap.sh for Podman, used to configure the build system for a Podman environment, see its phases below:

• Install Podman, GNU Make, FUSE and QEMU if it's not installed.
• Download the Debian container and install the recipe dependencies.
• Download the build system sources (if you run without the -d option - ./podman_bootstrap.sh -d)
• Show a message with the commands to build the Redox system.

make all (first run)

This is the command used to build all recipes inside your default TOML configuration (config/your-cpu-arch/desktop.toml or the one inside your .config), see its phases below:

• Download the binaries of the Redox toolchain (patched rustc, GCC and LLVM) from the build server.
• Download the sources of the recipes specified on your TOML configuration.
• Build the recipes.
• Package the recipes.
• Create the QEMU image and install the packages.

make all (second run)

If the build/$ARCH/$CONFIG/repo.tag file is up to date, it won't do anything. If the repo.tag file is missing it will works like make rebuild.

make all (Podman environment, first run)

This command on Podman works in a different way, see its phases below:

• Download the Redox container (Ubuntu + Redox toolchain).
• Install the Rust toolchain inside the container.
• Install the Ubuntu packages of the development tools to build all recipes (inside the container).
• Download the sources of the recipes specified on your TOML configuration.
• Build the recipes.
• Package the recipes.
• Create the QEMU image and install the packages.

make prefix

This command is used to download the build system toolchain, see its phases below:

• Download the Rust and GCC forks from the build server (if it's not present or you if you executed rm -rf prefix to fix issues).
• Build the relibc submodule.

make prefix (after "touch relibc")

• Build the new relibc changes

make rebuild

This is the command used to verify and build the recipes with changes, see its phases below:

• Verify source changes on recipes (if confirmed, download them) or if a new recipe was added to the TOML configuration.
• Build the recipes with changes.
• Package the recipes with changes.
• Create the QEMU image and install the packages.

make r.recipe

This is the command used to build a recipe, see its phases below.

• Search where the recipe is stored.
• Verify if the source folder is present, if not, download the source from the method specified inside the recipe.toml (this step will be ignored if the [source] and git = fields are commented out).
• Build the recipe dependencies as static objects (for static linking).
• Start the compilation based on the template of the recipe.toml
• If the recipe is using Cargo, it will download the crates, build them, link them/relibc to the program binary.
• If the recipe is using GNU Autotools, CMake or Meson, they will check the build environment and the presence library objects, build the libraries or the program and link them/relibc to the final binary.
• Package the recipe.

Typically, make r.recipe is used with make image to quickly build a recipe and create an image to test it.

make qemu

This is the command used to run Redox inside QEMU, see its phases below:

• It checks for pending changes, if found, it will trigger make rebuild.
• It checks the existence of the QEMU image, if not available, it will works like make image.
• A command with custom arguments is passed to QEMU to boot Redox without problems.
• The QEMU window is shown with a menu to choose the resolution.
• The bootloader does a bootstrap of the kernel, the kernel starts the init, the init starts the user-space daemons and Orbital.
• The Orbital login screen appear.

Developing for Redox

Currently Redox does not have a complete set of development tools that run natively. You must do your development on Linux or other Unix-like system, then include or copy your program to your Redox filesystem. This chapter outlines some of the things you can do as a developer.

(Before reading this chapter you must read the Build System page)

Including Programs in Redox

(Before reading this page you must read the Build System page)

This page will teach you how to add programs on the Redox image, it's a simplified version of the Porting Applications using Recipes page.

• Existing Recipe
  • Setup the Redox Build Environment
  • Setup Your Configuration
  • Build the System
  • Dependencies
  • Update crates
• Modifying an Existing Recipe
• Create Your Own Hello World
  • Setting up the recipe
  • Writing the program
  • Adding the program to the Redox image
• Running your program

The Cookbook system makes the packaging process very simple. First, we will show how to add an existing program for inclusion. Then we will show how to create a new program to be included. In the Coding and Building page, we discuss the development cycle in more detail.

Existing Recipe

Redox has many programs that are available for inclusion. Each program has a recipe in the directory cookbook/recipes/recipe-name. Adding an existing program to your build is as simple as adding it to config/$ARCH/myfiles.toml, or whatever name you choose for your .toml configuration definition. Here we will add the games package, which contains several terminal games.

Setup the Redox Build Environment

• Follow the steps in the Building Redox or Native Build pages to create the Redox Build Environment on your system.
• Build the system as described. This will take quite a while the first time.
• Run the system in QEMU.

cd ~/tryredox/redox

make qemu

Assuming you built the default configuration desktop for x86_64, none of the Redox games (e.g. /usr/bin/minesweeper) have been included yet.

• On your Redox emulation, log into the system as user user with an empty password.
• Open a Terminal window by clicking on the icon in the toolbar at the bottom of the Redox screen, and type ls /usr/bin. You will see that minesweeper is not listed.
• Type Ctrl-Alt-G to regain control of your cursor, and click the upper right corner of the Redox window to exit QEMU.

Setup your Configuration

Read the Configuration Settings page and follow the commands below.

• From your redox base directory, copy an existing configuration and edit it.

cd ~/tryredox/redox

cp config/x86_64/desktop.toml config/x86_64/myfiles.toml

nano config/x86_64/myfiles.toml

• Look for the [packages] section and add the package to the configuration. You can add the package anywhere in the [packages] section, but by convention, we add them to the end or to an existing related area of the section.

...
[packages]
# Add the item below under the "[packages]" section
redox-games = {}
...

• Add the CONFIG_NAME environment variable on your .config to use the myfiles.toml configuration.

nano .config

# Add the item below
CONFIG_NAME?=myfiles

• Save your changes with Ctrl+X and confirm with y

Build the System

• In your base redox folder, e.g. ~/tryredox/redox, build the system and run it in QEMU.

cd ~/tryredox/redox

make all

make qemu

Or

cd ~/tryredox/redox

make all qemu

• On your Redox emulation, log into the system as user user with an empty password.
• Open a Terminal window by clicking it on the icon in the toolbar at the bottom of the Redox screen, and type ls /usr/bin. You will see that minesweeper is listed.
• In the terminal window, type minesweeper. Play the game using the arrow keys or WSAD,space to reveal a spot, f to flag a spot when you suspect a mine is present. When you type f, an F character will appear.

If you had a problem, use this command to log any possible errors on your terminal output:

make r.recipe-name 2>&1 | tee recipe-name.log

And that's it! Sort of.

Dependencies

Read the Dependencies section to learn how to handle recipe dependencies.

Update crates

Read the Update crates section to learn how to update crates on Rust programs.

Modifying an Existing Recipe

If you want to make changes to an existing recipe for your own purposes, you can do your work in the directory cookbook/recipes/recipe-name/source. The Cookbook process will not download sources if they are already present in that folder. However, if you intend to do significant work or to contribute changes to Redox, please read the Coding and Building page.

Create Your Own Hello World

To create your own program to be included, you will need to create the recipe. This example walks through adding the "Hello World" program that the cargo new command automatically generates to the folder of a Rust project.

This process is largely the same for other Rust programs.

Setting Up The Recipe

The Cookbook will only build programs that have a recipe defined in cookbook/recipes. To create a recipe for the Hello World program, first create the directory cookbook/recipes/hello-world. Inside this directory create the "recipe.toml" file and add these lines to it:

[build]
template = "cargo"

The [build] section defines how Cookbook should build our project. There are several templates but "cargo" should be used for Rust projects.

The [source] section of the recipe tells Cookbook how to download the Git repository/tarball of the program.

This is done if cookbook/recipes/recipe-name/source does not exist, during make fetch or during the fetch step of make all. For this example, we will simply develop in the source directory, so no [source] section is necessary.

Writing the program

Since this is a Hello World example, we are going to have Cargo write the code for us. In cookbook/recipes/hello-world, do the following:

mkdir source

cd source

cargo init --name="hello-world"

This creates a Cargo.toml file and a src directory with the Hello World program.

Adding the program to the Redox image

To be able to run a program inside of Redox, it must be added to the filesystem. As above, create a filesystem config config/x86_64/myfiles.toml or similar by copying an existing configuration, and modify CONFIG_NAME in .config to be myfiles. Open config/x86_64/myfiles.toml and add hello-world = {} below the [packages] section.

During the creation of the Redox image, the build system installs those packages on the image filesystem.

[packages]
# Add the item below
hello-world = {}

To build the Redox image, including your program, run the following commands:

cd ~/tryredox/redox

make r.hello-world image

Running your program

Once the rebuild is finished, run make qemu, and when the GUI starts, log in to Redox, open the terminal, and run helloworld. It should print

Hello, world!

Note that the hello-world binary can be found in /usr/bin on Redox.

Coding and Building

(Before reading this page you must read the Build System page)

This page covers common development tasks on the Redox build system.

• Working with Git
  • Anonymous commits
• Using Multiple Windows
• Setup your Configuration
• The Recipe
• Git Clone
• Edit your Code
• Verify Your Code on Linux
• The Full Rebuild
• Test Your Changes
  • Test Your Changes (out of the Redox build system)
  • Testing On Real Hardware
    • Full bootable image creation
    • Partial bootable image creation
    • Flash the bootable image on your USB device
    • Burn your CD/DVD with the bootable image
• Update crates
• Search Text On Files
• Checking In your Changes
• Shortening the Rebuild Time
  • Build your recipe for Redox
  • Make a New QEMU Image
  • Most Quick Trick To Test Changes
  • Insert Text Files On QEMU (quickest method)
  • Insert files on the QEMU image using a recipe
  • Insert Files On The QEMU Image
• Working with an unpublished version of a crate
• A Note about Drivers
• Development Tips
• Visual Studio Code Configuration
• VS Code Tips and Tricks
  • Start in the "source" folder
  • Add it to your "Favorites" bar
  • Wait a Couple of Minutes
  • Save Often
  • Don't Use it for the whole of Redox
  • Don't Build the System in a VS Code Terminal

Working with Git

Before starting the development, read the Creating Proper Pull Requests page, which describes how the Redox team uses Git.

In this example, we will discuss how to create a fork of the games recipe, pretending you are going to create a Merge Request for your changes. Don't actually do this. Only create a fork when you have changes that you want to send to Redox upstream.

Anonymous commits

If you are new to Git, it request your username and email before the first commit on some offline repository, if you don't want to insert your personal information, run:

• Repository

cd your-repository-folder

git config user.name 'Anonymous'

git config user.email '<>'

This command will make you anonymous only on this repository.

• Global

git config --global user.name 'Anonymous'

git config --global user.email '<>'

This command will make you anonymous in all repositories of your user.

Using Multiple Windows

For clarity and easy of use, we will be using two terminal tabs on your system, each running a different GNU Bash shell instance.

1. The Build shell, normally at ~/tryredox/redox or where your base redox directory is.
2. The Coding shell, at cookbook/recipes/games/redox-games/source.

Setup your Configuration

To get started, follow the steps in the Including Programs in Redox page to include the games package on your myfiles configuration file. In your terminal window, go to your redox base directory and run:

make qemu

On Redox, run minesweeper as described in the link above. Type the letter f and you will see F appear on your screen. Use Ctrl-Alt-G to regain control of your cursor, and click the upper right corner to exit QEMU.

Keep the terminal window open. That will be your Build shell.

The Recipe

Let's walk through contributing to the recipe redox-games, which is a collection of terminal games. We are going to modify minesweeper to display P instead of F on flagged spots.

The redox-games recipe is built in the folder cookbook/recipes/games/redox-games. When you download the redox base package, it includes a file cookbook/recipes/games/redox-games/recipe.toml. The recipe tells the build system how to get the source and how to build it.

When you build the system and include the redox-games recipe, the toolchain does a git clone into the directory cookbook/recipes/games/redox-games/source. Then it builds the recipe in the directory cookbook/recipes/games/redox-games/target.

Edit the recipe so it does not try to automatically download the sources.

• Create a Terminal window running bash on your system, which we will call your Coding shell.
• Change to the redox-games directory.
• Open recipe.toml in a text editor.

cd ~/tryredox/redox/cookbook/recipes/games/redox-games

nano recipe.toml

• Comment out the [source] section at the top of the file.

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

• Save your changes.

Git Clone

To setup this recipe for contributing, do the following in your Coding shell.

• Delete the source and target directories in cookbook/recipes/games/redox-games.
• Clone the package into the source directory, either specifying it in the git clone or by moving it after clone.

rm -rf source target

git clone https://gitlab.redox-os.org/redox-os/games.git --origin upstream --recursive

mv games source

• If you are making a change that you want to contribute, (you are not, don't actually do this) at this point you should follow the instructions in Creating Proper Pull Requests, replacing redox.git with games.git. Make sure you fork the correct repository, in this case redox-os/games. Remember to create a new branch before you make any changes.

• If you want to Git Clone a remote repository (main repository/your fork), you can add these sections on your recipe.toml:

[source]
git = your-git-link
branch = your-branch # optional

Edit your Code

• Using your favorite code editor, make your changes. We use nano in this example, from your Coding shell. You can also use VS Code.

cd source

nano src/minesweeper/main.rs

• Search for the line containing the definition of the FLAGGED constant (around line 36), and change it to P.

const FLAGGED: &'static str = "P";

Verify Your Code on Linux

Most Redox programs are source-compatible with Linux without being modified. You can (and should) build and test your program on Linux.

• From within the Coding shell, go to the source directory and use the Linux version of cargo to check for errors.

cargo check

(Since much of the code in redox-games is older (pre-2018 Rust), you will get several warnings. They can be ignored)

You could also use cargo clippy, but minesweeper is not clean enough to pass.

• The redox-games recipe creates more than one executable, so to test minesweeper on Linux, you need to specify it to cargo. In the source directory, do:

cargo run --bin minesweeper

The Full Rebuild

After making changes to your recipe, you can use the make rebuild command, which will check for any changes to recipe and make a new Redox image. make all and make qemu do not check for recipes that need to be rebuilt, so if you use them, your changes may not be included in the system. Once you are comfortable with this process, you can try some tricks to save time.

• Within your Build shell, in your redox directory, do:

make rebuild 2>&1 | tee build.log

• You can now scan through build.log to check for errors. The file is large and contains many ANSI Escape Sequences, so it can be hard to read. However, if you encountered a fatal build error, it will be at the end of the log, so skip to the bottom and scan upwards.

Test Your Changes

In the Redox instance started by make qemu, test your changes to minesweeper.

• Log in with user user and no password.
• Open a Terminal window.
• Type minesweeper.
• Use your arrow keys or WSAD to move to a square and type f to set a flag. The character P will appear.

Congratulations! You have modified a program and built the system! Next, create a bootable image with your change.

• If you are still running QEMU, type Ctrl-Alt-G and click the upper right corner of the Redox window to exit.
• In your Build shell, in the redox directory, do:

make live

In the directory build/x86_64/myfiles, you will find the file livedisk.iso. Follow the instructions on the Testing on Real Hardware section and test out your change.

Test Your Changes (out of the Redox build system)

Redoxer is the tool used to build and run Rust programs (and C/C++ programs with zero dependencies) for Redox, it download the Redox toolchain and use Cargo.

Commands

• Install the tool

cargo install redoxer

• Install the Redox toolchain

redoxer toolchain

• Build the Rust program or library with Redoxer

redoxer build

• Run the Rust program on Redox

redoxer run

• Test the Rust program or library with Redoxer

redoxer test

• Run arbitrary executable (echo hello) with Redoxer

redoxer exec echo hello

Testing On Real Hardware

You can use the make live command to create bootable images, it will be used instead of make image.

This command will create the file build/your-cpu-arch/your-config/livedisk.iso, you will burn this image on your USB device, CD or DVD disks (if you have an USB device, Popsicle is the recommended method to flash your device).

Full bootable image creation

• Update your recipes and create a bootable image:

make rebuild live

Partial bootable image creation

• Build your source changes on some recipe and create a bootable image (no QEMU image creation):

make cr.recipe-name live

• Manually update multiple recipes and create a bootable image (more quick than make rebuild):

make r.recipe1 r.recipe2 live

Flash the bootable image on your USB device

If you can't use Popsicle, you can use the Unix tool dd, follow the steps below:

• Go to the files of your Cookbook configuration:

cd build/your-cpu-arch/your-config

• Flash your device with dd

First you need to find your USB device ID, use this command to show the IDs of all connected disks on your computer:

ls /dev/disk/by-id

Search for the items beginning with usb and find your USB device model, you will copy and paste this ID on the dd command below (don't use the IDs with part-x in the end).

sudo dd if=livedisk.iso of=/dev/disk/by-id/usb-your-device-model oflag=sync bs=4M status=progress

In the /dev/disk/by-id/usb-your-device-model path you will replace the usb-your-device-model part with your USB device ID obtained before.

Double-check the "of=/dev/disk/by-id/usb-your-device-model" part to avoid data loss

Burn your CD/DVD with the bootable image

• Go to the files of your Cookbook configuration:

cd build/your-cpu-arch/your-config

• Verify if your optical disk device can write on CD/DVD

cat /proc/sys/dev/cdrom/info

Check if the items "Can write" has 1 (Yes) or 0 (No), it also show the optical disk devices on the computer: /dev/srX.

• Burn the disk with xorriso

xorriso -as cdrecord -v -sao dev=/dev/srX livedisk.iso

In the /dev/srX part, the x letter is your optical device number.

Update crates

• Porting Applications using Recipes

Search Text On Files

To find which package contains a particular command, crate or function call, you can use the grep command.

This will speed up your development workflow.

• Command examples

grep -rnw "redox-syscall" --include "Cargo.toml"

This command will find any "Cargo.toml" file that contains the phrase "redox-syscall". Helpful for finding which package contains a command or uses a crate.

grep -rni "physmap" --include "*.rs"

This command will find any ".rs" file that contains the string "physmap". Helpful for finding where a function is used or defined.

Options context:

• -n - display the line number of the specified text on each file.

• -r - Search directories recursively.

• -w - Match only whole words.

• -i - Ignore case distinctions in patterns and data.

• grep explanation - GeeksforGeeks article explaining how to use the grep tool.

Checking In Your Changes

Don't do this now, but if you were to have permanent changes to contribute to a recipe, at this point, you would git push and create a Merge Request, as described in Creating Proper Pull Requests.

If you were contributing a new package, such as porting a Rust application to Redox, you would need to check in the recipe.toml file. It goes in the cookbook subproject. You may also need to modify a filesystem config file, such as config/your-cpu-arch/demo.toml. It goes in the redox project. You must fork and do a proper Pull Request for each of these projects. Please coordinate with the Redox team on the chat before doing this.

Shortening the Rebuild Time

To skip some of the steps in a full rebuild, here are some tricks.

Build your recipe for Redox

You can build just the redox-games recipe, rather than having make rebuild verifying each recipe for changes. This can help shorten the build time if you are trying to resolve issues such as compilation errors or linking to libraries.

• In your Build shell, in the redox directory, type:

make r.redox-games

Build system Makefiles have a rule for r.recipe-name, where recipe-name is the name of a Redox recipe. It will make that recipe, ready to load into the Redox filesystem.

Once your Redox recipe has been successfully built, you can use make rebuild to create the image, or, if you are confident you have made all packages successfully, you can skip a complete rebuild and just make a new image.

If you had a problem, use this command to log any possible errors on your terminal output:

make cr.recipe-name 2>&1 | tee recipe-name.log

Make a New QEMU Image

Now that all the packages are built, you can make a Redox image without the step of checking for modifications.

• In your Build shell, in the redox directory, do:

make image

• make image skips building any packages (assuming the last full make succeeded), but it ensures a new image is created, which should include the recipe you built in the previous step.

Most Quick Trick To Test Changes

Run:

make cr.recipe-name image qemu

This command will build just your modified recipe, then update your QEMU image with your modified recipe and run QEMU with Orbital.

Insert Text Files On QEMU (quickest method)

If you need to move text files, such as shell scripts or command output, from or to your Redox instance running on QEMU, use your Terminal window that you used to start QEMU. To capture the output of a Redox command, run script before starting QEMU.

tee qemu.log

make qemu gpu=no

redox login: user
# execute your commands, with output to the terminal
# exit QEMU
# exit the shell started by script

exit

The command output will now be in the file qemu.log. Note that if you did not exit the script shell, the output may not be complete.

To transfer a text file, such as a shell script, onto Redox, use the Terminal window with copy/paste.

redox login: user

cat > myscript.sh << EOF
# Copy the text to the clipboard and use the Terminal window paste
  EOF

If your file is large, or non-ASCII, or you have many files to copy, you can use the process described in the Insert Files On QEMU Image section. However, you do so at your own risk.

Files you create while running QEMU remain in the Redox image, so long as you do not rebuild the image. Similarly, files you add to the image will be present when you run QEMU, so long as you do not rebuild the image.

Make sure you are not running QEMU. Run make mount. You can now use your file browser to navigate to build/x86_64/myfiles/filesystem. Copy your files into or out of the Redox filesystem as required. Make sure to exit your file browser window, and use make unmount before running make qemu.

Note that in some circumstances, make qemu may trigger a rebuild (e.g. make detects an out of date file). If that happens, the files you copied into the Redox image will be lost.

Insert files on the QEMU image using a recipe

You can use a Redox package to put your files inside of the Redox filesystem, on this example we will use the recipe myfiles for this:

• Create the source folder inside the myfiles recipe directory and move your files to it:

mkdir cookbook/recipes/other/myfiles/source

• Add the myfiles recipe below the [packages] section on your Cookbook configuration at config/your-cpu-arch/your-config.toml:

[packages]
...
myfiles = {}
...

• Build the recipe and create a new QEMU image:

make r.myfiles image

• Open QEMU to verify your files:

make qemu

This recipe will make the Cookbook package all the files on the source folder to be installed on the /home/user directory on your Redox filesystem.

(This is the only way keep your files after the make image command)

Insert Files On The QEMU Image

If you feel the need to skip creating a new image, and you want to directly add a file to the existing Redox image, it is possible to do so. However, this is not recommended. You should use a recipe to make the process repeatable. But here is how to access the Redox image as if it were a Linux filesystem.

• NOTE: You must ensure that Redox is not running in QEMU when you do this.

• In your Build shell, in the redox directory, type:

make mount

The Redox image is now mounted as a directory at build/x86_64/your-config/filesystem.

• Unmount the filesystem and test your image. NOTE: You must unmount before you start QEMU.

cd ~/tryredox/redox

make unmount

make qemu

Working with an unpublished version of a crate

Some recipes use Cargo dependencies (Cargo.toml) with recipe dependencies (recipe.toml), if you are making a change to one of these Cargo dependencies, your merged changes will take a while to appear on crates.io as we publish to there instead of using our GitLab fork.

To test your changes quickly, follow these tutorials on Cargo documentation:

• Overriding Dependencies
• Working with an unpublished minor version

A Note about Drivers

The drivers and drivers-initfs recipes share the source folder, thus your changes on the drivers recipe source code will added on the drivers-initfs recipe automatically.

(The recipe.toml of the drivers-initfs recipe use the same_as data type to symlink the source, you can read the second line of the drivers-initfs recipe)

Development Tips

• Make sure your build system is up-to-date, read the Update The Build System section in case of doubt.
• If some program can't build or work properly, remember that something could be missing/hiding on relibc, some missing function or bug.
• If you have some error on QEMU, remember to test different settings or verify your operating system (Pop_OS!, Ubuntu, Debian and Fedora are the recommend Linux distributions to do testing/development for Redox).
• Remember to log all errors, you can use this command as example:

your-command 2>&1 | tee file-name.log

• If you have a problem that seems to not have a solution, think on simple/stupid things, sometimes you are very confident on your method and forget obvious things (it's very common).
• If you want a more quick review of your Merge Request, make it small, Jeremy will read it more fast.
• If your big Merge Request is taking too long to merge try to shrink it with other small MRs, make sure it don't break anything, if this method break your changes, don't shrink.

Visual Studio Code Configuration

Before you start the VS Code IDE to do Redox development, you need to run this command on your terminal:

rustup target add x86_64-unknown-redox

If the code that you are working on includes directives like #[cfg(target_os = "redox)], that code will be disabled by default. To enable live syntax and compiler warnings for that code, add the following line to your VS Code config file (.vscode/settings.json):

"rust-analyzer.cargo.target": "x86_64-unknown-redox"

VS Code Tips and Tricks

Although not for every Rustacean, VS Code is helpful for those who are working with unfamiliar code. We don't get the benefit of all its features, but the Rust support in VS Code is very good.

If you have not used VS Code with Rust, here's an overview. VS Code installation instructions are here.

After installing the rust-analyzer extension as described in the overview, you get access to several useful features.

• Inferred types and parameter names as inline hints.
• Peeking at definitions and references.
• Refactoring support.
• Autoformat and clippy on Save (optional).
• Visual Debugger (if your code can run on Linux).
• Compare/Revert against the repository with the Git extension.

Using VS Code on individual packages works pretty well, although it sometimes take a couple of minutes to kick in. Here are some things to know.

Start in the "source" folder

In your Coding shell, start VS Code, specifying the source directory.

code ~/tryredox/redox/cookbook/recipes/games/source

Or if you are in the source directory, just code . with the period meaning the source dir.

Add it to your "Favorites" bar

VS Code remembers the last project you used it on, so typing code with no directory or starting it from your Applications window or Favorites bar will go back to that project.

After starting VS Code, right click on the icon and select Add to Favorites.

Wait a Couple of Minutes

You can start working right away, but after a minute or two, you will notice extra text appear in your Rust code with inferred types and parameter names filled in. This additional text is just hints, and is not permanently added to your code.

Save Often

If you have made significant changes, rust-analyzer can get confused, but this can usually be fixed by doing Save All.

Don't Use it for the whole of Redox

VS Code cannot grok the gestalt of Redox, so it doesn't work very well if you start it in your redox base directory. It can be handy for editing recipes, config and make files. And if you want to see what you have changed in the Redox project, click on the Source Control icon on the far left, then select the file you want to compare against the repository.

Don't Build the System in a VS Code Terminal

In general, it's not recommended to do a system build from within VS Code. Use your Build window. This gives you the flexibility to exit Code without terminating the build.

Porting Applications using Recipes

The Including Programs in Redox page gives an example to port/modify a pure Rust program, here we will explain the advanced way to port pure Rust programs, mixed Rust programs (Rust and C/C++ libraries, for example), C/C++ programs and others.

(Before reading this page you must read the Build System page)

• Recipe
  • Recipe Configuration Example
  • Quick Recipe Template
• Cookbook
  • Cross Compiler
  • Cross Compilation
  • Environment Variables
    • Quick Template
  • Templates
    • Functions
    • cookbook_cargo function script
    • cookbook_configure function script
  • Custom Template
    • Packaging Behavior
    • Cargo script example
    • GNU Autotools script example
    • GNU Autotools script example (lacking a pre-configured tarball)
    • CMake script example
    • Analyze the source code of a Rust program
    • Cargo packages command example
      • Cargo package with flags
    • Cargo bins script example
    • Cargo flags command example
    • Disable the default Cargo flags
    • Enable all Cargo flags
    • Cargo profiles command example
    • Cargo examples command example
    • Rename binaries
    • Change the active source code folder
    • Configuration files
    • Script-based programs
      • Adapted scripts
      • Non-adapted scripts
  • Dynamically Linked Programs
    • Debugging
• Sources
  • Tarballs
    • Build System
    • Links
  • Git Repositories
    • GitHub release commit hash
    • GitLab release commit hash
• Dependencies
  • Bundled Libraries
  • Submodules
  • Environment Variables
  • Configuration
    • Arch Linux and AUR
    • Gentoo
    • FreeBSD
  • Testing
• Building/Testing The Program
• Update crates
  • One or more crates
  • All crates
  • Verify the dependency tree
• Patch crates
  • Redox forks
  • Local patches
• Cleanup
• Search Text On Recipes
• Search for functions on relibc
• Create a BLAKE3 hash for your recipe
• Verify the size of your package
• Submitting MRs

Recipe

A recipe is how we call a software port on Redox, this section will explain the recipe configuration and things to consider.

Create a folder at cookbook/recipes/program-category with a file named as recipe.toml inside, we will edit this file to fit the program needs.

• Commands example:

cd ~/tryredox/redox

mkdir cookbook/recipes/program-category/program-name

nano cookbook/recipes/program-category/program-name/recipe.toml

Recipe Configuration Example

The recipe configuration (recipe.toml) example below contain all supported recipe options. Adapt for your script, program, library or data files.

[source]
git = "repository-link"
upstream = "repository-link"
branch = "branch-name"
rev = "commit-hash"
tar = "tarball-link.tar.gz"
blake3 = "source-hash"
patches = [
    "patch1.patch",
    "patch2.patch",
]
same_as = "../program-name"
script = """
insert your script here
"""
[build]
template = "build-system"
dependencies = [
    "library1",
    "library2",
]
script = """
# Uncomment the following if the package can be dynamically linked
#DYNAMIC_INIT
insert your script here
"""
[package]
dependencies = [
    "runtime-dependency1",
    "runtime-dependency2",
]

• [source] - Section for data types that manage the program source (only remove it if you have a source folder)
• git = "repository-link" - Insert the Git repository of the program (can be removed if a Git repository is not used), you can comment out it to not allow Cookbook to force a git pull or change the active branch to master or main
• upstream = "repository-link" - If you are using a fork of the program source with patches add the program upstream source here (can be removed if the upstream source is being used on the git data type)
• branch = "branch-name" - Insert the program version or patched branch (can be removed if the master or main branches are being used)
• rev = "commit-hash" - Insert the commit hash of the latest stable version or commit of the program (can be removed if a stable version is not used or the latest commit is stable)
• tar = "tarball-link.tar.gz" - Insert the program source tarball (can be removed if a tarball is not used)
• blake3 = "source-hash" - Insert the program source tarball BLAKE3 hash, can be generated using the b3sum tool, install with the cargo install b3sum command (can be removed if using a Git repository or under porting)
• patches = [] - Data type to load .patch files (can be removed if patch files aren't used)
• "patch1.patch", (Under the patches data type) - The patch file name (can be removed if the patches data type above is not present)
• same_as = "../program-name" - Insert the folder of other recipe to make a symbolic link to the source folder of other recipe, useful if you want modularity with synchronization
• source.script (Under the [source] section) - Data type used when you need to change the build system configuration (to regenerate the GNU Autotools configuration, for example)
• [build] - Section for data types that manage the program compilation and packaging (don't remove it)
• template = "build-system" - Insert the program build system (cargo for Rust programs, configure for programs using GNU Autotools and custom for advanced porting with custom commands)
• build.dependencies = [] (Under the [build] section) - Data type to add library dependencies, be it statically linked or dynamically linked
• "library1", - The library name (can be removed if the dependencies data type above is not present)
• build.script - Data type to load the custom commands for compilation and packaging
• [package] - Section for data types that manage the program package
• package.dependencies = [] (Under the [package] section) - Data type to add interpreters or "data files" recipes to be installed by the package manager or build system installer
• "runtime-dependency1", - The name of the interpreter or data recipe (can be removed if the dependencies data type above is not present)

Quick Recipe Template

This is a recipe template for a quick porting workflow.

#TODO not compiled or tested
[source]
git = "repository-link"
rev = "commit-hash"
tar = "tarball-link"
[build]
template = "build-system"
dependencies = [
    "library1",
]

You can quickly copy and paste this template on each recipe.toml, that way you spent less time writting and has less chances for typos.

• If your program use a tarball, you can quickly remove the git and rev data types.
• If your program use a Git repository, you can quickly remove the tar data type.
• If you don't need to pin a commit hash for the most recent stable release, you can quickly remove the rev data type.
• If the program don't need dependencies, you can quickly remove the dependencies = [] section.

After the #TODO you will write your current porting status.

Cookbook

The GCC and LLVM compiler frontends on Linux use the Linux target triplet by default, it will create Linux ELF binaries that don't work on Redox because it can't undertstand them.

Part of this process is to use glibc (GNU C Standard Library) which don't support Redox system calls, to make the compiler use relibc (Redox C Library) the Cookbook needs to tell the build system of the program or library to use it, it's done with environment variables.

The Cookbook have templates to avoid custom commands for cross-compilation, but it's not always possible because some build systems aren't standardized or adapted for cross-compilation.

(Some build systems have different methods to enable cross-compilation and pass a different C standard library to the compiler, you will need to figure this out)

Cross Compiler

Cookbook use Rust/GCC forks to do cross-compilation of recipes (programs) with relibc to any supported CPU architecture, you can check our cross-compilers on GitLab (GCC, LLVM, Rust) and build server.

Cross Compilation

The Cookbook behavior is for cross-compilation because it allow us to do Redox development from Linux.

By default Cookbook use the architecture of your host system but you can change it easily on your .config file (ARCH?= field).

• Don't use a CPU architecture on the script data types of your recipe.toml, it breaks cross-compilation.
• All recipes must use our cross-compilers, a Cookbook template does this automatically but it's not always possible, study the build system of your program/library to find these options or patch the configuration files.

Environment Variables

If you want to apply changes on the program source/binary you can use these variables on your commands:

• ${COOKBOOK_RECIPE} - Represents the recipe folder.
• ${COOKBOOK_SOURCE} - Represents the source folder at recipe-name/source (program source).
• ${COOKBOOK_SYSROOT} - Represents the sysroot folder at recipe-name/target/your-cpu-arch/sysroot (library sources).
• ${COOKBOOK_BUILD} - Represents the build folder at recipe-name/target/your-cpu-arch/build (recipe build system).
• ${COOKBOOK_STAGE} - Represents the stage folder at recipe-name/target/your-cpu-arch/stage (recipe binaries).

We recommend that you use these variables with the " symbol to clean any spaces on the path, spaces are interpreted as command separators and will break the path.

Example:

"${VARIABLE_NAME}"

If you have a folder inside the variable folder you can call it with:

"${VARIABLE_NAME}"/folder-name

Or

"${VARIABLE_NAME}/folder-name"

Quick Template

You can quickly copy these environment variables from this section.

"${COOKBOOK_SOURCE}/"

"${COOKBOOK_BUILD}/"

"${COOKBOOK_SYSROOT}/"

"${COOKBOOK_STAGE}/"

Templates

The template is the build system of the program or library, programs using an GNU Autotools build system will have a configure file on the root of the source tarball, programs using CMake build system will have a CMakeLists.txt file with all available CMake flags and a cmake folder, programs using Meson build system will have a meson.build file, Rust programs will have a Cargo.toml file, etc.

(You can't use the script = data types if templates are used)

• template = "cargo" - Build with Cargo and cross-compilation variables (Rust programs with one package in the Cargo workspace).
• template = "configure" - Build with GNU Autotools and cross-compilation variables.
• template = "custom" - Run your commands on the script = field and build (Any build system or installation process).

The script = field runs any terminal command, it's important if the build system of the program don't support cross-compilation or need custom options that Cookbook don't support.

To find the supported Cookbook terminal commands, look the recipes using a script = field on their recipe.toml or read the source code.

• Recipes

Functions

Each template has a function in the Cookbook source code, these functions contain commands to trigger the build system with cross-compilation variables for the Redox target triplet.

• cargo (cookbook_cargo) - This function run the cargo build command
• configure (cookbook_configure) - This function run the ./configure, make and make install commands

cookbook_cargo function script

You can see the commands of the cookbook_cargo function below:

• Pre-script

# Common pre script
# Add cookbook bins to path
export PATH="${COOKBOOK_ROOT}/bin:${PATH}"

# This puts cargo build artifacts in the build directory
export CARGO_TARGET_DIR="${COOKBOOK_BUILD}/target"

# This adds the sysroot includes for most C compilation
#TODO: check paths for spaces!
export CFLAGS="-I${COOKBOOK_SYSROOT}/include"
export CPPFLAGS="-I${COOKBOOK_SYSROOT}/include"

# This adds the sysroot libraries and compiles binaries statically for most C compilation
#TODO: check paths for spaces!
export LDFLAGS="-L${COOKBOOK_SYSROOT}/lib --static"

# These ensure that pkg-config gets the right flags from the sysroot
export PKG_CONFIG_ALLOW_CROSS=1
export PKG_CONFIG_PATH=
export PKG_CONFIG_LIBDIR="${COOKBOOK_SYSROOT}/lib/pkgconfig"
export PKG_CONFIG_SYSROOT_DIR="${COOKBOOK_SYSROOT}"

# cargo template
COOKBOOK_CARGO="${COOKBOOK_REDOXER}"
function cookbook_cargo {
    "${COOKBOOK_CARGO}" install \
        --path "${COOKBOOK_SOURCE}" \
        --root "${COOKBOOK_STAGE}" \
        --locked \
        --no-track \
        "$@"
}

# helper for installing binaries that are cargo examples
function cookbook_cargo_examples {
    recipe="$(basename "${COOKBOOK_RECIPE}")"
    for example in "$@"
    do
        "${COOKBOOK_CARGO}" build \
            --manifest-path "${COOKBOOK_SOURCE}/Cargo.toml" \
            --example "${example}" \
            --release
        mkdir -pv "${COOKBOOK_STAGE}/usr/bin"
        cp -v \
            "target/${TARGET}/release/examples/${example}" \
            "${COOKBOOK_STAGE}/usr/bin/${recipe}_${example}"
    done
}

# helper for installing binaries that are cargo packages
function cookbook_cargo_packages {
    recipe="$(basename "${COOKBOOK_RECIPE}")"
    for package in "$@"
    do
        "${COOKBOOK_CARGO}" build \
            --manifest-path "${COOKBOOK_SOURCE}/Cargo.toml" \
            --package "${package}" \
            --release
        mkdir -pv "${COOKBOOK_STAGE}/usr/bin"
        cp -v \
            "target/${TARGET}/release/${package}" \
            "${COOKBOOK_STAGE}/usr/bin/${recipe}_${package}"
    done
}

• Post-script

# Common post script
# Strip binaries
if [ -d "${COOKBOOK_STAGE}/usr/bin" ]
then
    find "${COOKBOOK_STAGE}/usr/bin" -type f -exec "${TARGET}-strip" -v {} ';'
fi

# Remove cargo install files
for file in .crates.toml .crates2.json
do
    if [ -f "${COOKBOOK_STAGE}/${file}" ]
    then
        rm -v "${COOKBOOK_STAGE}/${file}"
    fi
done

cookbook_configure function script

You can see the commands of the cookbook_configure function below:

• Pre-script

# Common pre script
# Add cookbook bins to path
export PATH="${COOKBOOK_ROOT}/bin:${PATH}"

# This adds the sysroot includes for most C compilation
#TODO: check paths for spaces!
export CFLAGS="-I${COOKBOOK_SYSROOT}/include"
export CPPFLAGS="-I${COOKBOOK_SYSROOT}/include"

# This adds the sysroot libraries and compiles binaries statically for most C compilation
#TODO: check paths for spaces!
export LDFLAGS="-L${COOKBOOK_SYSROOT}/lib --static"

# These ensure that pkg-config gets the right flags from the sysroot
export PKG_CONFIG_ALLOW_CROSS=1
export PKG_CONFIG_PATH=
export PKG_CONFIG_LIBDIR="${COOKBOOK_SYSROOT}/lib/pkgconfig"
export PKG_CONFIG_SYSROOT_DIR="${COOKBOOK_SYSROOT}"

# configure template
COOKBOOK_CONFIGURE="${COOKBOOK_SOURCE}/configure"
COOKBOOK_CONFIGURE_FLAGS=(
    --host="${TARGET}"
    --prefix=""
    --disable-shared
    --enable-static
)
COOKBOOK_MAKE="make"
COOKBOOK_MAKE_JOBS="$(nproc)"
function cookbook_configure {
    "${COOKBOOK_CONFIGURE}" "${COOKBOOK_CONFIGURE_FLAGS[@]}"
    "${COOKBOOK_MAKE}" -j "${COOKBOOK_MAKE_JOBS}"
    "${COOKBOOK_MAKE}" install DESTDIR="${COOKBOOK_STAGE}"
}

• Post-script

# Common post script
# Strip binaries
if [ -d "${COOKBOOK_STAGE}/usr/bin" ]
then
    find "${COOKBOOK_STAGE}/usr/bin" -type f -exec "${TARGET}-strip" -v {} ';'
fi

# Remove libtool files
if [ -d "${COOKBOOK_STAGE}/usr/lib" ]
then
    find "${COOKBOOK_STAGE}/usr/lib" -type f -name '*.la' -exec rm -fv {} ';'
fi

Custom Template

The custom template enable the build.script = data type to be used, this data type will run any command supported by the GNU Bash shell.

The script section start at the location of the ${COOKBOOK_BUILD} environment variable (recipe-name/target/your-cpu-arch/build)

• Script example

script = """
first-command
second-command
"""

Packaging Behavior

The Cookbook download the recipe sources on the source folder (recipe-name/source), copy the contents of this folder to the build folder (recipe-name/target/your-cpu-arch/build), build the sources and move the binaries to the stage folder (recipe-name/target/your-cpu-arch/stage).

If your recipe has library dependencies, it will copy the library source and linker objects to the sysroot folder to be used by the build folder.

• Moving the program files to the Redox filesystem

The "${COOKBOOK_STAGE}"/ path is used to specify where the recipe files will go inside of Redox, in most cases /usr/bin and /usr/lib.

You can see path examples for most customized recipes below:

"${COOKBOOK_STAGE}"/ # The root of the Redox build system
"${COOKBOOK_STAGE}"/usr/bin # The folder where all global Unix executables go
"${COOKBOOK_STAGE}"/usr/lib # The folder where all static and shared library objects go

Cargo script example

Use this script if you need to customize the cookbook_cargo function.

script = """
COOKBOOK_CARGO="${COOKBOOK_REDOXER}"
COOKBOOK_CARGO_FLAGS=(
    --path "${COOKBOOK_SOURCE}"
    --root "${COOKBOOK_STAGE}"
    --locked
    --no-track
)
function cookbook_cargo {
    "${COOKBOOK_CARGO}" install "${COOKBOOK_CARGO_FLAGS[@]}"
}
"""

GNU Autotools script example

Use this script if the program or library need flags, change or copy and paste the "--program-flag" according to your needs.

(Some programs and libraries need more configuration to work)

script = """
COOKBOOK_CONFIGURE_FLAGS+=(
    --program-flag
)
cookbook_configure
"""

GNU Autotools script example (lacking a pre-configured tarball)

If you are using the repository of the program you will need to create a configuration file for GNU Autotools.

(Some programs and libraries need more configuration to work)

script = """
./autogen.sh
cookbook_configure
"""

CMake script example

Use this script for programs using the CMake build system, more CMake options can be added with a -D before them, the customization of CMake compilation is very easy.

(Some programs and libraries need more configuration to work)

script = """
COOKBOOK_CONFIGURE="cmake"
COOKBOOK_CONFIGURE_FLAGS=(
    -DCMAKE_BUILD_TYPE=Release
    -DCMAKE_CROSSCOMPILING=True
    -DCMAKE_EXE_LINKER_FLAGS="-static"
    -DCMAKE_INSTALL_PREFIX="/"
    -DCMAKE_PREFIX_PATH="${COOKBOOK_SYSROOT}"
    -DCMAKE_SYSTEM_NAME=Generic
    -DCMAKE_SYSTEM_PROCESSOR="$(echo "${TARGET}" | cut -d - -f1)"
    -DCMAKE_VERBOSE_MAKEFILE=On
"${COOKBOOK_SOURCE}"
)
cookbook_configure
"""

Analyze the source code of a Rust program

Rust programs and libraries use the Cargo.toml configuration file to configure the build system and source code.

While packaging Rust programs you need to know where the main executable is located in the Cargo project, to do this you need to verify the Cargo.toml files of the project.

A Rust program can have one or more Cargo packages to build, see some common assumptions below:

• Most Rust programs with a src folder use one Cargo package, thus you can use the cargo template.
• Most Rust programs with multiple Cargo packages name the main package with the name of the program.

Beyond these common source code organization, there are special cases.

• In some Rust programs the Cargo.toml file contains one of these data types:

[[bin]]
name = "executable-name"
[[lib]]
name = "library-object-name"

The [[bin]] is what you need, the program executable is built by this Cargo package.

(Ignore packages with the [[lib]] data type, Rust libraries don't need to be packaged because Rust has automatic dependency management, except for backup purposes)

But some programs don't have the [[bin]] and [[lib]] data types, for these cases you need to see the source code files, in most cases at the src folder.

• The file named main.rs contains the program executable code.
• The file named lib.rs contains the library object code (ignore it).

Cargo packages command example

This command is used for Rust programs that use package folders inside the repository for compilation, you need to use the name on the name field below the [package] section of the Cargo.toml file inside the package folder (generally using the same name of the program).

(This will fix the "found virtual manifest instead of package manifest" error)

script = """
cookbook_cargo_packages program-name
"""

(You can use cookbook_cargo_packages program1 program2 if it's more than one package)

Cargo package with flags

If you need a script for a package with flags (customization), you can use this script:

script = """
package=package-name
"${COOKBOOK_CARGO}" build \
            --manifest-path "${COOKBOOK_SOURCE}/Cargo.toml" \
            --package "${package}" \
            --release
            --add-your-flag-here
        mkdir -pv "${COOKBOOK_STAGE}/usr/bin"
        cp -v \
            "target/${TARGET}/release/${package}" \
            "${COOKBOOK_STAGE}/usr/bin/${package}"
"""

• The package-name after package= is where you will insert the Cargo package name of your program.
• The --add-your-flag-here will be replaced by the program flag.

Cargo bins script example

Some Rust programs use bins instead of packages to build, to build them you can use this script:

script = """
binary=bin-name
"${COOKBOOK_CARGO}" build \
            --manifest-path "${COOKBOOK_SOURCE}/Cargo.toml" \
            --bin "${binary}" \
            --release
            --add-your-flag-here
        mkdir -pv "${COOKBOOK_STAGE}/usr/bin"
        cp -v \
            "target/${TARGET}/release/${binary}" \
            "${COOKBOOK_STAGE}/usr/bin/${binary}"
"""

• The bin-name after binary= is where you will insert the Cargo package name of your program.
• The --add-your-flag-here will be replaced by the program flags.

Cargo flags command example

Some Rust softwares have Cargo flags for customization, search them to match your needs or make some program build.

script = """
cookbook_cargo --features flag-name
"""

Disable the default Cargo flags

It's common that some flag of the program doesn't work on Redox, if you don't want to spend much time testing flags that work and don't work, you can disable all of them to see if the most basic setting of the program works with this script:

script = """
cookbook_cargo --no-default-features
"""

Enable all Cargo flags

If you want to enable all flags of the program, use:

script = """
cookbook_cargo --all-features
"""

Cargo profiles command example

This script is used for Rust programs using Cargo profiles.