Troubleshooting the Build
In case you need to do some troubleshooting of the build process, this is a brief overview of the Redox toolchain, with some troubleshooting tips. This chapter is a work in progress.
When you run
podman_bootstrap.sh, the Linux tools and libraries required to support the toolchain and build process are installed. Then the
redox project is cloned from the Redox GitLab. The
redox project does not contain the Redox sources, it mainly contains the build system. The
cookbook subproject, which contains recipes for all the packages to be included in Redox, is also copied as part of the clone.
Not all Linux distributions are supported by
bootstrap.sh, so if you are on an unsupported distribution, try
podman_bootstrap.sh for Podman builds, or have a look at podman_bootstrap.sh and try to complete the setup up manually.
If you want to support your distribution/OS without Podman, you can try to install the Debian/Ubuntu package equivalents for your distribution/OS from your package manager/software store, you can see them on this section of
bootstrap.sh script and
redox-base-containerfile covers the build system packages needed by the recipes on demo.toml
(Note that some distributions/OSes may have environment problems hard to fix, on these systems Podman will avoid some headaches)
If you did not use
podman_bootstrap.sh to set up your environment, you can get the sources with
git clone https://gitlab.redox-os.org/redox-os/redox.git --origin upstream --recursive
If you are missing the
cookbook project or other components, ensure that you used the
--recursive flag when doing
git clone. Ensure that all the libraries and packages required by Redox are installed by running
bootstrap.sh -d or, if you will be using the Podman build,
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 processor architecture, config name, and whether to use Podman during the build process. Read through Configuration Settings to make sure you have the settings that are best for you.
The Redox toolchain, referred to as Prefix because it is prefixed with the architecture name, is downloaded and/or built. Custom versions of
gcc and many other tools are created. They are placed in the
If you have a problem with the toolchain, try
rm -rf prefix, and everything will be reinstalled the next time you run
If enabled, the Podman environment is set up. Podman is recommended for distros other than Pop!_OS/Ubuntu/Debian.
If your build appears to be missing libraries, have a look at Debugging your Podman Build Process.
If your Podman environment becomes broken, you can use
podman system reset and
rm -rf build/podman. In some cases, you may need to do
sudo rm -rf build/podman.
If you have others problems with Podman, read the Troubleshooting Podman chapter.
The list of Redox packages to be built is read from the filesystem config file, which is specified in .config or
mk/config.mk. If your package is not being included in the build, check that you have set
FILESYSTEM_CONFIG, then check the config file.
Each recipe source is downloaded using
tar, according to the
[source] section of
cookbook/recipes/RECIPE/recipe.toml (where RECIPE is the name of the recipe). Source is placed in
cookbook/recipes/RECIPE/source. Some packages use the older
If you are doing work on a package, you may want to comment out the
[source] section of the recipe. To discard your changes to the source for a package, or to update to the latest version, uncomment the
[source] section of the recipe, and use
rm -rf source target in the
PACKAGE directory to remove both the source and any compiled code.
After all recipes are fetched, a tag file is created as
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.
Each recipe is built according to the
recipe.toml file. The compiled recipe is placed in the
target directory, in a subdirectory named based on the processor architecture. These tasks are done by various Redox-specific shell scripts and commands, including
Cargo. These commands make assumptions about $PATH and $PWD, so they might not work if you are using them outside the build process.
If you have a problem with a package you are building, try
rm -rf target in the
RECIPE directory. A common problem when building on non-Debian systems is that certain packages will fail to build due to missing libraries. Try using Podman Build.
After all packages 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 packages into it. This is done outside of Podman, even if you are using Podman Build.
On some Linux systems, FUSE may not be permitted for some users, or
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
- Check your Rust version (run
cargo --version, then
exit), make sure you have the latest version of Rust nightly!
- Check your Rust version (run
- rustup.rs is recommended for managing Rust versions. If you already have it, run
make clean pullto remove all your compiled binaries and update the sources.
- Check if your
nasmare up to date
- Check if your
- Sometimes there are merge requests that briefly break the build, so check on chat if anyone else is experiencing your problems.
An outdated relibc copy can contain bugs (already fixed on recent versions) or outdated crates, to fix this, run:
make pull cd relibc cargo update cd .. touch relibc make prefix make rebuild
In some cases the
Cargo.lock of some Rust program can have a version of some crate that don't have Redox patches (old) or broken Redox support (changes on code that make the target OS fail), this will give you an error during the recipe compilation.
The reason of fixed crate versions is explained here.
To fix this, update the crates of your recipe after the first compilation of the recipe and compile it again.
- Go to the
sourcefolder of your recipe and run
cargo update, example:
cd cookbook/recipes/recipe-name/source cargo update make c.recipe-name make r.recipe-name ## Kernel Panics in QEMU If you receive a kernel panic in QEMU, capture a screenshot and send to us on [Matrix](./ch13-01-chat.md) or create an issue on [GitLab](https://gitlab.redox-os.org/redox-os/kernel/-/issues). Run `pkill qemu-system` to kill the frozen QEMU process.