Compiling Asterix programs
==========================
Asterix has a very basic, primitive way of compiling and linking source
code into an executable binary.

The Unix "cat" program is used to concatenate all source code files and
any run-time support code used by it. Then, the resulting stream of
source code is fed into the main compiler binary, "asterix", to produce
a stream of intermediate code.

The intermediate code is text-based and can be viewed and inspected.
To generate machine code, feed it to the assembler, "asterix-asm".

The machine code then just needs an ELF header so that it can be run on
Linux. The "elfwrap" program can be used to add this header; it simply
copies its input, prepends a small ELF header (its own, in fact),
adjusts the header's file size and memory size fields, and sends the
result back out.

The operating system's standard input, standard output, and piping
facilities can be used to connect these steps:

    cat program.ax compile.ax errline.ax error.ax num.ax rwx.ax str.ax \
        table.ax | ./asterix | ./asterix-asm | ./elfwrap > program
    chmod +x program

The "program" file then contains the resulting binary. The "compile.ax"
and other files contain run-time support code that the program can use.
Below is a brief description of these files.

The Makefile for Asterix contains a rule to automate these build steps;
the above command would be run after typing "make program", assuming
that there's a file called "program.ax" in the same directory. However,
this does not work if the program itself consists of multiple source
files.

The "asterix", "asterix-asm", and "elfwrap" programs all use static
buffers to hold their input and output. When compiling larger programs,
it may happen that these buffers fill up and compilation will fail. In
such cases, the buffer sizes will have to be increased. In most cases it
should be enough to adjust the size in the declarations of "in" and
"out" in the "main" functions of "asterix.ax", "asterix-asm.ax", and/or
"elfwrap.ax" and recompiling them.

Run-time support code
---------------------
The following files are usually linked into Asterix programs:

    File            Description
    ----------      ---------------------------------------------------
    compile.ax      Functions called by match/output items
    errline.ax      Error handling for programs with line-based input
    error.ax        Error handling functions
    num.ax          Conversion of numbers to and from ASCII
    rwx.ax          Wrappers for the read, write, and exit syscalls
    str.ax          Just a strlen function (not used by Asterix itself)
    table.ax        A very primitive key-value table implementation