Skip to content

Menix Docs

Compiling Bootstrap

This repository builds a fully bootable distribution for the Menix kernel.

It also includes several ports of popular apps and tools.

Prerequisites

Section titled “Prerequisites”

To build the distribution you will need the following tools installed on your system:

  • A POSIX-compatible shell
  • GNU make
  • curl

To create a bootable image you will additionally need:

  • dosfstools (for mkfs.vfat)
  • e2fsprogs (for mkfs.ext2)
  • parted (for partitioning the image)

To run the built image you will also need QEMU for the target architecture.

Build instructions

Section titled “Build instructions”

The easiest way to get a bootable image is to run

Terminal window
$ make

in the root of the repository. This will build a small subset of the distribution and create a bootable ISO named menix.iso in the build directory.

You can also build separate packages by running ../jinx build <package> inside the respective build directory for the target architecture.

For example, to build the menix package for the x86_64 architecture, you would run the following commands (assuming you are in the root of the repository):

Terminal window
$ cd build-x86_64     # Switch to the x86_64 build directory
$ ../jinx build menix # Build the menix package

The built package will be located in the pkgs directory.

If you want a build of the ENTIRE distribution, you will need a lot of free disk space (>20GB) and patience.

Running the ISO/image

Section titled “Running the ISO/image”

To run the ISO/image in qemu, you can use the provided make targets:

Terminal window
$ make qemu     # For menix.img
$ make qemu-iso # For menix.iso

This will run the image using QEMU with the appropriate options for the target architecture. If you want to pass your own QEMU flags, you can do so by setting the QEMUFLAGS variable, e.g.:

Terminal window
$ make qemu QEMUFLAGS="-m 512M -smp 4"

Debugging

Section titled “Debugging”

To debug Menix, build a normal image, but make sure to also build the package menix-debug. The binary is unstripped and contains debuginfo.

Run QEMU with:

Terminal window
$ make qemu QEMUFLAGS="-s -S" KVM=0

and then attach your debugger. For convenicence, there is a debugging configuration using CodeLLDB for VS Code. Simply select Run > Start Debugging and use .vscode/launch.json as the config.

Finally, start the menix-debug kernel in the bootloader and make sure KASLR has been disabled or you have provided the debugger with the base address.