-*-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.

* 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
M2-Planet V1.0 is the bedrock of all future M2-Planet versions. Any future
release that will depend upon a more advanced version to be compiled, will
require the version prior to it to be named. V2.0 and the same properties apply
To all future release of M2-Planet. All minor releases are buildable by the last
major release and All major releases are buildable by the last major release.

* DEBUG
To get a properly debuggable binary: make M2-Planet-gcc
However if you are comfortable with gdb, knowing that function names are
prefixed with FUNCTION_ the M2-Planet binary is quite debuggable.

* 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

* Magic
** argument and local stack
In M2-Planet the stack is first the EDI pointer which is preserved as should an
argument be a function which returns a value, it may be overwritten and cause
issues, this is followed by the previous frame's base pointer (EBP) as it will
need to be restored upon return from the function call. This is then followed by
the arguments which are pushed onto the stack from the left to the right,
followed by the RETURN Pointer generated from the function call, after which the
locals are placed upon the stack first to last followed by any Temporary values:
       +----------------------+
EDI -> | Previous EDI pointer |
       +----------------------+
EBP -> | Previous EBP pointer |
       +----------------------+
1st -> | Argument 1           |
       +----------------------+
2nd -> | Argument 2           |
       +----------------------+
... -> ........................
       +----------------------+
Nth -> | Argument N           |
       +----------------------+
RET -> | RETURN Pointer       |
       +----------------------+
1st -> | Local 1              |
       +----------------------+
2nd -> | Local 2              |
       +----------------------+
... -> ........................
       +----------------------+
Nth -> | Local N              |
       +----------------------+
temps-> .......................