From 63e9f40d47fe9a0ca4ace446e462049f835c3821 Mon Sep 17 00:00:00 2001 From: Achilleas Anagnostopoulos Date: Tue, 8 Aug 2017 22:58:14 +0100 Subject: [PATCH] Add build guide --- BUILD.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 BUILD.md diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 0000000..f14c788 --- /dev/null +++ b/BUILD.md @@ -0,0 +1,75 @@ +## 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.6+; recommended: 1.8) + +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](https://lld.llvm.org/) +is a potential alternative but doesn't yet fully support linker scripts). + +You can still build the kernel using [vagrant](https://www.vagrantup.com/). 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 elf32 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](http://www.qemu-project.org/) or +[virtualbox](https://www.virtualbox.org/) 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](src/arch/x86_64/script/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](src/gopheros/device/video/console/font). 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](https://github.com/phil-opp/binutils-gdb). + +The Makefile provides a `gdb` target which compiles the kernel, builds the ISO +file, launches qemu and attaches an interactive gdb session to it.