
   __ 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  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  Libraries

It is not necessary for all supported libraries to be installed.  

The following library versions are supported:

  GLib 2.0           = 2.30.3
  Pango 1.0          = 1.30.0
  GTK+ 3.0           = 3.2.4
  GtkSourceView 3.0  = 3.2.3
  VTE 2.90           = 0.28.2
  VTE 2.91           = 0.39.1

Later versions are expected to work but newer features are not supported.
Earlier versions may still work, depending on the actual dependencies.

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 GObject-based libraries.

Common GNU utilities are required, including Bash, Make, Grep and Sed.

pkg-config is required for the purpose of finding library dependencies.


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

2.1  Installation steps


  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.  Enter the command

        ./configure

      or

        ./configure --prefix <installdir>

      to install to <installdir>.

      If 'configure' does not find the required Standard ML compilers or
      libraries, refer to section 2.2 'Modifying the configuration', below.


  4.  Build using the command

        make


  5.  Install using the command

        make install

      This command requires permissions to write to the installation
      directory <installdir>, set in step 3.


2.2  Modifying the configuration

'configure' uses the PATH environment variable and pkg-config utility to find
dependencies.

'configure' checks for:

  - MLton by searching for 'mlton' in a directory in PATH

  - Poly/ML
      1. using pkg-config and, failing that,
      2. by searching for 'poly' in a directory in PATH

  - supported libraries using pkg-config

If any required dependencies are not found but are installed on your system,
either PATH or PKG_CONFIG_PATH (the pkg-config path) should be modified so
that the above checks find them.  The following sections describe how to update
these environment variables.


2.2.1  Changing PATH

PATH should be updated to include the directory containing the required program.
For example, to specify Poly/ML installed to /opt/polyml/polyml-5.5.2, then PATH
would be updated as follows:

  PATH=/opt/polyml/polyml-5.5.2/bin:${PATH}


2.2.2  Changing PKG_CONFIG_PATH

PKG_CONFIG_PATH should be updated to include the directory containing the
required PC file.  For example, to specify Poly/ML installed to
/opt/polyml/polyml-5.5.2, then PKG_CONFIG_PATH would be updated as follows:

  PKG_CONFIG_PATH=/opt/polyml/polyml-5.5.2/lib/pkgconfig:${PKG_CONFIG_PATH}
