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 keep in mind that this book is work-in-progress and sometimes can be outdated, any help to improve it is important.

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.

Origin Story

Redox OS was created in 2015 before the first stable version (1.0) of the Rust compiler and was one of the first operating systems written in Rust. It started as an unikernel (without a hypervisor) and gathered the contributions of many Rust developers.

As the project progressed, Jeremy Soller decided that the OS should be focused on stability and security. To achieve that, Redox was redesigned to adopt a microkernel architecture and a unified system API for resources.

Minix and Plan 9 were the main inspirations for the system design in the beginning.

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.

1. Our Goals
2. Our Philosophy
3. Why a New OS?
4. Redox Use Cases
5. Comparing Redox to Other OSes
6. Why Rust?
7. Side Projects
8. Influences
9. Hardware Support
10. Important Programs

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.

Complete Alternative to Linux/BSD

Redox has its own kernel, drivers and filesystem written in Rust. The driver implementations are complete for QEMU, and some hardware are known to work well. In terms of CPU architectures, Redox aims to have an equal support for three major architectures: x86 (32 and 64 bits), ARM (64 bits) and RISC-V (64 bits).

Redox can run C, C++ and Rust programs with the aid of relibc, an almost POSIX-compliant C Standard Library written in Rust. Relibc has the goal to support most C, C++ and Rust based software. Many programs and libraries can be built and executed without any patches, some maybe need patches to workaround some functions, especially if it relies on non-POSIX functions.

Redox can also run GUI programs running on top of Orbital. C, C++ and Rust programs can draw windows with the help of orbclient and liborbital (our official Orbital client libraries).

Both system services and drivers are working well to run important programs. We aim to have more POSIX and Linux compatibility to port more programs and attract more users.

Rust Ecosystem

Rust officially supports Redox as both Tier II and Tier III platforms. The Rust community has accepted Redox-specific code for years. Some well-known Rust libraries (crates) that supports Redox are winit, nix, rustix, and much more. These crates are backed by either Rust's C Standard Library Bindings or a specific implementation of the Rust's Standard Library. We upstream changes into these libraries as the system get new features.

Libraries using Rust libc are statically linked into relibc at compile-time. By this design choice, compiling any Rust program to Redox requires relibc available at linking time. While it seems like a inconvenience, it allows us to do quick development without having to push changes each time relibc is improved. To alleviate this "inconvenience", we have redoxer to allow developers to compile and test Rust programs into Redox without using our complete build system.

Security Design

The Redox kernel is a microkernel influenced by some operating systems, thus many system services have been moved from the kernel to userspace daemons or drivers. Both drivers and system services are normal programs in userspace with higher permissions in a special namespace which allows them to access hardware interrupts managed by the kernel.

All programs including the kernel, drivers and system services are talking to each other using an IPC system called "Scheme". Schemes live inside the /scheme filesystem directory and any program can access or create it using the standard file API. For more advanced usage software can use libredox and many other redox-* crates, detailed in another page.

Schemes are secured mainly by namespaces. One namespace is invisible to another one. In case of programs talking to each other in the same namespace, the kernel and drivers use caller user ID or group ID, similar to Linux having sudo, but we're about to change it into Capability-based security in near future.

The non-goals of Redox

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

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

Software Ports That Are Non-Goals

Redox aims to support most software, especially those that are important. Software that are not ported are either:

1. Not open source or libre, or known to have legal problems
2. No longer maintained (depending on importance we can fork and maintain it) or there's better alternative
3. Only using non-portable APIs like the Linux kernel or Windows
4. Lack of users and maintainers
5. The program language compiler lack Redox support

A well known example of software being too complicated to port is Chromium as it's heavily tuned to use OS-specific function calls and don't accept OS support beyond Linux in upstream, FreeBSD has to maintain hundreds of patches to make sure it's working. It's easier for us to port less complicated alternatives like Firefox, WebKit and Servo given that our limited resources are better spent on improving Redox itself.

This doesn't stop us from porting more programs even if they are non-POSIX. For example, Wayland is challenging to port as it depends on many Linux features. But given enough time, it will became available in Redox, just like how X11 is working on Redox.

System Designs That Are Non-Goals

Redox aims to have the answer to every system design challenge if possible. However, correctness and security is our top priority next to other aspect like "performance", "usability" or "stability". That may change as Redox get close to releasing the 1.0 stable version.

Redox have gotten though many major system design changes since its inception. Historically Redox was not designed to be a microkernel nor POSIX-compliant, then both have changed in early times. We also recently switched our system service interface (scheme) design and about to change the security design to a capability-based system.

Nowadays all recent and future major changes into Redox is happening via RFCs and reviewed by Redox OS Board Members. Any Request For Changes that reduces correctness or security are likely not going to be accepted, but this terms are flexible and not enforced until the 1.0 stable version.

One example major design that trade security over "usability" is userspace exec which has been fully implemented. A userspace exec means exec are fully managed in userspace, it means that the kernel have no way to know how any software has been executed (e.g.their arguments and environment variables), as the kernel also have been restricted to not read any userspace memory.

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.

This license was chosen to allow Redox to be used everywhere with minimum restrictions.

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

Programs running on top of Redox don't have to be MIT X11-style licensed, just like how other OSes do (e.g. proprietary programs and drivers on top of Linux). But all of officially ported programs so far is only OSI and GNU licensing compliant software.

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.

It allows us to unlock the full Rust potential by dropping legacy C and C++ code.

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 system components as possible out of the operating system kernel. Drivers, subsystems and other operating system functionality are excuted 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 system's resources. In Monolithic Kernels, the operating system's entire response to an event must be completed in supervisor mode. A bug in the kernel, drivers or hardware, can cause the system to enter a state where it can't 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.

Beyond monolithic kernels being much more vulnerable to bugs there's also the much higher complexity of post-Internet modern hardware and drivers that didn't existed when monolithic kernels were adopted, but since the adoption of Internet and the implementation of the TCP/IP network stack in BSD Unix the complexity grew fast. This growth has caused a epidemic of bugs that are hard or invisible to debug due to all monolithic kernel components sharing the same memory address space.

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 could 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 with a small chance of data corruption, but the kernel and maybe the essential system components 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 with the features and comodity that you would expect from them.

Benefits

The following items summarize the microkernel benefits:

• More stable and secure

  The very small size of the kernel allow the system to be more stable and secure because most system components are isolated in user-space, reducing the chance of a kernel panic and the severity of security bugs.

• Bug isolation

  Most system components run in user-space on a microkernel system. Because of this some types of bugs in most system components and drivers can't spread to other system components or drivers.

• More stable long execution

  When an operating system is left running for a long time (days, months or even years) it will activate many bugs and it's hard to know when they were activated, at some point these bugs can cause security issues, data corruption or crash the system.

  In a microkernel most system components are isolated and some bug types can't spread to other system components, thus the long execution tend to enable less bugs reducing the security issues, data corruption and downtime on servers.

  Also some system components can be restarted on-the-fly (without a full system restart) to disable the bugs of a long execution.

• 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 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 system components run in userspace, simplifying the testing and debugging.

• Easy and quick to expand

  New system components and drivers are easily and quickly added as userspace daemons.

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

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.

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.

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.

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 Requirements

The following requirements are mandatory to make Redox work, non-x86 CPUs have equivalents for them.

• MMU : Introduced by the Intel 8086 CPU line in 1978 and present in all CPUs since then
• FPU : Introduced by the Intel 8087 coprocessor in 1980 for the Intel 8086 CPU line and present in almost all CPUs since then
• FXSAVE extension or non-x86 CPU equivalent
• Page Size Extension or non-x86 CPU equivalent
• Paging global extension or non-x86 CPU equivalent

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 DRAM memory 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 CPU architecture is supported by the system, but the performance and stability may vary per program.

Why choosing i586 as the minimal supported x86 CPU?

• i686 (Pentium Pro) introduced MMX, SSE, and SSE2 extensions. Fortunately the kernel and other critical system components don't use them.
• i586 (Original Pentium) introduced a more efficient FPU and MMX extension which are critical for programs, also the most minimal CPU architecture supported by Rust and perhaps most Rust packages.
• i486 introduced FPU and atomic operations, which are used by the kernel and other critical system components. It would be possible to go all the way back to i486, but Redox will run with much less programs.
• i386 has no atomics and floating instructions (at all), which makes it not a target for both the kernel and other critical system components.

Compatibility Table

Important Programs

This page covers important programs and libraries supported by Redox as of October 2025.

Redox is designed to be source-compatible with POSIX and Linux applications, only requiring compilation or small patches.

This page contain programs that are known to work well on Redox or how well it was tested. All programs are compiled through our package cross-compilation system called Cookbook, which includes the configuration of all kinds of patches and forks that are required to make them run on Redox.

Everything on the following lists are tested on the x86_64 (Intel/AMD) CPU architecture, other CPU architectures may not have been tested yet.

Compilers

The following compilers have been tested to build on Redox, but the runtime status varies:

Interpreters

The following interpreters have been tested to build on Redox, but the runtime status varies:

GUI Libraries

Most GUI applications are running through Orbital (Redox display server and window manager), it supports the following GUI libraries:

• Mesa3D (OpenGL and EGL, via liborbital)
• SDL1 and SDL2 (via Mesa3D)
• winit (via orbclient)
• X11 (via TWM, which is via liborbital)

Applications

The following programs are well known to be working:

Emulators

Games

Servers

CLI Tools

The following CLI tools are known to be working. Programs listed below may not include core utilites:

Terminal Shells

Text Editors

System Monitors

Development Tools

Media Tools

Archive Tools

Storage Tools

Network Tools

Other Programs

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

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.
• Orbclient - Orbital client library for Rust programs.
• pkgutils - Redox package manager, with a command-line frontend and library.
• relibc - Redox C library.
• audiod - Redox audio server.
• bootloader - Redox boot loader.
• base - Redox essential system services and drivers.
• installer - Redox buildsystem builder.
• redoxer - A tool to run/test Rust programs inside of a Redox VM.
• games - A collection of mini-games for Redox (alike BSD-games).
• 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:

• coreutils - Redox-specific core utilities such as free, ps, shutdown, and so on.
• extrautils - Redox-specific extra utilities such as dmesg, less, which, 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.
• winit - The window handling library for Rust programs.

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.

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 and driver bugs 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 some disadvantages) with microkernels, a few of which will be covered here.

Better Stability

When compared to microkernels, Monolithic kernels tend to be prone to crashes and driver bugs. 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). Or the bugs in a driver can spread to other drivers without causing crashes, which is hard to ensure stability and a headache to investigate the root of the problems.

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

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.

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 Modularity and Configuration

Monolithic kernels are, well, monolithic. They do not allow fine-grained control like 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 add, replace, reload, modify, change, and remove system components or drivers, 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 Expansion

In microkernels new system components and drivers can be easily added using daemons, while in monolithic kernels the entire kernel needs to be updated to add them which can introduce bugs to other system components or drivers.

Sane Debugging

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

The "component panics" (where "component" is the name of the system component) are more common in microkernels than kernel panics because the kernel code size is very small, the log of a component panic can be saved which ease debugging a lot.

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

While in monolithic kernels a bug in a system component or driver can cause a kernel panic and freeze 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

BIOS Boot is a boot process that dates back to the IBM PC. Because of its lengthy history, BIOS starts up in 16-bit mode (Real Mode), and the boot loader needs to load in multiple stages to move into higher bit environments. The firmware will execute the boot sector located in the first sector of the main storage device, which is known as the stage 1 bootloader (OSDev Wiki).

The stage 1 bootloader is written in Assembly and can be found in asm/x86-unknown-none/stage1.asm. The stage 1 main task is to allow reading of the whole disk to load stage 2 in another sector of the storage device. The stage 2 bootloader is also written in Assembly. The main task is transferring BIOS functions from real mode to protected mode (32-bit), then switches to protected mode or long mode (64-bit) 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. The first code that is executed in Rust-written code is pub extern "C" fn start() in src/os/bios/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.

UEFI Boot

Redox supports UEFI booting on x86-64, ARM64, and RISC-V 64-bit machines. UEFI starts up in 64-bit mode; thus, the boot process doesn't need multiple stages. The firmware will find the EFI System Partition (ESP) on the storage device, then load and execute PE32+ UEFI programs typically located at /EFI/BOOT/BOOTX64.efi (OSDev Wiki).

In the case of 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 accessible after control is switched to the kernel. The bootloader then finds the RedoxFS boot partition on the disk and loads /boot/kernel and /boot/initfs files into memory.

For a live disk, it does load the whole partition into memory. It then loads /boot/kernel and /boot/initfs also at a different location in memory.

After the kernel and initfs have been loaded, it sets up a virtual paging for kernel and environment variables, including the location of the RedoxFS boot partition to be passed into it. Then, it maps the kernel to its expected virtual address and jumps to its entry function.

Kernel

The Redox kernel is a single ELF program in /boot/kernel. This 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 /scheme/initfs scheme, and loads and executes the init program.

The kernel creates three different namespaces during the bootstrap process. Each namespace has its schemes that can be accessed by userspace programs, depending on where it is loaded:

1. the null (0) namespace, a namespace that drivers are running on:

   • /scheme/memory
   • /scheme/pipe

2. the root (1) namespace, the initial namespace set up during boot:

   • /scheme/kernel.acpi
   • /scheme/kernel.dtb
   • /scheme/kernel.proc
   • /scheme/debug
   • /scheme/irq
   • /scheme/serio

3. Additional namespaces requested by user, also loaded for root namespace:

   • /scheme/event
   • /scheme/memory
   • /scheme/pipe
   • /scheme/sys
   • /scheme/time

Init

Redox has a multi-staged init process, designed to allow for the loading of storage drivers in a modular and configurable fashion. This is commonly referred to as an init RAMdisk (initfs). The RAMdisk is contained in /boot/initfs, which is a special file format containing the bootstrap code in ELF format and packed files which was loaded into /scheme/initfs by the kernel program.

RAMdisk Init

The ramdisk init has the job of loading the drivers and daemons required to access the root filesystem and then transferring control to the filesystem init. The load order is defined in /etc/init.rc in initfs:

1. Daemons required for relibc
   • rtcd loads machine-specific RTC into /scheme/time
   • nulld null handler, creates /scheme/null
   • zero zero handler, creates /scheme/zero
   • randd rand handler, creates /scheme/rand
2. Logging
   • logd system log handler, creates /scheme/log
   • ramfs loads in-memory FS handling into /scheme/memory
3. Graphics buffers
   • inputd virtual terminal (VT) handler, creates /scheme/input
   • vesad VESA interface handler, creates /scheme/display.vesa
   • fbbootlogd forwards log from logd to VT
   • fbcond handles keyboard interaction to VT
4. Live daemon
   • lived livedisk handler, creates /scheme/disk.live
5. Drivers in /etc/init_drivers.rc
   • ps2d loads PS/2 handling into /scheme/serio
   • acpid loads ACPI handling into /scheme/kernel.acpi
   • pcid PCI handler, creates /scheme/pci
   • pcid-spawner spawns drivers depending on available hardware
     • ahcid AHCI storage driver
     • ided IDE storage driver
     • nvmed NVME storage driver
     • virtio-blkd VirtIO BLK storage driver
     • virtio-gpud VirtIO GPU driver

After loading all drivers and daemons above, the redoxfs driver is executed with --uuid $REDOXFS_UUID where $REDOXFS_UUID is the partition chosen by the bootloader and creates /scheme/file. The command set-default-scheme file is then executed, so that the default path handler is set to /scheme/file.

Filesystem Init

The filesystem init continues the loading of drivers for all other functionality. This includes audio, networking, and anything not required for storage device access. The drivers' init configuration is mainly found in /usr/lib/init.d and /etc/pcid.d. In the redox builder repository, it's configurable in the config directory. 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, the user can log in to the system. The login program accepts a 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).

Tooling

RedoxFS tooling can be used to create, mount and edit contents of an .img file containing RedoxFS. It can be installed with:

cargo install redoxfs

If you found errors while installing it make sure to install the libfuse 3.x package for your Unix-like distribution.

Create a disk

You can create an empty, non-bootable RedoxFS by allocating an empty file with fallocate then run redoxfs-mkfs to initialize the whole image as RedoxFS.

fallocate -l 1G redox.img

redoxfs-mkfs redox.img

To create an encrypted disk use the --encrypt option, it will ask the password through a masked prompt:

redoxfs-mkfs --encrypt redox.img

To create a disk with contents from an existing directory use redoxfs-ar (currently the redoxfs-ar tool overwrites existing content and have no --encrypt option).

redoxfs-ar redox.img ./sysroot

Create a bootable disk

The second option of redoxfs-mkfs and third option of redoxfs-ar tools accepts a file that contains a raw image to be written as reserved disk space. This is meant to be a bootloader. Redox is booted using the official bootloader.

First you need to download the bootloader repository and build it, the following commands will build a BIOS bootloader:

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

make -C bootloader TARGET=x86-unknown-none BUILD=build all

Once the bootloader is available at bootloader/build/bootloader.bin after compilation, you can create a new bootable disk using either redoxfs-mkfs or redoxfs-ar:

redoxfs-mkfs redox.img bootloader/build/bootloader.bin

redoxfs-ar redox.img ./sysroot bootloader/build/bootloader.bin

You can also convert a non-bootable disk into bootable using redoxfs-clone:

redoxfs-clone redox.img redox-bootable.img bootloader/build/bootloader.bin

It's not possible to create a bootable UEFI using this option because it creates a GPT-partitioned disk, which currently is only implemented in redox-installer. A dual boot option in the same disk is also impossible if booting from a BIOS firmware.

Note that you need to have boot/kernel and boot/initfs in the image to make it actually bootable. You can build those from the main build system or the kernel and base repositories.

Mount a disk

To mount the disk run the redoxfs [image] [directory] command, for example:

mkdir ./redox-img

redoxfs redox.img ./redox-img

It will mount the disk using FUSE underneath.

The difference is that redoxfs-ar overwrites existing disk content. Mounting a disk through FUSE is the only way to update existing content in the RedoxFS-formatted image.

Unmount the disk

Unmount the disk using FUSE unmounting tool:

fusermount3 ./redox-img

Extend the disk

⚠️ Warning: Experimental, please backup before

To extend an existing disk, you need to extend the file before:

truncate -s 2GB redox.img

Then you can run the redoxfs-resize [disk] [size] command. The [size] option can be max (the default), min, or a fixed size defined in the parse-size library.

redoxfs-resize ./redox.img

minimum size: 438.75 MB (418.42 MiB)
maximum size: 2.00 GB (1.86 GiB)
new size: 2.00 GB (1.86 GiB)
growing by 1559135232
redoxfs-resize: resized filesystem on redox.img
	uuid: febb081e-06ff-4786-a878-f1bb031cdf97
	size: 2.00 GB (1.86 GiB)
	used: 438.65 MB (418.33 MiB)
	free: 1.56 GB (1.45 GiB)

Shrink the disk

⚠️ Warning: Experimental, please backup before

To shrink an existing disk you can use the redoxfs-resize tool:

redoxfs-resize ./redox.img min

minimum size: 438.77 MB (418.44 MiB)
maximum size: 2.00 GB (1.86 GiB)
new size: 438.77 MB (418.44 MiB)
shrinking by 1559135232
redoxfs-resize: resized filesystem on redox.img
	uuid: febb081e-06ff-4786-a878-f1bb031cdf97
	size: 438.77 MB (418.44 MiB)
	used: 438.64 MB (418.32 MiB)
	free: 122.88 kB (120 KiB)

You can use the value from "shrinking by ..." to accurately tell how much bytes can be shrinked:

truncate -s -1559135232 redox.img

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.

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.

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

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.

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.

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
• display.vesa
• display.virtio-gpu
• orbital
• pty
• audiorw
• audio
• usb.*
• sudo
• acpi
• input
• 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 type of 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 and more easy to use. The program is linked 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 partial POSIX compatibility.
• relibc has Linux functions for libraries and programs
• 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 Rust programs can be compiled for Redox.

The Redox Cookbook package system contain 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 - Terminal shell
• orbital - Desktop environment

Orbital

• orblogin - Login manager
• launcher - App panel
• background - Wallpaper program
• viewer - Image viewer
• calculator - Math program
• COSMIC Files - File manager
• COSMIC Editor - Text editor
• COSMIC Terminal - Terminal emulator
• COSMIC Reader - Document 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

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

If you don't have QEMU installed use one of the following commands on Ubuntu, Debian or PopOS based on the image that you want:

• x86-32 (i586) and x86-64 images

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

• ARM64 images

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

• RISC-V images

sudo apt-get install qemu-system-riscv

Use one of the following commands to run QEMU with a Redox-compatible configuration:

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

x86-32 (i586) image

• Run QEMU

SDL_VIDEO_X11_DGAMOUSE=0 qemu-system-i386 -d cpu_reset,guest_errors -smp 1 -m 2048 \
    -chardev stdio,id=debug,signal=off,mux=on,"" -serial chardev:debug -mon chardev=debug \
    -machine pc -cpu pentium2 -device AC97 -netdev user,id=net0 \
    -device e1000,netdev=net0 -device nec-usb-xhci,id=xhci \
    -drive file=`echo $HOME/Downloads/redox_demo_i586_*_harddrive.img`,format=raw

x86-64 image

• Run QEMU

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

ARM64 image

• Run QEMU

SDL_VIDEO_X11_DGAMOUSE=0 qemu-system-aarch64 -d cpu_reset,guest_errors -smp 4 -m 2048 \
    -chardev stdio,id=debug,signal=off,mux=on,"" -serial chardev:debug -mon chardev=debug \
    -bios /usr/share/AAVMF/AAVMF_CODE.fd -machine virt -cpu max -vga none -device ramfb -netdev user,id=net0 \
    -device e1000,netdev=net0 -device nec-usb-xhci,id=xhci \
    -drive file=`echo $HOME/Downloads/redox_demo_aarch64_*_harddrive.img`,format=raw

RISC-V image

Verify if the QEMU UEFI firmware is installed

• PFLASH0

ls -1 /usr/share/qemu-efi-riscv64/RISCV_VIRT_CODE.fd /usr/share/edk2/riscv/RISCV_VIRT_CODE.fd /usr/share/qemu/edk2-riscv-code.fd /usr/share/qemu-efi-riscv64/RISCV_VIRT_VARS.fd /usr/share/qemu/edk2-riscv-vars.fd

• PFLASH1

ls -1 /usr/share/qemu-efi-riscv64/RISCV_VIRT_VARS.fd /usr/share/edk2/riscv/RISCV_VIRT_VARS.fd /usr/share/qemu/edk2-riscv-vars.fd

At least one of each PFLASH command must be present, if the file location present on your system is different from the one used in the command you need to change it.

• Run QEMU

TODO: fix not enough space for firmware error

SDL_VIDEO_X11_DGAMOUSE=0 qemu-system-riscv64 -d cpu_reset,guest_errors -smp 4 -m 2048 \
    -chardev stdio,id=debug,signal=off,mux=on,"" -serial chardev:debug -mon chardev=debug \
    -drive if=pflash,format=raw,unit=0,file=/usr/share/qemu-efi-riscv64/RISCV_VIRT_CODE.fd,readonly=on -drive if=pflash,format=raw,unit=1,file=/usr/share/qemu-efi-riscv64/RISCV_VIRT_VARS.fd -machine virt,acpi=off -cpu max -vga none -device ramfb -audio none -netdev user,id=net0 \
    -device e1000,netdev=net0 -device nec-usb-xhci,id=xhci \
    -drive file=`echo $HOME/Downloads/redox_demo_riscv64gc_*_harddrive.img`,format=raw

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.

Use one of the following commands to run QEMU with a Redox-compatible configuration:

x86-32 (i586) image

• Run QEMU

TODO: test

"C:\Program Files\qemu\qemu-system-x86.exe" -d cpu_reset,guest_errors -smp 1 -m 2048
-chardev stdio,id=debug,signal=off,mux=on,"" -serial chardev:debug -mon chardev=debug
-machine pc -cpu pentium2 -device AC97 -netdev user,id=net0
-device e1000,netdev=net0 -device nec-usb-xhci,id=xhci -device usb-tablet
-drive file=redox_demo_i586_*_harddrive.img,format=raw

x86-64 image

• Run QEMU

TODO: test

"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 pc -cpu host -device ich9-intel-hda -device hda-duplex -netdev user,id=net0
-device e1000,netdev=net0 -device nec-usb-xhci,id=xhci -device usb-tablet
-drive file=redox_demo_x86_64_2024-09-07_1225_harddrive.img,format=raw

ARM64 image

• Run QEMU

TODO: test

"C:\Program Files\qemu\qemu-system-aarch64.exe" -d cpu_reset,guest_errors -smp 4 -m 2048
-chardev stdio,id=debug,signal=off,mux=on,"" -serial chardev:debug -mon chardev=debug
-drive -bios "C:\Program Files\qemu\share\edk2-aarch64-code.fd" 
-machine virt -cpu max -vga none -device ramfb -netdev user,id=net0
-device e1000,netdev=net0 -device nec-usb-xhci,id=xhci -device usb-tablet
-drive file=redox_demo_aarch64_*_harddrive.img,format=raw

RISC-V image

• Run QEMU

TODO: test

"C:\Program Files\qemu\qemu-system-riscv64.exe" -d cpu_reset,guest_errors -smp 4 -m 2048
-chardev stdio,id=debug,signal=off,mux=on,"" -serial chardev:debug -mon chardev=debug
-drive -bios "C:\Program Files\qemu\share\edk2-riscv-code.fd"
-machine virt,acpi=off -cpu max -vga none -device ramfb -audio none -netdev riscv,id=net0
-device e1000,netdev=net0 -device nec-usb-xhci,id=xhci -device usb-tablet
-drive file=redox_demo_riscv64gc_*_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 i586 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 CD/DVD, log in as the user named user with an empty password, click on the Redox OS icon in the Orbital bottom bar to open the app menu, then open the "System" app category and click on the "Redox Installer" app.

Of if you want to launch it from the terminal run the following command:

sudo redox_installer_gui

If you are using the server variant or want to use the TUI interface 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 /usr/bin/periodictable is a demonstration of the OrbTk user interface toolkit.

Kibi

Kibi is the default terminal text editor inpisred on GNU Nano but with more features, run the kibi command to use it.

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

Tasks

This page contain 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

Change current keyboard layout (map)

• Show all available layouts

inputd --keymaps

• Change current layout

inputd -K layout-name

Show system information

uname -a

Or

screenfetch

Show memory (RAM) information

free -h

Show storage information

df -h

Shutdown the computer

sudo shutdown

Show all running processes

ps

Show system-wide common programs

ls /usr/bin

Show all schemes

ls /scheme

Show all scheme resources

ls /scheme/scheme-name

Show the system log

dmesg

Or

cat /scheme/sys/log

Networking

Show system DNS name

hostname

Show all network addresses of your system

hostname -I

Ping a website or IP

ping (website-url/ip-address)

Show website information

whois https://website-name.com

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 directory paths in the PATH environment variable

echo $PATH

Show the dynamically linked 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 information

glxinfo | grep OpenGL

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.

Contributing

Now that you are ready to contribute to Redox, read our CONTRIBUTING document to guide you.

Please follow our guidelines for Using Redox GitLab and our Best Practices.

If you are contributing to Redox, it's important to join us on Chat. Merge Requests are only reviewed if you post a link in the MRs room on Chat. It's also important to join so you can align with our current efforts and avoid unnecessary work.

Chat

The best way to communicate with the Redox team is on Matrix Chat, to join our chat, you must request an invitation in the Join Requests room (this room acts as a guard against spam and bots)

When your invitation is sent, you will receive a notification on Matrix.

After you accept the invitation, you can open the Redox Matrix space and see the rooms that are available.

These rooms are English-only, we cannot offer support in other languages because the maintainers will not be able to verify the correctness of your responses. But if you post translator-generated messages, we will do our best to understand them.

About Matrix

Matrix is an open chat protocol and has several different clients. Element is a commonly used choice, it works on web browsers, Linux, MacOSX, Windows, Android and iOS.

Rules

We follow the Rust Code Of Conduct as rules of the chat rooms.

Threads

• If you want to have a big discussion in our Matrix space you should use a thread.
• A thread is a list of messages, like a forum topic.
• A thread is linked to the original message, but displayed to the side to help improve the visibility of new questions in the main message area.

Not all Matrix clients support threads, so if you are not able to see threads in your client, try a different client.

If you are unable to use a client that supports threads, let us know when you ask a question, and we will try to accommodate you as best we can.

• To start a thread on Element, hover your mouse cursor over the desired message and click on the button with the message icon (a rectangular speech bubble).
• To see all threads in a room click on the top-right button with a message icon.

We mostly use Element threads but there are other Matrix clients with threads support, like nheko.

The Redox Space

All rooms available on the Redox space:

• #redox-join:matrix.org - A room to be invited to Redox space.
• #redox-announcements:matrix.org - A room for important announcements.
• #redox-general:matrix.org - A room for Redox-related discussions (questions, suggestions, porting, etc).
• #redox-dev:matrix.org - A room for the development, here you can talk about anything development-related (code, proposals, achievements, styling, bugs, etc).
• #redox-gitlab-updates:matrix.org - GitLab activity notifications room
• #redox-rfcs:matrix.org - A room for system architecture design discussions and brainstorming for RFCs.
• #redox-support:matrix.org - A room for testing and building support (problems, errors, questions).
• #redox-mrs:matrix.org - A room to send all ready merge requests without conflicts (if you have a ready MR to merge, send there).
• #redox-gitlab:matrix.org - A room to send new GitLab accounts for approval.
• #redox-soc:matrix.org - A room for the Redox Summer Of Code program.
• #redox-board:matrix.org - A room for meetings of the Board of Directors.
• #redox-voip:matrix.org - A room for voice chat discussions.
• #redox-random:matrix.org - A room for off-topic discussions.
• #redox-memes:matrix.org - A room for memes.

Troubleshooting

If you don't to deal with the Element problems, try Nheko or Fractal.

If you have connection problems see this website to see if the matrix.org homeserver is normal.

Element

• Threads on Element have some bugs, typically marking messages as still unread, even after you have read them.

• Element in the web browser does not show new messages in a thread as part of its new message count. It only shows a green or red dot over the Threads icon on the lower left of the display. A red dot means that the message is a reply to you. Click the Threads icon to see which rooms have new thread messages.

• To display all threads in a room on Element in the web browser, click on the Threads icon on the top right of the display.

• If the Threads button on the top right has a dot, you may have unread messages on some thread, but this could be wrong.

• If a thread has a dot to the right, you have unread messages in that thread. Click on the thread to read it.

• When entering a room where you have previously received replies in a thread, you may hear a notification bell, even though there is no new message.

• Due to bugs, a thread you have previously read can show a dot and possibly count as unread messages. Click on the thread and make sure you have read it, and to clear it. If it is still not cleared, click on the "Thread options" ... button on the top right and select "Show in room". This will often clear it.

You can also mark an entire room as "Read" by mousing over the room name and selecting "Mark as read" from the "Room options" ... button.

• After doing the steps above, if you still have problems, try reloading the page.

• Element uses a cache, but clearing the cache sometimes causes problems, if you have encrypted rooms, like DM rooms, save your encryption keys before clearing your cache or you may lose the room history.

Read the Element documentation to learn more about encryption keys.

Best Practices and Guidelines

These are a set of best practices to keep in mind when making a contribution to Redox. As always, rules are made to be broken, but these rules in particular play a part in deciding whether to merge your contribution (or not). So do try to follow them.

Literate programming

Literate programming is an approach to programming where the source code serves equally as:

• The complete description of the program, that a computer can understand
• The program's manual for the human, that an average human can understand

Literate programs are written in such a way that humans can read them from front to back, and understand the entire purpose and operation of the program without preexisting knowledge about the programming language used, the architecture of the program's components, or the intended use of the program. As such, literate programs tend to have lots of clear and well-written comments. In extreme cases of literate programming, the lines of "code" intended for humans far outnumbers the lines of code that actually gets compiled!

Tools can be used to generate documentation for human use only based on the original source code of a program. The rustdoc tool is a good example of such a tool. In particular, rustdoc uses comments with three slashes ///, with special sections like # Examples and code blocks bounded by three backticks. The code blocks can be used to writeout examples or unit tests inside of comments. You can read more about rustdoc on the Rust documentation.

Writing Documentation Correctly (TM)

Documentation for Redox appears in two places:

• In the source code
• On the website (the Redox Book and online API documentation)

Redox functions and modules should use rustdoc annotations where possible, as they can be used to generate online API documentation - this ensures uniform documentation between those two halves. In particular, this is more strictly required for public APIs; internal functions can generally eschew them (though having explanations for any code can still help newcomers to understand the codebase). When in doubt, making code more literate is better, so long as it doesn't negatively affect the functionality. Run rustdoc against any added documentation of this type before submitting them to check for correctness, errors, or odd formatting.

Documentation for the Redox Book generally should not include API documentation directly, but rather cover higher-level overviews of the entire codebase, project, and community. It is better to have information in the Book than not to have it, so long as it is accurate, relevant, and well-written. When writing documentation for the Book, be sure to run mdbook against any changes to test the results before submitting them.

Rust Style

Since Rust is a relatively small and new language compared to others like C, there's really only one standard. Just follow the official Rust standards for formatting, and maybe run rustfmt on your changes, until we setup the CI system to do it automatically.

Rusting Properly

Some general guidelines:

• Use std::mem::replace and std::mem::swap when you can.
• Use .into() and .to_owned() over .to_string().
• Prefer passing references to the data over owned data. (Don't take String, take &str. Don't take Vec<T> take &[T]).
• Use generics, traits, and other abstractions Rust provides.
• Avoid using lossy conversions (for example: don't do my_u32 as u16 == my_u16, prefer my_u32 == my_u16 as u32).
• Prefer in place (box keyword) when doing heap allocations.
• Prefer platform independently sized integer over pointer sized integer (u32 over usize, for example).
• Follow the usual idioms of programming, such as "composition over inheritance", "let your program be divided in smaller pieces", and "resource acquisition is initialization".
• When unsafe is unnecessary, don't use it. 10 lines longer safe code is better than more compact unsafe code!
• Be sure to mark parts that need work with TODO, FIXME, BUG, UNOPTIMIZED, REWRITEME, DOCME, and PRETTYFYME.
• Use the compiler hint attributes, such as #[inline], #[cold], etc. when it makes sense to do so.
• Try to banish unwrap() and expect() from your code in order to manage errors properly. Panicking must indicate a bug in the program (not an error you didn't want to manage). If you cannot recover from an error, print a nice error to stderr and exit. Check Rust's book about Error Handling.

Avoiding Panics

Panics should be avoided in kernel, and should only occur in drivers and other services when correct operation is not possible, in which case it should be a call to panic!().

Please also read the kernel README for kernel-specific suggestions.

Testing

• It's always better to test boot every time you make a system change, because it is important to see how the OS boots and works after it compiles.

• Even though Rust is a safety-oriented language, something as unstable and low-level as a work-in-progress operating system will almost certainly have problems in many cases and may completely break on even the slightest critical change.

• Also, make sure you verified how the unmodified version runs on your machine before making any changes. Else, you won't have anything to compare to, and it will generally just lead to confusion. TLDR: rebuild and test boot often.

• The real hardware testing is bigger than QEMU testing and thus detect more bugs

• There's also the acid test suite from Redox, to use it run the make rp.acid command from the build system to install the suite in the Redox image, run the cd acid command to go to the acid directory and use the cargo test command to run correctness tests and cargo bench command to run stress tests.

• The relibc test suite is used to complement acid, use the make r.relibc-tests-bins command from the build system to run it or the make rp.relibc-tests command to add the source in the Redox image, build (cd relibc-tests and make run commands) and run it (make test command) later inside of Redox for more testing.

• The os-test test suite has the largest number of tests and is the recommended method to test the system, use the make r.os-test-bins command from the build system to run it or the make rp.os-test command to add the source in the Redox image, build (cd os-test and make all commands) and run it (make test command) later inside of Redox for more testing.

Using Redox GitLab

The Redox project is hosted here: Redox GitLab. You can download or clone the Redox source from there. However, if you wish to contribute, you will need a Redox Gitlab account.

This chapter provides an overview of Redox GitLab, how to get access, and how to use it as a Redox contributor.

Signing in to GitLab

Joining Redox GitLab

You don't need to join our GitLab to build Redox, but you will if you want to contribute. Obtaining a Redox account requires approval from a GitLab administrator, because of the high number of spam accounts (bots) that are created on this type of project. To join, first, go to Redox GitLab and click the Sign In/Register button. Create your User ID and Password. Then, send an message to the GitLab Approvals room indicating your GitLab User ID and requesting that your account be approved. Please give a brief statement about what you intend to use the account for. This is mainly to ensure that you are a genuine user.

The approval of your GitLab account may take some minutes or hours, in the meantime, join us on the chat and let us know what you are working on.

Setting up 2FA

Your new GitLab account will not require 2 Factor Authentication at the beginning, but it will eventually insist. Some details and options are described in detail below.

2FA Apps

Requirements Before Logging Into GitLab

Before logging-in, you'll need:

• your web browser open at Redox GitLab
• your phone
• your 2FA App installed on your phone.
• to add https://gitlab.redox-os.org/redox-os/ as a site in your 2FA App. Once added and the site listed, underneath you'll see 2 sets of 3 digits, 6 digits in all. i.e. 258 687. That's the 2FA Verification Code. It changes every so often around every minute.

Available 2FA Apps for Android

On Android, you may use:

• Aegis Authenticator - F-Droid/Play Store
• Google Authenticator

Available 2FA Apps for iPhone

On iPhone iOS, you may use:

• Google Authenticator
• Tofu Authenticator (open-source)
• iOS built-in authenticator

Logging-In With An Android Phone

Here are the steps:

• From your computer web browser, open the Redox GitLab
• Click the Sign In button
• Enter your username/email
• Enter your password
• Click the Submit button
• Finally you will be prompted for a 2FA verification code from your phone. Go to your Android phone, go to Google/Aegis Authenticator, find the site gitlab redox and underneith those 6 digits in looking something like 258 687 that's your 2FA code. Enter those 6 digits into the prompt on your computer. Click Verify. Done. You're logged into Gitlab.

Logging-In With An iPhone

Here are the steps:

• From your computer web browser, open the Redox GitLab
• Click the Sign In button
• Enter your username/email
• Enter your password
• Click the Submit button
• Finally you will be prompted for a 2FA verification code from your phone. Go to your iPhone, go to 2stable/Tofu Authenticator or to your Settings->Passwords for iOS Authenticator, find the site gitlab redox and underneath those 6 digits in looking something like 258 687 that's your 2FA code. Enter those 6 digits into the prompt on your computer. Click Verify. Done. You're logged into Gitlab.

Setting up PAT

Personal Access Token (PAT) is a replacement for passwords when authenticating via Git clients. When pushing code to GitLab, you need to create one.

Here are the steps needed to create a PAT after logging in to GitLab:

• Open Personal access tokens in User settings
• Click "Add new Token" at the top right of the page
• Enter the token name (can be anything) and expiration date (max is 1 year from today)
• Check read_repository and write_repository scopes
• Click "Create Token"
• Copy the PAT (displayed as masked password) under the section "Your Token"
• Save the PAT somewhere safe, like your password manager

When doing git push, you'll be asked for username and password. Enter the password from the PAT token you've created. This will happen every time you run git push. To remember it forever, run the command below to store it later in ~/.git-credentials:

git config --global credential.helper store

If you don't like to store it as plain text, it's also possible to save it only in RAM cache:

# <timeout> is how long it will be preserved in memory, defaults to 900 (seconds)
git config --global credential.helper 'cache --timeout=<timeout>'

If you have lost your PAT, it's OK to create another one.

Repository Structure

The Redox GitLab consists of a large number of Projects, you will find the projects organized as a very large, flat alphabetical list. This is not indicative of the role or importance of the various projects.

The Redox Project

The redox project is actually just the root of the build system. It does not contain any of the code that the final Redox image will include. It includes the Makefiles, configuration files, package system and a few scripts to simplify setup and building. The redox project can be found on the GitLab repository.

Recipes

The many recipes that are added into the Redox image are built from the corresponding software sources. The name of a Redox package almost always matches the name of its program or library, although this is not enforced.

The recipe contains the instructions to download and build a program, for its inclusion in the Redox image.

Cookbook

The cookbook system contains the infrastructure for building the Redox recipes, you can find its source code in the src folder and recipes under the recipes folder.

Crates

Some Redox projects are built as Rust crates, and included in Redox recipes using Cargo's dependency management system. Updates to a crate must be pushed to the crate repository in order for it to be included in your build.

Forks, Tarballs and Other Sources

Some recipes obtain their source code from places other than Redox GitLab. The Cookbook system can pull in source from any Git repository URL. It can also obtain tarballs which is most used by C/C++ programs.

In some cases, the Redox GitLab has a fork of another repository, in order to add Redox-specific patches. Where possible, we try to push these changes upstream, but there are some reasons why this might not be feasible.

Personal Forks

When you are contributing to Redox, you are expected to make your changes in a personal fork of the relevant project, then create a Merge Request (PR) to have your changes pulled from your fork into the master or main branches. Note that your personal fork is required to have public visibility.

In some rare situations, e.g. for experimental features or projects with licensing that is not compatible with Redox, a recipe may download sources located in a personal repository. Before using one of these recipes, please check with us on the chat to understand why the project is set up this way, and do not commit a Redox configuration file containing such a recipe without permission.

Creating Proper Bug Reports

If you identify a problem with the system that has not been identified previously, please create a GitLab Issue. In general, we prefer that you are able to reproduce your problem with the latest build of the system.

• Make sure the code you are seeing the issue with is up to date with upstream/master. This helps to weed out reports for bugs that have already been addressed.
• Search Redox Issues to see if a similar problem has been reported before. Then search outstanding merge requests to see if a fix is pending.
• Make sure the issue is reproducible (trigger it several times). Try to identify the minimum number of steps to reproduce it. If the issue happens inconsistently, it may still be worth filing a bug report for it, but indicate approximately how often the bug occurs.
• Explain if your problem happens in a virtual machine, real hardware or both. Also say your configuration (default options or customized), if you had the problem on real hardware say your computer model.
• If it is a significant problem, join us on the chat and ask if it is a known problem, or if someone plans to address it in the short term.
• Identify the recipe that is causing the issue. If a particular command is the source of the problem, look for a repository on Redox GitLab with the same name. Or, for certain programs such as games or command line utilities, you can search for the package containing the command with grep -rnw COMMAND --include Cargo.toml, where COMMAND is the name of the command causing the problem. The location of the Cargo.toml file can help indicate which recipe contains the command. This is where you should expect to report the issue.
• If the problem involves multiple recipes, kernel interactions with other programs, or general build problems, then you should plan to log the issue against the redox repository.
• If the problem occurs during build, record the build log using script or tee, e.g.

make r.recipe-name 2>&1 | tee recipe-name.log

If the problem occurs while using the Redox command line, use script in combination with your Terminal window.

tee qemu.log

make qemu

• Wait for Redox to start, then in this window:

redox login: user

• Execute the commands to demonstrate the bug
• Terminate QEMU

sudo shutdown

• If shutdown does not work (there are known bugs) then
• Use the QEMU menu to quit
• Then exit the shell created by script

exit

• Join us in the chat.

• Record build information like:

  • The rust toolchain you used to build Redox
    • rustc -V and/or rustup show from your Redox project folder
  • The commit hash of the code you used
    • git rev-parse HEAD
  • The environment you are running Redox in (the "target")
    • qemu-system-x86_64 -version or your current hardware configuration, if applicable
  • The operating system you used to build Redox
    • uname -a or an alternative format

• Format your log on the message in Markdown syntax to avoid a flood on the chat, you can see how to do it on the GitHub documentation.

• Make sure that your bug doesn't already have an issue on GitLab. Feel free to ask in the Redox Chat if you're uncertain as to whether your issue is new.

• Create a GitLab issue following the template. Non-bug report issues may ignore this template.

• Once you create the issue don't forget to post the link on the Dev or Support rooms of the chat, because the GitLab email notifications have distractions (service messages or spam) and most developers don't left their GitLab pages open to receive desktop notifications from the web browser (which require a custom setting to receive issue notifications).

By doing this you help us to pay attention to your issues and avoid them to be accidentally forgotten.

• Watch the issue and be available for questions.

Creating Proper Pull Requests

In order for changes you have made to be added to Redox, or other related projects, it is necessary to have someone review your changes, and merge them into the official repository.

This is done by preparing a feature branch, and submitting a merge request.

For small changes, it is sufficient to just submit a pull request. For larger changes, which may require planning or more extensive review, it is better to start by creating an issue. This provides a shared reference for proposed changes, and a place to collect discussion and feedback related to it.

The steps given below are for the main Redox project repository - submodules and other projects may vary, though most of the approach is the same.

Please note:

• Once you have marked your MR as ready, don't add new commits.
• If you need to add new commits mark the MR as draft again.

Preparing your branch

1. In an appropriate directory, e.g. ~/tryredox, clone the Redox repository to your computer using the following command:

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

• If you used podman_bootstrap.sh or native_bootstrap.sh scripts (see the Building Redox page), the git clone was done for you and you can skip this step.
• You need to create a Personal Access Token for pushing your code into your repository fork later.

2. Change to the newly created redox directory and rebase to ensure you're using the latest changes:

   cd redox
   

   git rebase upstream master
   

3. You should have a fork of the repository on GitLab and a local copy on your computer. The local copy should have two remotes; upstream and origin, upstream should be set to the main repository and origin should be your fork. Log into Redox Gitlab and fork the build system repository - look for the button in the upper right.

4. Add your fork to your list of Git remotes with:

   git remote add origin https://gitlab.redox-os.org/MY_USERNAME/redox.git
   

• Note: If you made an error in your git remote command, use git remote remove origin and try again.

5. Alternatively, if you already have a fork and copy of the repo, you can simply check to make sure you're up-to-date. Fetch the upstream, rebase with local commits, and update the submodules:

   git fetch upstream master
   

   git rebase upstream/master
   

   git submodule update --recursive --init
   

   Usually, when syncing your local copy with the master branch, you will want to rebase instead of merge. This is because it will create duplicate commits that don't actually do anything when merged into the master branch.

6. Before you start to make changes, you will want to create a separate branch, and keep the master branch of your fork identical to the main repository, so that you can compare your changes with the main branch and test out a more stable build if you need to. Create a separate branch:

   git checkout -b MY_BRANCH
   

7. Make your changes and test them.

8. Commit:

   git add . --all
   

   git commit -m "COMMIT MESSAGE"
   

   Commit messages should describe their changes in present-tense, e.g. "Add stuff to file.ext" instead of "added stuff to file.ext". Try to remove duplicate/merge commits from PRs as these clutter up history, and may make it hard to read.

9. Optionally run rustfmt on the files you changed and commit again if it did anything (check with git diff first).

10. Test your changes with make qemu or make virtualbox

11. Pull from upstream:

    git fetch upstream
    

    git rebase upstream/master
    

• Note: try not to use git pull, it is equivalent to doing git fetch upstream; git merge master upstream/master

12. Repeat step 10 to make sure the rebase still builds and starts.

13. Push your changes to your fork:

    git push origin MY_BRANCH
    

Submitting a merge request

1. On Redox GitLab, create a Merge Request, following the template. Explain your changes in the title in an easy way and write a short statement in the description if you did multiple changes. Submit!
2. Once your merge request is ready, notify reviewers by sending the link to the Redox Merge Requests room.

Incorporating feedback

Sometimes a reviewer will request modifications. If changes are required:

1. Reply or add a thread to the original merge request notification in the Redox Merge Requests room indicating that you intend to make additional changes.

   Note: It's best to avoid making large changes or additions to a merge request branch, but if necessary, please indicate in chat that you will be making significant changes.

2. Mark the merge request as "Draft" before pushing any changes to the branch being reviewed.

3. Make any necessary changes.

4. Reply on the same thread in the Redox Merge Requests room that your merge request is now ready.

5. Mark the merge request as "Ready"

This process communicates that the branch may be changing, and prevents reviewers from expending time and effort reviewing changes that are still in progress.

Using GitLab web interface

• Update your fork before new changes (click on the button to update the branch in the fork page)

1. Fork the repository that you want and click in the "Web IDE" button inside the "Code" blue button.
2. If you have many changes and prefer a faster review create a branch for each part of the changes by clicking in the button named as "master" or "main" in the bottom left position
3. Make your changes in the files and click in the "Source Control" button on the left side.
4. Explain your commits and apply
5. After the first commit creation a pop-up window will appear suggesting to create a MR, if your changes are ready click on the "Create MR" button.
6. If you want to make more changes continue in the IDE, once you finish to create commits return to the fork page and reload it
7. Click on the "Create merge request" button that will appear
8. Explain your changes and create the MR (you can squash your commits if their names don't contain relevant information)
9. If your merge request is ready send the link in the Redox Merge Requests room.

GitLab Issues

GitLab issues are a formal way to communicate with Redox developers. They are best used to document and discuss specific features or to provide detailed bug reports. This communication is preserved and available for later reference.

For problems that can be quickly resolved, or require a quick response, using the chat is probably better.

Once you create an issue don't forget to post the link on the Dev or Support rooms of the chat, because the GitLab email notifications have distractions (service messages or spam) and most developers don't left their GitLab pages open to receive desktop notifications from the web browser (which require a custom setting to receive issue notifications).

By doing this you help us to pay attention to your issues and avoid them to be accidentally forgotten.

If you haven't joined the chat yet, you should (if at all interested in contributing)!

Please follow the Guidelines for your issues, if applicable. You will need a Redox GitLab account. See Signing in to GitLab.

The Build Process

This chapter will cover the advanced build process of Redox.

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

• If the command ask your to choose an image repository select the first item, it will give an error and you need to run the time make all command again

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 clean pull
   

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

   ./podman_bootstrap.sh -d
   

4. 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 i586 -c demo qemu

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

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 i586 (32-bit Intel/AMD) CPU architecture (defined in config/i586/server.toml):

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

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

Example 2

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

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

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

💡 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, without Podman.

⚠️ Warning: Building outside Podman is not guaranteed to succeed. Unless you have problems using Podman, we recommend you to use the Podman Build before trying the Native Build to avoid build environment bugs.

📝 Note: Read the Build System Reference page after installation 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
• FreeBSD (experimental)
• MacOS (experimental, require workarounds)
• Nix (experimental)
• Solus (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.

   If the native_bootstrap.sh script does not work for you, please try reading the Advanced Build page to install the right packages for your operating system.

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. For the Native Build we recommend setting these in the .config file:

• ARCH=x86_64
• CONFIG_NAME=desktop
• PODMAN_BUILD=0 to disable Podman Build
• PREFIX_BINARY=0 to disable prebuilt prefix binary
• PREFIX_USE_UPSTREAM_RUST_COMPILER=1 to avoid compiling Rust compiler

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 needs to be written again every time the script is executed.

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 explain 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 configure 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 download the pre-compiled packages.

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

8. Create the hello-world recipe folder.

   mkdir recipes/other/hello-world
   

9. Create the source folder for the recipe.

   mkdir recipes/other/hello-world/source
   

10. Navigate to the recipe's source folder.

    cd 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 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 updae the Redox image.

    time make prefix rp.hello-world
    

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
  • .config
  • Cookbook Configuration
  • Command Line
  • mk/config.mk
  • build.sh
• Filesystem Configuration
  • CPU Architecture Codenames
  • Filesystem Size
  • Filesystem Customization
    • Creating a custom filesystem configuration
    • Adding a package to the filesystem configuration
  • Binary Packages
    • REPO_BINARY
  • Local Recipe Changes
  • Cookbook Offline Mode

Environment Variables

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

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

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

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

.config

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

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

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

ARCH?=i586
CONFIG_NAME?=desktop-minimal

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

Cookbook Configuration

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

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

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

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

Each Cookbook configuration defaults to environment variables which are:

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

Changing the QEMU CPU Core and Memory Quantity

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

QEMU_SMP?=<number-of-threads>
QEMU_MEM?=<number-in-mb>

Command Line

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

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

make CONFIG_NAME=demo qemu

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

export ARCH=i586; make all

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

mk/config.mk

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

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

nano mk/config.mk

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

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

build.sh

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

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

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

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

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

Filesystem Configuration

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

nano config/x86_64/desktop.toml

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

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

Feel free to create your own filesystem configuration.

CPU Architecture Codenames

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

See the currently supported CPU architectures by Redox below:

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

Filesystem Size

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

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

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

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

make FILESYSTEM_SIZE=512 image qemu

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

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

Filesystem Customization

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

Creating a custom filesystem configuration

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

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

   cp config/your-cpu-arch/desktop.toml config/your-cpu-arch/my_desktop.toml
   

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

   CONFIG_NAME?=my_desktop
   

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

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

Adding a package to the filesystem configuration

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

1. Open the my-desktop.toml file:

   nano config/your-cpu/my-desktop.toml
   

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

   [packages]
   acid = {}
   

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

   make rp.acid
   

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

Binary Packages

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

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

1. Open the my-desktop.toml file:

   nano config/your-cpu/my-desktop.toml
   

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

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

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

   make image
   

4. Open QEMU to verify your binary package:

   make qemu
   

REPO_BINARY

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

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

For example:

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

Local Recipe Changes

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

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

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

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

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

Cookbook Offline Mode

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

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

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

Build System Reference

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
  • Podman
  • QEMU/VirtualBox
• Environment Variables
• Scripts
• Git Auto-checkout
• Update The Build System
• 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.

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/redox-live.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.

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).
• repo - Contains all packaged recipes.
• recipes/recipe-name - A recipe (software port) directory (represented as recipe-name), this directory holds the recipe.toml file.
• 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)

• recipes/recipe-name/recipe.sh - The old recipe configuration format (can't be used as dependency of a recipe with a TOML syntax).
• recipes/recipe-name/source.tar - The tarball of the recipe (renamed).
• recipes/recipe-name/source - The directory where the recipe source is extracted or downloaded.
• recipes/recipe-name/target - The directory where the recipe binaries are stored.
• recipes/recipe-name/target/${TARGET} - The directory for the recipes binaries of the CPU architecture (${TARGET} is the environment variable of your CPU architecture).
• recipes/recipe-name/target/${TARGET}/build - The directory where the recipe build system run its commands.
• 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.
• recipes/recipe-name/target/${TARGET}/sysroot - The folder where recipe build dependencies (libraries) goes, for example: library-name/src/example.c
• recipes/recipe-name/target/${TARGET}/stage.pkgar - Redox package file.
• recipes/recipe-name/target/${TARGET}/stage.sig - Signature for the tar package format.
• 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.
• recipes/recipe-name/target/${TARGET}/stage.toml - Contains the runtime dependencies of the package and is part of both package formats.

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.
• make fstools - Build the Redox image builder (installer), Cookbook and RedoxFS.
• 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 cook - Build recipes enabled in the active filesystem configuration
• make repo - Package the recipe binaries, according to each recipe. Does nothing if $(BUILD)/repo.tag is present. You won't need this.
• make find - Show the recipe packages location
• make tree - Show the filesystem configuration recipes and recipe dependencies tree
• 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 push - Only install recipes with new changes in an existing Redox image
• 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 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 mount_live - Mount the live disk ISO
• make env - Creates a shell with a build environment configured to use the Redox toolchain. If you are using Podman Build it will change your current terminal shell to the container shell, you can use it to update crates of Rust programs or debug build issues such as missing packages (if you are using the Podman Build you can only use this command in one terminal shell, because it will block the build system directory access from other Podman shell)
• make fstools_clean - Clean the image builder, Cookbook and RedoxFS binaries.
• 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).

Podman

• 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 (don't use this command to replace the make env command because it don't setup the Redox toolchain in the Podman container shell)
• 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.

Recipe

• 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 p.recipe-name - Install the recipe binaries to an existing Redox image

• make c.recipe-name - Clean the recipe binaries.

• make u.recipe-name - Clean the recipe source code and binaries (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 ur.recipe-name - A shortcut for make u.recipe r.recipe (please backup or submit your source changes before the execution of this command).

• make rp.recipe-name - A shortcut for make r.recipe p.recipe

• make crp.recipe-name - A shortcut for make c.recipe r.recipe p.recipe

• make static_clean - Clean all statically linked recipe binaries

• make repo_clean - Clean all recipe binaries (alternative to make c.--all)

• make fetch_clean - Clean all recipe binaries and sources (alternative to make u.--all)

• make x.--all - Any recipe target (x) can be run in all recipes at recipes (like make c.--all which clean all recipe binaries, for example)

• make x.--category-folder-name - Any recipe target (x) can be run in all recipes of some category folder at recipes (like make u.--category-wip which clean all recipe sources and binaries from the wip folder, for example), if you need to use a sub-category use --category-folder-name/subfolder

All recipe targets also support multiple recipe entries by separating each recipe name with a comma. for example: make f.recipe1,recipe2 will download the sources of recipe1 and recipe2

QEMU/VirtualBox

• make qemu - Boot Redox in QEMU, if a build/harddrive.img file exists QEMU will run using that image. If you want to force a rebuild first, run the make rebuild qemu command. 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 (disables Orbital).
• make qemu gpu=virtio - Start QEMU with the VirtIO GPU driver.
• 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 (high-performance 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 kvm=no - Start QEMU without the Linux KVM acceleration if it's not supported.
• make qemu iommu=yes - Start QEMU with IOMMU enabled.
• make qemu gdb=yes - Start QEMU with the GDB configuration enabled, you need to run the make rp.gdbserver command before to install the GDB server in the Redox image (persist until the next image creation) or add the gdbserver recipe on your filesystem configuration (gdbserver = {}) to persist in new images, then run the make gdb command in another shell to connect the GDB processes.
• make gdb - Connects the host system GDB to the GDB server (gdbserver recipe) running inside of Redox in QEMU.
• make qemu option1=value option2=value - Cumulative QEMU options are supported.
• make virtualbox - Boot Redox in 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 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, ur or uf

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 all recipes and show their content.

(Require bat and ripgrep installed, run cargo install bat ripgrep to install)

scripts/recipe-match.sh "text"

Print Recipe

Show the content of the recipe configuration.

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 -i586 option will show the i586 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).

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"

Update The Build System

This is the recommended way to update your build system/recipe sources and binaries.

make pull rebuild

Sometimes you need to update the statically linked recipes manually with the make static_clean rebuild command or also rebuild all dynamically linked recipes with the make repo_clean all command.

(The Podman container is updated automatically if upstream add new packages to the Containerfile, but you can also force the container image to be updated with the make container_clean command)

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

Advanced Podman Build

To make the Redox build process more consistent across platforms, we are using Rootless Podman for major parts of the build.

Before reading through this section, make sure you have already read:

• Podman Build
• Build System Reference

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.

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

If you can't use the podman_bootstrap.sh script, you need to install at least:

• Podman 4.0 or later
• Rust
• libfuse 3.x (to build an image)
• QEMU (to run the image)

You can attempt to install the necessary packages below.

Pop!_OS/Ubuntu/Debian

sudo apt-get install git make curl podman fuse fuse-overlayfs slirp4netns qemu-system-x86 qemu-kvm qemu-system-arm qemu-system-riscv

⚠️ Warning: Ubuntu 22.04 ships with old Podman (3.x version), which will have issues. The official Podman installation guide requires Ubuntu 20.10 and newer to operate. If you do use the 22.04 version or older, please read Gory Details.

Arch Linux

sudo pacman -S --needed git make curl podman fuse3 fuse-overlayfs slirp4netns qemu-system-x86 qemu-system-arm qemu-system-riscv

Fedora

sudo dnf install git-all make curl podman fuse3 fuse-overlayfs slirp4netns qemu-system-x86 qemu-kvm qemu-system-arm qemu-system-riscv

OpenSUSE

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

FreeBSD

sudo pkg install git gmake curl fusefs-libs3 podman

MacOS

Building Redox using MacOS is experimental at the moment, even if using Podman you will experience clock skew which breaks the Makefile caching mechanism.

We recommend you to install QEMU, VirtualBox or UTM and create ARM64 or x86-64 Linux distribution virtual machine to build Redox and follow Podman or Native Build using the Linux distribution of your choice.

If you insist on using MacOS, please read Installing without FUSE. Otherwise, you will have a problem installing FUSE which requires you to turn off SIP for Apple Silicon-based MacOS.

• 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 in .config, the file build/container.tag will be created after the image is built. This file tells make that it can skip the image update 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.

Installing without FUSE

If installing FUSE is difficult for your operating system, you can avoid installing it by adding FSTOOLS_IN_PODMAN=1 in the .config file. It makes the installer run inside Podman. If you do set it, then you can avoid installing FUSE and Rust altogether in your host system.

An additional environment variable (FSTOOLS_NO_MOUNT) can also be set to not use FUSE during image creation, however image creation relies on correct files permission bit and ownership which means it only can be used within Podman. This configuration can be used as a last resort if FUSE is not working at all.

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

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 will not work.

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:

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

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

📝 Note: This section is no longer being recommended as the primary way to do development on new recipes. Any new dependencies should be compiled in a Cookbook recipe using the host:recipe-name syntax.

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

Historically, we've used --userns keep-id which the container's root user is actually mapped to your User ID on the host system. It was necessary in Podman 3.x and previous versions as Podman user mapping was not quite good and often broke with tar and buildah. In Podman 4.x onwards that it no longer necessary and we can drop it.

For Ubuntu 22.04 there's a temporary fix to it by manually updating crun.

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.

Before reading through this section, make sure you have already read:

• Podman Build
• Native Build
• Build System Reference

Setup Your Environment

Advanced users may accomplish the same as the native_bootstrap.sh script with the following steps:

• 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

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 the native_bootstrap.sh script, you need to install at least:

• Essential compilers: GCC, Rust and Nasm
• GNU search, text, and build tools: find, grep, make, patch, pkg-config, and sed
• Other build tools: autotools, cmake, meson, perl and python3
• Other file tooling: curl, rsync, tar and wget
• Libraries to build GCC: gmp, mpfr and mpc
• Rust tooling: cbindgen and just
• FUSE (to build an image) and QEMU (to run the image)

Additional programs or libraries might be needed to build more packages. You can attempt to install the necessary packages below.

⚠️ Warning: The following commands may be outdated

📝 Note: Always use the latest stable version of the Linux or Unix-like distribution of your choice, as any outdated tools might result in unexpected build errors. Redox cross-compilation is guaranteed to work reliably only in the current Podman environment, which is Debian 13 (Trixie).

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 qemu-system-arm qemu-system-riscv

• 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 qemu-system-arm qemu-system-riscv

• 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-system-x86 qemu-system-arm qemu-system-riscv

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

GNU Guix Users

Rust nightly isn't packaged in Guix currently, so you need a FHS-enabled container to use rustup:

guix shell --pure --container --emulate-fhs --network --share=$HOME \
  coreutils bash curl grep gcc-toolchain@14.3.0 nss-certs \
  -- bash -c 'curl --proto "=https" --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain nightly'

guix shell --pure --container --emulate-fhs --network --share=$HOME \
  coreutils bash gcc-toolchain@14.3.0 nss-certs zlib glibc \
  -- bash -c 'export LD_LIBRARY_PATH=$(dirname $(gcc -print-file-name=libgcc_s.so.1)):$LD_LIBRARY_PATH && source ~/.cargo/env && cargo install cbindgen'

Then you will be able to run the actual build except for the part that uses FUSE to build the root filesystem. Modify tryredox/redox in the command below to match where your sources are:

guix shell --pure --container --emulate-fhs --network --share=$HOME \
  coreutils bash curl wget gcc-toolchain@14.3.0 pkg-config fuse nss-certs zlib \
  grep make which findutils sed gawk diffutils tar gzip perl git git-lfs \
  binutils nasm just m4 patch autoconf automake help2man texinfo xz \
  bzip2 mpfr gmp file ncurses readline flex bison python ninja cmake \
  -- bash -c '
export LD_LIBRARY_PATH="/lib64:/lib:$LD_LIBRARY_PATH"
export CI=1
source ~/.cargo/env
cd ~/tryredox/redox
make all PODMAN_BUILD=0 REPO_BINARY=1
'

The FUSE portion needs to run outside of a Guix shell container. To do that, we will patch the Rust executables so they can find libgcc_s.so.1 under /gnu/store instead of /lib :

LIBGCC_DIR=$(guix shell --container --emulate-fhs gcc-toolchain bash coreutils \
  -- bash -c 'dirname $(readlink -f /lib64/libgcc_s.so.1)')

guix shell patchelf -- patchelf --set-rpath "$LIBGCC_DIR" build/fstools/bin/redox_installer

guix shell patchelf -- patchelf --set-rpath "$LIBGCC_DIR" build/fstools/bin/redoxfs

guix shell patchelf -- patchelf --set-rpath "$LIBGCC_DIR" build/fstools/bin/redoxfs-mkfs

Finally, you can run the image building part outside of a container so that FUSE works and launch qemu:

guix shell make just nasm qemu -- make qemu PODMAN_BUILD=0

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

Please read the MacOS warning in Advanced Podman Build. We recommend you to use the Podman Build if you insist on using MacOS.

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, list the installed toolchains, then install more Rust tooling:

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

then

source ~/.cargo/env

rustup default nightly

rustup toolchain list

cargo install cbindgen just

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.

Customizing C compiler

Redox requires a GCC-compatible compiler for the operating system to build additional host tools. GCC for the host system is searched automatically from PATH environment variable with a binary named as $GNU_TARGET-gcc (e.g. x86_64-linux-gnu-gcc).

If your operating system is not Linux or if you want to use a different compiler, you can export more environment variables in the .config file:

export REDOXER_HOST_AR=ar
export REDOXER_HOST_AS=as
export REDOXER_HOST_CC=cc
export REDOXER_HOST_CXX=c++
export REDOXER_HOST_LD=ld
export REDOXER_HOST_NM=nm
export REDOXER_HOST_OBJCOPY=objcopy
export REDOXER_HOST_OBJDUMP=objdump
export REDOXER_HOST_PKG_CONFIG=pkg-config
export REDOXER_HOST_RANLIB=ranlib
export REDOXER_HOST_READELF=readelf
export REDOXER_HOST_STRIP=strip

📝 Note: FreeBSD and MacOS default compiler is Clang, so their support is experimental as also using a GCC version other than 14.x (i.e. the GCC version in Debian 13). Try to set these environment variables if you find any issues in any recipe compilation.

Prefix

In addition to build tools from the system, building Redox requires additional compilers and tools bootstrapped from your host compilers:

• GCC
• GNU Binutils
• libtool
• Rust
• Relibc

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.

Prebuilt Prefix

Redox provides a prebuilt prefix toolchain to make building fast. The prebuilt prefix is only suitable for use inside Podman requiring glibc version 2.41 or newer (as the Podman Build container is based on Debian 13) and not all CPU compiler targets are available for ARM-based Linux.

If your Linux distribution is not using glibc or its version is older than 2.41, you need to set PREFIX_BINARY=0 and build your own prefix toolchain.

Prefix: GCC

Redox compiles its own GCC, GNU Binutils and Libtool to create a cross-compilation target to Redox. The whole build takes about a half hour or less if your hardware is relatively powerful. When it's completed it generates the gcc-install directory containing these cross-compilers.

Prefix: Rust

Redox OS is listed as both Tier 2 and Tier 3 platform support on Rust. The x86_64 architecture is listed as Tier 2 target which means that Rust's libstd is available for this target.

Redox compiles its own Rust compiler to be able to build Tier 3 libstd. Fortunately, we can choose to download from rustup instead of building the Rust compiler using the environment variable: PREFIX_USE_UPSTREAM_RUST_COMPILER in mk/config.mk.

Building Rust takes about 2 hours or more (if your hardware is relatively powerful) as it's also needed to compile LLVM. If you are building for the x86_64 target, downloading Rust from rustup (the official Rust binaries) might be preferable. When it's completed it generates the rust-install directory containing both GCC and Rust compiler.

Note that there maybe some patches in Redox Rust fork that has not been upstreamed, so your experience with using Rust from rustup might be different than building it.

Prefix: Relibc

Relibc is the C standard library written for Redox. Relibc is needed for both GCC and Rust to compile programs.

Relibc is very active in development even with PREFIX_BINARY=1 it will be compiled anyway so we always have the updated libc. Fortunately, compiling it is very quick. When it's completed it generates the relibc-install directory containing GCC and Rust bundled with updated relibc.

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.

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 redox 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 i586

The build system supports building for multiple CPU architectures in the same directory tree. Building for i586 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=i586 command, in the shell environment (export ARCH=i586) 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 i586. 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 i586
• 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/i586/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/i586/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/i586-unknown-redox/relibc-install/ cookbook/recipes/gcc/{build,sysroot,stage*} build/i586/*/{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/i586/*/{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 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)

• Notes
• 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
  • Prevent and Fix Breaking Changes
  • Update Your Branch
  • Update Crates
  • Verify The Dependency Tree
• Debug Methods
  • Boot
• Kill A Frozen Redox VM
• Kernel Panic
  • QEMU
  • Real Hardware

Notes

This section contain details which apply to Redox problems on virtual machines and real hardware.

General

• If you aren't doing development and has a compilation or runtime problem be sure to verify if your build system/recipes sources and binaries are up-to-date or holding breaking changes, a build system update, single or complete recipe binary cleanup may fix your problems in most cases

Read the Debug Methods and Boot sections for more details.

Real Hardware

• Test if your boot problem happens with live mode enabled and disabled, press the L key in the boot screen resolution menu to toggle
• If possible verify if your boot problem happens in UEFI and BIOS (UEFI has BIOS emulation which is called "CSM mode" and can be enabled in the UEFI settings)
• Photos are safer and faster to send boot logs than boot log text written by hand, which is error-prone and time consuming
• Verify if your computer has enough RAM to load the whole Redox image because data streaming from USB is not supported yet, if it has 1GB or less of RAM we recommend the server, desktop-minimal or desktop image variants to avoid OOM panics
• If you have a very weak 64 bits Intel or AMD CPU (single core and L cache smaller than 1MB, like Intel Atom CPUs released before 2010) and 1GB or less of RAM we recommended the Intel/AMD 32 bits Redox images and the server, desktop-minimal or desktop variants to avoid OOM panics and have better performance

Read the Debug Methods and Boot sections for more details.

Reporting

• Use Markdown code blocks to send logs, avoiding syntax breakage on Matrix clients or GitLab
• Use the "fresh build" or "clean build" terms to easily/quickly explain that you rebuilt all build system and recipe binaries from scratch (make clean all command)
• Use the "fresh clone" or "fresh copy" terms to easily/quickly explain that you downloaded a new build system copy from Git or bootstrap scripts

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 sources, it only contains the build system.

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.

If any command ask your to choose an image repository (after the make container_clean command execution) select the first item, it will give an error and you need to run the time make all command again

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

• Ensure that all the libraries and packages required by Redox are installed by running ./podman_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 the rm -rf prefix and make prefix or make clean all (if make prefix is not enough) commands.

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

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 podman_bootstrap.sh and native_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 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 ur.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.

Prevent and Fix Breaking Changes

Sometimes build system or recipe breaking changes are merged (you need to monitor the Dev room in our chat to know if some commit or MR containing breaking changes were merged) and you need to cleanup your recipe or build system tooling binaries before the recipe or build system source updates to avoid conflicts with the new configuration.

Build System Breakage Prevention

The following methods can prevent a build system breakage after updates that change file configuration behavior.

• Wipe all recipe binaries, update build system source and rebuild the system (most common prevention)

make clean pull all

• Wipe all recipe binaries and Podman container, update build system source and rebuild the system

make clean container_clean pull all

• Wipe all recipe binaries/sources, update build system source and rebuild the system (least common prevention)

make distclean pull all

Build System Fixing

If the breaking change affect multiple recipes or any recipe can't be built, read the following instructions:

• Wipe the build system binaries and build the system (most common fix)

make clean all

Check if the compilation or runtime error continues after this command, if the error continues run the command below:

• Wipe and rebuild the filesystem tooling

make fstools_clean fstools

Check if the compilation or runtime error continues after this command, if the error continues run the command below:

• Wipe the Podman container (not common fix)

make container_clean

Check if the compilation or runtime error continues after this command, if the error continues it doesn't happen because of breaking changes on the build system.

Recipe Fixing

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 command:

• Wipe the recipe sources and binaries and rebuild

make ur.recipe-name

Check if the compilation or runtime error continues after this command, if the error continues run the following command:

• 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 command:

• 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 command:

• Wipe all statically linked recipe binaries and rebuild the system (run this command if the binaries of multiple recipes are broken)

make static_clean rebuild

Check if the compilation or runtime error continues after this command, if the error continues run the following command:

• Wipe all recipe binaries and rebuild the system (run this command if the binaries of multiple recipes are broken)

make repo_clean all

Check if the compilation or runtime error continues after this command, if the error continues run the following command:

• Wipe all recipe sources and binaries and rebuild the system (run this command if the sources and binaries of multiple recipes are broken)

make fetch_clean all

Check if the compilation or runtime error continues after this command, if the error continues read the section below.

New Build System Copy

If the methods 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

cd redox

make all

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

(If you aren't building Redox to x86_64 change x86_64 in x86_64-unknown-redox to the CPU code that you are using)

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

• Read this Wikipedia section to learn about debugging techniques

• Use the dmesg command to read the kernel and userspace daemons log

• If Orbital hangs you need to verify if the system also freezed by pressing Super+F1 to see the boot log or Super+F2 to switch to other tty, login as root and run dmesg to read the system log ("Super" is the key with Windows logo)

• You can start the QEMU with the make qemu gpu=no command to easily copy the terminal text

• You can write to the debug: scheme, which will output on the console, but you must be the root user. This is useful if you are debugging an program 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 yet

• To use GDB add the gdbserver recipe in your filesystem configuration, run the make qemu gdb=yes command in one shell, start the gdbserver program on QEMU and run the make gdb command in another shell

• Use the following command for advanced logging:

make some-command 2>&1 | tee file-name.log

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.

• REPO_DEBUG - This environment variable will build the Rust program with assertions, checking and symbols.

(Debugging with symbols inside of Redox is not supported yet)

To enable them you can use the following commands or scripts:

• Permanently enable REPO_DEBUG for all recipes by adding the following text to your .config file:

REPO_DEBUG?=1

• Enable the REPO_DEBUG environment variable for one command, rebuild/package a recipe and add to the Redox image:

REPO_DEBUG=1 make cr.recipe-name image

• Enable the REPO_DEBUG environment variable for multiple commands, rebuild/package a recipe and add to the Redox image:

export REPO_DEBUG=1

make cr.recipe-name image

• Enable the COOKBOOK_DEBUG and COOKBOOK_NOSTRIP (they are equivalent to REPO_DEBUG environment variable) 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)

GDB On QEMU

Use the following instructions to debug a recipe with GDB:

• Build or rebuild the recipe with assertions/checking/symbols and install into the Redox image:

make crp.recipe-name REPO_DEBUG=1

If you want to permanently enable debug binaries add the following environment variable to your .config file:

REPO_DEBUG?=1

• Build and install the GDB server into the Redox image

make rp.gdbserver

• Start QEMU with the GDB configuration enabled:

make qemu kvm=no QEMU_SMP=1 gdb=yes

If the recipe has one executable, run the following command:

make debug.recipe-name

If the recipe has multiple executables use the following command:

make debug.recipe-name DEBUG_BIN=executable-name

Boot

If your boot hangs and the log don't show the reason, you can use the following environment variables to help:

• BOOTSTRAP_LOG_LEVEL=value : Bootstrap and process manager logging verbosity level
• INIT_LOG_LEVEL=value : Init logging verbosity level
• DRIVER_LOG_LEVEL=value : Logging verbosity level of all drivers
• DRIVER_*_LOG_LEVEL=value : Driver-specific logging verbosity level, for example: DRIVER_PS2_LOG_LEVEL=value for PS/2 logging and DRIVER_USB_LOG_LEVEL=value for USB logging
• RELIBC_LOG_LEVEL=value : Relibc logging verbosity level, you need to disable the no_trace feature flag by removing it from the default feature group and run the make static_clean rebuild command to use it
• INIT_SKIP=executable-name : Skip the execution of executables with hangs or errors, commas are supported if you want to skip multiple executables

They accept the following values:

• ERROR value: Known event that is a fatal error but recoverable.
• WARN value: Unexpected event coming from unexpected condition.
• INFO value: Significant event mostly useful for developer.
• DEBUG value: Detailed event monitoring to show how the service is being used.
• TRACE value: Very verbose information which is only useful when debugging.

Once you determine what you need press the E key to open the boot environment editor and add in the last lines and boot, for example:

default environment variables here
INIT_LOG_LEVEL=DEBUG
DRIVER_LOG_LEVEL=DEBUG

You can see an example output below:

2026-01-12T22-27-51.758Z [@ps2d::controller:468 WARN] ps2d: post-test unexpected value: 9C
2026-01-12T22-27-51.760Z [@ps2d::controller:337 ERROR] ps2d: keyboard failed to reset: 55

To disable the environment variables after boot run the export *_LOG_LEVEL=OFF command, for example: the export RELIBC_LOG_LEVEL=OFF command will disable relibc logging.

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 memory 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 Process

This page explain what each build system command does in detail.

(Read the Build System to know the context of each command)

• Bootstrap Scripts
• Toolchain
• Build System
• Recipes
• QEMU

Bootstrap Scripts

podman_bootstrap.sh

• Install Podman, GNU Make, Rust, FUSE and QEMU if it's not installed in the host system.
• 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.

native_bootstrap.sh

• Install the Rust toolchain (using rustup.rs).
• Install the recipe build tools from your Linux or Unix-like distribution.
• 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.

Toolchain

make prefix

• Download our Rust and GCC forks from the Redox 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" command)

• Build the new relibc changes

Build System

make pull

• Update the build system source and submodules
• Checkout submodules to the latest pinned commit

make all (first execution)

• Download the binaries of the Redox toolchain from the build server (if make prefix was not executed before).
• Download the sources of the recipes specified on your filesystem configuration.
• Cross-compile recipes to Redox.
• Package recipe binaries as pkgar files.
• Install packages in the QEMU virtual disk formatted with RedoxFS.

make all (second execution and next)

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 work like the make rebuild command.

make all (Podman environment, first execution)

• Download the Redox container image.
• Install the Rust and Redox toolchains (inside the container).
• Install the recipe build tools (inside the container).
• Download the sources of the recipes specified on your filesystem configuration.
• Cross-compile recipes to Redox (inside the container).
• Package recipe binaries as pkgar files.
• Install recipe packages in the QEMU virtual disk formatted with RedoxFS.