Installing CIAO 4.15.2 Using the ciao-install Script

Quick Start: Running ciao-install

Just looking for a reminder on how to run the ciao-install script? Here is it:

unix% bash /<path>/ciao-install

or, as described further below,

unix% bash /<path>/ciao-install --help

For a detailed description of running the script, read the rest of this thread.

System Requirements

CIAO is supported on a number of operating systems, which are listed on the Platform Support page. Certain system requirements are necessary to successfully install and run CIAO; review these system requirements before continuing with the installation.

Installation Issues

Users should be aware of these installation items before installing CIAO 4.15.2. Additional problems which are seen less frequently are listed on the Installation & Smoke Tests bug page.

Remove old parameter files

With every new CIAO release, some parameter files have changed: new parameters may be added and occasionally old ones removed or renamed. Deleting or renaming the local parameter directory ensures that the correct parameter files will be accessed the first time a tool is run:

unix% rm ~/cxcds_param4/*

Download the ciao-install script

download the ciao-install script.

Note

Note: If you download multiple copies of ciao-install it is likely that your browser will append a number onto the file name, eg "ciao-install(1)". Be sure to check that you are using the last/correct version of this file.

Where should CIAO and CALDB be installed?

The CIAO software package and the Chandra Calibration Database (CALDB) can be installed in any location and do not need to be installed with root or super-user privileges.

Installing the CIAO Software

In this example, the CALDB will be installed as a subdirectory of CIAO. If you want your CALDB to be in a different location, refer to "How to install the CALDB in an independent directory".

ciao-install may be run from any location. It prompts for required information. Here are the prompts and sample answers for a user named "ciaouser"; each prompt is explained in the following section:

unix% bash /<path>/ciao-install
ciao-install v1.32 installing ciao-4.15
Requested packages: sherpa tools prism obsvis contrib CALDB_main
Script log file is /home/ciaouser/ciao-install-22-11-15.09.38.04.log
Download directory for tar files (/home/ciaouser): /soft/download
CIAO installation directory (/home/ciaouser): /soft
Run smoke tests? (y|n) (y): 
Delete tar files after install? (y|n) (n):
Save these settings? (y|n) (y): 
Preparing to install CIAO for Linux 64 bit

Note that tab completion may be used at these prompts.

sherpa tools obsvis contrib CALDB_main

Download directory for tar files (/home/ciaouser): /soft/download

CIAO installation directory (/home/ciaouser): /soft

Run smoke tests? (y|n) (y): 

Delete tar files after install? (y|n) (n):

Save these settings? (y|n) (y): 

Preparing to install CIAO for Linux with Python 3.7

At this point, the script begins to download the software tarfiles and install them (e.g. gunzip and untar them). The name, filesize, and download location of each file is printed to the screen:

Downloading file ciao-control (1 Kb) to /soft
Downloading file ciao-ciao-4.15-bin-core-Linux.tar.gz (193 Mb) to /soft
Verifying file /soft/ciao-4.15-bin-core-Linux.tar.gz
Installing file /soft/ciao-4.15-bin-core-Linux.tar.gz in /soft
Downloading file ciao-4.15-bin-obsvis-Linux.tar.gz (1 Mb) to /soft
Verifying file /soft/ciao-4.15-bin-obsvis-Linux.tar.gz
Installing file /soft/ciao-4.15-bin-obsvis-Linux.tar.gz in /soft
Downloading file ciao-4.15-bin-sherpa-Linux.tar.gz (1 Gb) to /soft
Verifying file /soft/ciao-4.15-bin-sherpa-Linux.tar.gz
Installing file /soft/ciao-4.15-bin-sherpa-Linux.tar.gz in /soft
Downloading file ciao-4.15-bin-tools-Linux.tar.gz (87 Mb) to /soft
Verifying file /soft/ciao-4.15-bin-tools-Linux.tar.gz
Installing file /soft/ciao-4.15-bin-tools-Linux.tar.gz in /soft
Downloading file ciao-4.15-contrib-3.tar.gz (2 Mb) to /soft
Verifying file /soft/ciao-4.15-contrib-3.tar.gz
Installing file /soft/ciao-4.15-contrib-3.tar.gz in /soft

The files sizes will be different for different platforms.

After the files are downloaded and unpacked, the script configures CIAO and reindexes the CIAO help files ("ahelp"):

running chcon to allow CIAO to work with SELinux
Running configure ./configure
Re-indexing ahelp system
Creating binary compiled python modules

The 'running chcon' line only appears on Linux installations. It indicates that the installation has been updated to run under Security-Enhanced Linux, if is installed on your system.

The script will then run the smoke tests. Since the smoke tests include tests of a number of the GUI applications in CIAO, windows will appear and disappear during these tests. This can make using your computer difficult, since these windows may take the mouse focus or overlap your working windows.

The screen output provides a count of how many tests have been run:

Running smoke tests
 Requested test suite includes 40 tests
   [1/40] Running test ahelp-smoke001 ... PASS
   [2/40] Running test ipython-smoke001 ... PASS
   [3/40] Running test ipython-smoke002 ... PASS
...

This will continue until all the tests have finished, at which point you should see

   [38/40] Running test tools-dmstat-smoke001 ... PASS
   [39/40] Running test tools-dmstat-smoke002 ... PASS
   [40/40] Running test tools-dmstat-smoke003 ... PASS
 40 smoke tests run: 40 PASSED, 0 FAILED, 0 SKIPPED
Processing complete!
Script Log file is /home/ciaouser/ciao-install-22-11-15.09.38.04.log

Verifying test successes

A successful test is logged with a "... PASS", while an unsuccessful test reports:

   [7/40] Running test <testname> ... FAIL
         Review /tmp/smoke.username/<testname>/diff.log for details

The smoke tests print a summary of successful and failed tests. If all tests were successful:

All smoke tests completed:  PASS 
*************************************************************
Smoke tests complete. All tests passed!

or if any failed:

 1 out of 40 smoke tests FAILED.

       !! CIAO MAY HAVE FAILED TO INSTALL PROPERLY !!
 Please check http://cxc.harvard.edu/ciao/bugs/smoke.html
 for a list of known issues before contacting the Help Desk.

Finished!

The script finished by printing the installation location.

CIAO 4.15.2 installed in /soft/ciao-4.15

Known Smoke Test Issues

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

You can now proceed to the creating a CIAO alias step.

How to Install the CALDB in an Independent Directory

The destination directory for the CALDB must exist before running ciao-install. In this example, we want to install the CALDB into /soft/CALDB. The directory is created, then --caldb switch is used to set this location in ciao-install.

unix% mkdir /soft/CALDB
unix% bash /<path>/ciao-install --caldb /soft/CALDB
ciao-install v1.32 installing ciao-4.15
Requested packages: sherpa tools obsvis contrib CALDB_main
Script log file is /home/ciaouser/ciao-install-22-11-15.09.38.04.log
Download directory for tar files (/home/ciaouser): /soft/download
CIAO installation directory (/usr): /soft
Run smoke tests? (y|n) (y): 
Delete tar files after install? (y|n) (n):
Save these settings? (y|n) (y): 

ciao-install is run one time: it installs the CIAO software in /soft, installs the CALDB in /soft/CALDB, and links CIAO to the CALDB directory. It then runs the smoke tests, as described in detail in the "Installing the Software: CALDB within CIAO" section.

Using ciao-install to patch CALDB in an independent directory

ciao-install can also be used to apply patches to CIAO, the CALDB, and the contributed software scripts.

Copy existing CALDB files from previous CIAO installation

Users can now choose to automatically copy the CALDB files from an existing CIAO directory into the current version. This may allow ciao-install to then download just the much smaller CALDB patch file.

unix% bash /path/ciao-install --copy-caldb /soft/common/CALDB
ciao-install v1.32 installing ciao-4.15
Requested packages: sherpa tools obsvis contrib CALDB_main
Script log file is /home/ciaouser/ciao-install-22-11-15.09.38.04.log
Download directory for tar files (/soft): 
CIAO installation directory (/soft): 
Run smoke tests? (y|n) (y): 
Delete tar files after install? (y|n) (n): 
Preparing to install CIAO for Linux 64 bit
Downloading file ciao-control (1 Kb) to /soft
Copying CALDB from /soft/common/CALDB to /soft/ciao-4.15
...
Installing file /soft/ciao-4.15-bin-tools-Linux.tar.gz in /soft
CALDB patch download required.
Downloading file caldb_4.10.7_upgrade.tar.gz (607 Mb) to /soft
Verifying file /soft/caldb_4.10.7_upgrade.tar.gz
Installing file /soft/caldb_4.10.7_upgrade.tar.gz in ciao-4.8/CALDB
...

To save disk space, some users may wish to simply create a link to the existing CALDB directory. This can be done using the --link-caldb option. Note: users should be careful when using links since any patches/upgrades will be visible to all the versions of CIAO that link to that location and removing the old CIAO installation will break the current version.

Create a CIAO alias

It is strongly suggested that you create an alias to make it easy to set up and use CIAO.

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.

Check the CALDB installation

The scripts package contains the check_ciao_caldb tool which performs a simple test of the Chandra CALDB installation. Users must have selected the default full CIAO installation or have selected the Scripts Package for this utility to be installed.

After starting CIAO, running the tool should produce screen output like the following:

unix% ls -1F /soft/ciao-4.15/CALDB/
data/
docs/
software/
unix% check_ciao_caldb
 CALDB environment variable = /soft/ciao-4.15/CALDB
             CALDB version = 4.10.7
             release date  = 2023-09-14T16:00:00 UTC
CALDB query completed successfully.

If CALDB is installed in a different location, the check_ciao_caldb output will include the line:

CALDB environment variable = /soft/ciao-4.15/CALDB
        which is a link to = /soft/CALDB/

For a more-thorough validation please follow the chkcif steps described on the download CALDB page.

Additional options

The ciao-install script has several other additional options. Use --help to review them.

unix% bash /path/ciao-install --help
ciao-install v1.32

Usage: /path/ciao-install [options...]

  -h --help Print this message
  --download-only Download only Do not install
  --install-only  Install only Do not download
  --download <dir> Download directory
  --prefix <dir> Install directory
  --logdir <dir> Log file directory
  --config <--with-top=dir> Extra configure switches
  --caldb <dir> Location of the CALDB
  --copy-caldb <dir> Location of to copy into ciao
  --link-caldb <dir> Location of to link into ciao
  --system <system> System to install
           (Linux, macOSX)
  --batch Batch mode (no prompts)
  --silent Silent mode (implies batch) No tty output
  --delete-tar Delete tar files after install.
  --add <segment> Add additional segment to CIAO.
  --remove <segment> Force this segment to not install in CIAO.
  -f --force Force re-install
  -v --version Report version and exit

Clean Up

Finally, you may delete the tarfiles from the original download directory. For this example we would say:

unix% cd /soft/download
unix% rm ciao-4.15*gz
unix% rm caldb_4.10.7_main.tar.gz 

You may also delete the log file(s) - e.g. ciao-install-<date>.log - once you have reviewed them for errors.

Notes