
   __ o  o __
   \_\|__|/_/
     \(o  o)      Giraffe Library Installation
      |\ _|
 \    |\`-' /\
  \___|/|_ /  \
   \  |\|  \  /
    \_______\/


 ******************************************************************************
 *                                                                            *
 *                 Warning!  This is an unstable pre-release!                 *
 *                                                                            *
 * This release has limitations and omissions that may not be documented.     *
 * Furthermore, subsequent releases may introduce changes to the Standard ML  *
 * API that are incompatible with code using this release.                    *
 *                                                                            *
 ******************************************************************************

This INSTALL file covers the following topics:

  1. Prerequisites
       1.1  Standard ML compilers
       1.2  C Libraries
       1.3  Tools
  2. Installation


Full documentation is available in the User Manual at

  http://www.giraffelibrary.org/doc/installation.html


         ---------------        1.  Prerequisites       ---------------

1.1  Standard ML Compilers

Giraffe Library supports both MLton and Poly/ML compilers.  It is not necessary
to install both compilers to use Giraffe Library.


If using MLton, release 20130715 or later is required.  See

  http://mlton.org/
  http://mlton.org/Installation

for instructions on downloading and installing MLton.


If using Poly/ML, version 5.5.0 or later is required.  See

  http://www.polyml.org/download.html

for instructions on downloading and installing Poly/ML.


1.2  C Libraries

In this alpha release, all supported C libraries must be installed.  Therefore
the following C libraries must be installed:

  GTK+           >= 3.2.0
  Pango          >= 1.30.0
  GtkSourceView  >= 3.2.3
  VTE            >= 2.90

The major version should not be greater than the version specified above to
ensure compatibility.  Other versions may still work depending on the functions
actually used.

The C header files for these libraries are required.  Therefore, when using a
package management system, the `devel' or `dev' package is required.

On recent releases of Fedora, the above libraries and source header files are
installed by the following Yum command:

  yum install gtk3-devel pango-devel gtksourceview3-devel vte3-devel


1.3  Tools

Standard tools commonly found on Unix-like systems are required.

An ANSI C compiler, such as GCC, is required to build minimal C libraries
that support the SML interface to GObect-based libraries.

Common GNU utilites are required, including:
  - Bash
  - Make


         ---------------        2.  Installation        ---------------

1.  Unpack the source release tarball for version <ver> with the command

  tar -xzf giraffe-<ver>.tar.gz


2.  Change directory to the source directory with the command

  cd giraffe/


3.  In `Makefile`, update the line

  INSTALLDIR := <dir>

to make <dir> the root installation directory.  For this alpha release, it
is recommended that <dir> is not a system location such as /usr or /usr/local
but a non-system location such as ${HOME}/giraffe .


4.  Ensure that versions of MLton and Poly/ML in the path are suitable
versions to build with.  Check using the commands

  mlton
  poly -v

If an alternative version is required, add its bin directory to the front
of the PATH environment variable.  For example,

  PATH=/opt/mlton/mlton-20130715/bin:${PATH}


5.  Build using the command

  make mlton polyml

It is not necessary to specify both 'mlton' and 'polyml', only the required
compilers.


6.  Install using the command

  make install

This command requires permissions to write to the root installation
directory INSTALLDIR, set in step 3.  If any compilers were not specified in
step 5, `make install' may report errors but these can be ignored.
