================================================================================ Instructions for Installing CIAO 4.5 Binary packages December 2012 ================================================================================ This document describes the binary installation and verification testing (i.e. smoke tests) of CIAO. Installing CIAO from the binary packages is easy with the ciao-install script. You can download a version customized for your installation from the web site. The script will ask you a few simple questions and then installs the software and runs the smoke tests for you. A pointer to additional information about ciao-install is located in Section I. Alternatively, the instructions shown in Section II below can be used to install the binary packages and run the smoke tests at the command line. Section III provides an overview of the Smoke tests and instructions for running the tests. The installation instructions in this document are also available as one of the Introductory CIAO science threads, at http://cxc.harvard.edu/ciao4.5/threads/ciao_install_tool/ Please check the CIAO website: http://cxc.harvard.edu/ciao4.5/ for the most recent updates to this document and further installation assistance. -------------------------------------------------------------------------------- Table of contents -------------------------------------------------------------------------------- I) Installing the Binary packages with ciao-install II) Installing the Binary packages at the Command Line III) Smoke Tests -------------------------------------------------------------------------------- I) Installing the Binary packages with ciao-install -------------------------------------------------------------------------------- The ciao-install script provides an easy and flexible way of installing CIAO. You can provide ciao-install with switches to work in a custom environment. Full details about the script can be found in the file: ftp://cxc.harvard.edu/pub/ciao4.5/all/ciao-install.README The script can be generated at the CIAO download page located at: http://cxc.harvard.edu/ciao4.5/download -------------------------------------------------------------------------------- II) Installing the Binary packages at the Command Line -------------------------------------------------------------------------------- If you want to install CIAO manually please follow the instructions below, where ">" indicates the shell prompt: 1) cd to the directory you want CIAO rooted in 2) Unzip / untar the binary files (requires gzip and tar) > gunzip -c ciao-4.5-bin-core-.tar.gz | tar xf - > gunzip -c ciao-4.5-bin-obsvis-.tar.gz | tar xf - > gunzip -c ciao-4.5-bin-tools-.tar.gz | tar xf - > gunzip -c ciao-4.5-bin-chips-.tar.gz | tar xf - > gunzip -c ciao-4.5-bin-sherpa-.tar.gz | tar xf - > gunzip -c ciao-4.5-bin-prism-.tar.gz | tar xf - > gunzip -c ciao-4.5-bin-graphics-.tar.gz | tar xf - Where = Linux - Built on CentOS 5.8 Linux Linux64 - Built on CentOS 5.8 Linux - 64 bit osxl64 - Built on Lion compatible with Mountain Lion (64 bit mode) osx64 - Built on Snow Leopard (64 bit mode) 3) Run the configuration script: > cd ciao-4.5 > ./configure If the CIAO users see the installation in a different location than where it was physically installed > ./configure --with-top= will set the location of $ASCDS_INSTALL to something other than the current working directory, which is useful for read-only or virtual file systems. For more information on the configure script options please refer to the compilation instructions section below. 4) Create binary-compiled Python modules: > sh bin/ciao-python-fix The binary installation includes Python files that were byte-compiled on a machine at the Chandra X-ray Center. This script will generate byte-compiled python files optimized for your hardware. 5) Create a link to the Calibration data (if needed): > ln -s CALDB This link must exist in the $ASCDS_INSTALL directory for the parts of CIAO that require the CALDB to work correctly. 6) Create the ahelp index Setup for ciao > source bin/ciao.csh (csh users) or > . bin/ciao.bash (bash users) Create the indexes: > ahelp -r 7) Run the smoke tests (optional) > cd test > make -k |& tee ~/ciao_test.log (csh) or > make -k 2>&1 | tee ~/ciao_test.log (sh, bash, ksh) Successful tests are reported with a message such as: [2/41] Running test prism-smoke001 ... PASS whereas failed tests will be reported with a message such as: [2/41] Running test prism-smoke001 ... FAIL Further information on the tests can be found in section (III) below. 8) It is strongly suggested that the user create an alias in $HOME/.cshrc (csh and tcsh shell users) or $HOME/.login (sh, ksh, and bash shell users) (csh and tcsh) > alias ciao "source /ciao-4.5/bin/ciao.csh" if the installation root is in /soft, this would be: alias ciao "source /soft/ciao-4.5/bin/ciao.csh" (borne shell) > alias ciao=". /ciao-4.5/bin/ciao.sh" so if the installation root is in /soft, this would be: alias ciao=". /soft/ciao-4.5/bin/ciao.sh" likewise, ksh and bash users would have: alias ciao=". /soft/ciao-4.5/bin/ciao.ksh" alias ciao=". /soft/ciao-4.5/bin/ciao.bash" From this point on, the alias 'ciao' will setup the package for use. > ciao Note: In the unlikely event that a CIAO program crashes you may see the message: Broken pipe ${EXE} "$@" -or- Terminated ${EXE} "$@" This is due to the fact that all programs are now called from wrapper scripts. -------------------------------------------------------------------------------- III) Smoke Tests -------------------------------------------------------------------------------- A set of tests have been packaged with CIAO 4.5 These tests are intended to be run: 1. After a user has downloaded and configured the binary packages; to ensure there were no problems or binary incompatibilities, and/or 2. To be run after a user has rebuilt CIAO from source (either using pre-compiled OTS or compiling OTS from source). The tests are not a complete regression test of the system; they were chosen to expose the most critical problems with a reasonable download size and run within a reasonable time. The current data volume is roughly 280Mb of data and the run-time and takes about 5min on a 3GHz Linux machine. Outputs generated from the user's install are compared against a baseline to ensure that everything worked okay. To run the tests, users should start up CIAO (e.g. use the ciao alias created in step 8 above), check that the 'ahelp -r' command from step 6 has been run (the file $ASCDS_INSTALL/doc/xml/CXCHelpDB should exist), and then > cd $ASCDS_INSTALL/test > make -k |& tee ~/ciao_test.log (csh) or > make -k 2>&1 | tee ~/ciao_test.log (sh) A successful test will look like: [1/41] Running test FOO-smoke001 ... PASS where 'FOO' is the name of an individual test. If users see a message that reports: [1/41] Running test FOO-smoke001 ... FAIL then there is an unexpected problem with the tests. Note that if users see additional warnings/errors and the test reports PASS, then the test is good (tests sometimes do test error conditions). All the test outputs are written to $ASCDS_WORK_PATH/smoke.$LOGNAME where $LOGNAME is your system login name. The tests need about 60 Mb to run. The test scripts clean up the disk space upon successful completion. Tests which fail leave their test output so you may check the results. Once you are satisfied with the smoke test results they should remove $ASCDS_WORK_PATH/smoke.$LOGNAME and all its subdirectories. $ASCDS_WORK_PATH is set in the /bin/ciao.*sh setup scripts as /tmp by default. If the machine does not have a /tmp or users don't have write permission, users will need to edit the appropriate ciao.*sh script to change the ASCDS_WORK_PATH location or set that ASCDS_WORK_PATH to a different location. If this variable is set, ciao.*sh will not modify it. Summary of Smoke Tests: ----------------------- Tools: tools-ape1.sh : basic acis_process_events test (rand off) tools-asphist1.sh : asphist w/ ACIS data, [@flt] dm filter tools-asphist2.sh : asphist w/ HRC data incl. dtf tools-csmooth1.sh : csmooth, dm grade+status+region filter tools-dmcoords1.sh : basic ACIS test tools-dmcoords2.sh : basic HRC test tools-dme1.sh : dmextract w/ PI bin, incl background tools-dme2.sh : dmextract w/ time bin incl bkg tools-dmstat1.sh : NaN test, table tools-dmstat2.sh : Null test (integer), table tools-dmstat3.sh : Image, sub-space tools-hpe1.sh : basic hrc_process_events tools-mkacisrmf1.sh : no wmap, using obs file for CALDB lookup tools-mkacisrmf2.sh : wmap in tdet coords tools-mkacisrmf3.sh : wmap in det coords tools-mkwarf1.sh : wmap in tdet coords tools-mkwarf2.sh : wmap in det coords tools-tcm1.sh : tg_create_mask tools-tgdetect1.sh : basic tgdetect tools-tge1.sh : basic tgextract using inregion=CALDB tools-tge21.sh : basic tgextract2 tools-tre1.sh : basic tg_resolve_events, using [#row] filter tools-wav1.sh : wavdetect, dm grade+status filter A subset of a CALDB tree, containing enough data for the datasets used by the test suite, has been packaged with the ciao distribution Ahelp: ahelp-smoke001.sh : Help system test Datamodel: dm-smoke001.sh : Straight copy dm-smoke002.sh : Column filter, #row filter dm-smoke003.sh : Exclude filter dm-smoke004.sh : Use file subspace as filter dm-smoke005.sh : Region filter on vector with 1D binning dm-smoke006.sh : Data filters, 2D binning dm-smoke007.sh : Subspace edit Obsvis: obsvis-smoke004.sh : General gui window creation Crates: pycrates-smoke001.sh : General functionality Prism: prism-smoke001.sh : Prism test prism-smoke002.sh : Prism test Chips: chips-smoke001.sh : Plots: contour, curve, histogram chips-smoke002.sh : Annotations: labels, lines, points, regions chips-smoke003.sh : Portable state files chips-smoke004.sh : Undo/redo Sherpa sherpa-smoke001.sh : General functionality Ds9 ds9-smoke001.sh : General functionality