QSAS Installation Instructions
==============================
Version 2.3.00
--------------

Contents
--------
0. Host Requirements
1. Installation
    1.1 Installation using Configure
    1.2 Incremental updates using Configure
    1.3 Mac OSX Installation
    1.4 Installation from Build Scripts (old method os src build)
    1.5 Installation from packages (RPM, DEB)
    1.6 Building packages
    1.7 Building the Windows version
    1.8 Trouble shooting installation
2. Running QSAS
3. Building Plugins
4. Licence and acknowledgments

    
0. Host Requirements
--------------------
To perform a source build of QSAS, the host machine 
will require the QT third  party libraries. It will also need
the QT headers - on most Linux flavours these are installed already
since QT is used by the KDE windowing system, but on some Linux installations 
these will need installing (usually from the developers pack).

0.1 Compilers
-------------
QSAS is built under the gnu C++(g++) compiler.

0.2 Qt
------
QSAS makes extensive use of the Qt GUI toolkit for all user 
interface windows and therefore the qt library must be present
for the distribution to build on the host machine. QSAS runs
on Qt versions 3.xx and 4.2.x, 4.3.x and 4.4.x. Versions 4.0 and
4.1 of QSAS have not been tested, and QSAS is not designed to work
with them.

Qt is a free utility for Solaris and Linux platforms available from

http://www.trolltech.com/products/download/freelicense/qtfree-dl.html

Apple Mac users ONLY need install Qt if they wish to build plugins 
locally that use Qt.

0.3 CDF (Installed with QSAS)
-----------------

QSAS uses CDF 3.1 versions onwards in order to provide access to
Themis data files which use the CDF_EPOCH16 data type that is not
available in earlier versions.

To ensure this is available QSAS now always builds against the
CDF library shipped with it (src/Utilities/qcdf).

For CDF stand alone utilities or user defined plugins that use CDF
installation of CDF in parallel is possible. This is available for free from

http://nssdc.gsfc.nasa.gov/cdf/cdf_home.html

QSAS uses cdf 3.1 and sets the environment variable CDF_FILEBACKWARD
to be sure so that QSAS generated cdf files will be readable by software
compiled against CDF 2.7. 

To force QSAS to build against a locally installed version of
CDF set the environment CDF_DIR to point to the local cdf
installation (must be cdf v3rsion 3.1 or later), see below, 1.1.6.


1. QSAS Installation Instructions 
---------------------------------

To install QSAS, you need to perform the following steps....

To uncompress `qsas-2.3dist.tar.gz' use the `gzip' command...

     gzip -d qsas-2.3dist.tar.gz 

The resulting file will be named `qsas-2.3dist.tar'. 

Then use the `tar' command to extract the QSAS source files.
`tar' will create a directory named `qsas-2.3dist' containing
several subdirectories.  The source files for the distribution
will be placed into these directories.

The syntax for the `tar' command is different on some flavours
of UNIX.  For most UNIX systems use...

      tar -xvf qsas-2.3dist.tar

1.1 QSAS UNIX(Linux/Solaris) Self Installation Using Configure
--------------------------------------------------------------

   For Apple Mac OSX go to section 1.3
   
   The following steps should automatically build and install QSAS.

	1. Set your current directory (cd) to the top level QSAS 
	directory (the directory named `qsas-2.3dist' created by `tar').

	2.1 In order to configure QSAS to install into a target directory 
	/home/mydir/QSAS_2.3 it should be necessary only to type the following command...
	   
	    ./configure --prefix=/home/mydir/QSAS_2.3
	    
	This will search all the usual locations  (/usr/lib, /usr/local/lib, /lib etc)
	for the QT libraries. This may take a few minutes. If the --prefix option
	is omitted QSAS will be installed in ~/QSAS23 where ~ is the user's home directory.
	 
	If unable to locate a usable version of Qt it will stop with an error message (see step 6 below).
	    
	3. If no errors are reported compile, link, remove debug symbols and install the QSAS system by running the command

	     make install-strip

	Please be patient here, since a base configuration takes between 15 and 40 minutes 
	to compile depending on your hardware.

	NB. If you wish to retain the debugging symbols to use QSAS with a debugger
	use the following command instead... 
	
	     make install
	     
     QSAS is now installed in the target directory specified.
	
	To save space after installation you can type
	
	    make clean
	    
	NB. Do not remove the top-level QSAS distribution directory (qsas-2.3dist)
	if possible, as this can be subsequently used for installing incremental 
     updates to your QSAS installation (see below.)
	  
	4. To run QSAS, execute the script in the bin sub-directory of the 
	   target directory, e.g. ...

	    /home/mydir/QSAS_2.3/bin/QSAS
	   
	 This script may be copied into each user's own space or added to their path environment.
	 Individual copies of the QSAS script may be edited to change default
	 locations for placing e.g. plot files or savesets.

	  
	


1.2 Incremental Updates for configure Installation
    ----------------------------------------------
    Having run configure, make, make install-strip (or make install) on your
    machine, it is possible to perform incremental updates by downloading from
    the QSAS web page

    http://www.sp.ph.ic.ac.uk/csc-web/csc.html

    any gzipped-tar patch files. These patch files are not available
    for all releases, for example when there are changes to configure.in.
    
    Changing directory to the top-level QSAS distribution directory (qsas-2.3dist) 
    and unzipping / extracting these files (as described above using gzip -d and tar -xvf), 
    will copy over any updated source and configure.in files. Then re-running

          make install-strip 

    will compile and install these changes into your target QSAS installation directory.
    It is not necessary to re-run ./configure unless CDF, pgplot or QT libraries have moved.
    In this case it is advisable to fetch a full QSAS distribution and rebuild as per section 1.1.
    

1.3. Mac OSX Installation
     --------------------

   The Mac OSX installation is available as separate downloads. Do not attempt 
   to build the Mac version from the configure distribution. Download the Mac specific 
   distribution which will unpack as a disk image. Double click the QSAS 
   installer as for other Mac applications.
   
   The Mac version is otherwise identical at source level to this distribution.
   
   Different installers are provided for the PowerPC and Intel chip sets.


1.4. UNIX(Linux,Solaris) Old Style Installation Using Build Script
     ------------------------------------------------------------

   QSAS can alternatively be built using the old-style standard build scripts,
   supplied in the bin sub-directory of the binary distribution (build_qt3 and build_qt4). Download a
   binary version and follow the build from source instructions in that 
   distribution.
   
1.5. Installation from packages (RPM, DEB)
     ------------------------------------------------------------

   QSAS can now be installed from pre-built packages for selected Linux distributions and
   CPU architectures. To install a QSAS package from your system, just run, as root user:
   
          rpm -i qsas-....rpm
   
   or
   
          dpkg -i qsas-....deb

   depending of your distribution's packaging system.
   
   QSAS will be installed in /usr/local/qsas-(version), and a link to the QSAS script is set up
   as /usr/bin/qsas. After installation, you should be able to start QSAS by running "qsas" from
   the shell prompt.
   
   To uninstal QSAS, run as root user:
   
         rpm -e qsas
   
   or
   
          dpkg -r qsas
   
1.6. Building packages
     ------------------------------------------------------------

   The whole "configure/make" sequence described in 1.1 is automated to produce an RPM package
   when using the so-called source RPM (qsas-....src.rpm). To build a package for your system
   from the source rpm, run, as a root user:
      
          rpmbuild --rebuild qsas-....src.rpm
   
   This may fail on 64-bit architectures: in this case, set the environment variable FORCE_SIZE
   to 64 before running rpmbuild.An RPM package will be created in a folder depending on your
   system, e.g. "/usr/src/rpm/RPMS/_your_arch_". Follow the instructions in 1.5 to install it.
   
   To generate a DEB package from the generated RPM package, run, as root:
   
          alien --scripts qsas-....rpm
   
   The resulting DEB file will be output in your current folder. It can be installed as
   described in 1.5.

1.7. Building the Windows version
     ------------------------------------------------------------

   See the doc/build_windows.txt file

1.8 Trouble Shooting Installation
     ---------------------------------
   
   Specific platform dependencies can be specified if autoconf fails,
   or if you wish to build QSAS against a specific version of a local library.
   Some of these are itemised below.
   
   If a compilation has failed, it is advisable to run
       make distclean
   and then
       ./reconf
   before trying the options below.
   
   1.   To specify a specific local version of Qt or CDF,
	or if your local installation of Qt is not in one of the 'usual places'
	there are two ways to tell configure where to look.
	
	In the simplest case you can tell configure to use a specific environment
	variable, such as the location of Qt by adding the
	environment and its value to the configure command, e.g.
	
	./configure --prefix=/home/mydir/QSAS_2.3 TQ_DIR=/usr/lib/qt-3.3
	
	then configure will look in the directories /usr/lib/qt-3.3 and
	/usr/lib/qt-3.3/lib for the QT libraries.
	
	The command configure accepts a variety of variables and command 
	line options.  Entering...
	
	./configure --help 
	
	will give an overview of these options.
	
	Alternatively, to set several environments at once, modify the shell 
	script file named 'qsas-2.3dist/share/config.site' 
	and specify the locations of the Qt or CDF sub-directories 
	for your distribution. These will be pre-pended to the search path
	used by configure.

	It is then necessary to use the CONFIG_SITE environment variable to point to the 
	directory path for the config.site file containing your settings

	
	   ./configure --prefix=/home/mydir/QSAS CONFIG_SITE=./share/config.site

	Once you have run configure successfully go back to step 1.1.3 and continue
	compiling and installing QSAS.
	
	If a configure has failed, it is advisable to run the command
	
	   make distclean
	   
	followed by
	
	   ./reconf
	
	to clean up the distribution and ensure changes occur everywhere.

   2.   Conflicts can arise if multiple versions of compilers are installed
        on the target platform. QSAS will attempt to make a sensible choice
	of compiler, but if errors occur during make, then conflicts may
	be due to compiler conflicts.
	
   3.   64 bit architecture machines are generally able to compile in
    	32 bit mode, and will have complete library sets for both.
	
	It is possible for the autoconf version of QSAS to get
	confused between these two library trees, and this can
	cause compilation failure.
	
	An extra environment variable is accepted by configure to
	force QSAS to try to use one set of libraries. The enviroment
	FORCE_SIZE can be set to 64 or 32, e.g.
	 ./configure --prefix=/home/mydir/QSAS  FORCE_SIZE=32
	 
	This is, as yet, not fully tested, so please inform us if you try this
	environment.
	
   
   
2. Running QSAS
   ------------

2.1 Running QSAS under Linux and Solaris (installed from source)

   To run QSAS, execute the script in the bin sub-directory of the 
   target directory, e.g. ...

	    /home/mydir/QSAS_2.3/bin/QSAS

   For binary installations this will be QSAS-2.3/bin/QSAS.
   
   This script may be copied into each user's own space or added to their path environment.
   Individual copies of the QSAS script may be edited to change default
   locations for placing e.g. plot files or savesets.

   In the recommended installation (using configure), the QSAS script 
   will be modified to reflect the location of the QSAS installation. 
   In binary distributions and those built with the build script this 
   script must be hand-edited first.

2.2 Running QSAS under Linux (installed from package)

   A "qsas" symlink to the QSAS script should be installed in /usr/bin.
   Simply running "qsas" should start the software.

2.3 Running QSAS under Mac OSX
   
   In Mac installations QSAS is launched by double clicking the QSAS 
   application /Applications/QSAS_2_3/QSAS. 
   
   This application may be dragged to the Dock or the Shortcuts pane 
   of the finder as normal and launched with a single click. 
   
   This will first launch X11 and a pgplot server, 
   so startup is slower than on other platforms. The X11 window can 
   safely be dismissed as command line output is directed to the 
   console application ( /Applications/Utilities/Console ).
   
   The menu bars for QSAS windows follow the Mac convention
   of being placed at the top of the screen, and the menu will
   be applicable to the QSAS window currently selected.
   
2.4 Running QSAS under Windows

   Edit the QSAS/bin/QSAS.bat file and adapt the first line i
   necessary. Then, just double-click QSAS.bat to start QSAS.

3. Building Plugins
   ----------------
   
   A script file "buildPlugin" is created automatically on
   running make after ./configure. It will be installed in
   the bin directory. 
   
   Edit the Makefile (called Makefile.std for QSAS builds)
   to locate the sources to be built (cf. Makefile.std files
   in the various plugin directories in the distribution
   src/Ext/*/Makefile.std).
   
   Place this script in the directory
   containing the plugin source files and type 
   
   buildPlugin
   
   This should compile the sources against the same libraries as
   used in the QSAS installation and place the resulting
   dynamic library in the chosen folder in the QSAS installation.

4. Licence and Acknowledgments
   ---------------------------
    
   QSAS is supplied under GPL licence, see separate Licence file.
    
   Please refer to individual licencing and copy statements contained
   in various 3rd party software components.
   
   This software was developed at Queen Mary and Imperial Colleges,
   London University as part of the UK Cluster Mission
   support activity and was funded by PPARC.
    
   csc-support-dl@imperial.ac.uk

   For more details, please refer to the QSAS Installation document, 
   available from

   http://www.sp.ph.ic.ac.uk/csc-web/DOCS/QSASinstallation.pdf
   
   PLplot is supplied under the LGPL license: http://www.gnu.org/licenses/lgpl.html
   
   The Windows version of QSAS is delivered together with standard compiled Qt libraries, thanks to exception 4-a of GPL_EXCEPTION_ADDENDUM.TXT provided by Nokia. You can get the original source on http://trolltech.com/downloads/opensource/appdev/windows-cpp