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.

How can I test my changes on real hardware?

  • Read this section.

How can I write a driver?

How can I port a program?

How can I debug?

  • Read this section.

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 this 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 this 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 this 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?

As Redox is not ready for development or daily usage yet, the programs need to be built outside of Redox and installed on the image.

The cross-compilation also reduce the portability requiirements of the program, because the build tools don't need to work on Redox, only on Linux/BSD.

Does Redox support OpenGL and Vulkan?

  • Read this 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 the dependencies of some program?

  • Read this section.

How can I configure the build system of the recipe?

  • Read this category.

How can I search for functions on relibc?

  • Read this section.

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?

  • Read this section.

How can I see all kernel schemes?

  • Read this section.

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

  • Read this section.

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

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

  • Verify if you have the GNU Bash shell installed on your system.

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 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 bootstrap.sh again to download a fresh build system or install Pop OS!, Ubuntu or Debian.

Recipes

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

  • Read this section.

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

QEMU

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

  • Read this section.

Real Hardware

I got a kernel panic, what can I do?

Read this section.

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

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