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

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 libstd 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 from your host system to the new OS 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 (if used), program libraries or the program source code (dependency-free).
  • Some developers prefer to develop from other operating systems like Linux, MacOSX or FreeBSD, 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.

(To run interpreted programs and scripts the programming language's interpreter needs to be ported to Redox)

How can I port a program?

How can I write a driver?

How can I debug?

Does Redox support OpenGL and Vulkan?

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

What is a recipe?

  • A recipe is a software port on Redox.

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 to update relibc in all recipes or the make prefix cr.recipe-name command to update one recipe)
  • 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 (run the make clean pull all command to not cause conflicts with the previous artifacts locations, if the previous location of the build artifacts had contents you can try to fix manually or download the build system again to avoid confusion or fix hard conflicts)

How can I test my changes on real hardware?

How can I insert files to the Redox image?

  • If you use a recipe your changes will persist after the make image command, but you can also mount the Redox filesystem to insert them directly.

How can I change my Redox 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-cpu-arch environment variable on your .config file and run the make all command, read the config section for more details.

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

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

How can I use a recipe in my build system?

  • Go to your filesystem configuration and add the recipe:
nano config/your-cpu-arch/your-config.toml

[packages]
...
recipe-name = {}
...
  • Build the recipe
make r.recipe-name
  • Rebuild the Redox image to add the recipe
make image

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

  • Build the recipe, image and launch QEMU:
make r.recipe-name image qemu

How can I skip building all recipes?

  • Insert the REPO_BINARY=1 environment variable to your .config file, it will download pre-compiled recipe binaries from the build server if available.

How can I skip building all recipes except a specific recipe?

  • After inserting the REPO_BINARY=1 environment variable to your .config file, go to your Cookbook configuration and add the source-based variant of the recipe.
nano config/your-cpu-arch/your-config.toml

[packages]
...
recipe-name = "source"
...
  • Make sure to download the recipe package before rebuilding the image.
make r.recipe-name
  • Rebuild the Redox image to install the recipe package
make image

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

./native_bootstrap.sh -d

(If you are using Podman this process is automatic)

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

Porting Questions

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 Linux kernel API 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.

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?

Read the Schemes and Resources page.

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 userspace schemes?

Read the Userspace Schemes section.

How can I see all kernel schemes?

Read the Kernel Schemes section.

What is the difference between kernel and userspace schemes?

Read the Kernel vs Userspace Schemes section.

How does a userspace 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.

How the system calls are used by userspace daemons?

All userspace daemons use the system calls through relibc like any normal program.

GitLab Questions

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 build system 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 ran "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 execution, this error doesn't happen)

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

If the make clean pull all command doesn't work download a fresh build system or wait for an upstream fix.

Recipes

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

Read the Solving Compilation Problems section.

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

  • Missing dependencies
  • Environment leakage (when the recipe build system use the Linux environment instead of Redox environment)
  • Misconfigured cross-compilation
  • The recipe needs to be ported to Redox

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

Verify if your recipe.toml file 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" file 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?

Read the Kill A Frozen Redox VM section.

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.