civicaml/bin/README

Overview
========

There are three binaries in the toolchain:

- The compiler "civcc", which compiles CiviC source code to assembly source

- The assembler "civas", which compiles assembly source to an object file that
  can be run by the VM.

- The virtual machine "civvm", which runs one or more object files, one of
  which should export a "main" function.

Additionally, there is a run script "civrun" which takes one file name argument
and runs it through the entire pipeline, deleting intermediate files
afterwards. E.g. for the first assignment you may want to run:
$ bin/civrun euclid.cvc
Please enter an integer value: 60
Please enter an integer value: 45
15

Or even:
$ echo 60 45 | bin/civrun euclid.cvc 2>&1
15

The toolchain also contains the file "civic.h" which defines the CiviC standard
library supported by the VM. It is practical to keep this in the same directory
as the reference compiler binary, because the compiler adds the folder in which
it resides in to the include directories of the C preprocessor (along with the
current working directory).

You may want to add the toolchain directory to your $PATH so you can run the
tools without having to prefix "<...>/bin/" every time when using the
toolchain. E.g. add to your ~/.bashrc:
export PATH=$PATH:<directory_where_you_unpacked_the_toolchain>/bin

Reference compiler usage
========================

You can use the output of the reference compiler "civcc" as benchmark for your
own compiler. Apart from the extensions in the language reference, it
implements constant propagation/folding on compiler-generated variables, and
also does rudimentary loop unrolling. You are not expected to reproduce this,
these phases are just there to show you how even simple optimizations can have
a significant effect on code size.

Some other remarks about the compiler:

- Optimizations can be disabled with the -noopt flag.

- By default it reads CiviC code from stdin, and prints assembly to stdout, so
  you can use it with unix pipes.

- The "-v 2" verbosity option makes it print the AST after each phase, showing
  you step-by-step transformations. This can be very useful when you are
  confused about what a milestone should do. You can compile simple example
  file and see how the reference compiler transforms it in the different phase.
  Use -noopt as well if you want to get something closer to what your own
  compiler should do (since you don't need to implement optimizations).

- the "-upto ..." argument makes the compiler stop after a certain phase and
  print the AST (or assembly) at that point. E.g. when you are implementing
  context analysis and want to compare your output to that of the refrence
  compiler, use "-upto context" or "-upto context -v 2".

- The generated assembly code contains comments that shows to which CiviC code
  it corresponds. This can be used for relating instructions to AST nodes
  during debugging, and we recommend you do the same in your own compiler
  (although it is not required). Note that the last optimization phase
  (peephpole optimization) strips these comments, so you will need to pass "-v
  2" or -noopt to actually see them. You can also disable them completely by
  passing "-v 0".