From 8bb4145fe06265ba88571707444598b69ecc9006 Mon Sep 17 00:00:00 2001
From: Jeremiah Orians <jeremiah@pdp10.guru>
Date: Fri, 25 May 2018 18:37:53 -0400
Subject: [PATCH] Improving Documentation to help new programmers get
 functional

---
 HACKING   | 34 ++++++++++++++++++++++++++++++++++
 INSTALL   | 20 ++++++++++++++++++++
 README.md |  7 ++++++-
 3 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 HACKING
 create mode 100644 INSTALL

diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..1ac0e2c
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,34 @@
+-*-mode:org-*-
+
+M2-Planet being based on the goal of bootstrapping the Minimal C compiler required to support structs, arrays, inline assembly and self hosting;
+is rather small, under 1.7Kloc according to sloccount
+
+* SETUP
+The most obvious way to setup for M2-Planet development is to clone and setup mescc-tools first (https://github.com/oriansj/mescc-tools.git)
+Then be sure to install any C compiler and make clone of your choice.
+
+Should you wish to verify or leverage the M2-Moon bootstrap path;
+please make sure to setup M2-Moon (https://github.com/oriansj/M2-Moon.git)
+and then setup the knight-vm (https://github.com/oriansj/knight-vm.git)
+
+* BUILD
+The standard C based approach to building M2-Planet is simply running:
+make M2-Planet
+
+Should you wish to verify that M2-Planet was built correctly run:
+make test
+
+* ROADMAP
+The current outstanding work for M2-Planet involves porting M2-Planet into M2-Moon and extending its functionality
+
+* DEBUG
+To get a properly debuggable binary:
+make M2-Planet-gcc
+
+* Bugs
+M2-Planet assumes a very heavily restricted subset of the C language and many C
+programs will break hard when passed to M2-Planet.
+
+M2-Planet does not actually implement any primitive functionality, it is assumed
+that will be written in inline assembly by the programmer or provided by the
+programmer durring the assembly and linking stages
diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..b8bbf43
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,20 @@
+Building and Installing M2-Planet
+
+* Get it
+	git clone https://github.com/oriansj/M2-Planet.git
+
+* Prerequisites
+** Bootstrapping
+M2-Planet will be bootstrappable by M2-Moon and mescc-tools
+
+** Development
+The tools required for easier development include binutils, gcc and make; along with the above bootstrapping programs
+
+* Build it
+	make
+
+* Check it
+	make test
+
+* Install it
+	make install
diff --git a/README.md b/README.md
index 4f2615c..3c64dec 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,7 @@
 # M2-Planet
-The PLAtform NEutral Transpiler
+The PLAtform NEutral Transpiler, when combined with mescc-tools;
+allows one to compile a subset of the C language into working binaries
+with introspective steps inbetween.
+
+A lovely set of examples of M2-Planet programs are in tests but the most
+surprising part of all M2-Planet can self-host M2-Planet.