======================== BuildMgr Module ======================
== Code Management scripts / top level makefile for SOPHYA ====
===============================================================
           (C) LAL-IN2P3/CNRS         1998-2010 
           (C) Universite Paris Sud   1998-2010 
           (C) IRFU/CEA               1998-2010
===============================================================

### README file for SOPHYA Build makefiles and scripts (BuildMgr) ####
See http://www.sophya.org and the SOPHYA overview manual for more information


====================================
A/ Software build and installation :
====================================

1/ Configuration: 
csh> cd BuildMgr/
csh> ./configure -h
configure [-sbase SOPHYABASE] [-scxx SOPHYACXX] [-incln] 
  [-minc mymake.inc]  [-compopt 'cc/cxxOptions'] 
  [-arch64] [-arch32] [-sasz64] [-ldble128] [-nofpic] [-nothsafe] [-boundcheck] [-sodebug]
  [-extp dir1 -extp dir2 ...] [-extip dir1 -extip dir2 ... ] [-extlp dir1 -extlp dir2 ... ]
  [-noextlib] [-noext fits] [-noext fftw] [-noext lapack] [-noext astro]
  [-alsofftwfloat] [-usefftw2] [-uselapack2] 
  [-wgrdl] [-epip mdir1 -motp mdir2 ...]  [-noPI] [-slballinone]
  (See SOPHYA manual/web pages for a detailed description of configure options)

###  Configuration example : 
# configure with c-fitsio, installed in /usr/local/include and /usr/local/lib, 
# with g++ as cxx compiler. The target installation directory is $HOME/SObjs/ 
# To get c-fitsio : http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html


# Create the target installation directory (if not already existing)
csh> mkdir ~/SObjs
# Define the SOPHYABASE environment variable
csh> setenv $SOPHYABASE ~/SObjs/
# run the configure script 
csh> ./configure -sbase $SOPHYABASE -scxx g++ -extp /usr/local 
     -noext fftw -noext lapack -noext astro

2/ compile and build the libraries
csh> make libs extlibs slb slbext 
# Or if you want to compile also PI (need Motif or Lesstif)
csh> make all slball 

3/ Compile some test and utility programs
csh> make basetests prgutil 
# To compile piapp
csh> make piapp 

4/ You can clean the .o files, if you are not going to recompile after 
changing or update source files
csh> make cleanobj

5/ List of Makefile targets
  > libs extlibs PI = all 
  > slb slbext slbpi = slball    (OR = slballinone)
  > clean  cleanobj
  > tests prgutil prgmap progpi = prgall 
  > basetests piapp (ou progpi)  pmixer 

6/ Currently tested on the following platform/compilers
-------------------------------------------------------------------------
Linux kernel 2.6             g++ 4.1 4.4     (GNU g++ compiler)    
Linux kernel 2.6             icc 10.1        (Intel compiler)                           
MacOSX/Darwin 10.3/10.4      g++ 3.3,4.0     (Apple/GNU compiler)
MacOSX/Darwin 10.5           g++ 4.0         (Apple/GNU compiler)
MacOSX/Darwin 10.6           g++ 4.2         (Apple/GNU compiler)
IBM AIX 5.3                  xlC 8.0         (AIX native compiler)
HP/Compaq/DEC OSF 5.x        cxx 6.x         (native Tru64/OSF compiler)
-------------------------------------------------------------------------

============================
B/ Code management scripts :
============================

1/ configure : c-shell script configuration 
   ./configure -sbase /tmp/sbase/ -scxx cxx -extp /usr/local/extlibs

2/ mkmflib : c-shell script for creation of library module Makefile / smakefile
   ./mkmflib -sbase /tmp/sbase SUtils

3/ mkmfprog : c-shell script for creation of programs module Makefile / smakefile
   ./mkmfprog -sbase /tmp/sbase SUtils

4/ domkmf : c-shell script : calls mkmflib for all modules 
   ./domkmf -sbase /tmp/sbase

5/ chk_cvs.csh : Compares/updates modules using CVS
  Usage: chk_cvs.csh [-a] [-all] [-nos] [-u] [r]
         chk_cvs.csh  -h  for help

6/ Makefile/smakefile : Top level makefile for library and program modules 

7/ Configuration files used to generate sophyamake.inc
   - Linux_g++_make.inc: Linux with g++ compiler 
   - OSF1_cxx_make.inc:  HP/Compaq/Digital Tru64 with native cxx compiler
   - Darwin_g++_make.inc: Apple/MacOSX with the native GNU compiler
   - IRIX64_CC_make.inc: SGI IRIX-64 system and native CC compiler 
   - AIX_xlC_make.inc : IBM AIX system and compiler xlC 
   - Linux_icc_make.inc : Linux with Intel compiler


==========================================
C/ List of modules SOPHYA and PI modules :
==========================================

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

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 (obsolete) 

* 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


================================================
D/ How to use Sophya libraries and/or programs :
================================================

1./ Set the Sophya environment variable :
  that is the repository where the libraries and the programs stand,
  for example:
  > setenv SOPHYABASE /home/.../SophyaWork

  ..Remark:
  The choice of the name is up to you, but if you want
  to use versions on different operating systems (or compilators)
  the "SOPHYABASE" repository must be different, for example:
  > setenv SOPHYABASE /home/.../SophyaWork_Linux_gcc2.95
  > setenv SOPHYABASE /home/.../SophyaWork_Linux_gcc4
  > setenv SOPHYABASE /home/.../SophyaWork_OSF1_cxx
  > setenv SOPHYABASE /home/.../SophyaWork_OSF1_gcc
  > ...

  So you will find:
  ..shared libraries   in:  $SOPHYABASE/slb
  ..archived libraries in:  $SOPHYABASE/lib
       (you will probably prefer to use the shared versions of the libraries)
  ..programs           in:  $SOPHYABASE/exe
  ..include files      in:  $SOPHYABASE/include
       (you will only need it if you write code using sophya libraries)
  ..object files       in:  $SOPHYABASE/obj
       (you probably should not have to use it)

2./ Using Sophya shared libraries:
  As you would do for any software,
  add the repository name of Sophya shared libraries to LD_LIBRARY_PATH
  > setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${SOPHYABASE}/slb

3./ Using Sophya programs:
  As you would do for any software,
  add the repository name of Sophya programs to PATH
  > setenv PATH ${PATH}:${SOPHYABASE}/exe
  then recomputed the internal hash table for executables
  > rehash

4./ Using external libraries which are wrapped in Sophya external modules:
  Sophya is presently using the archived version of the external libraries
  so nothing special have to be done.

5./ Making your own programs:
  If you are writing code using Sophya you may like to
     "include $(SOPHYABASE)/include/sophyamake.inc"
  in your own Makefile.
  That will provide you with default variables for the libraries repositories
  and names as well as standard compilation and link options for
  various current OS and compilators.
     (please see: > more $SOPHYABASE/include/sophyamake.inc )
  That is JUST AN HELP that Sophya provides, you may prefer
  to deal YOURSELF with libraires path/names and compiler/linker options.
