Developer FAQ

The website FAQ have questions and answers of newcomers and end-users, while this FAQ will cover organization, technical questions and answers of developers and testers, feel free to suggest new questions.

(If all else fails, join us on Chat)

General Questions

What is the correct way to update the build system?

How can I verify if my build system is up-to-date?

  • After the make pull command, run the git rev-parse HEAD command on the build system folders to see if they match the latest commit hash on GitLab.

When I should rebuild the build system or recipes from scratch?

Sometimes run the make pull rebuild command is not enough to update the build system and recipes because of breaking changes, learn what to do on the following changes:

  • New relibc functions and fixes (run the make prefix clean all command after the touch relibc command)
  • Dependency changes on recipes (run the make cr.recipe-name command)
  • Configuration changes on recipes (run the make cr.recipe-name command)
  • Source code changes on recipes (run the make ucr.recipe-name command)
  • Changes on the location of the build system artifacts (if the previous location of the build artifacts had contents, you need to download the build system again to avoid confusion or conflicts)

How can I test my changes on real hardware?

How can I write a driver?

How can I port a program?

How can I debug?

How can I insert files to the QEMU image?

  • If you use a recipe your changes will persist after a make image but you can also mount the Redox filesystem.

How can I change my build variant?

  • Insert the CONFIG_NAME?=your-config-name environment variable to your .config file, read the config section for more details.

How can I increase the filesystem size of my QEMU image?

  • Change the filesystem_size field of your build configuration (config/ARCH/your-config.toml) and run make image, read the Filesystem Size section for more details.

How can I change the CPU architecture of my build system?

  • Insert the ARCH?=your-arch-code environment variable on your .config file and run make all, read the config section for more details.

I only made a small change to my program. What's the quickest way to test it in QEMU?

  • If you already added the program recipe to your Cookbook configuration file, run:
make r.recipe-name image qemu

How can I install the packages needed by recipes without a new download of the build system?

  • Download the bootstrap.sh script and run:
./bootstrap.sh -d

How can I use the packages from the CI server on my build system?

  • Go to your Cookbook configuration and add the binary variant of the recipe.
nano config/your-cpu-arch/your-config.toml

[packages]
...
recipe-name = "binary"
...
  • Run make rebuild to download/install the package.

How can I cross-compile to ARM from a x86-64 computer?

  • Insert the ARCH?=aarch64 environment variable on your .config file and run make all.

How can I build the toolchain from source?

  • Disable the PREFIX_BINARY environment variable inside of your .config file.
nano .config

PREFIX_BINARY?=0
  • Wipe the old toolchain binaries and build a new one.
rm -rf prefix

make prefix
  • Wipe the old recipe binaries and build again with the new toolchain.
make clean all

Why does Redox have unsafe Rust code?

It is an important goal for Redox to minimize the amount of unsafe Rust code.

In some cases we must use unsafe, for example at certain points in the kernel and drivers, these unsafe parts are generally wrapped with a safe interface.

These are the cases where unsafe Rust is mandatory:

  • Implementing a foreign function interface (FFI) (for example the relibc API)
  • Working with system calls directly (You should use Rust std:: library or relibc instead)
  • Creating or managing processes and threads
  • Working with memory mapping and stack allocation
  • Working with hardware devices

If you want to use unsafe Rust code on Redox anywhere other than interfacing with system calls, ask for Jeremy Soller's approval before.

Why does Redox have Assembly code?

Assembly is the core of low-level because it's a CPU-specific language and deal with things that aren't possible or feasible to do in high-level languages like Rust.

Sometimes required or preferred for accessing hardware, or for carefully optimized hot spots.

Reasons to use Assembly instead of Rust:

  • Deal with low-level things (those that can't be handled by Rust)
  • Writing constant time algorithms for cryptography
  • Optimizations

Places where Assembly is used:

  • kernel - Interrupt and system call entry routines, context switching, special CPU instructions and registers.
  • drivers - Port IO need special instructions (x86_64).
  • relibc - Some parts of the C runtime.

Why does Redox do cross-compilation?

Read some of the reasons below:

  • When developing a new operating system you can't build programs inside of it because the system interfaces are premature. Thus you build the programs on your host system and transfer the binaries to the filesystem of the new OS
  • Cross-compilation reduces the porting requirements because you don't need to support the compiler of the program's programming language, the program's build system and build tools. You just need to port the programming language standard library, program libraries or the program source code (dependency-free)
  • Some developers prefer to develop from other operating systems like Linux or MacOSX, the same applies for Linux where some developers write code on MacOSX and test their kernel builds in a virtual machine (mostly QEMU) or real hardware

(Interpreted programs and scripts require the programming language interpreter to work on Redox)

Does Redox support OpenGL and Vulkan?

  • Read the GPUs section.

Porting Questions

What is a recipe?

  • A recipe is a software port on Redox, it does cross-compilation by default if you use Cookbook templates.

How to determine if some program is portable to Redox?

  • The source code of the program must be available
  • The program should use cross-platform libraries (if not, more porting effort is required)
  • The program's build system should support cross-compilation (if not, more porting effort is required)
  • The program shouldn't directly use the APIs from the Linux kernel on its code (if not, more porting effort is required)
  • The program shoudn't use X11 or Wayland directly on its code (if not, more porting effort is required)

Some APIs of the Linux kernel can be ported, while others not because they require a complete Linux kernel (thus the drivers and filesystems code require reverse-engineering to be ported to Redox).

How to determine the dependencies of some program?

How can I configure the build system of the recipe?

How can I search for functions on relibc?

Which are the upstream requirements to accept my recipe?

Scheme Questions

What is a scheme?

When does a regular program need to use a scheme?

  • Most schemes are used internally by the system or by relibc, you don't need to access them directly. One exception is the pseudoterminal for your command window, which is accessed using the value of $TTY, which might have a value of e.g. "pty:18". Some low-level graphics programming might require you to access your display, which might have a value of e.g. "display:3".

When would I write a program to implement a scheme?

  • If you are implementing a service daemon or a device driver, you will need to implement a scheme.

How do I use a scheme for sandboxing a program?

  • The contain program provides a partial implementation of sandboxing using schemes and namespaces.

How can I see all user-space schemes?

How can I see all kernel schemes?

What is the difference between kernel and user-space schemes?

User-Space Questions

How does a user-space daemon provide file-like services?

  • When a regular program calls open, read, write, etc. on a file-like resource, the kernel translates that to a message of type syscall::data::Packet, describing the file operation, and makes it available for reading on the appropriate daemon's scheme file descriptor. See the Providing A Scheme section for more information.

Kernel Questions

Which CPU architectures the kernel support?

  • i686 with limitations
  • x86_64
  • ARM64 with limitations

How the system calls are used by user-space daemons?

  • All user-space daemons use the system calls through relibc like any normal program.

GitLab Questions

I have a project/program with breaking changes but my merge request was not accepted, can I maintain the project in a separated repository on the Redox GitLab?

  • Yes.

I have a merge request with many commits, should I squash them after merge?

  • Yes.

Should I delete my branch after merge?

  • Yes.

How can I have an anonymous account?

  • During the account creation process you should add a fake name on the "First Name" and "Last Name" fields and change it later after your account approval (single name field is supported).

Troubleshooting Questions

Scripts

I can't download the bootstrap scripts, how can I fix this?

  • Verify if you have curl installed or download the script from your web browser.

I tried to run the "podman_bootstrap.sh" and "native_bootstrap.sh" scripts but got an error, how to fix this?

  • Verify if you have the GNU Bash shell installed on your system.
  • Verify if Podman is supported on your operating system.
  • Verify if your operating system is supported on the native_bootstrap.sh script

Build System

I called "make all" but it show a "rustup can't be found" message, how can I fix this?

  • Run this command:
source ~/.cargo/env

(If you installed Rustup before the first podman_bootstrap.sh run, this error doesn't happen)

I tried all troubleshooting methods but my build system is still broken, how can I fix that?

  • If make clean pull all doesn't work, run the podman_bootstrap.sh again to download a fresh build system.

Recipes

I had a compilation error with a recipe, how can I fix that?

I tried all methods of the "Troubleshooting the Build" page and my recipe doesn't build, what can I do?

  • It happens because your system has an environment problem or missing packages, remove the recipe from your build configuration file to workaround this.

All recipes follow this syntax recipe = {} below the [packages] section, the configuration files is placed at config/your-cpu-arch.

When I run "make r.recipe" I get a syntax error, how can I fix that?

  • Verify if your recipe.toml has some typo.

When I run "cargo update" on some recipe source it call Rustup to install other Rust toolchain version, how can I fix that?

It happens because Cargo is not using the Redox fork of the Rust compiler, to fix that run make env from the Redox build system root.

It will import the Redox Makefile environment variables to your active shell (it already does that when you run other make commands from the Redox build system root).

I added the dependency of my program on the "recipe.toml" but the program build system doesn't detect it, then I installed the program dependency on my Linux distribution and it detected, why?

Read the Environment Leakage section.

QEMU

How can I kill the QEMU process if Redox freezes or get a kernel panic?

Real Hardware

I got a kernel panic, what can I do?

Read the Kernel Panic section.

Some driver is not working with my hardware, what can I do?

Read the Debug Methods section and ask us for instructions in the Matrix chat.