Bootstrapping Asterix
=====================

Overview
--------
Asterix was not written in C or any other mainstream language, but is
instead bootstrapped through a series of custom predecessor languages
and compilers that were created before it.

The chain looks like this, starting from the top:

    Compiler            Repository
    --------            ----------
       hex  (*) }
      lhex      }   ---    cmeta
      cmeta     }
        |
       cm2      }
       cm3      }
       bm1      }   ---    mcss
       bm2      }
       am1      }
        |
      prox1     }
      prox2     }   ---    prox
        |
     asterix    }   ---   asterix

(*) Note: the cmeta repository contains the initial 213-byte hex-to-
binary converter, "hex", as a binary in the repository. If you don't
want to use it, remove it first before running make. In that case, it
will be built by "hex.sh" from the file "hex.hex" using your shell.
Or, you could build your own hex-to-binary converter, or use a different
method to convert "hex.hex" to a binary, and put that in its place.

Each of these compilers is built by (and therefore requires) the one
before it. Most of them are metacompilers, which can build themselves --
once they have been bootstrapped, of course.

Most also produce different intermediate code and have their own
specific assemblers to translate that into native machine code.

Finally, to produce executable binaries, they use a program called
"elfwrap" to prepend an ELF header to the code. Most of them use the
initial elfwrap from the cmeta repository. Prox1 and prox2 use a version
of elfwrap written in prox1, but initially require cmeta's elfwrap for
bootstrapping. Prox1 elfwrap is used in the Asterix bootstrap, but after
that, Asterix also builds and uses its own version of elfwrap.

These predecessor languages are not as thoroughly documented as Asterix
is, but this document will at least show how to use them to bootstrap
Asterix.

The bootstrap procedure will reference a couple of Git repository URLs,
which will not remain valid forever. But as long as they are, it should
be possible to follow the procedure without having to manually find and
prepare all the prerequisites that are specific to Asterix. There are
a few more generic prerequisites, though.

Prerequisites
-------------
* 64-bit Linux kernel running on the amd64 (a.k.a. x86_64) architecture
* A shell (commandline interpreter)
* A few common Unix utilities: cat, chmod

These "soft" prerequisites are less important, but bootstrapping may be
more difficult without them:

* Git
* Make
* Any text editor
* More Unix utilities such as: cmp, cp, diff, ls, mv, rm, sed
* (For checksumming) sha256sum; commandline openssl can do RIPEMD160

You don't really need any of these for the build, but they could be
useful in solving issues if you encounter any.

Bootstrapping procedure
-----------------------
1.  Go one directory level up from the Asterix repository and clone the
    cmeta, mcss, and prox repositories (or otherwise obtain copies of
    them), putting them side-by-side together with Asterix:

    cd ..
    git clone https://pimgooss.home.xs4all.nl/src/cmeta/.git cmeta
    git clone https://pimgooss.home.xs4all.nl/src/mcss/.git mcss
    git clone https://pimgooss.home.xs4all.nl/src/prox/.git prox

                                <src>
                                  |
                     /-------+----+----+-------\
                     |       |         |       |
                  asterix  cmeta      mcss   prox

2.  Go back into the Asterix directory:

    cd asterix

3a. To build using make, run:

    make prereq all

    The "prereq" target builds prox (including a recursive "make prereq"
    on prox), while the "all" (default) target builds Asterix itself.

3b. Alternatively, to build without using make, run:

    ./make.sh

    You can call make.sh with the "-h" or "--help" option to get some
    more information and a list of other (non-default) targets it can
    build.

4.  (Optional) Run "make test" to recompile using the bootstrapped binary
    and compare it against itself

Verification
------------
The resulting binaries should have the following sizes and checksums:

Binary       Size (in bytes)
-----------  ---------------
asterix      30783
asterix-asm  22676
elfwrap      4954

Binary       SHA256 checksum
-----------  ----------------------------------------------------------------
asterix      783deba8266bc16ddb0c51ca56c6586803793653638fdebb73504850988e50a3
asterix-asm  9420d80d82df2a0ec6d97360617feb36d3a916087fc9842a7e8cb06e7bdd4b69
elfwrap      ed91f4a95926922465215ec91fa050821fa740957f7e9974de766398969ac5be

Binary       RIPEMD160 checksum
-----------  ----------------------------------------
asterix      ed8d34197cf1926d470e8e219c0ab0bc2d22d56f
asterix-asm  cc43de9641558be14b668c0587a17443ff19b67b
elfwrap      5c0a544273ff2b5295117833a87761c6c98edc82