
   __ o  o __
   \_\|__|/_/
     \(o  o)      Giraffe Library Installation
      |\ _|
 \    |\`-' /\    Version 1.0.0-alpha.12
  \___|/|_ /  \
   \  |\|  \  /
    \_______\/


This INSTALL file covers the following topics:

  1  Prerequisites
       1.1  SML compilers
       1.2  Standard tools
       1.3  Libraries
  2  Installation
  3  Additional configuration


Full documentation is available at

  http://giraffelibrary.org/


         ---------------        1  Prerequisites        ---------------

Most of the dependencies can be easily installed via a package management
system.  Example commands are given to show how this can be done on Fedora,
Ubuntu and macOS (using MacPorts and Brew).  Further information about
packages available via these package management systems can be found as
follows:

  Fedora
    https://src.fedoraproject.org/projects/rpms/*

  Ubuntu
    http://packages.ubuntu.com/

  macOS using MacPorts
    https://www.macports.org/ports.php

  macOS using Brew
    https://brew.sh/

Package management systems do not typically give a choice about which
version of a dependency is used.  To install a specific version, it is
necessary to build from source.


1.1  SML compilers

Giraffe Library supports both MLton and Poly/ML compilers.  It is not necessary
to install both compilers to use Giraffe Library.  At least one of the following
versions is required:

    MLton    >= 20130715
    Poly/ML  >= 5.6

The package management commands to install the supported SML compilers on
Fedora, Ubuntu and macOS (using MacPorts and Brew) are shown below.  The
commands can be adjusted as required.

  Fedora

    sudo dnf install mlton   # Fedora 20 or later for required version
    sudo dnf install polyml  # Fedora 24 or later for required version


  Ubuntu

    sudo apt-get install mlton   # Ubuntu 18.04 (Bionic) or later for required version
    sudo apt-get install polyml  # Ubuntu 16.04 (Xenial) or later for required version


  macOS using MacPorts

    sudo port install polyml

    Note that MLton is not available from MacPorts.


  macOS using Brew

    brew install mlton
    brew install polyml

If the required versions cannot be provided via the package management system,
the SML compilers can be build from source.  For instructions on installing
MLton from source, see

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

For instructions on installing Poly/ML from source, see

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


1.2  Standard tools

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

  - An ANSI C compiler, such as GCC, and a linker are 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.
  - The pkg-config utility is required for the purpose of finding library
    dependencies for compiling and linking.

The package management commands to install the standard tools on Fedora, Ubuntu
and macOS (using MacPorts and Brew) are shown below.  The commands can be
adjusted as required.

  Fedora

    sudo dnf install gcc binutils bash make coreutils grep sed pkgconfig


  Ubuntu

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


  macOS using MacPorts

    sudo port install binutils bash gmake coreutils grep gsed pkgconfig

    Note that a compiler and linker provided by Xcode can be used.


  macOS using Brew

    brew install binutils bash make coreutils grep gnu-sed pkg-config

    Note that a compiler and linker provided by Xcode can be used.


1.3  Libraries

Giraffe Library provides SML bindings to libraries where the interface is based
on the indicated version:

  - GLib 2.0              2.66.4
  - Atk 1.0               2.36.0
  - cairo 1.0             1.14.0
  - HarfBuzz 0.0          2.7.2
  - Pango 1.0             1.48.0
  - GdkPixbuf 2.0         2.40.0
  - GTK 3.0               3.24.24
  - GtkSourceView 3.0     3.24.11
  - VTE 2.90              0.36.5  (VTE is a Virtual Terminal Emulator)
  - VTE 2.91              0.62.1

Later versions of these libraries are expected to work but newer features are
not available.  Earlier versions of these libraries may still work, depending on
the actual dependencies of an application using Giraffe Library.  It is not
necessary for all available libraries to be present: Giraffe Library will not
install bindings to libraries that it cannot find using pkg-config.

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 typically
also required.  (This does not apply to MacPorts.)

The package management commands to install all available libraries with their
source header files on Fedora, Ubuntu and macOS (using MacPorts and Brew) are
shown below.  The commands can be adjusted as required.

  Fedora

    sudo dnf install gtk3-devel gtksourceview3-devel
    sudo dnf install vte3-devel    # Fedora 29 or earlier
    sudo dnf install vte291-devel  # Fedora 21 or later


  Ubuntu

    sudo apt-get install libgtk-3-dev \
                         libgtksourceview-3.0-dev
    sudo apt-get install libvte-2.90-dev  # Ubuntu 14.04 (Trusty) only
    sudo apt-get install libvte-2.91-dev  # Ubuntu 15.04 (Vivid) or later


  macOS using MacPorts

    sudo port install gtk3 gtksourceview3 vte


  macOS using Brew

    brew install gtk+3 gtksourceview3 vte3

If the required versions cannot be provided via the package management system,
the libraries can be build from source.  To do this, a build environment such as
JHBuild [https://wiki.gnome.org/HowDoI/Jhbuild] or BuildStream
[https://wiki.gnome.org/Newcomers/BuildSystemComponent] is recommended.


         ---------------         2  Installation        ---------------

2.1  Installation steps


  1.  Unpack the release archive 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 SML compilers that should be ignored, the
      following options can be specified as required:

        --without-mlton
        --without-polyml

      If 'configure' does not find the required SML 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.


  6.  Clean up using the commend

        make distclean


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 SML 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.6, then PATH
would be updated as follows:

  PATH=/opt/polyml/polyml-5.6/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.6,
PKG_CONFIG_PATH would be updated as follows:

  PKG_CONFIG_PATH=/opt/polyml/polyml-5.6/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
