Overview

This guide will describe how to retrieve the code, how to get it running in a virtual environment, and how to develop. So, this isn't so much a "User's Guide" now as a "Developer's Guide". This guide currently assumes you're working on a linux (though it'll probably work with BSD, too).

Tools Required

  1. subversion (revision control software)
  2. VirtualBox (virtual machine software)
  3. Standard GNU Development Tools (gcc, gnu make, gnu ld, etc)
  4. nasm (an assembler)

Retrieving the Code

The code must be retrieved from the sourceforge code repository for this project. Generally, it should be safe to retrieve the trunk, as this should always be a working branch. Alternatively, you can retrieve the latest milesone.

svn must be used to retrieve the code. I will assume that you want to check the code out to a directory (which you've already created) called projects/the-k-os in your home directory:

[me@mine ~]$ mkdir -p ~/projects/the-k-os [me@mine ~]$ cd ~/projects/the-k-os [me@mine the-k-os]$ svn co https://the-k-os.svn.sourceforge.net/svnroot/the-k-os/trunk A trunk/i386-obj A trunk/tests A trunk/tests/test_kmalloc.c A trunk/tests/test_kterm.c A trunk/tests/test_strntolower.c A trunk/tests/test_cprintf.c A trunk/tests/test_kterm_readline.c A trunk/tests/Makefile A trunk/vm A trunk/vm/ext2.flp [ ... etc ... ] Checked out revision 134. [me@mine the-k-os]$ cd trunk

Compiling the Code

Ensure that gcc, ld, make and nasm are in your path. From the root of whichever directory you just checked out (e.g., trunk), call make:

[me@mine trunk]$ make /usr/bin/nasm -f elf -o i386-obj/start.o src/start.asm cc -fno-builtin -nostdinc -Wall -I./include -I./include/stdlib -c -o i386-obj/math.o src/math.c cc -fno-builtin -nostdinc -Wall -I./include -I./include/stdlib -c -o i386-obj/vga.o src/video/vga.c cc -fno-builtin -nostdinc -Wall -I./include -I./include/stdlib -c -o i386-obj/kmain.o src/kmain.c cc -fno-builtin -nostdinc -Wall -I./include -I./include/stdlib -c -o i386-obj/idt.o src/platform/ia-32/idt.c /usr/bin/nasm -f elf -o i386-obj/gdt.o src/platform/ia-32/gdt.asm /usr/bin/nasm -f elf -o i386-obj/irq_handlers.o src/platform/ia-32/irq_handlers.asm /usr/bin/nasm -f elf -o i386-obj/isr_handlers.o src/platform/ia-32/isr_handlers.asm [ ... etc ... ] ld -T link/kmain.ld -o i386-obj/kernel.bin i386-obj/start.o i386-obj/kmain.o i386-obj/math.o i386-obj/vga.o i 386-obj/idt.o i386-obj/gdt.o i386-obj/irq_handlers.o i386-obj/isr_handlers.o i386-obj/isrs.o i386-obj/irq.o i 386-obj/asm.o i386-obj/keyboard.o kosh/kosh.o i386-obj/kterm.o i386-obj/multiboot.o src/stdlib/cprintf.o i386 -obj/cpu.o i386-obj/cpuid.o i386-obj/pic.o -L./src/stdlib -lstd -L./kosh -lkoshlib [me@mine trunk]$

Building the Virtual Disk

Assuming there were no errors in compilation, the next step is to write the compiled kernel onto a virtual floppy that can subsequently be mounted by VirtualBox. In the bin directory, there are sample mkdiskimage scripts. For linux, copy bin/mkimgdisk.example to bin/mkimgdisk and ensure that it is executable. Then, run it:

[me@mine trunk]$ bin/mkimgdisk

It's a silly script with low intellegence. It really must be run from the directory above bin/ since it uses internal relative paths. The script will use sudo so you must be able to escalate any command to root via sudo (on many distributions, this means you must be in the admin group). If you cannot make that work, you can manually execute the lines in the script (minus the sudo lead-in) as root. Basically, the script will attach a vm image (in the vm/ directory) to a loopback device. It will then mount the device under mnt/. It will copy the kernel image (i386-obj/kernel.bin if compilation was successful) to the root of this device. Finally, it unmounts the device.

Virtual Environment

The floppy must be booted on a virtual machine. I use Sun's VirtualBox, which is available for multiple platforms. If you are using Linux, it may be available as a package through your distribution's package manager. These instructions are for VirtualBox (using the QT frontend), but other virtual machine packages should be roughly similar. It's really just a matter of getting the floppy to boot.

First, the media must be configured. After launching VirtualBox, select File >> Virtual Media Manager. Select the Floppy Images tab. Click the Add button. Navigate to the trunk/vm directory, and select ext2.img.

Next, the virtual machine must be created. Select Machine >> New. In the resulting wizard, read the text and click Next. For the VM name, you may put anything, but I generally choose something like the-k-os. For OS Type / Operating System I select Other and for Version I select Other/Unknown. I then click Next.

The amount of memory you devote will depend greatly on your environment, but soon, there will probably be paged memory and the page size will probably be 4 MB. So, it's a good idea to set this something significantly larger than 4 MB (as little as 64 MB will probably be OK, but 128 or 256 might be a better number). Set the memory allocation and click Next.

For "Virtual Hard Disk" unselect the Boot Hard Disk option, then click Next. It'll probably gripe with a pop-up. Just click Continue. On the "Summary" screen, click Finish.

The VM must now be told to boot from the virtual floppy that is being managed by VirtualBox. Select your newly created VM, and Machine >> Settings. Select Floppy in the left nav, then click the option Mount Floppy Drive. Select the Image File option, then the ext2.img media. Click OK.

Finally, the virtual machine must be launched. Select the created VM, then Machine >> Start.

KoSH

If all goes well, you should get a KoSH shell prompt. Here, you can type help to get a list of commands. When you're done, exit will exit from KoSH and effectively halt the OS. At this point, close the window from your host OS, and select Power off the Machine.