Build instructions for Oaklisp
==============================

The build system uses autotools (autoconf/automake) so a simple build
would be:

  autoreconf --install    (to install the autotools support files)
  ./configure             (to configure the system)
  make                    (to compile everything)
  make install            (to install everything)

For further details read INSTALL generated by running autoreconf.

Bootstrapping
=============

The only unusual aspect here is that Oaklisp is written in Oaklisp,
i.e., is self-hosting.  This causes a bootstrap issue.

There are only two files required to actually run Oaklisp:

 oaklisp		the executable / emulator / virtual machine
 oakworld.bin		pre-built oaklisp (read in by the executable)

The file oakworld.bin contains the pre-built, pre-compiled Oaklisp
system: the parts that are written in Oaklisp itself.  This means you
need an existing oakworld.bin in order to run "oaklisp" in order to
build a new oakworld.bin.  Oaklisp *cannot* run without an existing
oakworld.bin file.  You can however build the executable "oaklisp"
(which is written in C) without a working Oaklisp.  So all you really
need is oakworld.bin.  The executable "oaklisp" will look for
oakworld.bin at a compile-time-specified location, but can be
instructed to look elsewhere.

The ./configure script will look for oakworld.bin in a few places, and
use it in the build.  If it cannot find oakworld.bin automatically,
you can give an explicit location

  ./configure --with-world=/complete/path/to/oakworld.bin

See ./configure --help for details of these options.

Alternative Bootstrapping Interfaces
====================================

There are other ways to pass this information to the compiled emulator
at build time, e.g.,

  make OAKWORLD=$(pwd)/prebuilt/src/world/oakworld.bin

or

  make OAKWORLD=/usr/local/lib/oaklisp/oakworld.bin

If you already have Oaklisp installed, you can just use that:

  make OAK=/usr/local/bin/oaklisp

CPU Architecture Issues
=======================

Oaklisp is sensitive to the endianness of the CPU
<http://en.wikipedia.org/wiki/Endianness>.  The oakworld.bin included
in the git branch containing a prebuilt world, or available for
download as a separate file, is for a little-indian architecture.  x86
and x86-64 processors are little-endian.  Oaklisp can be made to cross
build an oakworld.bin for a different-endian architecture.

The executable "oaklisp" currently only works in 32-bit mode.  It can
be built as a 32-bit executable on 64-bit machines, assuming that
32-bit development libraries are available.  (These are available on
most systems, sometimes as an optional package.  E.g., on Debian or
debian-derived distributions like Ubuntu, the correct package is
gcc-multilib.)  Compiling with GCC on an x86_64 aka amd64 architecture
machine one should use the -m32 which builds an i386 architecture
executable.  This should be added by default by the build system.  For
the adventurous -mx32, which uses the x86_64 instruction set with
32-bit pointers, also works provided that x32 kernel support is
enabled and the x32 development files are available.
