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 via pip3, as well as the y4 DSL:
```
pip3 install xbstrap y4
```
The git, subversion and mercurial 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 a build 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 named bootstrap-site.yml with the following contents:
```
auto_pull: true

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 and build_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 the container.rootfs key with the path to your rootfs.
If you want this build directory to be used for building for an architecture other than the default (x86_64), you can define the arch and arch-triple options. For instance, if you want to build for riscv64:
```
define_options:
  arch: riscv64
  arch-triple: riscv64-managarm
```
Note: Every build directory only builds for the one architecture specified by the options. If you want to build managarm for multiple architectures, set up a build directory for each architecture desired.

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 into kmscon plus some functional commands to play with (such as less and grep)
- base-devel: same as base plus some extra development tools (such as gcc and binutils)
- weston-desktop: full managarm experience with a selection of terminal and GUI software
You can install these meta-packages by doing:
```
xbstrap install weston-desktop
```
This command will download binary packages from our build servers.
In order to rebuild parts of the system locally (e.g., after making changes to the source code), use the --rebuild flag:
```
xbstrap install --rebuild managarm-system managarm-kernel mlibc mlibc-headers
```

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:
1. 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).
2. 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.
3. 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 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. 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/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

Managarm Handbook