This section describes how to install BoA and all required additional software packages.

So far, BoA has been successfully installed and used in various LINUX distributions and on Mac OS X.

This documentation descibes the installation process on

• SuSE 10.0 (32bit version)
• Scientific Linux 4.2 (32bit version)}
• Fedora Core 6 (32bit version)
• Fedora Core 7 (32bit version)

In addition, BoA has been reported to be installed and working properly on

• Debian/Etch (32bit version)

Prerequisites

For the LINUX distributions covered by this documentation, the following software packages must be installed prior to the installation of BoA to be able to install and run BoA. (The given version numbers indicate the versions that where used during development and tests with the respective LINUX distribution.)

SuSE 10.0 (32bit version)

Depending on the original setup, some or all of the packages specified in the table may already be installed on your system. Use SuSE's package manager YaST to check if the necessary packages are present and to install or update them if necessary.

Scientific Linux 4.2 (32bit version)}

With the exception of gcc4-gfortran, all packages listed in the table are part of a standard Workstation installation. If necessary, use the package manager yum to install gcc4-gfortran and any other missing package.

Fedora Core 6 (32bit version)

With the exception of compat-gcc-34-g77, all packages listed in the table are part of a standard Software development installation. If necessary, use the package manager yum to install compat-gcc-34-g77 and any other missing package.

Fedora Core 7 (32bit version)

With the exception of compat-gcc-34-g77, all packages listed in the table are part of a standard Software development installation. If necessary, use the package manager yum to install compat-gcc-34-g77 and any other missing package.

Conflicts with other software

BoA is delivered including a set of programs and libraries (called the BoA Library) necessary to run BoA. This makes a installation of BoA more or less self-contained and reduces the chance of conflicts with other software installed on your system.

However, the behaviour of a system is not only determined by the set of software that is installed on it, but also by the environment that is definded both system-wide and on a per-user basis in various startup scripts. (For a complete list of the startup scripts consult the documentation of your system; most important are the startup scripts of the shell in use. See man bash and man csh)

During the installation of BoA, the installation script tries to set up an environment that allows a smooth installation. When running boa, BoA's start-up scripts .boarc.sh and .boarc.csh try the same. However, there may be situations when this is not successfull. If this is the case, careful inspection of the environment must be performed. (To give an example: During the development phase of BoA, running BoA failed reproducably on one particular system; after scrutinizing various startup scripts, the cause turned out to be a startup script for IRAF, that changed the C and Fortran compilers. After commenting out the IRAF related lines, BoA ran without any further problems.)

Installing BoA

A complete distribution ofBoA contains two tar-archives:

• BoaLib-<DATE>.tgz, containing the BoA Library, a set of programs and

  • libraries necessary to run BoA, in versions that have been verfied to work properly together with BoA's scripts.

• Boa-<DATE>.tgz, containing Python scripts, Fortran programs that

  • provide BoA's core functionality. The archive also contains startup and example scripts as well as BoA's documentation.

(<DATE> indicates the release date of each tar-archive.)

A complete installation of BoA includes installation of the BoA Library and of BoA itself. Both installation steps are described below.

Please note that the following instructions relate to the installation of BoA on the LINUX distributions listed above. For installation instructions for other LINUX distributions and for Mac OS X, please consult http://www.astro.uni-bonn.de/boawiki.

Installing the BoA Library

The BoA Library is contained in the tar-archive BoaLib-<DATE>.tgz. It is a set of programs and libraries necessary to run BoA, in versions that have been verfied to work properly together with BoA's scripts (contained in Boa-<DATE>.tgz).

In particular, the BoA Library contains the following programs and libraries:

The installation process will install the BoA Library in its own dirctory tree. The root of this directory tree is referred to as BOA_LIB_HOME in this document. If not specified otherwise during the installation process, BOA_LIB_HOME is $HOME/boalib, where $HOME is your home directory.

You do not need root privileges to install the BoA Library as long as you install it to a location where you have write permission.

To install the BoA Library, proceed as follows:

1. Unpack the archive to the dirctory BoaLib-<DATE>-install by typing

     tar zxf BoaLib-<DATE>.tgz

• and go to this directory:

     cd BoaLib-<DATE>-install

• This dirctory may safely be deleted after the BoA Library has been installed.

2. Run the configure script to create the install script:

     ./configure

---

• Remark for Fedora Core 6:

  • For an unknown reason, the configure script fails to locate the X libraries and X header files properly for Fedora Core 6. Specify the locations explicitely by

    ./configure --x-libraries=/usr/lib --x-includes=/usr/include

---

• Remark for Fedora Core 7:

  • The bash implementation that comes with Fedora Core 7 contains a bug in IO redirection that leads to problems with tests in the BoA Library's installation script. To avoid these problems, replace the file install.in in the dirctory BoaLib-<DATE>-install by the file install.in found here before running the configure script!
    
    For an unknown reason, the configure script fails to locate the X libraries and X header files properly for Fedora Core 7. Specify the locations explicitely by

  • ./configure --x-libraries=/usr/X11R6/lib --x-includes=/usr/X11R6/include

---

• The configure script tests for each software package that is part of the BoA Library whether this particular software package is already installed on your computer. If the configure script finds the particular software package on the computer, it tries to find out the version. Only if the configure script finds out that the particular software package is installed in exactly the version that comes with the BoA Library, this particular software package will be skipped in the following installation step. In most other cases (configure cannot locate the software, the versions do not match, configure cannot find out the versions, etc.) configure registers the software package for installation.

• (The execptions from this rules are the packages Numeric and
  • scipy_distutils: To avoid conflicts from different Python versions, these packages are registered for installation whenever Python is registered.) You can override this default behaviour with options of the configure script. E.g.

     ./configure --with-python

• will register Python for installation, even if the correct Python version is already installed on your computer, while

     ./configure --without-python

• will prevent Python to be installed. Typing

     ./configure --with-all

• will mark all packages for installation without checking. You can combine these options to finetune the installation:

     ./configure --with-python --without-slalib

• will work as expected as will

     ./configure --with-all --without-python

• For a list of all possible options --with-package and --without-package, type

     ./configure --help

• The configure script will also specify BOA_LIB_HOME, the root of the directory tree where the BoA Library will be installed. By default this is $HOME/boalib where $HOME is your home directory. You can specify a different root using the --prefix option as in

     ./configure --prefix=$HOME/myOwnBoaLibrary

---

• Remark for SuSE 10.0:

  • If you want to use a preinstalled Python, make sure that the package python-devel is installed on your system. Use SuSE's package manager YaST to install it if necessary.

---

3. Run the install script:

     ./install 

• This will install the software packages that where registered for installation by the configure script. If the root of the dirctory tree

  BOA_LIB_HOME (either $HOME/boalib or the directory specified explicitely with configure --prefix) already exists, the install script will warn you and query you whether you really want to proceed. If unsure, answer "N"; this will abort the installation. You can rerun the configure script specifiying a different prefix and then run install again. The rest of the installation happens without any input from you. Note that the install process can take about 30 min to complete. After running this script, the BoA Library is installed and ready to be used. You may proceed with the installation of BoA itself.

Troubleshooting

• In case of errors during the installation, the install script prints out error messages and aborts. Consult the log files that are specified in the error message to find out possible reasons for the failure. Quite often the cause for a failure to install the BoA Library are special setting

  of shell variables (e.g. PYTHONPATH) in shell startup scripts. If the reason for the failure is unclear, delete the directory tree with the incomplete installation of the BoA Library, run

     ./configure --with-all

• and run the install script again. If errors still occur, the most probable causes are problems with the environment defined by the set of path settings, shell variables etc. which are set both in system-wide and user-specific startup scripts. (For a complete list of the startup scripts consult the documentation of your system; most important are the startup scripts of the shell in use. See man bash and man csh.) During the installation of the BoA Library, the installation script tries to set up an environment that allows a smooth installation. However, there may be situations when this is not successfull. If this is the case, careful inspection of the environment must be performed.

Installing BoA

The tar-archive Boa-<DATE>.tgz contains

• Python scripts, Fortran programs and some related data files necessary to
  • run BoA
• startup scripts for bash and csh to set the correct shell environment to run
  • BoA
• example scripts and related data in MBFits files to be used as cookbook
  • examples for BoA
• scripts for the reduction of Laboca data
• rcp files with instrument-specific parameters
• BoA's documentation

Before you can install BoA, you must install the BoA Library contained in BoaLib-<DATE>.tgz (see above).

By default, the BoA Library is installed into a dirctory tree with root }. However, when installing the BoA Library you can choose a different directory tree by specifying the prefix option for the BoaLib-<DATE>-install/configure command. The root of this directory tree (either the default $HOME/boalib or the one secified by the prefix option of BoaLib-<DATE>-install/configure) is referred to as BOA_LIB_HOME in this document.

BoA'a installation process will install the software in its own dirctory tree. The default for the root of this tree is $HOME/boauser where $HOME is your home directory. If you want to install BoA to another location, you can specify BoA's root dirctory during the the configuration as described below.

You do not need root privileges to install the software, as long as you install it to a location where you have write permission.

To install BoA, proceed as follows:

1. Unpack the archive to the dirctory Boa-<DATE>-install by typing

     tar zxf Boa-<DATE>.tgz

• and go to this directory:

     cd Boa-<DATE>-install

• This dirctory may safely be deleted after the BoA has been installed.

2. Run the configure script to create the install script:

• In general, the configure script must be run including the specification of

  the variable BOA_LIB_HOME:

     ./configure BOA_LIB_HOME=$BOA_LIB_HOME

• where $BOA_LIB_HOME is the root of the directory tree to which the BoA Library has been installed (see above). BOA_LIB_HOME needs not be specified if the BoA Library has been installed to the default location ($HOME/boalib).

Examples:

• You installed the BoA Library without specifying a prefix by

  • running (in BoaLib-<DATE>-install)

            ./configure

    Then you can run the configure script in Boa-<DATE>-install also without argument:

            ./configure

• You installed the BoA Library specifying a prefix by

  • running (in BoaLib-<DATE>-install)

            ./configure --prefix=$HOME/myBoaLib

    Then you must specify the BOA_LIB_HOME argument when running the configure script in Boa-<DATE>-install:

            ./configure BOA_INFRA_HOME=$HOME/myBoaLib

• By default, the configuration scripts registers BoA, the startup scripts, the example scripts, and the documentation for installation. You can override this default behaviour with options of the configure script. E.g.

     ./configure --without-examples

• will prevent the example scripts to be installed. For a list of all

  possible options --with-package and --without-package, type

     ./configure --help

• The configure script will also specify the root of the directory tree where

  Boa will be installed. By default this is $HOME/boauser. You can specify a different root using the --prefix option as in

     ./configure --prefix=$HOME/myOwnBoa

3. Run the install script:

     ./install 

• This will install BoA into a dirctory tree with root $HOME/boauser (if the configure command was called without specifying a prefix) or with the root specified by the configure command. The root dirctory will contain the following subdirctories:

  • boa: BoA's Python and Fortran code
  • examples: Example scripts and related data
  • laboca: Scripts for the reduction of Laboca data
  • rcp: rcp files with instrument-specific parameters
  • doc: BoA's documentation

  The install script will also create the two startup scripts .boarc.sh and .boarc.csh in your home dirctory. (If these files already exist, the existing files are renamed .bosrc.sh~ and .boarc.csh~.) These files contain definitions of shell variables, path settings, and aliases necessary to run BoA.

4. Run BoA:

• In order to run BoA, first run the correct startup script by typing

     source ~/.boarc.sh (if you are working in bash)

• or

     source ~/.boarc.csh (if you are working in csh)

• (You may include this line into your .bashrc or .cshrc file to automate this task.) You can then run BoA by typing

     boa

---

• Remark for Fedora Core 6 and 7:

  • Fedora Core may have the kernel security extension SELinux enabled. This can result in an error message containing the phrase cannot restore segment proc after reloc: Permission denied when starting BoA.

    If this is the case, goto ${HOME}/boalib/lib/python2.3/site-packages/Numeric and issue the command

    chcon -t texrel_shlib_t *.so

    Then goto ${HOME}/boauser/boa/fortran and issue the same command there. This should solve the problem.

---

Troubleshooting

• In case of errors during the installation, the install script prints out error messages and aborts. Consult the log files that are specified in the error message to find out possible reasons for the failure. A possible cause for errors during the installation is an incorrect

  specification of the variable BOA_LIB_HOME and/or the prefix option when running the configure script. Check your settings and rerun configure and install if necessary. Other possible causes for problems both during installtion and when running BoA are conflicts with the environment defined by the set of path settings, shell variables etc. which are set both in system-wide and user-specific startup scripts. (For a complete list of the startup scripts consult the documentation of your system; most important are the startup scripts of the shell in use. See man bash and man csh.) During the installation of BoA, the installation script tries to set up an environment that allows a smooth installation. When running BoA, the

  start-up scripts .boarc.sh and .boarc.csh try the same. However, there may be situations when this is not successfull. If this is the case, careful inspection of the environment must be performed. (To give an example: During the development phase of BoA, running BoA failed reproducably on one particular system; after scrutinizing various startup scripts, the cause turned out to be a startup script for IRAF, that changed the C and Fortran compilers. After commenting out the IRAF related lines, BoA ran without any further problems.)

Uninstalling BoA

To uninstall BoA, delete the directory tree into which BoA has been installed, and the startup scripts ~/.boarc.sh and ~/.boarc.csh.

To uninstall the BoA Library, delete the directory tree to which the BoA Library has been installed.