********************************************************
* NOTE: This document is OBSOLETE, look into the User Manual
* doc/E3D.pdf for detailed instructions.
*
* Installation of E3D, the Euro3D visualization tool
* Version 1.2
*
* S.F.Sanchez, 17.03.04
*
********************************************************

CONTENT:

1.- Instroduction and Requisites

2.- E3D pre-installation
    2.1.- PGPLOT installation
    2.2.- LCL installation

3.- E3D Installation

4.- Known Problems

[1] Requisites
-----------------------------------------

E3D is the Euro3D visualization tool, a tool for visualizing Integral
Field Spectroscopy (or 3D) data. It uses as "native" format the Euro3D
data format (Kissler-Patig et al., 2004, AN, 325, 159).  Computed
under C and Tcl/Tk, it uses the LCL library (Pecontal-Rousset et
al. 2004, AN, 325, 163) as I/O library, and PGPLOT (T.Pearson,
http://www.astro.caltech.edu/~tjp/pgplot/) as graphical library.

Prior to install E3D it is needed to install and test both PGPLOT
(with certain expecific drivers) and LCL. This will be described in
the pre-installation.

Once described how to install both libraries we will describe how to
install E3D.

[2].- E3D pre-installation
------------------------------------------

 For consistency we recomend that all the libraries needed for running
 E3D would be installed in the same directory tree. Lets name this
 directory DIR=directory.

 [Note: In the case of LCL is mandatory to do so]

 [2.1].- PGPLOT installation
 ---------------------------
 E3D uses the version 5.2 of PGPLOT. You can download PGPLOT from the 
 webpage:
 http://www.astro.caltech.edu/~tjp/pgplot/
 [pgplot5.2.tar.gz]
 or from our webpage:
 http://www.aip.de/~ssa/euro3d/pgplot5.2.tar.gz
 
 Copying the tar file, decompressing and untar would create a
 directory named "pgplot". The installation of PGPLOT is well
 described in file "install-unix.txt", under this directory.
 We recomend the following steps:

 (a) Copy the "drivers.list" distributed with E3D (in the "data"
 directory of the E3D directory tree or from the web:
 http://www.aip.de/~ssa/euro3d/drivers.list

 (b) Run the command:
     ./makemake /work2/ssa/pgplot linux g77_gcc

  [Note: In case of not a linux system you should run,
     ./makemake 
  and follow the instructions]

 (c) Run the command:
     make

 (d) Run the command:
     make cpg

 (e) Define the following enviromental variables:
     PGPLOT_DIR = DIR/pgplot/
     PGPLOT_DEV = /xs
     LD_LIBRARY_PATH = ${LD_LIBRARY_PATH}:${PGPLOT_DIR}
     where DIR is the recommended directory tree.
     E.g., for a tcsh shell:
     setenv PGPLOT_DIR /directory/Euro3D/pgplot/
     setenv PGPLOT_DEV /xs
     setenv LD_LIBRARY_PATH  ${LD_LIBRARY_PATH}:${PGPLOT_DIR}

  (f) Run the Tcl/Tk demo:
      ./pgtkdemo.tcl
      This demo should open an interactive GUI.

 [2.2] - LCL installation
---------------------------
   You can download the LCL library from the Euro3D internal webpage
   or from:
   http://www.aip.de/~ssa/euro3d/E3D_io_LCL-1.0c.tar.gz

   The installation of LCL is well documented in the document that you
   can find under the "doc/InstallationGuide-1.0a" directory.
  
   The installation steps are summarized here:
   (a) Copy the tar file to the directory DIR.
   
   (b) Decompress and untar the file.
  
   (c) Go to the created directory, e.g., 
       cd E3D_io_LCL-1.0c

   (d) ./configure
   
   (e) make

   (f) define the enviromental variables: 
       IFU_PATH and IFU_DEFAULT_FMT

       E.g., for a tcsh shell

      setenv IFU_PATH "DIR";
      setenv IFU_DEFAULT_FMT "Euro3D";
 
     [[Note: The IFU_PATH points to DIR not to DIR/E3D_io_LCL-1.0c]]

   (g) go to the directory:  
       cd checklib/exec
       and run the test program:
       ./check_E3D_io

       If all the tests are ok, then you have LCL properly installed.

[3] E3D installation
--------------------
   Once you have installed PGPLOT and LCL, and tested them, you can
   install E3D.
   You can download E3D from the Euro3D internal webpage or from:
   http://www.aip.de/~ssa/euro3d/e3d-1.2.tar.gz

   The installation of E3D is documented in the document E3D.ps under
   the "doc" directory of E3D.   

   The installation steps are summarized here:
   
   (a) copy the tar-gzip file to the directory DIR.

   (b) decompress and untar the file.

   (c) go to the created directory (e.g., e3d-1.2)

   (d) Run:
       ./configure
   (e) Edit the file:
       add_defs/makedefs.local
       You will find different definitions of V3D_LIBS, for 
       different architectures. Please, decoment the one
       that fits better with your computer.
   (f) Run:
       make

   (g) go to the scripts directory (i.e., cd scripts).
  
   (h) Run:
       ./install.pl

   (i) Add the "user/bin" directory to your PATH.
       E.g., for a tcsh shell:
       setenv PATH = ${PATH}:DIR/e3d-1.2

   (j) Run:   
       tk_e3d.tcl
       This is the E3D GUI. For testing it, you can load the file
       "test.fits" under the "scripts" directory.

 [Note: We recomend that once compiled E3D, you create a symbolic
 link, to a generic directory (e.g., e3d) and add that to the PATH,
 instead the current version directory:
    cd DIR
    ln -s e3d-1.2 e3d
    setenv PATH = ${PATH}:DIR/e3d	
 The reason for doing so is that E3D is a program under development,
 and therefore new versions would be available with the pass of time.
 Once you have compiled a new version you have to change only the
 symbolic link]


[4] Known problems
------------------

(*) When I run the ./makemake for installing PGPLOT I got a message
    saying that I cannot find F77 (or G77) or that it does not
    generate executables.

    Reasons:
    (a) In certain "default" Linux distributions fortran it is not
    included (e.g., Suse). Therefore, since there is no fortran
    compiler it is not possible to install PGPLOT. You need to
    download a fortran compiler or expecify this package using your
    distribution installation tool (e.g., yast).

    (b) There is a redefinition of the G77 enviromental variable.
    If you have installed IRAF in your computer, using the CD "Linux
    for Astronomy", or similar, it does include a redefinition of G77
    (or F77),pointing to a non standard script that does not necesary generate
    executables. For checking that you should do:
    echo $G77 or echo $F77
    if it points to a certain script, then should redifine it prior to
    install PGPLOT:
    e.g., setenv G77 g77

(*) When I run the ./make for compiling PGPLOT I got an error message
    saying that it cannot find the "tk" or/and the "tcl" libraries.

    Reasons:
    (a) You do not have tcl/tk libraries installed in your computer.
    This libraries are normally distributed with the mayority of the
    Unix/Linux OS, however we have found cases where this is not the
    case.

    For testing if you have the tcl/tk libraries installed you should
    try:
    ls /usr/lib/libtk* 
    ls /usr/lib/libtcl*  
    or 
    ls /usr/lib/local/libtk* 
    ls /usr/lib/local/libtcl*
    
    If you do not have any of the libraries, then you have to install 
    the Tcl/Tk libraries.  For doing so, go to webpage:
    http://www.tcl.tk/
    and follow the instructions in there.

    (b) You have the tcl/tk libraries, but they do not have a symbolic
    link between the standard name (e.g., libtk.so), and the current
    version name (e.g., libtk8.4.so). 

    You can tests that this is the reason repeating the "ls" command
    in (a). If you see the libriries (e.g., /usr/lib/libtk8.4.so) but
    not the standard name (e.g.,  /usr/lib/libtk.so), then you do not
    have this link.
    We have found this problem under certain Suse distributions, and
    under Solaris. 

    (Solution A)
    For solving this problem you have to edit the "makefile" under the 
    PGPLOT directory, and change the definition of TK_LIBS, from the
    default definition:
    TK_LIBS=-L/usr/lib -ltk -ltcl -L/usr/X11R6/lib -lX11 -ldl
    to:
    TK_LIBS=-L/usr/lib -ltkN.N -ltclN.N -L/usr/X11R6/lib -lX11 -ldl
    Where N.N is the version number of the tcl/tk library (that you
    get from the "ls").
    e.g.,
    TK_LIBS=-L/usr/lib -ltk8.4 -ltcl8.4 -L/usr/X11R6/lib -lX11 -ldl

    (Solution B)
    If you have superuser access in your machine, then you may try to
    do a symbolic link between the physical libraries (libtk8.4 and
    libtcl8.4) in the directory /usr/X11R6/lib, and the expected ones
    (libtk and libtcl). In that case you should not apply solution A.


(*) I have compiled PGPLOT and the LCL library, but when I try to
    compile E3D, running "make", it breaks when trying to compile 
    "Euro3D.c". I got the message:

    Euro3D.c:17:43: IFU_io.h: No such file or directory
    Euro3D.c:18:41: data_io.h: No such file or directory

    In this case the compiler cannot find the LCL library path.
    This could be due to the use of a wrong version of LCL, or
    an inconsistency between the installed version and the version
    that has been indicated to E3D to look for.

    For checking this you should look for the name of the parent
    directory of the LCL library directory tree. It should be
    something like:
    E3D_io_LCL-1.0c  (i.e., version 1.0c of LCL)

    Read the file "add_defs/makedefs" under the E3D arquitecture.  The
    first not commented line includes the definition of the directory
    of where to look for the LCL library (stored in the variable
    C_ioLIBS_PATH). It should be:    
    C_ioLIBS_PATH = $(topdir)/../E3D_io_LCL-1.0c

    If you have another version of the LCL library (e.g., the 1.0a)
    you should modify this file prior to compile.
        
        

    






