The build process fetches files from the Redox Gitlab server. From time to time, errors may occur which may result in you being asked to provide a username and password during the build process. If this happens, first check for typos in the
git URL. If that doesn't solve the problem and you don't have a Redox GitLab login, try again later, and if it continues to happen, you can let us know through chat.
This build process for the current release (0.8.0) is for Pop!_OS/Ubuntu/Debian. The recommended build environment for other distros is our Podman Build. Please follow those instructions instead. There is partial support for non-Debian distros in
bootstrap.sh, but it is not maintained.
If you're on a supported Linux distro, you can just run the bootstrap script, which does the build preparation for you. First, ensure that you have the program
(This command is for Pop!_OS, Ubuntu or Debian, adjust for your system)
which curl || sudo apt-get install curl
Then run the following commands:
mkdir -p ~/tryredox
curl -sf https://gitlab.redox-os.org/redox-os/redox/raw/master/bootstrap.sh -o bootstrap.sh
time bash -e bootstrap.sh
You will be asked to confirm various installations. Answer in the affirmative (y or 1 as appropriate). The above does the following:
- installs the program
curlif it is not already installed
- creates a parent folder called
tryredox. Within that folder, it will create another folder called
redoxwhere all the sources will reside.
- installs the pre-requisite packages using your operating system's package manager(Pop!_OS/Ubuntu/Debian
dnf, Arch Linux
- clones the Redox code from GitLab and checks out a redox-team tagged version of the different subprojects intended for the community to test and submit success/bug reports for.
curl -sf operates silently, so if there are errors, you may get an empty or incorrect version of bootstrap.sh. Check for typos in the command and try again. If you continue to have problems, join the chat and let us know.
Please be patient, this can take 5 minutes to an hour depending on the hardware and network you're running it on. Once it completes, update your path in the current shell with:
The build system uses several configuration files, which contain settings that you may wish to change. These are detailed in Configuration Files. By default, the system builds for an
x86_64 architecture, using the
desktop configuration (
config/x86_64/desktop.toml). Set the desired
CONFIG_FILE in .config. There is also a shell script build.sh that will allow you to choose the architecture and filesystem contents easily, although it is only a temporary change.
Now we have:
- fetched the sources
- tweaked the settings to our liking
- possibly added our very own source/binary package to the filesystem
We are ready to build the entire Redox Operating System Image. Skip ahead to build.sh if you want to build for a different architecture or with different filesystem contents.
To build all the components, and the packages to be included in the filesystem.
time make all
This will make the target
build/x86_64/desktop/hardrive.img, which you can run with an emulator.
Give it a while. Redox is big. This will do the following:
- fetch some sources for the core tools from the Redox source servers, then build them. As it progressively cooks each package, it fetches the package's sources and builds it.
- create a few empty files holding different parts of the final image filesystem.
- using the newly built core tools, build the non-core packages into one of those filesystem parts.
- fill the remaining filesystem parts appropriately with stuff built by the core tools to help boot Redox.
- merge the different filesystem parts into a final Redox Operating System image ready-to-run in an emulator.
Note that the filesystem parts are merged using the FUSE. Bootstrap.sh installs
libfuse. If you have problems with the final assembly of Redox, check that
libfuse is installed and you are able to use it.
build.sh is a shell script that allows you to easily specify the architecture you are building for, and the filesystem contents. When you are doing Redox development, you should set them in
.config (see Configuration Settings). But if you are just trying things out, use
build.sh to run
make for you. e.g.:
./build.sh -a i686 -c server live- Run
i686architecture, using the
config/i686/server.toml. The resulting image is
build/i686/server/livedisk.iso, which can be used for installation from a USB.
./build.sh -f config/aarch64/desktop.toml qemu- Run
arm64/AArch64architecture, using the
config/aarch64/desktop.toml. The resulting image is
build/aarch64/desktop/harddrive.img, which is then run in the emulator QEMU.
If you use
build.sh, it's recommended that you do so consistently, as
make will not be aware of which version of the system you previously built with
build.sh. Details of
build.sh and other settings are described in Configuration Settings.
You can immediately run your image
build/x86_64/desktop/harddrive.img in an emulator with the following command:
Note that if you built the system using
build.sh to change architecture or filesystem contents, you should also use it to run the emulator.
./build.sh -a i686 -c server qemu
build/i686/server/harddrive.img (if it does not exist) and run it in the QEMU emulator.
To run the emulation with no GUI, use:
make qemu vga=no
If you want to capture the terminal output, use:
make qemu vga=no
Running with no GUI is the recommended method of capturing console and debug output from the system or from your text-only program. The
script command creates a new shell, capturing all input and output from the text console to the log file with the given name. Remember to type
exit after the emulation terminates, in order to properly flush the output to the log file and terminate
If you have problems running the emulation, you can try
make qemu kvm=no or
make qemu iommu=no to turn off various virtualization features. These can also be used as arguments to
Expose Redox to other computers within a LAN. Configure Qemu with a "TAP" which will allow other computers to test Redox client/server/networking capabilities.
Join the Redox chat if this is something you are interested in pursuing.
For a livedisk or installable image, use:
time make live
This will make the target
build/x86_64/desktop/livedisk.iso, which can be copied to a USB drive or CD for booting or installation. See Creating a bootable USB drive or CD for instructions on creating a USB drive and booting from it.
If you intend on contributing to Redox or its subprojects, please read Creating a Proper Pull Request so you understand our use of forks and set up your repository appropriately. You can use
./bootstrap.sh -d in the
redox folder to install the prerequisite packages if you have already done a
git clone of the sources.