Public | Automated Build

Last pushed: 13 days ago
Short Description
Tools required to build MonkOS.
Full Description


MonkOS is an experimental 64-bit operating system for Intel and AMD
processors. It is a mix of C and assembly language and is a work in progress.
Currently, it consists of a BIOS boot loader, a virtual console system, an
interrupt handling system, a paged memory manager, a heap allocator, a few
simple device drivers, and a primitive interactive shell. The boot loader is
designed to launch the operating system from a cdrom.


The OS currently builds under linux using a cross-compiler. There are two
ways to build it: (1) by installing all the necessary tools on your system and
running make, or (2) by using a ready-made docker container that contains
all the build tools you'll need.

Building with local tools

To build with tools installed on your local system, you'll need to have
the following software already installed:

  • gcc x86_64 cross-compiler for elf binaries (I have used versions 4.8, 5.3,
    6.3 and 7.1 successfully)
  • gnu binutils (I used version 2.26)
  • nasm assembler
  • genisoimage
  • exuberant-ctags (optional, for help with editing)
  • gdb (optional, for debugging)
  • qemu (optional, for testing)
  • doxygen (optional)

Most of these tools are available from standard linux package managers. The
cross-compiler, however, is not. To build a cross-compiler, consult the
instructions on this page. Make
sure to also follow the libgcc without
instructions. Note
that the red-zone instructions are a bit out of date; if you are using a more
recent version of gcc (such as 5.3 or greater), you'll need to modify the
gcc/config.gcc file (not gcc/

Once you've installed all the tools and made sure the cross-compiler is in
your path, run make.

$ make

This results in a bootable cdrom ISO file called monk.iso in your build

Building with docker-ized tools

Because it can be a bit of a pain to build and install a cross-compiler, a
docker container has been prepared, allowing you to avoid building the cross-compiler
yourself. To run the docker-based build, make sure you have a recent
version of docker installed on your system, add yourself to your system's
docker user group, and then type the following:

$ make docker

This will pull down the docker container
if you don't already have it, run the build inside the container, and generate
the iso file (and all other intermediate output files) in your build
subdirectory. It behaves almost exactly as if you ran make using a cross-
compiler installed locally on your system.

Running MonkOS

There are several ways to run MonkOS once you have the iso file. The first and
most time-consuming way is to burn it to a CD or DVD ROM using your favorite
burning utility. This is the only way to test MonkOS on a bare-metal system.

Alternatively, you can launch the operating system using virtual machine
software like VMware or virtualbox.

Or you can run the operating system in a linux-based emulator like qemu or
bochs. The MonkOS makefile makes this alternative particularly easy by
providing a simple build rule to launch the OS in qemu:

$ make test

You can also use the makefile to start a kernel debugging session under qemu
and gdb. First, launch qemu in debugging mode:

$ make debug

Then start a gdb debugger session by attaching gdb to the qemu debugger

$ gdb
(gdb) set arch i386:x86-64
(gdb) symbol-file build/monk.sys
(gdb) target remote localhost:8864
(gdb) layout src

Other build options

Run make docs to build nicely formatted documentation for MonkOS. You'll
need doxygen installed on your system to do this.

$ make docs

The doxygen documents will appear in the docs/monk subdirectory. To view
them, launch them in your browser (in this case firefox):

$ firefox docs/monk/index.html

To build code tags for easy symbol searching within your editor, use the
makefile to run the exuberant-tags utility:

$ make tags

This produces a .tags file in your MonkOS directory.

To clean up all intermediate files, use the clean build:

$ make clean

To clean all generated dependencies files, use the cleandeps build:

$ make cleandeps


Please consult the
Doxygen-formatted documentation,
which is part of the MonkOS documentation set.


These are some of the resources I have relied on in my attempt to better
understand the numerous and various aspects of bootloader and OS development:


Use of this source code is governed by a BSD-style license that can be found
in the LICENSE file.

Docker Pull Command
Source Repository

Comments (0)