# C VM

This is a C implementation of Collapse OS' native words. It allows Collapse OS
to run natively on any environment with a C89 compiler.

## Requirements

For "stage" and "cos-serial" binaries, the only requirement is a C89 compiler.
No function is used outside of the ANSI C standard library.

The "cos-grid" binary requires POSIX and the curses library.

However, the build process uses Make and assumes a POSIX environment. Any build
outside of a POSIX environment has to be made "by hand".

## Build

Running `make` will yield 3 executables:

cos-serial: a Collapse OS prompt running in serial mode. It's the simplest way
to run Collapse OS, but it can't run Grid applications such as the Visual
Editor. However, it can be used non-interactively, that is, you can pipe
commands to interpret to it.

cos-grid: Emulates a 80x32 grid using the "curses" library and runs Collapse OS
within it. It can run Grid applications such as the Visual Editor.

stage: special binary used to compile and spit. Instead of spitting contents
to stdout, it does so on stderr, and at the end of its run, pops the 2 last
elements of the PSP, considers it a spitting range, and dumps the contents of
its memory within that range.

To play around, you'll almost always want to run "make && ./cos-grid".

## Execution model

Executables above implement the same logic that "real" boot VM do, that is to
implement an execution model and implement the base set of native words.

Then, they load the forth binaries that serial.bin and grid.bin are and run them
through the execution model, beginning with BOOT (there is no concept of
starting at address 0 for the C VM).

Unlike in "real" VM code, native words don't contain binary code, they contain
a sequential ID. When the C VM encounters a word of type 0, it simply reads that
ID then call the corresponding function in its function array.

Therefore, serial.bin and grid.bin are platform-independant. You can take the
same binary and run it through a C VM compiled on another architecture, it's
going to run in the same way.

The C VM is always little endian.

Two forth binaries are built here, serial.bin and grid.bin. They both contain a
full Collapse OS system and differ only in the way they implement (emit): The
first one simply spits to its stdout port, the second one implements the Grid
protocol.

Because Collapse OS needs itself to build itself, serial.bin is part of the
distribution tarball and is not automatically refreshed through "make" like
grid.bin is. To refresh "serial.bin", run "make updatebootstrap".

## Problems?

If your binaries begin behaving badly (hangs, spew garbage, etc.), first try a
"make clean". If it doesn't work, you might have broken your "serial.bin". Try
re-copying it from the distribution tarball.

A modified `blkfs` can also break things (although even with a completely broken
blkfs, you should still get to prompt), you might want to run
`rm blkfs && make` to ensure that the `blkfs` file is in sync with the contents
of the blk.fs files.

If that doesn't work, there's also the nuclear option of rebuilding from a
source folder freshly extracted from the distributed archive.