oriansj--M2-Planet/docs/M2-Planet.1

.\"Made with Love
.TH M2-Planet 1 "JULY 2019" Linux "User Manuals"
.SH NAME

M2-Planet \- The PLAtform NEutral Transpiler (Or just terrible C compiler)

.SH SYNOPSIS
.na

M2-Planet --architecture ARCHITECTURE --file FILE [--output FILE] [--debug]

.SH DESCRIPTION

M2 is the most minimal C compiler that can be bootstrapped from Hex
.br
At it's core is the minimal subset of the C language required
to make a more powerful C compiler. (with a few extras for convience)

.br
Those core primitives being: if (with continue), while (with
break), asm, structs (with -> support) gotos (with labels) and return.

With do and for loops, arrays, function pointers and simple macro support
as nice extras
.br
The supported ARCHITECTURES are as follows: knight-native,
knight-posix, x86, amd64, armv7l, aarch64 and riscv64.

Unofficially all tested armv7l binaries have also worked on armv6l
hosts that have thus far been tested but no promise of compatibility
until someone is willing to put in the work.

(with planned ports to z80 and 6502)
If you fail to specify an architecture, the default of knight-native
will be used.

The option --bootstrap-mode exists purely for testing C code for cc_*
compatibility

.br

The minimal libc required to work with M2-Planet generated output is
literally only a half-dozen lines of assembly and to simplify use
M2libc (https://github.com/oriansj/M2libc.git) was created with the
goal of providing commonly desired C library functionality.

with architecture specific elf-headers and functions in the
directories matching the architecture name.

.br

.SH EXAMPLES

Typically, M2-Planet will be called in scripts used in bootstrapping

.br
# M2-Planet --architecture x86 -f return.c -o return.M1
.br

Then to convert the assembled output into a working binary,
M1 and hex2 are used to convert the assembly output of M2-Planet;
with blood-elf generating dwarf stubs if additional debug info is
desired.
.br

# M1 -f M2libc/x86/x86_defs.M1 -f M2libc/x86/libc-full.M1 \
-f return.M1 --little-endian --architecture x86 -o return.hex2


# hex2 -f M2libc/x86/ELF-x86.hex2 -f return.hex2 --little-endian \
--architecture x86 --base-address 0x8048000 -o example
.br

.SH COMPATIBILITY

M2-Planet is compatible with all Turing complete machines;
even the ones that try to be Turing complete -1

.SH AUTHORS
Jeremiah Orians <Jeremiah@pdp10.guru>
.br
Jan (janneke) Nieuwenhuizen <janneke@gnu.org>
.br
deesix <deesix@tuta.io>
.br
Sanne Wouda <sanne.wouda@gmail.com>

.SH COPYRIGHT
Copyright 2016-2021 Jeremiah Orians <Jeremiah@pdp10.guru>
.br
Copyright 2017 Jan Nieuwenhuizen <janneke@gnu.org>
.br
Copyright 2020-2021 deesix <deesix@tuta.io>
.br
Copyright 2020-2021 Sanne Wouda <sanne.wouda@gmail.com>
.br
License GPLv3+.

.SH "SEE ALSO"
M1(1), hex2(1), blood-elf(1), kaem(1), syscalls(2)