Firmament is a multi-scale execution engine for cluster computing under
development at the University of Cambridge Computer Laboratory.

It is currently in early alpha stage, with much of the high-level functionality
still missing, and interfaces frequently changing.


SYSTEM REQUIREMENTS
-------------------

Firmament is currently known to work on Ubuntu 10.10 (maverick), 11.10 (oneric),
12.10 (quantal) and 13.04 (raring); with caveats (see below) on 12.04 (precise)
and 13.10 (saucy); it does NOT work without extra actions on 10.04 and 11.04.

UPDATE 03/2014: Ubuntu versions prior to 12.10 no longer work as they cannot
build libpion, which is now included as a self-built dependency in order to
ease transition to libpion v5 and for compatibility with Arch Linux. Below
information is included for historical reference.

Other configurations are untested - YMMV. Recent Debian versions typically work
with a bit of fiddling.

Reasons for known breakage:
* Ubuntu 10.04 - packaged clang/LLVM version too old (requires Clang >=2.9).
* Ubuntu 11.04 - broken dependency on /usr/include/linux/errno.h;
                 see http://pad.lv/774215 for a possible workaround
* Ubuntu 12.04 - when using Boost v1.48, the HTTP interface does not compile
                 due to libpion-net relying on a deprecated (and removed) Boost
                 feature. As a workaround, disable -D__HTTP_UI__ in
                 include/Makefile.config.unix
* Ubuntu 13.04 - segfault failures when using Boost 1.53 packages; use 1.49
                 (default).
* Ubuntu 13.10 - clang/LLVM include paths need to be fixed.
                 /usr/{lib,include}/clang/3.2 should be symlinked to
                 /usr/lib/llvm-3.2/lib/clang/3.2.

BUILDING & RUNNING
--------------------

$ make all

will fetch dependencies are necessary, and may ask you to install required
packages.

$ make test

will run unit tests.

Other targets can be listed by running

$ make help

Binaries are in the build/ subdirectory of the project root, and all accept the
--helpshort argument to show their command line options.

Start by running a coordinator:

$ build/engine/coordinator --platform PL_UNIX --listen_uri tcp://<host>:<port>

Once the coordinator is up and running, you can access its HTTP interface at
http://<host>:8080/ (the port can be customized using --http_ui_port argument).

To submit a toy job, first make the examples target and then use the script in
scripts/job/job_submit.py. Note that jobs are currently submitted to the web UI
port, and NOT the internal listen port!

$ make examples
$ cd scripts/job/
$ python job_submit.py <host> <webUI port (8080)> <binary>

Example for the last line:

$ python job_submit.py localhost 8080 /home/me/build/examples/hello_world

(Note that you may need to run 'make' in the script directory since the script
depends on some protocol buffer data structures that need to be compiled. If
you have run 'make all', all script dependencies should automatically have been
built, though.)

If this all works, you should see the job print "Hello world" in the
coordinator's console.