INSTALL

SparForte Installation

This file contains instructions for building and installing SparForte.
General information about SparForte can be found in the doc/ directory.


SHORT VERSION

Installing the Binary Version

   1. gmake install

Building from Sources

   1. configure
   2. gmake
   3. gmake test (optional)
   4. gmake install (as root user)


LONG VERSION

The primary test plaform for SparForte is Linux or FreeBSD.  There
is also old support for DEC Alpha and Cywin.  HP-UX is obsolete.

Information on porting SparForte to other platforms can be found in the
documentation: SparForte should port to a modern Unix-compatible platform
within a few hours by creating a bush_os interface file based on the
standard C libraries for your operating system.  Please contribute new
os_bindings files to the SparForte project.


REQUIREMENTS

We have attempted to avoid re-inventing existing functionality wherever
possible and tried to keep the dependency list reasonably small, but it
still may be challenging for an inexperienced user to build and install
SparForte from sources.  Most users are probably better served by using binary
packages from their distributor, if they are available.

The following software packages are required for SparForte:

  * A Bourne-compatible shell such as bash or ksh.  dash may work.  On
    distributions using non-Bourne shells, to run "make tests" you will have
    to replace the shell symlink to an appropriate shell.

    # rm /bin/sh
    # ln -s /bin/bash /bin/sh

  * GNU make is required; other make programs may not work.  GNU make is often
    installed under the name "gmake" and the SparForte makefile assumes this is the
    name of your software building program.

  * GCC is required; SparForte is written in Ada 2005 and C, both of which are
    available recent versions of GCC.  Most modern Linux distributions,
    including Red Hat,  have GCC with Ada and C support active or available
    from an online repository.

  * Optional PCRE (Perl Compatible Regular Expressions) library

  * gzip is needed to unpack the source code in the first place.  If you are
    reading this, you know this already.

  * a optional database, either (or both or neither):

    * postgresql.  To verify that postgres is installed, try "psql --version".
      For more information, visit http://www.postgresql.org.

    * MySQL.

  * SDL (Simple DirectMedia Layer) library and SDL_image

  These may not be installed on your operating system, or some components
  may be missing.  How you install these depends on your operating system.

  The provision.sh script will attempt to identify your version of Linux and
  install all the required software.

  Alternatively, you may want to install the requirements manually, selecting
  which software you want.  For example:

   - Fedora/Red Hat Linux - yum install package-name (or use add/remove
     software in the menus)
   - SuSE Linux - yast
   - Debian Linux - apt-get install package-name (visit packages.debian.org
     for a list of available packages)
   - FreeBSD - pkg_add package-name
   - Pre-build versions of SDL_image are available from www.libsdl.org 

  The package name depends on your operating system.  For example:

    - Ubuntu/Debian Linux users can try gnat-4.6 (or similar)
    - Red Hat/Fedora Linux users can try gcc-gnat
    - SuSE Linux   users can try gcc-ada

  Example: Ubuntu Linux

  The default Debian database is PostgreSQL.  However, Debian doesn't
  install Ada, SDL, MySQL or the PostgreSQL development packages.  Check
  packages.debian.org for a list of software package names.

  $ apt-get install gnat-4.6
  $ apt-get install libsdl1.2-dev
  $ apt-get install libsdl-image1.2-dev
  $ apt-get install libsdl-ttf2.0-dev
  $ apt-get install libmysqlclient-dev
  $ apt-get install postgresql-client
  $ apt-get install postgresql-server-dev-9.1
  $ apt-get install postgresql-server-dev-all
  $ apt-get install libgstreamer0.10-dev

  Update the locate database: Debian uses a static Ada Run-Time file so SparForte
  will need to use locate instead of ldconfig to find it.  (Running updatedb
  is safe even if this was not true.)

  $ updatedb

  SDL_image is installed but the filename contains the version number so
  SparForte can't see it.  Create a symbolic link to the standard name.

  $ ln -s /usr/lib/libSDL_image-1.2.so.0.1.3 (or similar) /usr/lib/libSDL_image.so
  $ ldconfig

  Example: FreeBSD

  $ pkg_add -r gmake
  $ pkg_add -r glocate
  $ pkg_add -r gcc
  $ pkg_add -r gnat
  $ pkg_add -r sdl
  $ pkg_add -r sdl_image
  $ pkg_add -r mysql55-server
  $ pkg_add -r postgresql91-server
  $ gupdatedb
  $ sh configure
  $ make

INSTALLATION

SparForte has a language test suite to verify builds and the sample
programs are validated before a release.  While we try to build SparForte on
a variety of platforms, we cannot guarantee that the source code will build
successfully on every platform nor can we guarantee that third paries will
not introduce changes that will break build dependencies.  Please report
any issues you find.

The latest version of SparForte is always located at the PegaSoft web site,
http://www.pegasoft.ca.

By default, SparForte will install under /usr/local.

1. configure

   The first step of the installation procedure is to select your operating
   system.  Run "configure" and the configure script will identify your
   operating system and create a new file called "bush_os.ads" containing the
   binding for your system calls.

   configure will also check for the basic tools needed to build SparForte
   (including an Ada compiler).  When it is finished configuring SparForte,
   configure will run the configure programs for the ADAVOX and APQ third-
   party libraries used by SparForte. The APQ configuration script will ask
   questions about your database software.  (Note: SparForte currently supports
   PostgreSQL and MySQL.)

   configure recognizes the following options (you can also use environment
   variables):

    --arch= (ARCH variable): specify a different machine processor
            architecture (normally determined by uname -p)

    --make= (GMAKE variable): the location of GNU make.  Use this if
            configure can't find it in a standard location.

    --prefix= (PREFIX variable): the root directory for the installation
            (by default, /usr/local)

    --manprefix= (MANPREFIX variable): the root directory for the
            installation of the man page (by default, /usr/local)

    --with-gnat-cgi: by default, GNAT.CGI is not included in SparForte
            because it raises an exception if SparForte is not running
            in a CGI context.  Use this switch to enable support.

    --without-bdb (NO_BDB variable): disable Berkeley DB support

    --without-mysql (NO_MYSQL variable): disable MySQL database support

    --without-opengl (NO_OPENGL variable): disable OpenGL support

    --without-pcre (NO_PCRE variable): disable PCRE library support

    --without-postgres (NO_POSTGRES variable): disable PostgreSQL database
            support

    --without-readline (NO_READLINE variable): disable GNU readline support
            and use the old SparFrote input functions

    --without-sound (NO_SOUND variable): disable gstreamer sound support.

    Common Problems

    - pg_config not found.

      You'll need to install the postgresql development packages (or equivalent
      for your O/S) if you want to add support for this database.

2. make

   Use GNU make to build SparForte.  Linux users can just type "make" or "make all".
   If GNU make is not your native make (e.g. FreeBSD), use "gmake".

   On Raspberry Pi/Linux, you may need to increase your swap space in order to
   build SparForte successfully.  You can do this by (1) creating an empty
   file with "dd"; (2) "mkswap" to configure it as swap space; (3) "swapon"
   to activate it.  You can check your swap space with "free".

   If you see "ld: cannot find -lx" where x is a library name:

   This means the linker cannot find a library file (usually libx.so where
   x is a library name, but this depends on your operating system).

   There are several possible reasons for this.

   Either (1) You will need to install additional packages.  For example,
   you installed a database server without the development files.

   (2) Your operating system has a different name for x, typically with
   a version number attached to the name.  This happens frequently with
   SDL_image although it can happen with other libraries as well.

   First, do a search using the "find" or "locate" commands to determine if
   you have the library installed.  If not, install it.  If it exists but
   has a different name, following the Debian example above: use "ln" to
   create a link and ldconfig to register the alternative name for the
   library.

   (3) You've installed the package but need to run "ldconfig" to refresh
   the linker's database and add the names of the new libraries.

   (4) The libraries are stored in an unusual location and a "-L" switch
   must be added to the src/GNUmakefile specifying where the libraries are
   found.  Some packages have a "config" program to determine the proper
   settings, such as "SDL_config", "pg_config" or "mysql_config".

3. (Optional) "gmake test" to run the SparForte core language regression
   tests.  The tests should by run as an unprivileged user (as some tests
   check file access rights and will fail if run as root).

   Alternatively, "gmake coverage" to generate code coverage
   results with gcov and lcov, or "gmake releasetest" to perform more
   extensive testing prior to pushing changes to GitHub.

4. (Optional) "gmake install" will copy the spar executable to the
   /usr/local/bin/ directory so that other users can access it.  Alteratively,
   you can copy the spar executable and man page yourself and set the
   appropriate permission bits.

You can now run the spar executable.

Type "gmake help" for a list of all options.  There are more options in the
src directory makefile.


INSTALLING FOR WEB TEMPLATES

SparForte can run as a CGI program.  The exact requirements depends on
your Linux distribution.

On Unbuntu/Linux Mint, the CGI directory is /usr/lib/cgi-bin.  Apache
will not run a program outside of this directory.  Copy the spar
executable to /usr/lib/cgi-bin.

Create your scripts using .cgi ending, and include #!/usr/lib/cgi-bin/spar
in the bang path at the top of your scripts.


CREATING A LAUNCHER (DESKTOP ICON)

If you are using Gnome desktop, right-click and select create launcher.
Use a "Launch in Terminal" type.  An icon for your launcher can be
found in the top directory of the SparForte download file.

- END OF DOCUMENT -