***************************************************************************

          	   Frequently Asked Questions
      (written and maintained by J.Pety, pety@iram.fr, 2003)

***************************************************************************

Summary
-------

1. GILDAS dependancies

  1.1 What are the prerequisite to compile GILDAS?
  1.2 Where is available cfitsio?
  1.3 Where is available Intel f90?

2. Getting, compiling and installing GILDAS

  2.1 How to get the last version of the soft?
  2.2 How to compile GILDAS?
  2.3 How to test GILDAS?
  2.4 How to install GILDAS?
  2.5 How to move GILDAS?

3. Compilation troubleshooting

  3.1

4. Machine/OS/Compilers

  4.1 What is the list of machine/OS currently supported?
  4.2 How to compile GILDAS on another machine/OS?
  4.3 What is the list of compiler currently supported?
  4.4 How to compile GILDAS with another compiler?

5. Coexistence of different GILDAS versions

  5.1 When do I need several concurrent version?
  5.2 What are the needed requirements to be able to survive with several
      concurrent versions?
  5.3 What are the standard directory name conventions for GILDAS?
  5.4 How do I build several concurrent versions?
  5.5 How do I deal with several concurrent version as an end-user?
  5.6 How do I deal with several concurrent version as a developer?

6. GILDAS developer's corner

  6.0 How do I get write access to the repository?
  6.1 How do I set up my own working copy from the repository?
  6.2 Why all the files in my working copy are in read-only mode?
  6.3 How the repository knows I am finished editing the code?
  6.4 Can I check-in data into the CVS repository?
  6.5 What should my .bashrc look like?

7. GILDAS maintainer's corner

  7.0 Description of the GILDAS adminstrative scripts
  7.1 What is the GILDAS release policy?
  7.2 How is the monthly release build?
  7.3 How do we correct a bug in a monthly release?

***************************************************************************

1. GILDAS dependancies
----------------------

1.1 What are the prerequisite to compile GILDAS?

  You need:
    - a UNIX/LINUX box;
    - a Fortran-90 compiler;
    - GNU make;
    - the LessTif library installed;
    - (optionnally the cfitsio library installed if you want the
       ALMA-TIFITS support).

1.2 Where is available cfitsio?

1.3 Where is available Intel f90?

***************************************************************************

2. Getting, compiling and installing GILDAS
-------------------------------------------

2.1 How to get the last version of the soft?

  > cd $HOME
  > export CVSROOT=:pserver:anonymous@cvs.iram.fr:/CVS/GILDAS
  > cvs co gildas-src

  This will give you read-only access to the current state of the software.

2.2 How to compile GILDAS?

  > cd $HOME/gildas-src
 (> sh)
  > source admin/gildas-env.sh
  > make

  Please note that:

  a. You must set LD_LIBRARY_PATH to point to your fortran compiler
     libraries. This is site dependant and thus is not set automatically by
     gildas-env.sh. For instance for the lf95 compiler (at IRAM):

         export LD_LIBRARY_PATH=/opt/lf9561/lib

     and for the Intel Fortran 90 (at IRAM):

         export LD_LIBRARY_PATH=/usr/local/FortranIntel-7.1/compiler70/ia32/lib

  b. You must use the Bourne shell or any compatible shell (e.g. bash) but
     not csh. The "sh" will ensure that.
  c. The gildas-env.sh script reset up your $PATH and $LD_LIBRARY_PATH
     variables so that you can test your compilation before installing it.
  d. You must use the GNU make (default linux make). It may be called
     gmake on your system.

2.3 How to test GILDAS?

  Basic testing facilities are available through the demonstration
  procedures. The available list is:

  > cd $HOME/gildas-src/kernel/demo;           sic @ demo.sic
  > cd $HOME/gildas-src/kernel/demo;          greg @ demo.greg
  > cd $HOME/gildas-src/packages/astro/demo; astro @ demo.astro
  > cd $HOME/gildas-src/packages/map/demo; mapping @ demo.map

2.4 How to install GILDAS?

  > cd $HOME/gildas-src
 (> sh)
  > source admin/gildas-env.sh
  > make install

  The same restrictions as for the compilation apply (cf. section 2.2).
  The default executable tree will have $HOME/gildas-exe as root
  directory. If you want to install GILDAS into this-directory instead, you
  have to type:

  > make prefix=this-directory install

2.5 How to move GILDAS?

  Once the installation process is finished, you end up with an executable
  tree. It is possible to move the executable tree elsewhere at the
  condition that you edit the two configuration files of GILDAS to reflect
  this change of position. If your root directory of your executable tree is
  named "gildas-exe", then you need to edit the following files:

    gildas-exe/machine-os-compiler/etc/bash_profile
    gildas-exe/machine-os-compiler/etc/gag.dico.gbl

***************************************************************************

3. Compilation troubleshooting
------------------------------

dlsym

***************************************************************************

4. Machine/OS/Compilers
-----------------------

4.1 What is the list of machine/OS currently supported?

  At least:
    - 32 bits PC/Linux

  For an up-to-date list, please look into the admin/Makefile.def file of
  the distribution. In principle, every UNIX/Linux machine should be
  supported.

4.2 How to compile GILDAS on another machine/OS?

  Please first read section 2 to be sure to understand the standard
  compilation and installation procedure. Then this is a three-step
  process:

    1. Ensure that your system is recognized by the building mechanism.
       To do this, you have to edit the $gagdir/admin/define-system.sh
       script (this script is called by the gildas-env.sh script). Here is
       the part to edit:

       case `uname` in
	   Linux)
	       MACHINE=pc
	       OS_KIND=linux
	       if [ -f /etc/redhat-release ]; then
		   OS_VERS=redhat`cut -d" " -f5 /etc/redhat-release`
	       else
		   OS_VERS=linux
	       fi
	       DEF_COMPILER=ifc ;;
	   *)
	       defsys_error "Unknown operating system. Sorry"
	       return 1
       esac

    2. Then you have to modify the names of the commands used during
       compilation and installation and the compilation flags. All these
       information are grouped in the $gagdir/admin/Makefile.def file. So
       you just need to edit this file. You have to add a section like the
       following one:

       ifeq ($(GAG_COMP_SYSTEM),pc-linux-lf95)
	 GLOBAL_CPPFLAGS = -P -traditional -C -D LF95="lf95" -D IEEE="ieee"
	 CC = gcc
	 GLOBAL_CFLAGS = -pipe -c -O -Dlinux -Dunderscore -I/usr/local/include -I/usr/X11R6/include
	 FC = lf95
	 GLOBAL_FFLAGS = -I$(incdir) --mod .:$(incdir) --chk=u --in --trace --swm 1041
	 LIB_EXT = a
	 LINEAR = lapack
       endif

    3. Finally you need to build GILDAS as explained in section 2. You may
       encounter compilation errors that are not catch by the compilers
       used daily at IRAM. Please try to understand and correct them if you
       know enough of FORTRAN, which is probably the case if you are
       reading this section. If you do not succeed, please send the last
       50 lines output by the make command.

  When the compilation succeeded, please email us the changes you did to
  ensure that we include them in the next GILDAS compilation for your
  convenience.

4.3 What is the list of compiler currently supported?

  At least:
    - HP    f90
    - Intel f90
    - Lahey f95

  For an up-to-date list, please look into the admin/Makefile.def file of
  the distribution. In principle, every Fortran-90 compiler should be
  supported.

4.4 How to compile GILDAS with another compiler?

  Please follows the same steps as in 4.2.

***************************************************************************

5. Coexistence of different GILDAS versions
-------------------------------------------

5.1 When do I need several concurrent versions?

  Here are a few cases when you may need concurrent version of GILDAS on
  the same hard disk:
    - The same version of the sources compiled and stored on the same
      machine but compiled with two different compilers.
    - The same version of the sources compiled on different machines but
      stored on a centralized file system.
    - Different version of the source compiled and stored on the same
      machine. For instance, developers may want a stable and a
      development version on their laptop.
  IRAM has all those needs at the same time.

5.2 What are the needed requirements to be able to survive with several
  concurrent versions?

  There must be:
    * Clear, standard conventions for the directory names where
      to store each version;
    * An easy way to build the version following the standard;
    * An easy way to select the version and source the corresponding
      environement;
    * An easy way to browse the sources of one version for developers.

5.3 What are the standard directory name conventions for GILDAS?

  The root directory of all the GILDAS version you will built is named
  $HOME/gildas. If you want, you may change that by setting the $gaghome
  environment variable to the directory name you prefer. In this directory,
  you will four kinds of subdirectories:
    1. The administrative directory named "admin" which store the common
       administrative scripts for all the built version.
    2. The log directory named "logs/version" where version may be dev,
       jan04, etc...
    3. The source directories named "gildas-src-version/system", where
       version may be dev, jan04, etc... and system is the system (ie
       MACHINE-OS-COMPILER) used to compile this particular source tree.
    4. The executable directories named "gildas-exe-version", where version
       may be dev, jan04, etc...
5.4 How do I build several concurrent versions?

  The "build" script is for you:

    1 > export CVSROOT=:pserver:anonymous@cvs.iram.fr:/CVS/GILDAS
    2 > export gaghome=$HOME/gildas
    3 > mkdir $gaghome
    4 > cd $gaghome
    5 > cvs co -d admin gildas-src/admin
    6 > cd admin
    7 > ./build -h
    8 > ./build -u -c ifc  dev
    9 > ./build -u -c lf95 dev
   10 > ./build -u jan04

  Comments:
    * Lines 1 and 2 use bash syntax. However, use of build is independant
      of the shell. So you can as well use a csh syntax to define CVSROOT
      and gaghome.
    * If you are a GILDAS developer, you should replace anonymous by your
      name in line 1.
    * "build" is not a self-contained script. This is why you need lines 2
      to 6. Maybe someday a build-init script will appear in the
      distribution...
    * Line 7 gives you up-to-date informations.
    * Lines 8 to 10 assume that you are under a linux system and will
      successively build the development version using i) the Intel F90
      compiler and ii) the Lahey F95 compiler and the jan04 monthly
      release using the default linux compiler (defined as ifc).

5.5 How do I deal with several concurrent version as an end-user?

  The "source-gag.sh" script is for you. Just put in your .bashrc file the
  following lines:

    1 export gaghome=~gildas/gildas
    2 alias  gag="source $gaghome/admin/source-gag.sh"

  Comments:
    * The "source-gag.sh" script is written in bourne shell, so you need
      to be under bash to use it. Sorry if this is inconvenient for you.
    * In line 1, you obviously should customize gaghome to fit your
      installation.

  Then, at the bash prompt:

    > gag jan04
    Selecting GILDAS version: dev (pc-redhat7.2-ifc)
    > greg
    GREG> help

  Enjoy!

5.6 How do I deal with several concurrent version as a developer?

  The "go.sh" and "source-gag.sh" scripts are for you. You should have in
  your .bashrc file the following lines:

    1 export CVSROOT=:pserver:your-name@cvs.iram.fr:/CVS/GILDAS
    2 export gaghome=$HOME/gildas
    3 alias  gag="source $gaghome/admin/source-gag.sh"
    4 alias   go="source $gaghome/admin/go.sh"
    5 #
    6 source $gaghome/admin/source-gag.sh -n -e dev
    7 source $gaghome/admin/source-gag.sh -n -s dev

  Comments
    * The "go.sh" and "source-gag.sh" scripts are written in bourne shell,
      so you need to be under bash to use it.
    * Line 1 sets up your cvs environment.
    * In line 2, you may customize gaghome the same way you did before you
      used the "build" script.
    * Line 3 defines the alias that will allow you to easily select a
      version and source the corresponding environment.
    * Line 4 defines the alias that will allow you to easily browse through
      the sources (once the version is selected).
    * Lines 6 and 7 are optional. They allow me to select a default version
      without sourcing the corresponding environment. This way, I am able
      to use go directly to browse the development version but I do not
      enforce sourcing a peculiar environment (which mean changing your
      PATH, LD_LIBRARY_PATH and others) each time you open an xterm.

  Then at the bash prompt:

    1 > go greg
    2 Going to /home/pety/gildas/gildas-src-dev/pc-redhat7.2-ifc/kernel/lib/greg
    3 > cvs edit gregsub.f
    4 > emacs gregsub.f &
    5 > gag -s dev
    6 > go kernel
    7 > make
    8 > greg
    9 GREG> help
   10 GREG> exit
   11 > go back
   12 > cvs commit -m"Stupid test" gregsub.f
   13 > make install
   14 > go -e lib
   15 > ls -l libgreg.*

  Comments:
    * Lines 1 and 2, we directly go to the dev version selected in the
      .bashrc. The default for the go.sh script is to browse the source
      tree.
    * Line 3, we warn cvs that we will change gregsub.f
    * Line 4, we modify gregsub.f
    * Lines 5 to 7, we want to compile to see the effect of our
      modification. We must first source the environment needed to ensure
      compilation success (line 5). Changing of working directory line 6
      allows us to compile both the library and the library dependencies
      (ie greg) with only one make command line 8.
    * Lines 8 to 11, we are able to test the change. As we are using the
      source tree environment, we need to call greg and not greg (this is
      a trick to have a better control).
    * Line 11, we go back to the greg lib directory.
    * Lines 12 and 13, we commit and install our changes.
    * Lines 14 and 15, we verify that the changes correctly appears in the
      executable tree.

***************************************************************************

6. GILDAS developer's corner
----------------------------

6.0 How do I get write access to the repository?

  The repository is run under pserver, which means you need a password to
  gain write access to the repository. This password will saved to the
  $HOME/.cvspass file and will travel through internet in a very lightly
  encrypted way. So you will probably want to have a password specific to
  CVS (i.e. different from your account password).

6.1 How do I set up my own working copy from the repository?

  > cd $HOME
  > export EDITOR=emacs (or your favorite editor)
  > export CVSROOT=:pserver:your-name@cvs.iram.fr:/CVS/GILDAS
  > cvs login
  > cvs co gildas-src

  Then you are free to do whatever cvs enable. Do not misuse it!

6.2 Why all the files in my working copy are in read-only mode?

  This is a project wide policy to allow a developer who wants to work on
  some part of the code whether someone else is already working on it.

  If you just want the source to compile them, you do not need that the
  files are in write mode (obviously the directories are in write mode by
  default!).

  If you want to change part of the code (new feature and/or bug
  correction), you need to make the files writable. There are two
  possibilities:

    1. The BAD one: chmod -R u+w *

    2. The GOOD one: cvs edit [file/directory]

  The second possibility is the best because it not only make the files
  writable but also warns the repository that you want to make changes to
  some of the project files. When someone else wants to change the same
  files before you are finished, he/she can know that you are working on it
  just by typing: cvs editors [directory] before typing: cvs edit.

  To help you, there exist a script named "go" to browse through the new
  GILDAS tree. The first command done by this script just after arriving in
  a new directory is cvs editors!

6.3 How the repository knows I am finished editing the code?

  Commiting (= check-in in CVS world) your changes is one way to tell you
  are finished. This means that after every commit your files come back to
  read-only.

  The other way is to use the cvs unedit command. Be careful when you use
  this command: as you did not commit but you want to stop editing your
  files, CVS assumes that the changes you made are scories and CVS erases
  them in your working copy. You have been warned!...

6.4 Can I check-in data into the CVS repository?

  Be careful: a CVS repository is *not* a data storage area!

  Storing data into CVS is not recommanded for two reasons:

  1. Data volume are generally large. Please think that many people will
     checkout the GILDAS tree on their computer. If you check-in data into
     CVS, people will clutter their computer with probably unwanted data.

  2. Data are generally binaries. CVS does not handle well binaries (See
     below for special precaution when adding a binary file).

  This means that data files should as much as possible be kept outside
  the repository. The current policy is to keep a binary file inside the
  distribution when either it is a file needed by a program at run time
  and it can not be easily remade or it is a small data file for demo
  purpose.

6.5 What should my .bashrc look like?

  - I like simple stuffs. I just want one GILDAS version.

      1 export CVSROOT=:pserver:your-name@cvs.iram.fr:/CVS/GILDAS
      2 export gagsrcdir=$HOME/gildas-src
      3 export gagexedir=$HOME/gildas-exe
      4 alias  gag="source $gagsrcdir/admin/source-gag.sh"
      5 alias   go="source $gagsrcdir/admin/go.sh"

    Comments:
      * Line 1 sets up your cvs environment.
      * Lines 2 and 3 must be customize to fit the way you installed your
        GILDAS version.
      * Line 4 defines the alias that will allow you to easily source the
        environment corresponding to your installation.
      * Line 5 defines the alias that will allow you to easily browse
        through the sources of your version.
      * The environment is not sourced by default to avoid cluttering your
        PATH and LD_LIBRARY_PATH variables. Just type "gag" at the prompt
	when you want to use your version.

  - I like complex stuffs. I want several GILDAS versions.

    Please look at question 5.6.

***************************************************************************

7. GILDAS maintainer's corner
-----------------------------

7.0 Description of the GILDAS administrative scripts

  For complete, up-to-date documentation, please type:

    > source script-name.sh -h

  or

    > script-name -h

  There are two kinds of scripts: public ones (ie the end-user is directly
  interacting with them) and private ones (ie they are used by the upper
  level scripts and should not directly be called by the end-user).

  Private scripts:

    * define-system.sh

	Define environment variables:
	   GAG_COMP_SYSTEM=MACHINE-OS_KIND-COMPILER,
	   GAG_EXEC_SYSTEM=MACHINE-OS_VERS-COMPILER.
	A default compiler is provided for each combination of MACHINE and
	OS. This default compiler may be overriden using the -c option.

    * define-version.sh

	Define standard directory name conventions used by the "build" and
	"source-gag.sh" scripts to enable easy coexistence of different
	GILDAS version. To do this, define the following environment
	variables:
	   GAG_VERS, GAG_TAG, SRCDIR, EXEDIR, LOGDIR

    * redefine-path

        Adds an additionnal directory path to an already existing path. Try
        to be clever enough:
	  1. To avoid adding directories which already belongs to the path;
	  2. Replace a pattern by another one to enable easy shift of used
	     GILDAS version.

  Public scripts:

    * gildas-env.sh

	Define the environment needed for compilation, test and
	installation GILDAS. It take the following steps:
	  1. Definition of:
		* gagadmdir       (administrative directory);
		* gagsrcdir       (root directory of the source tree);
		* gagintdir       (root directory of the integration tree);
		* gagexedir       (root directory of the executable tree);
		* GAG_ROOT_DIR    (root directory of the currently used tree);
		* GAG_VERS        (current gildas version);
		* GAG_EXEC_SYSTEM (MACHINE-OS-COMPILER);
		* GAG_OBSERVATORY (default observatory at ASTRO startup);
		* GAG_PAPER_SIZE  (default paper size in PostScript files).
	  2. Search for useful, but non-essential GILDAS dependencies (ie
	     CFITSIO, PNG) in the LD_LIBRARY_PATH. Default to sensible
	     solution when not found.
	  3. (Re)define needed paths for full use of the source tree in
	     place (ie before installation). Some of the (re)defined paths
	     are also useful at compile time.

    * show-path

         Print long paths in an human readable format. Come in handy when
         you search for a special directory into a very long path.

    * go.sh

        Enable easy browsing through GILDAS sources or executables by
	providing shortcuts. When browsing the sources, verify whether
	others are already editing the target directory. The default
	browsed GILDAS trees are defined by the $gagsrcdir and the
	$gagexedir environment variables.

    * source-gag.sh

        Source the GILDAS environment of either the source tree (defined by
        $gagsrcdir) or the executable tree (defined by $gagexedir). When
        the $gaghome enviroment variable exists, source-gag.sh first
        defines the $gagsrcdir or the $gagexedir using standard conventions
        (see build script). Else source-gag.sh assumes that $gagsrcdir or
        $gagexedir have been defined elsewhere by the user.

    * build

        (Re)build (ie get, compile and install) a GILDAS version using standard
	directory name conventions. A log of all command output is automatically
	kept. When used with the "source-gag.sh" script, it enable easy coexistence
	of many different GILDAS version. However, it may also be used to regularly
	rebuild just one version.

    * rebuild-iram

	Script used:
	  1. To rebuild every night the development version of GILDAS on
	     all systems available at IRAM. When compilation on all systems
	     is a success, tags the version as "last" (for last fully
	     compilable version);
	  2. To build the monthly version on all IRAM systems.
	An abbreviated log is sent to the GILDAS maintainer. When restarted
	by hand after a bug correction, this scripts tries hard to rebuild
	only what is affected by the bug fix. This script is triggered by a
	cron job as described in the "rebuild-iram.cron" file.

7.1 What is the GILDAS release policy?

  The release policy of GILDAS is based on the following assumption: If the
  soft compiled correctly, there is no reason why a snapshot should be less
  bugged than another one. At regular interval, a release is thus
  automatically issued for distribution outside IRAM. As the main trunk of
  the CVS repository is used by GILDAS developers, a branch is created at
  release time. This way bugs of the release may be corrected along the
  branch without interfering with current developments. The branch will
  naturally die at the next release when a new branch will be created. If
  no bugfixes are needed for this particular release, the branch will not
  be used at all. When a bug is fixed into the current branch, it should
  most often be corrected in the main trunk. The interval between two
  releases must thus be small enough to avoid code divergence between the
  branch and the trunk. However it must be large enough to avoid too much
  book-keeping.  A monthly release seems a good compromise. Only the last
  release will be maintained. If a bug is found into an older release, it
  should be fixed in the last release only (due to manpower shortage) and
  the user should be asked to upgrade.

		 Branch R1           Branch R2
	      _________________   __________________
	     /                   /
     _______/___________________/_________________________ main trunk
	    |                   |
	 Release R1         Release R2

7.2 How is the monthly release build?

  The first day of every month after the daily build a release is
  automatically issued. The steps used are the following:

    1. A new branch is started from the main trunk. This branch starts at
       the last "stable" daily build to avoid releasing uncompilable
       software. The name of the branch is made from the three first
       letters of the name of the starting month followed by the two last
       digits of the current year (e.g. oct03). The choice of the current
       month is due to the fact that most bug fixes will happen during this
       month: the name of the branch to correct is thus obvious.
    2. The branch is then immediately tagged with the name of the release,
       i.e. the name of the branch followed by a (e.g. oct03a). This just
       means that up to 25 bug fixes (from b to z) could be released.
    3. A gzipped tarball is then created for distribution.

7.3 How do we correct a bug in a monthly release?

  Let's say that the buggy release is named "oct03d", i.e. this release is
  the 4th release issued in October 2003 due to previous bug
  corrections. Here are the actions to follow:

    1. Create a working copy that reflects the month release branch. It is
       probably better to create it independant of your development working
       copy to avoid mixing different states of the code. Here is a
       possibility that will create a branch working copy of GILDAS in the
       directory gildas-oct03

	  > cvs co -r oct03 -d gildas-src-oct03 gildas-src

       This working copy will reflect the last state of the release,
       i.e. oct03d. Be careful, you need to put the name of the branch
       (e.g. oct03) not the name of the release (e.g. oct03d). The name of
       the release will create the working copy reflecting the
       release. However you won't be able to commit the changes you do
       because this working copy is just an old snapshot: it is not a
       branch!
    2. Fix the bug (that's easy to say...) and commit to the repository as
       usual (cvs knows that you are working inside a branch).
    3. Tag the fixed state of the branch as "oct03e" and make an associated
       new release. A procedure will be available to do so.
    4. Merge the bug fix into the main trunk to avoid repeating the same
       bug fix after the next release! This is not completely obvious. A
       recommended possibility is:

	 * Turn the branch working copy into a main trunk working copy
	   typing: cvs up -A
	 * Merge the changes you have just entered into the branch with:

	      > cvs up -j oct03d -j oct03

	   The "-j" stands for join. There are two "-j" to allow you to
	   merge only from the last merged point. The first "-j" gives the
	   starting point you want to use and the second "-j" the plain
	   branch name.  This will probably save you a lot of book-keeping
	   you have already done during the last merge.  Obviously this
	   will work only if the last bug fix has been merged: so if you
	   correct a bug in a release, please merge it as soon as possible.
	 * Turn back the working copy into a branch working copy typing:
	   cvs up -r oct03

***************************************************************************
