From 5b1487c877f67a2b0d4dadc6e387169fe819b2f0 Mon Sep 17 00:00:00 2001 From: Sam Tebbs Date: Sat, 7 Sep 2019 23:38:12 +0100 Subject: [PATCH] Improve readme --- README.md | 46 ++++++++++++++++++++++++++++++++++++++-------- hello.jpg | Bin 0 -> 15113 bytes 2 files changed, 38 insertions(+), 8 deletions(-) create mode 100644 hello.jpg diff --git a/README.md b/README.md index af62a18..1a5ce71 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,57 @@ [![Build Status](https://dev.azure.com/samueltebbs/pluto/_apis/build/status/SamTebbs33.pluto?branchName=develop)](https://dev.azure.com/samueltebbs/samueltebbs/_build/latest?definitionId=1&branchName=develop) +Pluto is a kernel written almost entirely in [Zig](https://github.com/ziglang/zig) and supports x86, with aarch64 and x64 backends being planned. + +![Hello image](hello.jpg) + +## Goals +* **Should be written in Zig as much as possible**. Assembly should only be used where required for functionality or performance reasons. +* **Light and performant**. The kernel should be usable both on embedded and desktop class CPUs, made possible by it being lightweight and modular. +* **Basic utilities will be written in Zig**. This includes a basic text editor and shell, and will be part of the filsystem external to the kernel itself. +* **Easy to port**. The kernel is oblivous to the underlying architecture, meaning that ports only need to implement the defined interface and they should work without a hitch. + +All of these goals will benefit from the features of Zig. + ## Build -Requires *xorriso* and the grub tools (such as *grub-mkrescue*). +Requires a master build of Zig ([downloaded](https://ziglang.org/download) or [built from source](https://github.com/ziglang/zig#building-from-source)) *xorriso* and the grub tools (such as *grub-mkrescue*). A gdb binary compatible with your chosen target is required to run the kernel (e.g. *qemu-system-i386*). ``` -mkdir -p bin/kernel -mkdir -p bin/iso/boot/grub zig build ``` -Note that the `mkdir` invocations are only needed once. See `zig build --help` for a list of options. - ## Run ``` zig build run ``` -To debug the kernel: + +## Debug +Launch a gdb instance and connect to qemu. ``` -zig build run -Ddebug=true zig build debug ``` -# Test +## Test +Run the unitests or runtime tests. ``` zig build test ``` + +## Options +* `-Ddebug=`: Boolean (default `false`). + * **build**: Build with debug info included or stripped (see #70 for planned changes). + * **run**: Wait for a gdb connection before executing. +* `-Drt-test=`: Boolean (default `false`). + * **build**: Build with runtime testing enabled. Makes the kernel bigger and slower but tests important functionality. + * **test**: Run the runtime testing script instead of the unittests. Checks for the expected log statements and fails if any are missing. + +## Contribution +We welcome all contributions, be it bug reports, feature suggestions or pull requests. We follow the style mandated by zig fmt so make sure you've run `zig fmt` on your code before submitting it. + +We also like to order a file's members (public after non-public): +1. imports +2. type definitions +3. constants +4. variables +5. inline functions +6. functions +7. entry point/init function diff --git a/hello.jpg b/hello.jpg new file mode 100644 index 0000000000000000000000000000000000000000..be1ab5f5d855800534df2012bc8d4dad7bee9f1b GIT binary patch literal 15113 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