SAGA C++ FRAMEWORK INSTALLATION OVERVIEW

  Quick Start - Unix
  ------------------

  For a complete installation documentation, see docs/manual/install.html or
  http://saga.cct.lsu.edu/

  Quick Start - Windows
  ---------------------

=== OLD INSTALL GUIDE ===


PREREQUISITES
----------------------------------------------------------------

  The SAGA C++ Frameworks depends on some 3rd party open source
  libraries. To successfully build the libraries and adaptors,
  you need to have the following packages installed on your
  system:

  - The main prerequisit is Boost (http://www.boost.org/) in
    version 1.33 or newer. configure honors the value of
    BOOST_LOCATION.

  - The adaptors require a number of addotional packages - if
    these packages are not available, some adaptors will not be
    build.  These packages are (configure environments in
    brackets):

    - xmlrpc++ (XMLRPC_LOCATION) - optional
      - version >= 0.7
      - http://xmlrpcpp.sourceforge.net/
      - xmlrpc++ is a simple implementation of remote procedure
        calls.

    - sqlite3 (SQLITE3_LOCATION) - optional
      - version >= 3.0
      - http://www.sqlite.org/

    - postgresql (POSTGRESQL_LOCATION) - optional
      - version >= 8.0
      - http://www.postgresql.org/

  Most of the packages should be available directly through your
  platform's software repository. It's recommend to install
  these pacakges into the system's default location (/usr,
  /usr/local, etc.) otherwise the build system won't find them
  and you'll have to specifiy the locations manually. 


BUILD AND INSTALL 
----------------------------------------------------------------

  This is the general way to build the libraries and default
  adaptors. For details and snapshot specific issues read the
  Release notes.

  - Unpack the tarball using GNU tar; it will create a directory
    saga-cpp-framework-<version>. For example:
    
      tar zxvf saga-cpp-framework-<version>.tar.gz

  - Run configure in the top directory of the source
    distribution. You can pass a lot of options to configure. At
    least, you should use option --prefix to specify where to
    install the library. For example:

      ./configure --prefix=<DESTDIR>

    To see other options of configure run: ./configure --help

    For example, you might pass --without-<PACKAGE> to exclude
    a specific package from the build process.

    Note: at the moment, DESTDIR is ignored, and ./install is
    used instead.  This will be fixed in later versions.

  - Create the libraries and default adaptors

      make

  - Install the libraries, default adaptors and configuration
    files

      make install

    This will create (in case it doesn't exist) a directory
    <DESTDIR> containing:

      lib/
      lib/saga
      include/saga
      share/saga


CONFIGURE THE INSTALLATION
----------------------------------------------------------------

  To help SAGA to find its configuration files, you should set
  the SAGA_LOCATION variable to <DESTDIR>:

    export SAGA_LOCATION=<DESTDIR>

  If you have installed SAGA to a non default location on you system,
  you may also want to add the SAGA libraries to the dynamic loader's 
  include path:

  - On Linux and most other Unix systems:
    
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SAGA_LOCATION/lib

  - On MacOS X:
    
    export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$SAGA_LOCATION/lib

  If you want SAGA to produce more verbose output and debugging statements,
  you can set the SAGA_VERBOSE variable to a non-zero value:

   export SAGA_VERBOSE=1

USE THE LIBRARIES 
----------------------------------------------------------------

  Here's a small program reading the content of a file using SAGA's
  package_file I/O methods:

  /////////////////////////////////////////////////////////////////////////////
  //
  #include <string>
  #include <saga.hpp>

  int main( int argc, char* argv[] )
  {
    if ( argc < 2 ) {
      std::cout << "\nUsage: " << argv[0] << " [URL] \n" << std::endl;
    }
    else {
      saga::size_t readbytes = 0;
      char inbuff[64];

      try {
        saga::file f (argv[1], saga::file::Read);

        while (readbytes = f.read (saga::buffer(inbuff)))
          std::cout << std::string(inbuff,readbytes) << std::flush;
      } catch (saga::exception const &e) {
        std::cout << "Couldn't read the file: " << e.what() << std::endl;
      }
    }
    return 0;
  }
  //
  /////////////////////////////////////////////////////////////////////////////
  
  Copy the source to a file "saga_file_read.cpp" and compile it using the
  following command:

    g++ saga_file_read.cpp -o saga_file_read               \
        -I$SAGA_LOCATION/include                           \
        -I$BOOST_LOCATION/include -L$SAGA_LOCATION/lib/    \
        -lsaga_engine -lsaga_package_namespace             \
        -lsaga_package_file    

  The resulting binary should be able to read and print out the contents of
  arbitrary local files on your system - for example:
 
    ./saga_file_read any://localhost//$HOME/.bashrc

  should print out the content of your .bashrc file.

  NOTE: If you try to substitute localhost with a hostname that doesn't point
        to your local machine, the execution will fail, since this SAGA
        distribution contains no "remote" adaptors. However, check our webpage
        at http://saga.cct.lsu.edu periodically for new adaptor releases.

        Once you add a remote file adaptor to your system, for example the
        globus_gridftp_file_adaptor (which is under heavy development), you
        will be able to use the little program above to read remote files from 
        Globus gridFTP locations without changing the code or recompiling the
        application :)


  Have fun!

    The SAGA development team.