4.2 Compilation procedure for CO5BOLD

The installation procedure has changed significantly since the early releases: now, there is a configure script (see Sect.4.3) that creates the complete (temporary) Makefile, which can be used to compile CO5BOLD and produce the executable rhd.exe. The detailed installation procedure is:

1. Choose/create a proper base directory. This could be $HOME. Then the master directory will typically be $HOME/for - this is the default created by the tar file. However, you might prefer to put the files into $HOME/CO5BOLD or $HOME/CO5BOLD/VersionNumber instead.
2. Put all source files and the configure script there. This will be done typically by expanding the gzipped tar file for.tar.gz e.g. with
     tar -zxvf for.tar.gz
   
   (or by copying all files from an existing installation). On a restricted UNIX you might be forced to use
     gunzip for.tar.gz
     tar -xvf for.tar
   
   instead. Unpacking the tar file creates a sub directory for in the local directory (and possibly overwrites existing files!). You get sub sub directories as described in Sect.3.1 and files as listed in Tables 3.2 and 3.3. See the Readme file 'for/README'.
3. Change with
     cd for/hd/rhd
   
   into the main directory.
4. Look at the existing sub directories, e.g. with
     ls -og | grep "^d"
   
   to see if you find one that fits your machine. The directory
     for/hd/rhd/conf
   
   should not be used. It contains only the configure script. But any other directory will do. If you don't like any of the existing directories - or there are none, create your own e.g. with
     mkdir YOUR_MACHINE
   
   Change into this directory with
     cd YOUR_MACHINE
   
5. Check if there is a configure script or a link to it with
     ls -og configure
   
   which should give something like
     lrwxrwxrwx  1  17 2014-01-07 15:15 configure -> ../conf/configure
   
   If it is not there, create the link with
     ln -s ../conf/configure .
   
6. Start the configure script to create the (first version of the) Makefile with
     ./configure
   
   A partly colorized output can be generated with
     ./configure -c
   
   This gives you a screen output like
   Configuration script for CO5BOLD Makefile
   =========================================
   
   No ./.configurerc file found.
   Writing template ./.configurerc.
   
   Checking default settings for environment variables:
   No compiler         specified                  : F90_COMPILER=
   No parallelization  requested, assuming default: F90_PARALLEL= scalar
   No debugging        requested, assuming default: F90_DEBUG   = 0
   No LHDrad   module  requested, assuming default: F90_LHDRAD  = 0
   No MSrad    module  requested, assuming default: F90_MSRAD   = 0
   No SHORTrad module  requested, assuming default: F90_SHORTRAD= 1
   No chem.    module  requested, assuming default: F90_CHEM    = 0
   No hion.    module  requested, assuming default: F90_HION    = 0
   No dust     module  requested, assuming default: F90_DUST    = 0
   No MHD      module  requested, assuming default: F90_MHD     = 0
   No TWEAK    module  requested, assuming default: F90_TWEAK   = 0
   No explicit machine specified, assuming default: F90_MACHINE = local
   No explicit path    specified, assuming default: F90_BASEPATH= /home/bf/for
   
   List of control environment variables:
   F90_COMPILER =
   F90_PREFLAGS =
   F90_POSTFLAGS=
   F90_PARALLEL = scalar
   F90_DEBUG    = 0
   F90_LHDRAD   = 0
   F90_MSRAD    = 0
   F90_SHORTRAD = 1
   F90_CHEM     = 0
   F90_HION     = 0
   F90_DUST     = 0
   F90_MHD      = 0
   F90_TWEAK    = 0
   F90_MACHINE  = local
    -> MACHINE  = i686
       MACMODEL = Intel Pentium
   F90_BASEPATH = /home/bf/for
   
   System and compiler info:
   Linux system with i686 architecture
     PGI compiler
     version=3.3-2
   
   Compiler call:
   pgf90 -byteswapio -fast -Mvect=sse -Mcache_align -Minfo=inline
   
   Write compiler name and flags into file compiler_flags.info
   
   New Makefile written..........................................
   
   A new 'Makefile' is produced. An existing one is appended to 'Makefile_old'. Additionally, the file 'compiler_flags.info' is written which contains the compiler call in Fortran format.
7. Check the output of the configure script and the header of the new Makefile. You get an overview over the existing environment variables that control the configure script (see Sect.4.3) with
     env | grep F90_
   
   Obs.: at the beginning there might be none. It is convenient to collect the control environment variables in the configure resource file .configurerc. During the first call of configure in any directory, a template .configurerc file is produced.
8. Look into the header (and if necessary the rest) of the configure script or into Sect.4.3 or try
     ./configure -h
   
   to find out how to change the environment variables to control the script. For instance, if you want to enable debugging options, type:
     export F90_DEBUG=1
   
   Restart the configure script after every change in the control variables! With e.g.
     export F90_MACHINE=dummy
     export F90_PREFLAGS="-Oprettyfast +Qsomethingelse"
     ./configure
   
   it is possible to specify all machine-dependent settings yourself (see Sect.4.3.1.16 and Sect.4.3.1.3). This is useful when dealing with a compiler hitherto unknown to the configure script.
9. Start the compilation with
     make
   
   to produce the executable rhd.exe. Symbolic links are created that point from the current directory to each source-code file needed to compile CO5BOLD in its requested configuration.

A simple sample installation might look like the following (the sub directory 'for' is put directly into the home directory).

# -- Choose the base directory --
cd $HOME

# -- Put the tar file there --
# ...

# -- Expand the tar file --
tar -zxvf for.tar.gz

# -- Go into (default) master directory --
cd for/hd/rhd/YOUR_MACHINE

# -- Activate OpenMP und MSrad radiation transport --
export F90_PARALLEL=openmp
export F90_MSRAD=1

# -- Start the configure script to produce the Makefile --
./configure

# -- Compile using the Makefile --
make

echo 'Voila!'

If you want to compile in a directory in a completely different place (not in a sub directory of for as described above), you have to set the environment variable F90_BASEPATH (see Sect.4.3.1.17) to make the paths to the source files known to the configure script. That might look like

  mkdir SOME_REMOTE_PLACE
  cd SOME_REMOTE_PLACE
  export F90_BASEPATH=$HOME/for
  ln -s $F90_BASEPATH/hd/rhd/conf/configure .
  ./configure

The variable F90_BASEPATH also has to be set explicitly if the main directory for should have another name. Renaming the sub-directories with the source files is not a good idea - it requires modifications of the configure script itself. If you install a new CO5BOLD version on top of an older one it might be safer (particularly, if Fortran file names have change), to remove all earlier generated temporaty links and files with

  make removeall

so that the entire sequence looks like:

  ./configure
  make removeall
  make

If you want to remove temporary object and info files after a successful compilation, you could use

  make clean

as in:

  ./configure
  make
  make clean