Release Note for ISDC Support Software

Issue:	2.0
Date:	13 October 2000

Contents:

1. Introduction

1.1 Scope
1.2 Contents of the ISDC Support Software Package
1.3 Getting the ISDC Support Software Package

2. Changes since the last version
3. Installation Guide

3.1 Introduction
3.2 Unpacking the package and setting up the directory structure
3.3 Setting up ROOT
3.4 Auto-configuring Makefiles
3.5 Compilation and Installation of SUPPORT-SW
3.6 Sample Executables
3.7 Additional Comments on isdcroot

4. Known Problems
5. Getting Help

1. Introduction

1.1 Scope

The ISDC Support Software is a set of (not so) basic libraries and tools that are to be used for the development of INTEGRAL data analysis software. The Support Software is included on the Reference Platform definition; hence a new release of the Support Software always matches a new release of the Reference Platform definition. The version number is identical. The Reference Platform definition is presented in:

http://isdc.unige.ch/index.cgi?Software+swplatform

Since Reference Platform 1.5, ROOT is required for the complete installation. ROOT support is however optional, and can be disabled. The Support Software can be compiled without it, but some tools will be missing. You can obtain ROOT from the ISDC Software WWW page. The ROOT package is considered as part of the Reference Platform like compilers. If you want to use ROOT support, ROOT must be installed before the ISDC Support Software is compiled.

1.2 Contents of the ISDC Support Software Package




# The ISDC Support Software Package version 2.0 contains the following components:
#
# ISDC makefiles
#
    makefiles        2.1.1      changed
#
# ISDC templates
#
    templates        2.0        changed
#
# ISDC libraries
#
    cfitsio          2.0.37.1   changed
    cfortran         4.3
    common           1.3.4      changed
    dal              1.4.5      changed
    dal3aux          3.2.0      changed
    dal3cat          2.4.1      changed
    dal3gen          3.2.1      changed
    dal3hk           2.6.1      changed
    dal3ibis         3.2.0      changed
    dal3jemx         3.2.0      changed
    dal3omc          3.1.0      changed
    dal3spi          3.2.0      changed
    ril              3.0
    pil              1.5.1      changed
    sla_c            2.1
    sla_f90          2.1.2      changed
#
# ISDC tools
#
    isdcroot         1.6        changed
    dal_attach       1.1
    dal_create       1.0
    dal_detach       1.0
    dal_list         1.0
    dal_verify       2.0
    idx_add          2.3        changed
    idx_find         2.1        changed

	

1.3 Getting the ISDC Support Software Package



If you have not yet downloaded the ISDC Support Software Package, you can grab it from the ISDC WWW Software page:

http://isdc.unige.ch/Software/sw/sys-sw/support-sw/support-sw-2.0.tar.gz

2. Changes since the last version

1. The ISDC Reference Platform has significantly changed. The most prominent changes impacting on the Support Software are:
   • The Operating System is now Solaris 2.8 -- previously 2.6
   • The compilers (C/C++ and FORTRAN) are now Sun Forte 6.0 -- previously Sun Workshop 5.0
   • GNU make is now version 3.79.1 -- previously 3.77
   • ROOT is now version 2.25.03. -- previously 2.24.02 (see also section 3.3).
   • The NAG library is now part of the 'Reference Software' section of the Reference Platform. NAG used to be part of the Support Software. See also Note 2 of section 3.4.
2. For details on the changes, please refer to the CHANGES files of the individual components.

3. Installation Guide

NOTICE:

Please read sla_c/LICENSE file before installing this package.

3.1 Introduction

The whole process of building SUPPORT-SW library is automated using Makefile and configure scripts. The goal is to achieve portability across different architectures. Version 2.0 of SUPPORT-SW has been tested on the following Reference Platform:

Sun Solaris 8

It has also been tested on the following secondary platform:

(unknown) Linux 2.2.x

To successfully compile and install SUPPORT-SW one needs the following generic UNIX tools:

C compiler (required)
system utilities like make, gzip, sed and tar (required)
F90 compiler (optional)
C++ compiler (optional)
ROOT (optional)


Note: The GNU version of make v. 3.79.1 must be used.
Be aware of the fact that the version of GNU make has changed with respect to Reference Platform 1.6.
!!!! REALLY, YOU NEED GNU MAKE !!!!
It will not work with SUN's make, for instance.

On Solaris, the C/C++ and F90 compiler should be SUN Forte 6 C/C++ and F90 Compilers. On Linux, gcc 2.95.2 C compiler, g++ 2.95.2 C compiler and Fujitsu Fortran 95 Express 1.0 F90 compiler have been used. Note that the SUN Workshop 5 C++ requires patches. Please ask your system administrator to install the patches as described on the Reference Platform definition WWW page.

SUPPORT-SW is self contained, and therefore does not require any other package apart from those listed above. SUPPORT-SW library may compile/run on other architectures, but efforts to compile, test and support any other platform than the Reference Platform are limited. To install SUPPORT-SW, about 150 MB are required temporarily for the compilation results. The installation directory will contain about 41 MB.

3.2. Unpacking the package and setting up the directory structure

The user must first decide where the libraries will be installed. The ISDC_ENV environment variable should be set to this directory:
>> setenv ISDC_ENV my_install_dir

my_install_dir MUST BE an absolute path!

Please note that this directory (and its subdirectories) should not contain any previous version of ISDC libraries. The best solution is to have it empty (directory itself should exist).

If you have not downloaded the SUPPORT-SW package, you can grab it from the ISDC WWW Software page:

http://isdc.unige.ch/Software/sw/sys-sw/support-sw/support-sw-2.0.tar.gz

After having downloaded the SUPPORT-SW package, the user has to move it to an empty directory ("my_source_dir") in which he or she has read and write permission. It is recommended that this directory is ${ISDC_ENV}/support-sw. This way the directory layout will match that of ISDC. The user has then to enter this directory, to which she/he will also have to copy the Support Software Package tar-file:

>> cd my_source_dir

Then the following should be done:

>> gzip -d support-sw-2.0.tar.gz
>> tar xvf support-sw-2.0.tar

The first line uncompresses the distribution file, the second unpacks files from tar file, creating many files and subdirectories.

3.3 Setting up ROOT

Note: IF YOU DON'T WANT TO BUILD ROOT-DEPENDENT TOOLS, SKIP THIS SECTION.

Once ROOT is installed, three points must be checked to make sure that compilation of ROOT-dependent tools will be successful:

• The ROOTSYS environment variable points to the directory where the ROOT dynamic libraries, include files and executables can be found
• The directory where the ROOT dynamic libraries are sitting must be accessible by the dynamic linker. So you must type:
  >> setenv LD_LIBRARY_PATH $ROOTSYS/lib:$LD_LIBRARY_PATH
• The ROOT executables must be in your execution path, so you must type:
  >> setenv PATH $ROOTSYS/bin:$PATH

A very convenient way to test whether the three above points are set correctly is to type:

>> root

If you indeed enter ROOT, ROOT is set correctly. (Type ".q" to exit from ROOT)

3.4 Auto-configuring Makefiles

Before attempting auto-configuration, the directory tree has to be set to the clean state. This is done with the following command:
>> make distclean

This command deletes any existing object files, executables produced by build process, config.cache, Makefile produced by previous run of configure script. This is not necessary when one untars the SUPPORT-SW in a clean directory, but it nevertheless never hurts to type this command. In the worst case, you would get the error message:

make: *** No rule to make target `distclean'. Stop

This can be safely ignored.

The auto-configuration script (being a GNU product!) favors gcc over other C compilers. So if one has gcc and other C compiler installed on the system, it is possible to force the use of another compiler by setting the CC environment variable. On the Reference Platform (SUN Solaris), the Workshop C Compiler is selected by typing:

>> setenv CC cc

Similarly, the Workshop F90 Compiler is selected by typing:

>> setenv F90 f90

The compilers must be in your execution path.

Note 1:


If you use the combination "gcc + Fujitsu F90 compiler", you have to type instead:
>> setenv CC "gcc -Df2cFortran"

Other combinations of C/F90 compilers may require other symbols.

Note 2:


The default setting for the NAG library is libnag.a. If at your site, you have a different name for the NAG library, you may change the default value by typing:
>> setenv NAGLIB _your_NAG_library_name_

For example one would have to type 'setenv NAGLIB nagff' if the site specific name is libnagff.a.

To link any component with the NAG library, one has to do the following:

In the component specific makeisdc1.in instead of 'hard-wiring' the name of the NAG library (e.g. -lnag) one should specify -l$(NAGLIB).

To auto-configure SUPPORT-SW one has to run the configure script provided with the SUPPORT-SW package by typing:
>> makefiles/ac_stuff/configure

in the directory where SUPPORT-SW has been untarred.

Please note that all the "setenv"'s must be made before configuring. If you change your mind about the value of an environment variable, you must redo the configuration.

The configure script will recursively descend and create the Makefiles into each package.

If you don't want to compile Fortran 90 support, you can explicitly disable it by typing:

>> makefiles/ac_stuff/configure --without-fortran90

Similarly, compilation of ROOT-dependent packages is disabled by typing:

>> makefiles/ac_stuff/configure --without-isdcroot

Note that you can always reconfigure your system with different options. Typing `make distclean' may however be necessary in some cases. After the first configure has been made, one can simply type: `ac_stuff/configure' instead of `makefiles/ac_stuff/configure'.

The `configure' script analyses the system on which is run and produces `Makefile' according to rules defined in `Makefile.in', adapting it to the architecture of the machine on which is run. Specifically, it checks whether C and F90 compilers are workable. If F90 compiler is not present Makefile will contain only those parts relevant to C code. If the F90 compiler does not support 8 byte, compilation will not succeed.

Note: Efforts to port ISDC libraries on other platforms and set of compilers are limited. Therefore the configure script may fail when run on unsupported platforms.

3.5 Compilation and Installation of SUPPORT-SW

If the environment variable ISDC_ENV points to /isdc/dev, you must first type:
>> setenv ISDC_DEV_ALLOW_GLOBAL_INSTALL yes

Compilation and installation of SUPPORT-SW are made in one single step by issuing the command :

>> make global_install

This will compile all relevant source files and create the library files, the F90 modules, and the C and F90 sample executables. The installation terminates by moving the library, the C header, the F90 module and the User's Manual to the correct location in the ISDC system tree. If everything went fine, you should see the following message:

  ************ everything compiled and installed successfully ***********

  executables/parameter files are installed in     : /isdc/dev/bin
  F90 modules are installed in                     : /isdc/dev/f90mod
  documentation, help, .txt files are installed in : /isdc/dev/help
  C/C++ include .h files are installed in          : /isdc/dev/include
  .a, .so library files are installed in           : /isdc/dev/lib
  FITS file template files are installed in        : /isdc/dev/templates

	

Instead of /isdc/dev, you will see: `my_install_dir'

To get rid of the results of the compilation, one can type:

>> make clean

or even (this removes in addition the results of configure script):

>> make distclean

These commands work recursively in the entire SUPPORT-SW tree.

Note: If you type twice `make distclean' consecutively, you may get an error message. Just re-launch configuration if needed.

It is even possible to remove completely the source tree, as the User's Manual files are copied in the ${ISDC_ENV}/help directory. It means that you can safely type:

>> cd ..
>> rm -r my_source_dir

In the directory pointed to by ISDC_ENV.

Note: DON'T CLEAN THE DIRECTORY IF YOU WANT TO PLAY WITH THE SAMPLE PROGRAMS, AS THEY ARE NOT INSTALLED. You can always re-make them, except if you remove the directory.

3.6 Sample Executables

Each library is accompanied with C and F90 sample programs that both show whether the compilation of the libraries has succeeded, and give examples of how to use them.

Information about the sample programs is to be found in the individual packages.

3.7 Additional Comments on isdcroot

In the version included in the support-sw, isdcroot will compile only on the Solaris Reference Platform and on the Linux secondary platform. If you wish to install isdcroot on a different platform, you will have to modify manually the Makefiles provided in the isdcroot package. Please ask ISDC Help-desk (isdc-help@obs.unige.ch) for help in this case.

If you think you have the Reference Platform or the secondary platform and compilation of isdcroot fails, please make sure that you have the correct compiler, the correct version of the OS and (on Linux) of the C/C++ standard libraries.

4. Known Problems

As of the writing of this note, the following Software Problem Reports (SPR) have not been closed:
106, 108

and the following Software Change Requests (SCREW) have not been implemented:

107

Please refer to the ISDC Change Control WWW-pages http://isdc.unige.ch/index.cgi?Changectrl+changectrl for more details.

5. Getting Help

If you have problems installing or using the ISDC Support Software Package, please send an E-mail to isdc-help@obs.unige.ch