
        //----------------------------------------------//
        //  Langage Objet pour la RElativite NumeriquE  //
        //                  (LORENE)                    //
        //----------------------------------------------//

			*******************************
			*  INSTALLATION INSTRUCTIONS  * 
			*******************************

	 $Id: INSTALL,v 1.9 2013/07/17 12:16:12 j_novak Exp $

Comments or questions should be addressed to 
eric.gourgoulhon@obspm.fr, philippe.grandclement@obspm.fr, jerome.novak@obspm.fr.

See also the file INSTALL_linux for some features specific to Linux.
				

0/ Prerequisites
   =============

  0.1/ Softwares absolutely required by LORENE:
       ----------------------------------------

gmake: the GNU make utility

a C++ compiler: any compiler compliant to the ISO norm of C++ should be able
    to compile LORENE

a Fortran 77 compiler: a small part of LORENE is written in Fortran 77, namely
    the Fast Fourier Transform used by the spectral method and the solver
    of Poisson equation in 2-dimensional space. In future releases of LORENE,
    these parts should be rewritten in C++, so that a Fortran 77 compiler
    will no longer be necessary to compile LORENE.  
    Note: the Fortran 95 compiler of the GCC 4.0 suite, namely gfortran, 
    works well (no need to downgrade to the old g77

CVS: The internet access to Lorene sources is performed via a CVS server.
    CVS (Concurrent Versions System) is powerfull tool to
    manage versions and develop over the network. CVS is a free software
    under the GNU General Public License. It comes in standard with
    many Linux distributions. If you don't have it on your system, you
	can download it from the web site

		http://www.nongnu.org/cvs/
		
LAPACK: Lorene uses the LAPACK (Linear Algebra PACKage) library to perform
    linear algebra operations. LAPACK must therefore be installed on
	your system (including the development packages). LAPACK is a public 
    domain software and can be downloaded from 
		http://www.netlib.org/lapack/
    If you are using Linux, note that LAPACK comes along with many Linux 
    distributions.

GSL  (GNU Scientific Library): LORENE uses the GSL library to compute Bessel
    functions involved in some elliptic operators. GSL must therefore be 
    installed on your system. GSL is a free software and can be 
    downloaded from the GSL web site:
        http://www.gnu.org/software/gsl/
    If you are using Linux, note that GSL comes along with many Linux
    distributions.

your C compiler / preprocessor must support a "-M" option to output a
     dependency file, or use  
makedepend: to create dependencies in makefiles. On Linux systems, makedepend 
    comes along with X11 development packages (for instance libxorg-x11-devel 
    in Mandriva 2006 or xorg-x11-devel in SuSE 9.2)
	
    
   0.2/ Optional FFT library for LORENE:
        -------------------------------
FFTW3 (Fastest Fourier Transform in the West):  By default, LORENE uses a
    FORTRAN Fourier Transform. It is possible to use a faster library written
    in C, namely FFTW, version 3 (older versions are incompatible!) that can be
    downloaded from the FFTW Web site. If you are using Linux, note that FFTW3
    comes along with most of distributions. To use it, you will have to set the
    appropriate variable FFT_DIR to FFTW3 in the local_settings file


   0.3/ Software required only to produce graphical outputs:
        ---------------------------------------------------

PGPLOT: Lorene uses the PGPLOT library for producing 2-D graphical outputs.
	You can use Lorene without PGPLOT provided that you don't perform
	any call to the routines 
		Lorene/C++/Source/Non_class_members/Graphics/des_*
	However, it is recommended to install PGPLOT on your system, from
	the web site
		http://www.astro.caltech.edu/~tjp/pgplot/

	If you are using Linux, see the companion file INSTALL_linux. 
    See in particular the instructions for a quick installation of PGPLOT 
    Note that a small correction must be applied to the makefile if you are 
    using gcc 4.0 (or above) (remplacement of g77 by gfortran)


OpenDX: this powerful software is used to produce 3-D visualization of 
    various Lorene objects. The corresponding OpenDX scripts are located 
    in the directory  Lorene/Visu/OpenDX.
    OpenDX can be freely downloaded from the web page http://www.opendx.org/.



  0.3/ Softwares required to generate LORENE HTML documentation:
       --------------------------------------------------------
Doxygen: LORENE uses the software Doxygen to produce LaTeX and HTML
    documentation from the source files themselves (class declarations in
    Lorene/C++/Include/*.h). You can of course compile and run LORENE codes 
    without Doxygen being installed on your system. But to write any piece of 
    code, it is necessary to have LORENE documentation. Therefore, it is 
    strongly recommended to install Doxygen on your system, if you do not 
    already have it (Doxygen comes along with many Linux distributions). 
    Doxygen is a free software under the GNU General Public License. 
    You can download it from the Doxygen web site:  
        http://www.stack.nl/~dimitri/doxygen/

LaTeX: the text formatting system TeX/LaTeX is required by DOC++ to generate
	the PostScript documentation, as well as to treat the mathematical
	formulae in the HTML documentation.



1/ Download from the CVS repository
   ================================

Connect to the CVS repository in Meudon:

	cvs -d :pserver:anonymous@octane.obspm.fr:/cvsroot login

 	password: anonymous

   Download Lorene by typing

	cvs -z5 -d :pserver:anonymous@octane.obspm.fr:/cvsroot checkout Lorene


2/ Set of the environment variable HOME_LORENE
   ===========================================

Enter to Lorene root directory which has just been created

	cd Lorene

   and define HOME_LORENE to be the full path name of this directory:
   -- if your Unix shell is csh or tcsh, type

   	setenv HOME_LORENE $PWD

   -- if it is instead bash (common under Linux), type

   	export HOME_LORENE=$PWD

For future use of Lorene, it would be helpful to define HOME_LORENE in
the resource file .cshrc .tchsrc or .bashrc in your home directory by
inserting the line
	setenv HOME_LORENE /??/Lorene        in .cshrc or .tchsrc
	export HOME_LORENE=/??/Lorene        in .bashrc

where /?? denotes the full path to the Lorene directory
This will avoid to set it manually after each login.


3/ Defining the parameters specific to your system
   -----------------------------------------------

Before to launch the compilation of Lorene, you have to specify which
compilers to use, with which options, and where are located some system
libraries. This information should be passed to Lorene via the
file
	$HOME_LORENE/local_settings

This file is the only one of the Lorene distribution which is
architecture/system dependent. It will be included by all the
Lorene Makefiles, which are fully architecture independent.

Some templates files are provided in the directory Local_settings for
   -- Linux with GNU compilers   (local_settings_linux)
   -- SGI Irix                   (local_settings_irix)
   -- Compaq Alpha Digital Unix  (local_settings_alpha)
   -- IBM AIX                    (local_settings_aix)
   -- MacOS X with GNU compilers (local_settings_darwin)

To create the file $HOME_LORENE/local_settings, you simply have to
copy one of this file into local_settings by typing, e.g. under Linux

	cd $HOME_LORENE
	cp Local_settings/local_settings_linux local_settings

You may then edit local_settings to adapt it to some special features of
your system implementation, e.g. to use FFTW3 instead of the standard 
FORTRAN FFT, changing the FFT_DIR variable from FFT991 to FFTW3.


4/ Compiling
   =========

The compilation of Lorene is launched via the command (in the HOME_LORENE
directory)

   	gmake

This will first create the Lorene documentation, including the HTML
reference guide, provided Doxygen is installed on your system (see the 
prerequisites section above).
Then the C++ part is compiled and the Fortran 77 one.

To read Lorene's reference manual, open the file 
$HOME_LORENE/Doc/refguide/index.html in a web browser

If you run into trouble during the compilation, you can clean the C++ directory,
leaving only the sources as downloaded by the CVS checkout command, by

	cd $HOME_LORENE/C++
	gmake uninstall
	
Then, you can fix the problem (e.g. add a path for include file in
local_settings), and perform the gmake command again.



5/ Testing the installation
   ========================

If everything went well with the compilation, you can check the link with
LAPACK and PGPLOT libraries with

	gmake test

This will produce three executables:

	$HOME_LORENE/Test/test_fft	: check LAPACK and PGPLOT
	$HOME_LORENE/Test/test_lapack	: check LAPACK only
	$HOME_LORENE/Test/test_pgplot	: check LAPACK and PGPLOT


6/ Upgrading the installation
   ==========================

As a research software, LORENE is under permanent development. 
You should therefore run from time to time the commands 

	cd $HOME_LORENE
	cvs update -d
	gmake

to get the latest version of LORENE. 
The script $HOME_LORENE/lorene_up contains the above commands, so 
that it is equivalent to type

	$HOME_LORENE/lorene_up

7/ Removing everything but the sources
   ===================================

To restore the Lorene directory in the state it was just prior to step 4/
(compilation), type

	cd $HOME_LORENE
	gmake uninstall
	

