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.  If you already
have Oaklisp installed, you can just use that: in the above use

  make OAK=/usr/local/bin/oaklisp

and that's that.

If you don't have Oaklisp already installed, read on.

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 has an option
to look elsewhere.  You may need to pass this option to the compiled
emulator at build time, e.g.,

  make OAKWORLDFLAGS="--world $(pwd)/prebuilt/src/world/oakworld.bin"

or

  make OAKWORLDFLAGS="--world /usr/local/lib/oaklisp/oakworld.bin"

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.
