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


This INSTALL file covers the following topics:

  1. Prerequisites
       1.1  Standard ML compilers
       1.2  Libraries
       1.3  Tools
  2. Installation
  3. Additional configuration


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.2 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 libraries are supported, where the interface is based on the
indicated version:

  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.

In order to use a library, its C header files are required.  Therefore, when
using a package management system, the 'devel' or 'dev' package is also
required.

The package management commands to install the above libraries and source header
files on Fedora, Ubuntu and Mac OS X are shown below.  The commands can be
adjusted as required.

  Fedora

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

    yum install vte291-devel  # Fedora 21 or later


  Ubuntu

    sudo apt-get update  # synchronize package index

    sudo apt-get install libpango1.0-dev \
                         libgtk-3-dev \
                         libgtksourceview-3.0-dev \
                         libvte-2.90-dev

    sudo apt-get install libvte-2.91-dev  # Ubuntu 15.04 (Vivid) or later


  Mac OS X

    sudo port install pango gtk3 gtksourceview3 vte


Further information about packages available via these package management
systems can be found as follows:

  Fedora    - https://apps.fedoraproject.org/packages/
  Ubuntu    - http://packages.ubuntu.com/
  Mac OS X  - https://www.macports.org/ports.php


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 for compiling and linking.

The package management commands to install the above tools on Fedora, Ubuntu
and Mac OS X are shown below.

  Fedora

    yum install gcc bash make coreutils grep sed pkgconfig


  Ubuntu

    sudo apt-get install gcc bash make coreutils grep sed pkg-config


  Mac OS X

    sudo port install gcc49  # or another GCC version, e.g. gcc48

    sudo port install bash gmake coreutils grep gsed pkgconfig


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

      to install to GIRAFFEHOME, if set, otherwise /opt/giraffe.  Alternatively,
      enter the command

        ./configure --prefix <installdir>

      to install to <installdir>.  For further options, enter the command

        ./configure --help

      If 'configure' finds Standard ML compilers that should be ignored, the
      following options can be specified as required:

        --without-mlton
        --without-polyml

      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 set in step 3.


2.2  Modifying the configuration

'configure' uses the PATH environment variable and pkg-config utility to find
dependencies if not specified by command line options.

'configure' searches for:

  - MLton
      1. using directories from command line options and, if not specified,
      2. by searching for 'mlton' in a directory in PATH

  - Poly/ML
      1. using directories from command line options and, if not specified,
      2. using pkg-config and, failing that,
      3. 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,
the configuration can be modified by one of the following methods to ensure that
the above checks find them:

  - adding command line options as described in section 2.2.1

  - changing PATH as described in section 2.2.2

  - changing PKG_CONFIG_PATH (the pkg-config path) as described in section 2.2.3


2.2.1  Specifying directories using command line options

The installation directory prefix of Standard ML compilers can be specified by
the following configure options:

  --mlton-prefix <DIR>
  --polyml-prefix <DIR>

The sub-directories can be overridden using the following options for
non-standard installations:

  --mlton-bindir <DIR>
  --mlton-includedir <DIR>
  --polyml-bindir <DIR>
  --polyml-libdir <DIR>


2.2.2  Changing PATH

PATH can 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.3  Changing PKG_CONFIG_PATH

PKG_CONFIG_PATH can 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,
PKG_CONFIG_PATH would be updated as follows:

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


         ---------------   3.  Additional configuration   ---------------

3.1  OS X using Macports

When running a GTK+ application, the following message may appear:

  Dynamic session lookup supported but failed: launchd did not provide a
  socket path, verify that org.freedesktop.dbus-session.plist is loaded!

This error occurs because D-Bus is not running.  Enter the following command to
start the session D-Bus:

  launchctl load -w /Library/LaunchAgents/org.freedesktop.dbus-session.plist

The session D-Bus will start automatically after subsequent logins.  To stop
the session D-Bus, enter the command:

  launchctl unload -w /Library/LaunchAgents/org.freedesktop.dbus-session.plist

Source: https://trac.macports.org/ticket/44498#comment:6
