doc: add a basic README

1 files changed, 69 insertions, 0 deletions

diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..c418cd8
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,69 @@
+TeachOS Kernel
+==============
+
+The TeachOS kernel for the core of the operating system.
+It is implemented in assembly and C++, where the amount of assembly is kept to a minimum.
+The primary design goal of the kernel is to be teachable and useful as part of the operating systems lecture track at OST.
+Therefore, subsystems might not be implemented in a runtime performance optimal way but rather to be understandable and clear.
+
+Development
+-----------
+
+Development happens primarily on Linux.
+Other platforms (e.g. Windows, macOS) may allow building of the kernel as well, however at the time of this writing they are not officially supported.
+To manage the toolchain and dependencies of the kernel, conan is used as a package manager.
+
+Required Tools
+~~~~~~~~~~~~~~
+
+In orer to build the kernel, the following tools are required:
+
+- Python 3 to run conan
+- A C and C++ toolchain to build the kernel toolchain
+- GRUB2 to build the bootable ISO image
+
+Setup
+~~~~~
+
+Create an activate a Python virtual environment, for example by using the ``venv`` module:
+
+.. code-block:: bash
+
+    $ python -m venv .venv
+    $ source .venv/bin/activate
+
+With the virtual environment activated, install the required Python package from the ``requirements.txt`` file:
+
+.. code-block:: bash
+
+    $ pip install -r requirements.txt
+
+Next, prepare the default conan profile and install the required packages (note: the example below assumes x86_64 is being targeted as the kernel's platform):
+
+.. code-block:: bash
+
+    $ conan profile new --detect default
+    $ conan install -if .conan/install -pr:b default -pr:h .conan/profiles/x86_64-gcc -b missing 
+
+The second command may need to be rerun in case the conan dependencies change.
+
+Building
+~~~~~~~~
+
+With the setup performed, the kernel can now be built:
+
+.. code-block:: bash
+
+    $ conan build -if .conan/install .
+
+Developing in an IDE
+~~~~~~~~~~~~~~~~~~~~
+
+This repository includes a configuration for Visual Studio Code.
+In order to work on the kernel from within Visual Studio Code, activation of the conan build environment is required:
+
+.. code-block:: bash
+
+    $ source build/generators/conanbuild.sh
+
+Afterward the IDE can be started from the same shell and will automatically pick up the required environment variables.