source: Sophya/trunk/SophyaLib/Mgr/README@ 4066

========================== Mgr Module =========================
============= Code Management scripts for SOPHYA ==============
===============================================================

List of modules:
==================

* Mgr/           Scripts for code management and makefiles
* BaseTools/     General architecture support classes
* SysTools/      Interface to various services provided by the operating system
* SUtils/        Utility classes and functions
* TArray/        Template numerical arrays, vectors and matrices
* SkyMap/        Local and full sky maps
* SkyT/          Spectral emission and detector frequency response modelling   
* Samba/         Miscellaneous classes (TOD analysis, Spherical Harmonics, ...)
* NTools/        Some standard numerical analysis tools 
* HiStats/       Histogram-ming and data set handling classes

Modules using external library 
* FitsIOServer/  FITS format file I/O (interface with cfitsio library)
* LinAlg/        Interface with Lapack linear algebra package
* IFFTW/         Interface with FFTW package
* XAstroPack/    Interface with astronomy library (XEphem)
                 The XEphem library code is in the SOPHYA module XephemAstroLib

* XephemAstroLib/ The code of the external XEphem astronomy library, extracted from XEphem

Modules with main programs
* Tests/         Simple test programs

* PMixer/        skymixer and utility main programs

* PrgUtil/       Utility main programs

* PrgMap/        Utility main programs for sky map manipulation

PI/piapp GUI and interactive analysis framework

* PI/            GUI class library and application framework
* PIGcont/       PI contour drawer
* PIext/         specific GUI objects for SOPHYA classes and piapp framework
* ProgPI/        interactive analysis tool using SOPHYA, PI PIGCont and PIext


Compilation and software installation:
======================================

The build procedure for the present version of SOPHYA has been 
tested on :

Operating system            Compiler
......................................................................
Compaq/DEC OSF 5.1           cxx 6.3         (shared-library only)
Compaq/DEC OSF 5.1           g++ 2.95        (shared-library only)
SGI                          CC  7.30        (shared-library only)
Linux                        KCC 3.4         (shared-library only)
Linux                        g++ 2.95        (static and shared library)
MacOSX/Darwin 10.1           c++/gcc 2.95    (shared-library only)

The environment variables  SOPHYADEVREP EXTLIBDIR SOPHYACXX must be defined
for building and installing the libraries.

$SOPHYACXX is the name of C++ compiler being used.
$SOPHYADEVREP is the path to where the libraries and executables will be put.
$SOPHYADEVREP/Include : header files
The libraries and binaries will be put in subdirectories containing 
the operating system name and the compiler name: `uname`-$SOPHYACXX
For example, on a Linux system, using the GNU compiler:

$SOPHYADEVREP/Linux-g++/Libs     archive librarires
$SOPHYADEVREP/Linux-g++/ShLibs   shared libraries
$SOPHYADEVREP/Linux-g++/Exec     binaries

The build procedure expects to find the include files and the libraries 
for cfitsio in :
$EXTLIBDIR/Include/FitsIO 
$EXTLIBDIR/`uname`-$SOPHYACXX/Libs
This would translate to Linux-g++ on a Linux system, using g++.
$EXTLIBDIR/Linux-g++/Libs

Example of c-shell commands to build the libraries:
The use of GNU make program is mandatory 

# We select our C++ compiler
csh> setenv SOPHYACXX g++
# Setup the build directory
csh> mkdir /usr/local/Sophya/
csh> setenv SOPHYADEVREP  /usr/local/Sophya/
csh> setenv SOPHYABASEREP /usr/local/Sophya/
csh> setenv EXTLIBDIR  /usr/local/ExtLibs/

# --------------- Note for SGI ---------------------
# SOPHYA can be compiled on SGI IRIX64 OS in 32 bits or 64 bit mode
# The environment variable SOPHYA_SGI64 has to be set to select 
# compilation in 64 bits mode
# ---------------------------------------------------

# Use the top level makefile in Mgr/ 
csh> cd $SRC
csh> cp Mgr/Makefile Makefile
# Step 1: Create the directory tree and copy the include files (.h)
csh> make depend
# Step 2: Compile the modules without external library reference
csh> make libs
# Step 3: Compile the modules WITH  external library reference (optional) 
csh> make extlibs
# Step 4: Build libsophya.so
csh> make slb
# Step 5: Build libextsophya.so 
csh> make slbext
# Step 6: Compile the PI and PIext modules (optional)
csh> make PI
# Step 7: Build the corresponding shared library libPI.so (optional)
csh> make slbpi


To compile all modules and build the shared libraries, it is possible to use:

# Step 2,3,6
csh> make all
# Step 4,5,7
csh> make slball

The building of shared libraries on SGI can be also done using the script 
mkslbsgi.csh in Mgr/

csh> cp Mgr/mkslbsgi.csh .
csh> mkslbsgi.csh slball

# To compile test programs
csh> cd Tests
csh> make arrt ...
csh> cd ..
# To compile other programs, for example from the PMixer module
csh> cd PMixer
csh> make
csh> cd ..
# To build (s)piapp (libPI.so is needed)
csh> cd ProgPI
csh> make 
csh> cd ..

Notes:
======
1) We had to build the shared libraries on our SGI system using the 
script (mkslbsgi.csh). The corresponding CC command was not performing
correctly when issued by the GNU make program
2) The top level Makefile should be modified if one wishes to use 
static libraries, except for g++. The compiler driver has to be 
invoked for building archive libraries, in order to include 
template instanciation into the archive.



Scripts in Mgr/ module :
========================

* chk_cvs.csh : Compares/updates modules using CVS
  Usage: chk_cvs.csh [-a] [-all] [-nos] [-u] [r]
         chk_cvs.csh  -h  for help
  Example :
  Cmd> Mgr/chk_cvs.csh -u  
  Updates all modules 

* crerep_sophya
  Creates the directory tree structure :
                             $DEV/BASEREP/Include
                                         /OSF1-cxx/
                                         /OSF1-cxx/Objs
                                         /OSF1-cxx/Libs
                                         /OSF1-cxx/ShLibs
                                         /OSF1-cxx/Exec/
                                         ....
  Usage: crerep_sophya <nom des repertoires> [nom_machine-compilateur]
  Example :
  Cmd> crerep_sophya $SOPHYADEVREP OSF1-cxx 
  Cmd> crerep_sophya ~/Work/ Linux-g++

* install_sophya
  Install SOPHYA libraries/include files from dev directory ($SOPHYADEVREP)
  to the install ($SOPHYABASEREP) directory
  Copy files Include/*.h Libs/*.a ShLibs/*.so Exec/*

  Usage: install_sophya <-s repertoire source> <-d repertoire destination>
                      [-m nom_machine-compilateur]
  Example 
  Cmd> install_peida -s  ~/Work  /exp/Planck/DPC

* mkmf
  Creates a GNUmakefile in each library module and the global 
  GNUmakefile at top level

  Steps :
  - mkmflien : Creates symbolic links for all header files in $SOPHYADEVREP/Include

  - mkmflib : Creation of a GNUmakefile in each library module

  - mkmfPI : Creation of a GNUmakefile for PI and PIext module

  - Top level makefile creation


* mkmflib 
  Creation of the GNUmakefile for a library module
  The file exclude in the module directory may contain the 
  list of source files (.cc .c) not to be compiled.
  Usage: mkmflib ModuleName
  
* mkmfprog
  Creation of the GNUmakefile for a module containing 
  the main programs 
  Usage: mkmfprog ProgModuleName