colonel/README

===============
*** Colonel ***
===============
Colonel (pronounced as it is spelt) is a kernel project I'm working on in my
free time. As a personal project, you really shouldn't run it anywhere but in
an emulator. Currently the project supports the following architectures:

 - x86
  - i386
  - i686

# Compiling
-----------
In order to compile this project you will require the following:

 - GCC Cross-Compiler (https://gcc.gnu.org/)
 - GNU Binutils (https://www.gnu.org/software/binutils/)
 - CMake (https://cmake.org/)

You may want to compile GCC and Binutils from source for your target
architecture. You can find the available toolchains for building in the
`toolchains/' directory. To compile you can run the following commands:

  cd build/
  cmake -DCMAKE_TOOLCHAIN_FILE=../toolchains/<toolchain_file> ..
  make

This should create a release build of the project. If you would like debug
flags then add the `-DCMAKE_BUILD_TYPE=debug' option to the `cmake' command.

# Testing
---------
The safest environment to test this in would be an emulator. The one I use is
QEMU (https://www.qemu.org/). You can run the kernel directly (i.e.
`colonel.bin') by using the `-kernel' option. If you'd like to debug the kernel
using QEMU and GDB you can do so by running `qemu -S -s -kernel colonel.bin',
which will open a server on `localhost' allowing you to connect with GDB for
debugging. At this point you can connect to the server and load the symbols by
running the following in the GDB prompt:

  (gdb) target remote localhost:1234
  (gdb) symbol-file colonel.bin

From this point on you can use GDB to debug the kernel.

# License
---------
This project is licensed under the terms and conditions of the GNU General
Public License version 3 or greater (look at `LICENSE' file for more
information).