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. sh provision.sh
   2. gmake install

Building from Sources

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


LONG VERSION

Installing SparForte assumes that you are familiar with the Linux
command line and know basic programming knowledge.  You should know how
to resolve common open source issues like missing software libraries or
missing C language header files.

The primary test platform for SparForte is Linux.  It is also tested on
Raspberry Pi.  Volunteers have ported it to MacOS.  It is occasionally
tested on Cygwin and FreeBSD.  It used to be supported on DEC Alpha and
HP-UX but this has not been maintained.

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 spar_os interface file based on the
standard C libraries for your operating system.  Please contribute new
os_bindings files to the SparForte project so they can be shared with others.


BINARY DISTRIBUTIONS vs. SOURCE CODE

The binary versions are created while testing SparForte before release.
They are built for specific version of specific Operating Systems.  You
will need to run the provision.sh script to install all the library
dependencies for your operating systems.

The binary distributions should containt the spar binary and the
SparForte manual in the doc directory and sample scripts in the examples
directory.

The source code file has the source code in Ada, C and shell scripts,
along with the SparForte manual and sample scripts.  You will need to
build SparForte from the source files to use it.


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 also works.  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.  It is enabled
    by default but can be disabled with the configure script.

  * gzip or bzip2 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 is also optional
    for graphics

  * gstreamer is optional for sound

  * GNU locate is optional.  The configure script will fallback to using
   the "find" command.

Check the website release announcements for any known build issues for a
release.


DEPENDENCIES

  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 was written to quickly set up test environments
  for SparForte.  However, it can also help users install dependencies
  before building SparForte from sources or installing a binary release.
  The provision.sh script will attempt to identify your version of Linux and
  install all the required software dependencies.

  The provision.sh script recognizes most common Linux distributions (such
  as Arch, Debian, Red Hat, OpenSuSE and Ubuntu) but it does not recognize
  all possible distributions as there are so many of them.  Also, the names
  of dependencies may change between releases of a Linux distribution.

  Alternatively, you may want to install the requirements manually if you
  have the technical skills to do so, selecting which software you want.
  Different distributions or operating systems use different command line
  software installers.  For example:

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

  The package name depends on your operating system.  For example, the
  Ada language varies between systems:

    - 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

  If you GNU locate is installed, 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. provision

   Install the software dependencies, if you have not already done so.

   provision recognizes most of the "without" options that configure uses.
   For example, if you do not wish to install Berkeley DB libraries, you
   can skip installing them using the --witout-bdb option.  Then configure
   SparForte without Berkeley DB support.

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

3. 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".

4. (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.

5. (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.


LOGIN SHELL

SparForte will run as a login shell if you place it in the /etc/passwd
file accordingly.  Alternatively, change /etc/shells to allow users to
select spar as a shell with chsh.  You will need to be the superuser to
copy or edit these files.

You can run SparForte in login shell mode without making it your login
shell by running it using the "--login" (or "-l") command option.


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 -