Skip to content

Latest commit

 

History

History
75 lines (57 loc) · 3.47 KB

BUILD.md

File metadata and controls

75 lines (57 loc) · 3.47 KB
Raw

Building running and debugging gopher-os

The project Makefile contains targets for building either the kernel image or a bootable ISO while running on Linux or OSX.

Building on Linux

To compile gopher-os wheh running on Linux you need a fairly recent version of:

  • binutils (>= 2.26.0)
  • xorriso
  • grub
  • nasm
  • gcc (for GNU ld)
  • go 1.7+

The above dependencies can be installed using the appropriate package manager for each particular Linux distribution.

Building on OSX

To properly link the kernel object files so that the bootloader can pick up the multi-boot signature we need to be able to control the linker configuration. For the time being this is only possible when using GNU ld (lld is a potential alternative but doesn't yet fully support linker scripts).

You can still build the kernel using vagrant. For this purpose, a Vagrantfile is provided so all you need to do is just install vagrant on your machine and run vagrant up before running any of the following make commands.

Supported Makefile build targets

The project Makefile will work on both Linux and OSX (using vagrant) targets. When running under OSX, the Makefile will ensure that all build-related commands actually run inside the vagrant box. The following build targets are supported:

  • kernel: compile the code into an elf binary.
  • iso: compile the code and build a bootable ISO using grub as the bootloader.

Booting the gopher-os ISO file

Once the kernel ISO is successfully built, either qemu or virtualbox can be used to boot it. The Makefile provides handy targets for doing this:

  • make run-qemu
  • make run-vbox

Supported kernel command line options

To apply any of the following command line arguments there are two options:

  1. patch grub.cfg before building the kernel image and append the required command line arguments at the end of the lines starting with multiboot2
  2. alternatively, you can boot the ISO, wait for the grub menu to appear and press e. This will bring up an editor where you can modify the command line before booting the kernel.

The following command line options are currently supported:

Command Description
consoleFont=$fontName use a particular font name (e.g terminus10x18). This option is only used by console drivers supporting bitmap fonts. The set of built-in fonts is located here. If this option is not specified, the console driver will pick the best font size for the console resolution
consoleLogo=off disable the console logo. This option is only valid for console drivers that support logos.

Debugging the kernel

If you wish to debug the kernel, you need to install gdb. Unfortunately the gdb version that ships with most Linux distributions (and also the one that can be installed with brew on OSX) has a bug which prevents gdb from properly handling CPU switches from 32-bit protected to 64-bit long mode. This causes problems when trying to debug the kernel while it is running on qemu. The solution to this problem is to manually compile and install a patched gdb version which is available here.

The Makefile provides a gdb target which compiles the kernel, builds the ISO file, launches qemu and attaches an interactive gdb session to it.