(********************************************************************)
(*                                                                  *)
(*  install.txt                                                     *)
(*                                                                  *)
(*  Copyright (C) 1990 - 2013  Thomas Mertes                        *)
(*  All rights reserved.                                            *)
(*                                                                  *)
(*  Documentation: Installation of the Seed7 interpreter            *)
(*                                                                  *)
(*  This file is distributed "AS IS" in the hope that it will be    *)
(*  useful, but WITHOUT ANY WARRANTY; without even the implied      *)
(*  warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.*)
(*                                                                  *)
(********************************************************************)


1. INSTALLATION IN THE HOME DIRECTORY
=====================================

    Unpack the Seed7 package to the home directory. Then use a
  console or shell to compile interpreter and compiler. Just go to
  the directory 'seed7/src' and type:

    make depend
    make
    make s7c

  A detailed description of the compilation process can be found
  in the file 'seed7/src/read_me.txt'. After the compilation you
  can go to the 'seed7/prg' directory and start a Seed7 program
  like hello.sd7 with:

    s7 hello

  The programs find their include files in the 'lib' directory.
  It is not necessary to add a directory to the PATH variable.
  It is just necessary that the PATH variable contains '.' .
  When the PATH variable does not contain '.' a program must be
  started with:

    ./s7 hello

  This installation can be used for playing a little bit with
  the example programs.


2. USING INTERPRETER AND COMPILER FROM OTHER DIRECTORIES
========================================================

    It is desireable to allow calls of the interpreter (s7)
  and the compiler (s7c) from any directory. E.g.:

    s7 myprog

  To allow this, the path of 'seed7/bin' must be added to
  the PATH variable. E.g.: When your Seed7 directory is at
  /home/tm/seed7 you need to add /home/tm/seed7/bin to your
  PATH variable. Adding something to the PATH variable is
  highly system dependent. Please refer to descriptions of
  your operating system, to do it.

    Under operating systems, which support symbolic links,
  another strategy is possible. You can add symbolic links
  to the interpreter and compiler executable to a directory,
  which is in the PATH variable. E.g.: When /usr/local/bin
  is in the PATH variable you could do:

    cd /usr/local/bin
    su ...
    ln -s /home/myuser/seed7/bin/s7 .
    ln -s /home/myuser/seed7/bin/s7c .
    exit


3. INSTALLATION IN A SYSTEM DIRECTORY
=====================================

    It is not necessary to install Seed7 in your home directory.
  Compiling and installing Seed7 in any other directory is also
  possible. In this case it is important to compile Seed7 at its
  final place. The 'make' commands use the source directory to
  hardcode some configuration values in the interpreter and in
  the compiler. Moving the seed7 directory afterwards would
  cause that interpreter and compiler cannot find the include
  libraries or the runtime libraries. Installing Seed7 in a
  system directory is done with the following steps:

  a) Put the seed7 directory at some place. E.g. /usr/local/src:

       cd /usr/local/src
       su ...
       tar -xvzf seed7_05_yyyymmdd.tgz
       chown -R ... seed7
       exit

  b) Compile Seed7 interpreter and compiler at this place:

       cd /usr/local/src/seed7/src
       make depend
       make
       make s7c

     The paths to the include library and to the runtime library
     are hardcoded in interpreter (s7) and compiler (s7c).
     In this example the paths are"/usr/local/src/seed7/lib"
     and "/usr/local/src/seed7/bin".

  c) Add the direcory with the interpreter and compiler
     executables to the search path. Alternatively you can
     create a link to the interpreter (seed7/bin/s7) and to the
     compiler (seed7/bin/s7c) in a directory, which is in the
     search path. In our example we chose /usr/local/bin:

       cd /usr/local/bin
       su
       ln -s /usr/local/src/seed7/bin/s7 .
       ln -s /usr/local/src/seed7/bin/s7c .
       exit


4. WHAT A BINARY PACKAGE SHOULD INSTALL
=======================================

    A binary Seed7 package needs to install four groups of files:

  - The executables of the interpreter (s7 from "seed7/bin") and
    the compiler (s7c from "seed7/bin" or "seed7/prg").
  - The Seed7 include libraries (files from "seed7/lib" with the
    extension .s7i).
  - The static Seed7 object libraries (the files seed7_05.a,
    s7_con.a, s7_draw.a, s7_data.a and s7_comp.a from "seed7/bin").
  - Documentation files (the files COPYING and LGPL and all files
    from "seed7/doc").

  The table below shows the suggested directories for Linux/Unix/BSD:

  +---------------------+---------------+-------------------------+
  | Directory           | Macro         | Group of files          |
  +---------------------+---------------+-------------------------+
  | /usr/bin            | -             | Executables (s7 + s7c)  |
  | /usr/lib/seed7/lib  | SEED7_LIBRARY | Seed7 include libraries |
  | /usr/lib/seed7/bin  | S7_LIB_DIR    | Static libraries        |
  +---------------------+---------------+-------------------------+

  The macros must be defined, when the interpreter is compiled. This
  can be done by calling 'make depend' with:

    make S7_LIB_DIR=/usr/lib/seed7/bin SEED7_LIBRARY=/usr/lib/seed7/lib depend

  Afterwards the interpreter can be compiled with 'make' and the
  Seed7 compiler can be compiled with 'make s7c'. This three make
  commands can be combined to

    make S7_LIB_DIR=/usr/lib/seed7/bin SEED7_LIBRARY=/usr/lib/seed7/lib depend s7 s7c

  Alternatively the Seed7 compiler can be compiled as post-install step.
  This requires that "seed7/prg/s7c.sd7" is also installed. The actual
  compilation of s7c is done with:

    s7 s7c -O2 s7c

  It is also possible to compile the Seed7 compiler in the build directory.
  In this case it is necessary to specify the direcories SEED7_LIBRARY
  and S7_LIB_DIR with the options -l and -b:

    ./s7 -l ../lib s7c -l ../lib -b ../bin -O2 s7c

  Compiling s7c with a make command should be preferred.


5. SEED7 SCRIPTS AS EXECUTABLE
==============================

  Under (Unix like) operating systems a Seed7 script can find
  the s7 interpreter with the "shebang". You nedd to add the
  path to the s7 interpreter as first line of the script. E.g.:
  
    #! /home/tm/seed7/bin/s7

  The first line informs the operating system to use the given
  command when the scipt is executed. Additionally the Seed7
  script needs execute permission. The execute permission can
  be added with:

    chmod chmod +x mySeed7Scipt

  Afterwards the Seed7 script can be started with:

    ./mySeed7Script

  The operating system takes the command from the "shebang" and
  actually executes:

    /home/tm/seed7/bin/s7 ./mySeed7Script

  It is also possible to add parameters to the "shebang". E.g.:

    #! /home/tm/seed7/bin/s7 -q

  To avoid hard-coding the path of the Seed7 interpreter in the
  "shebang" the program 'env' can be used. In this case the
  directory of the Seed7 interpreter must be in the PATH variable.
  The "shebang" would look be:

    #! /usr/bin/env s7

  The first line informs the operating system to start the program
  'env' which itself searches for 's7' in the directories of the
  PATH variable. Then the 's7' interpreter is started to execute
  the desired program. This solution has the drawback that no
  parameters can be used.


6. CONFIGURATION
================

    The include library search path of interpreter and compiler
  is hardcoded. Additionally it can be changed in several ways:

  - Interpreter and compiler support the option -l, which allows
    the addition of a directory to the include library search path.

  - The environment variable SEED7_LIBRARY can also be used to add
    a directory to the include library search path.

  - The pragma 'library' can be used to specify the include library
    search path in a program. E.g.:

      $ library "../mylib";

  The directory where the compiler searches for runtime libraries
  is hardcoded. This can be overruled in one way:

  - The compiler supports the option -b, which can be used to
    specify the directory of the Seed7 runtime libraries.
