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://repos.managarm.org/buildenv/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:
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.
build/bootstrap-site.ymlfile you just created, replace the
container.rootfskey with the path to your
Initialize the build directory with
cd build xbstrap init ../src
Decide which software you want to include in the image you create. There are several meta-packages available which help you decide this:
base: just enough to boot into
kmsconplus some functional commands to play with (such as
base-devel: same as
baseplus some extra development tools (such as
weston-desktop: full managarm experience with a selection of terminal and GUI software
To actually execute the build, we recommend that you install the necessary tools and packages as binaries from our build server. This can save you multiple hours of compilation, depending on your machine.
Note: this only works if you build in a container (though this is untested with Docker). Containerless builds must do a full build from source (see below).
xbstrap pull-pack --deps-of <meta-package> mlibc mlibc-headers # e.g xbstrap pull-pack --deps-of base mlibc mlibc-headers xbstrap install --deps-of <meta-package> # The following two commands fetch managarm and mlibc (plus their required tools) to enable local development: xbstrap download-tool-archive --build-deps-of managarm-system --build-deps-of managarm-kernel --build-deps-of mlibc xbstrap install --rebuild managarm-system managarm-kernel mlibc mlibc-headers
If instead you want to build everything from source, simply run
xbstrap install <group>, e.g
xbstrap install weston-desktop. Note that this can take multiple hours, depending on your machine.
After managarm's packages have been built, building a HDD image of the system is straightforward.
For all methods, the image creation and updation commands shown below require the following programs to be installed on the host:
mkfs.vfat. Refer to image_create for more details on this.
Decide what method you want to use to copy files to 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
libguestfsto be installed on the host. After installing
libguestfs, if you encounter errors while making the image it might be necessary to run the following:
sudo install -d /usr/lib/guestfs sudo update-libguestfs-appliance
Add the following to
build/bootstrap-site.yml, depending on what mount method you have chosen:
define_options: mount-using: 'loopback' # or guestfs/docker
Create the image:
xbstrap run initialize-empty-image
Copy the system onto it:
xbstrap run make-image
Launch the image using QEMU:
xbstrap run qemu # Note that you can combine the last two operations: xbstrap run make-image qemu
Alternatively, you can call the necessary scripts manually (check their help messages for more information):
../src/scripts/update-image.pyfor copying the files onto the image (the mount method can be selected with the
../src/scripts/vm-util.py qemufor launching QEMU