From be7ec7c825dc02b8872d5f87cc78cb17fde02d8e Mon Sep 17 00:00:00 2001
From: Alex Auvolat <alex.auvolat@ens.fr>
Date: Sun, 15 Feb 2015 22:23:19 +0100
Subject: Complete README

---
 README.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 90 insertions(+), 1 deletion(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 77d7332..91337d9 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,92 @@
+# kogata operating system project
+
 kogata operating system : small and <del>beautiful</del>small.
 
-No explanation (sorry, maybe later).
+## Project characteristics
+
+### Written in C
+
+I have considered using higher-level languages but for lack of understanding of
+the associated compiler, I never have had the same impression of understanding
+exactly what was happening that I had with C. Also, the necessity of a runtime
+is bothering. I do regret not being able to exploit the magic of strongly typed
+functionnal languages, but what can I do...
+
+### Monolithic design
+
+I would have liked to do a microkernel, but the necessity for asynchronous
+communication makes it much more difficult to code, and contradicts the goal of
+having simple and straightforward code.
+
+### Emphasis on code quality and reliability
+
+The code for the project must make sense, be simple and straightforward, and be
+easily understandable in complete detail so that we can track bugs and extend
+the system more easily.
+
+### Goal : small and cool
+
+I would love to have kogata fit on a 1.44MB floppy and run with a full GUI and
+some cool apps (remember the QNX demo floppy!). Also, I want to be able to use
+it on older computers and prove that such machines can still be put to use.
+
+### Plans for the future
+
+* Module system for extending the kernel
+* In userspace, simple Scheme-like scripting language
+* The obvious stuff ;-)
+
+## How to build
+
+### Requirements
+
+* git for accessing the repository
+* `i586-elf` cross-compiler built by [these scripts](http://adnab.me/cgit/cross-scripts.git/about/).
+* nasm
+* for testing, either qemu or bochs
+
+### Building and running
+
+To build, clone the repo somewhere and simply run:
+
+    $ make
+
+Launching qemu is also included in the makefile:
+
+	$ make run_qemu
+
+Warning: dependencies between portions of code are not necessarily well handled
+by the makefile system. If you made changes and the OS fails miserably, try
+doing a `make rebuild` before blaming your code.
+
+### Runing the tests
+
+The directory `src/tests/` contains a few tests for some of the core
+components. The running of these tests is automated. To run the test suite,
+simply invoke the corresponding make target (everything is rebuilt before
+running the tests):
+
+	$ make run_tests
+
+## Structure of the project
+
+### Modules
+
+* The kernel
+* Libraries
+  * `libkogata` : basic system functionnality (memory allocator, mutexes, debugging)
+  * `libc` : implementation of a (very restricted) subset of the standard C library, basically just
+    the functions that were needed somewhere
+  * `libalgo` : usefull data structures (hashtables, AVL trees, maybee more in the future)
+* Userspace : not much work done yet
+
+### Files in the repository
+
+    doc/                  documentation (none yet, sorry!)
+	src/
+	src/kernel/           code for the kogata kernel
+	src/common/           code shared between kernel and userspace libs
+	src/lib/              code for userspace libraries
+	src/apps/             userspace binaries
+	src/tests/            test suite
+
-- 
cgit v1.2.3