Manually Installing CIAO 4.15.2

CIAO

CIAO unpacks into a directory called ciao-<version>/, i.e. ciao-4.15 for this release. If the current version of CIAO were to be installed into /usr/local/, the full path to CIAO would be /usr/local/ciao-4.15/. This directory (/usr/local/ciao-4.15/) is referred to as the root directory of CIAO in the rest of this thread. It is also the value that the $ASCDS_INSTALL environment variable is set to once CIAO has been started.

In the rest of this thread we will assume CIAO is being installed into the /soft/ directory.

CALDB

CALDB may be installed in two ways:

• within the CIAO installation, in the directory $ASCDS_INSTALL/CALDB
• in a separate directory, in which case $ASCDS_INSTALL/CALDB will be a soft link to the actual CALDB location.

This thread assumes that you have installed the CALDB before starting the CIAO installation, as CIAO has to be linked to the location of those files. Installation instructions are available on the CALDB website:

• Installing (or upgrading) the CALDB

Installing CIAO as the root user

It is is strongly suggested that CIAO be installed as a non-privileged, regular user and not as the root user. If CIAO must be installed in a directory owned by root and you are following the manual process, then

1. create the ciao-4.15/ directory in the desired location, as the root user;
2. use the chown utility to change ownership of this directory to the installer's username;
3. unpack CIAO into the newly-created directory as the installer, not as the root user.

1. Change to the CIAO installation directory

The CIAO 4.15.2 tarfiles create a directory named ciao-4.15 for the software installation. It is not necessary to create the CIAO directory before starting the installation.

Move to the directory in which you would like the top level of the CIAO installation to be located. If you are installing the software for a local network, this directory must also be visible to all potential CIAO users.

This thread will use the /soft directory:

unix% cd /soft/

2. Unpack CIAO 4.15.2

From the CIAO location just chosen, untar the CIAO 4.15.2 binary packages. (If you prefer more screen output, add the "v" option to the gtar command.)

unix% pwd
/soft

unix% gtar xzf /soft/download/ciao-4.15-bin-core-Linux.tar.gz

unix% gtar xzf /soft/download/ciao-4.15-bin-obsvis-Linux.tar.gz

unix% gtar xzf /soft/download/ciao-4.15-bin-sherpa-Linux.tar.gz

unix% gtar xzf /soft/download/ciao-4.15-bin-tools-Linux.tar.gz

When all the files are unpacked, the CIAO directory will look like:

unix% ls -F ciao-4.15
COPYING*        README.obsvis     VERSION_sherpa  config.sub*    lib/
COPYING.LIB*    VERSION           VERSION_tools   configure*     ots/
INSTALL_BINARY  VERSION.prop_tk   bin/            configure.in*  param/
INSTALL_SOURCE                    binexe/         contrib/       share/
LICENSE         VERSION_core      ciao-type       data/          test/
LICENSE.SAO     VERSION_graphics  config/         doc/
Makefile        VERSION_obsvis    config.guess*   include/
README          VERSION_prism     config.h.in     install-sh*

3. Scripts & Modules Package

The science scripts are written and maintained by local CIAO users at the CXC. More information on each of the scripts is available from the CIAO 4.15.2 Scripts Page. Check that page for announcements about new scripts and updates to existing ones.

The tarfile is designed to be unpacked from the same directory as the CIAO software.

unix% pwd
/soft/

Unpack the script tarfile:

unix% tar xzvf /soft/download/ciao-4.15-contrib-3.tar.gz
./ciao-4.15/
./ciao-4.15/contrib/
./ciao-4.15/contrib/Changes.CIAO_scripts
./ciao-4.15/contrib/README_CIAO_scripts
./ciao-4.15/contrib/VERSION.CIAO_scripts
./ciao-4.15/contrib/bin/
./ciao-4.15/contrib/bin/acis_bkgrnd_lookup

...

./ciao-4.15/contrib/param/merge_obs.par
./ciao-4.15/contrib/param/specextract.par

The tarfile contains a VERSION.CIAO_scripts file. Compare the timestamp in this file to the "Last Updated" date on the Scripts page to determine when you need to update your local scripts installation.

4. Upack CIAO 4.15.2 Patch

CIAO 4.15.2 is a patch on top of the CIAO 4.15 package and must be unpacked after the base 4.15 files are unpacked. The tarfiles are designed to be unpacked from the same directory as the CIAO software. The contents of the patch tar files will overwrite the existing files.

unix% gunzip -c /soft/download/ciao-4.15.1-patch-bin-core-Linux.tar.gz | tar xf - 
unix% gunzip -c /soft/download/ciao-4.15.1-patch-bin-sherpa-Linux.tar.gz | tar xf - 

5. Run the configuration script

Run the CIAO configuration script:

unix% cd ciao-4.15/

unix% ./configure
Running CXC configure, v4.4.1
checking build system type... x86_64-unknown-linux-gnu
checking host system type... x86_64-unknown-linux-gnu
checking target system type... x86_64-unknown-linux-gnu
checking for more... /bin/more
checking for main in -lpthread... no
  --with-imagerdir not specified, defaulting to /soft/ciao-4.15/ots/bin
configure: creating ./config.status
config.status: creating bin/ciao_setup.csh
config.status: creating bin/ciao_setup.sh
config.status: creating ots/lib/python3.9/config-3.9m/Makefile
config.status: creating bin/ciao.sh
config.status: creating bin/ciao.csh
config.status: creating bin/ciao.ksh
config.status: creating bin/ciao.bash
config.status: creating bin/setup_obsvis.sh
config.status: creating bin/setup_obsvis.csh
config.status: creating bin/setup_chips.sh
config.status: creating bin/setup_chips.csh
config.status: creating bin/setup_sherpa.sh
config.status: creating bin/setup_sherpa.csh
config.status: creating bin/setup_tools.sh
config.status: creating bin/setup_tools.csh
config.status: creating bin/ciao-python-fix
config.status: creating test/smoke/bin/setup.sh
config.status: creating test/Makefile

6. Run the ciao-python-fix script

Next, the ciao-python-fix script needs to be run. Despite it's name, it does more than just stuff related to python. Its runs a program that will set the location of various CIAO and off-the-shelf (OTS) libraries.

unix% bash bin/ciao-python-fix

Once this script is run, the CIAO installation cannot be moved or relocated to a different directory without repeating the configure and ciao-python-fix steps.

7. Link to CALDB

Create a link to the calibration data, changing the path to match your system installation:

unix% pwd
/soft/ciao-4.15/

unix% ln -s /soft/CALDB CALDB

At this point, your directory should look like:

unix% ls -F
CALDB@          README           binexe/         config.sub*    lib/
COPYING*        README.obsvis    ciao-type       configure*     ots/
COPYING.LIB*    VERSION          ciao_installed  configure.in*  param/
INSTALL_BINARY  VERSION.prop_tk  config/         contrib/       share/
INSTALL_SOURCE  VERSION_core     config.guess*   data/          test/
LICENSE         VERSION_sherpa   config.h.in     doc/
LICENSE.SAO     VERSION_tools    config.log      include/
Makefile        bin/             config.status*  install-sh*

8. Create a CIAO alias

It is strongly suggested that you create a CIAO alias before continuing.

The alias syntax depends on the shell (tcsh, csh, bash); see this FAQ for help in determining which shell you are using.

• csh/tcsh users should add the following to their $HOME/.cshrc file.

  alias ciao "source /soft/ciao-4.15/bin/ciao.csh"
  

• bash users should add the following to their $HOME/.bashrc file.

  alias ciao="source /soft/ciao-4.15/bin/ciao.sh"
  

• ksh users should add the following to their $HOME/.login file.

  alias ciao="source /soft/ciao-4.15/bin/ciao.sh"
  

Users can create the file if one does not already exist. These are simply text files that can be edited with the users favorite text editor (emacs, vi, gedit, etc.).

More information is given in the Running CIAO section of the Starting CIAO thread.

Once the alias is defined, you will be able to simply type

unix% ciao

and CIAO will be setup and ready to use in that window.

Run individual smoke tests

To run (or re-run) an individual smoke test you have to use the runtests Makefile target as shown here

unix% cd $ASCDS_INSTALL/test
unix% make test-PACKAGE runtests

Where PACKAGE can be: ahelp, crates, dm, ds9, obsvis, sherpa, tools, or ui. For example to just re-run the sherpa smoke tests, run the following command:

unix% cd $ASCDS_INSTALL/test
unix% make test-sherpa runtests
 Requested test suite includes 1 test
   [1/1] Running test sherpa-smoke001 ...  PASS

All smoke tests PASSED.

Known Smoke Test Issues

There is a bug page for known smoke test issues. If you experience a problem that isn't listed there, submit it to CXC Helpdesk.

Known Conflicts

There are some known conflicts between CIAO and other software or system libraries and tools. They are documented in the following webpages:

• "Watch Out" List

• Other Software Packages bug page