Building Managarm
This guide shows how to build a managarm distribution from source utilising the bootstrap-managarm patches and build scripts.
Building a managarm distribution from source
Build environment
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.
Preparations
- 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
xbstrap
build system viapip3
:pip3 install xbstrap
- The
git
,subversion
andmercurial
tools are required on the host (whether you build in a container or not). Install these via your package manager. - Clone this repository into a
src
directory and create abuild
directory:git clone https://github.com/managarm/bootstrap-managarm.git src mkdir build
Creating a cbuildrt
environment
-
Download and install the latest
cbuildrt
release by running:xbstrap prereqs cbuildrt xbps
Note: If you choose to build
cbuildrt
from source, make sure to place the resulting binary either in$PATH
or in~/.xbstrap/bin
. -
Download and unpack the latest Managarm
rootfs
somewhere:curl https://repos.managarm.org/buildenv/managarm-buildenv.tar.gz -o managarm-rootfs.tar.gz tar xvf managarm-rootfs.tar.gz
-
Inside the
build
directory, create a file namedbootstrap-site.yml
with 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
src_mount
andbuild_mount
values 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. -
In the
build/bootstrap-site.yml
file you just created, replace thecontainer.rootfs
key with the path to yourrootfs
.
Building
-
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 intokmscon
plus some functional commands to play with (such asless
andgrep
)base-devel
: same asbase
plus some extra development tools (such asgcc
andbinutils
)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.gxbstrap install weston-desktop
. Note that this can take multiple hours, depending on your machine.
Creating Images
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:
rsync
, losetup
, sfdisk
, mkfs.ext2
, 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
docker
group since it does not require additional root authentication. We discourage this because it usesdocker 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. After installinglibguestfs
, 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/managarm/tools/gen-initrd.py
and../src/scripts/update-image.py
for copying the files onto the image (the mount method can be selected with the--mount-using
argument)../src/scripts/vm-util.py qemu
for launching QEMU