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?
- When I should rebuild the build system or recipes from scratch?
- 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?
- How can I change my build variant?
- How can I increase the filesystem size of my QEMU image?
- How can I change the CPU architecture of my build system?
- I only made a small change to my program. What's the quickest way to test it in QEMU?
- How can I install the packages needed by recipes without a new download of the build system?
- How can I use the packages from the CI server on my build system?
- How can I cross-compile to ARM from a x86-64 computer?
- How can I build the toolchain from source?
- Why does Redox have unsafe Rust code?
- Why does Redox have Assembly code?
- Why does Redox do cross-compilation?
- Does Redox support OpenGL and Vulkan?
- Porting Questions
- Scheme Questions
- What is a scheme?
- When does a regular program need to use a scheme?
- When would I write a program to implement a scheme?
- How do I use a scheme for sandboxing a program?
- 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
- Kernel Questions
- 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?
- I have a merge request with many commits, should I squash them after merge?
- Should I delete my branch after merge?
- How can I have an anonymous account?
- Troubleshooting Questions
- Scripts
- 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?
- When I run "make r.recipe" I get a syntax error, how can I fix that?
- When I run "cargo update" on some recipe source it call Rustup to install other Rust toolchain version, how can I fix that?
- 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?
- QEMU
- Real Hardware
General Questions
What is the correct way to update the build system?
- Read this page.
How can I verify if my build system is up-to-date?
- After the
make pull
command, run thegit 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 thetouch 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?
- Read this section.
How can I write a driver?
- Read this README.
How can I port a program?
- Read this page.
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 runmake 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 runmake 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 runmake 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 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 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?
- 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?
- Read this.
Scheme Questions
What is a scheme?
- Read this 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 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 typesyscall::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 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 thepodman_bootstrap.sh
again to download a fresh build system.
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-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 this section.
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.