This guide shows how to build a managarm distribution from source utilising the bootstrap-managarm patches and build scripts.
To make sure that all build environments work properly, it is recommended to setup a build environment with our lightweight containerized build runtime cbuildrt (see below for instructions). It is also possible to build with Docker (see here), or by installing the dependencies manually (see here), but these methods are no longer recommended.
Make sure that you have at least 20 - 30 GiB of free disk space.
- Create a directory which will be used for storing the
source and build directories. Here we use
~/managarm, but it can be any directory.
mkdir ~/managarm && cd ~/managarm
- Install the
xbstrapbuild system via
pip3 install xbstrap
mercurialtools are required on the host (whether you build in a container or not). Install these via your package manager.
- Clone this repository into a
srcdirectory and create a
git clone https://github.com/managarm/bootstrap-managarm.git src mkdir build
Download and install the latest
cbuildrtrelease by running:
xbstrap prereqs cbuildrt xbps
Note: If you choose to build
cbuildrtfrom source, make sure to place the resulting binary either in
Download and unpack the latest Managarm
curl https://mirrors.managarm.org/cbuildrt/rootfs/managarm-buildenv.tar.gz -o managarm-rootfs.tar.gz tar xvf managarm-rootfs.tar.gz
builddirectory, create a file named
bootstrap-site.ymlwith the following contents (replace the
container.rootfskey as appropriate):
pkg_management: format: xbps container: runtime: cbuildrt rootfs: /path/to/your/rootfs uid: 1000 gid: 1000 src_mount: /var/lib/managarm-buildenv/src build_mount: /var/lib/managarm-buildenv/build allow_containerless: true
Note: you must keep the
build_mountvalues as shown above if you want to be able to use pre-built tools from our build server. These paths refer to locations on the container, not on your host machine. Also note that these paths cannot be changed after starting the build; doing so will likely result in a broken directory tree.
Initialize the build directory with
cd build xbstrap init ../src
There are several meta-packages available which control what software is built, this means that the build can be started using one of the following commands:
If you want the full managarm experience with a selection of terminal and gui software available to try out use
xbstrap install weston-desktop
If you want to boot into
kmsconand have some functional commands to play around with use
xbstrap install base
If you want some development tools in addition to the functionality of
xbstrap install base-devel
If you only want to build the bare minimum to boot into
xbstrap install --all
Note that this command can take multiple hours, depending on your machine.
Note: if using a Docker container the following command are meant to be ran outside the Docker container, in the
builddirectory on the host. Adding to the aforementioned commands, one would
exitfrom the container once the build finishes, enter the
builddirectory, and proceed as follows.
After managarm's packages have been built, building a HDD image of the system is straightforward. The image_create.sh script can be used to create an empty HDD image.
image_create.sh script and mark it executable:
wget 'https://raw.githubusercontent.com/qookei/image_create/master/image_create.sh' chmod +x image_create.sh
This repository contains an
update-image.py script to mount the image and copy the system onto it.
This script can use 3 different methods to copy files onto the image:
- Using libguestfs (the default method). We recommend this when root access is not possible or desirable. However, it is much slower than method 2 and requires some setup on the host (see below).
- Using a classic loopback and mount (requires root privileges). We recommend this when root access is acceptable because it is the fastest method and most guaranteed to work.
- Via Docker container (only works with the Docker build method). This is handy in case the user is in the
dockergroup since it does not require additional root authentication. We discourage this because it uses
docker run --privileged(which is not safer than giving root access) and currently has some bugs.
Going with method 1 will require
libguestfs to be installed on the host.
libguestfs it might be necessary to run the following:
sudo install -d /usr/lib/guestfs sudo update-libguestfs-appliance
If you're using xbstrap to invoke the script, selecting the desired method can be done by adding the following to the
define_options: mount-using: 'loopback' # or guestfs/docker
When invoking the script directly, selecting the method can be done with the
For all methods, the
make-image invocations shown below require the following programs to be installed:
mkfs.vfat. Refer to image_create for more details on this.
Hence, running the following commands in the build directory should produce a working image and launch it using QEMU:
# Create a HDD image file called 'image'. # Check "./image_create.sh -h" for more options. ./image_create.sh -o image -s 4GiB -t ext2 -p gpt -l limine -be # Copy the system onto it. xbstrap run make-image # Launch the image using QEMU. xbstrap run qemu # Or as a one-liner: xbstrap run make-image qemu # Alternatively, you can call the necessary scripts manually: # Check their help messages for more information. ../src/managarm/tools/gen-initrd.py ../src/scripts/update-image.py ../src/scripts/vm-util.py qemu