***************************************************************************** HEASOFT 6.10 - INTRODUCTION ***************************************************************************** New as of HEASOFT 6.0 is the HEADAS build environment which replaces earlier versions of configuration files and Makefiles as used in HEASOFT 5.3.1. The build procedure remains basically the same however, i.e. modeled after a typical GNU software distribution. HEASOFT is the generalized term for the full set of software distributed from the HEASARC, incorporating all of the newly- developed software in the HEADAS environment (e.g. Swift) as well as all of the traditional HEASARC software (FTOOLS, XANADU, XSTAR). As always, we recommend removing completely any previous HEASOFT installation before proceeding. Users who have recently made use of the Swift software distributions should note that starting with this release we no longer require you to set both LHEASOFT and HEADAS environment variables before initializing the software. Since the older (LHEASOFT) packages have been moved to the new HEADAS system, there is only one environment variable (HEADAS) to set, and we have dispensed with usage of the temporary "hinit.csh/.sh" file. See the instructions below for full details regarding initialization of the software. This document is a guide to installing HEASOFT 6.10 (includes FTOOLS 6.10, FV 5.3, HEATOOLS 2.9, SUZAKU 17, SWIFT 3.7, XIMAGE 4.5.1, XRONOS 5.22, XSPEC 12.6.0q, and XSTAR 2.2.1bc) from the source code or pre- compiled binary distributions on Unix systems (and the Linux-like Cygwin environment for Windows), available for download via: http://heasarc.gsfc.nasa.gov/lheasoft/download.html This document is also available online at: http://heasarc.gsfc.nasa.gov/lheasoft/install.html ***************************************************************************** CONTACT INFORMATION ***************************************************************************** For online information about FTOOLS or FV please see: http://heasarc.gsfc.nasa.gov/ftools For correspondence regarding FTOOLS, HEATOOLS or FV please send us mail via: http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp For correspondence regarding SWIFT please visit: http://heasarc.gsfc.nasa.gov/cgi-bin/Feedback and select Swift under "Choose a mailing list". For online information about XANADU (XIMAGE, XRONOS and XSPEC), please see: http://heasarc.gsfc.nasa.gov/xanadu For correspondence regarding XANADU (XIMAGE, XRONOS or XSPEC), send email to: xanprob@athena.gsfc.nasa.gov For online information about XSTAR please see: http://heasarc.gsfc.nasa.gov/xstar/xstar.html For correspondence regarding XSTAR please send email to: xstarhelp@athena.gsfc.nasa.gov For general online information on the HEASARC, please see: http://heasarc.gsfc.nasa.gov/ ***************************************************************************** SUPPORTED ARCHITECTURES AND OPERATING SYSTEMS ***************************************************************************** For the latest information about supported architectures, operating systems and compilers, all users should visit this web page: http://heasarc.gsfc.nasa.gov/lheasoft/supported_platforms.html ***************************************************************************** BUILDING AND INSTALLING HEASOFT ***************************************************************************** The procedure for building and installing HEASOFT is modeled on GNU software distributions. As always, changes in the package structure since the last release have prompted a few changes in the procedure, so please read this entire document before continuing, and follow the instructions step by step. BEFORE YOU START Please visit the known bugs page at http://heasarc.gsfc.nasa.gov/lheasoft/bugs.html to learn of any problems identified after the latest version of HEASOFT was released. You will need the following to build this software: - Up to 2 GB free disk space (if building all of HEASOFT) Actual space needed varies with system architecture and software packages selected. - ANSI C compiler We support the proprietary compilers on SunOS 5.6 (Solaris 2.6) and higher, and gcc v3.1 or higher on all platforms. The default compiler chosen by configure on SunOS is the proprietary "cc". On Linux, Darwin, and Cygwin systems, only the GNU compilers are supported, and gcc (cc/gcc on Darwin) is chosen first by configure. There are instructions below for choosing a specific compiler. - ANSI C++ compiler (several caveats, so please read carefully) On SunOS 5.6 (Solaris 2.6) and higher, we support (and recommend) the proprietary "CC" compiler (SunStudio12 preferred), and also g++ 3.1 or higher. For all other platforms we only support g++ 3.1 and higher. Some packages (notably Xspec 12) may require more recent versions of g++. Please note that there is a problem with g++ 3.4.3 that prevents Xspec 12 from linking, but otherwise the 3.2.x, 3.3.x, and 3.4.x or 4.x.x compilers should be sufficient to build Xspec 12. There are instructions below for choosing a specific compiler. - Fortran compiler * On PC Linux, the GNU Fortran compiler (gfortran or g77) is recommended. * On Mac OS X, g95 (fink-installed or from http://www.g95.org/) is recommended, but gfortran (fink- or macports-installed) is also supported. * On SunOS/Solaris, we recommend f95 (Workshop or SunStudio) but gfortran is also supported. - make GNU make (gmake) is *required* for building our software. If you do not have gmake installed, you can obtain it by anonymous ftp via the GNU website: http://www.gnu.org/order/ftp.html Note that on most Linux and Mac OS X platforms, the default "make" command is GNU make (gmake) though (as on Mac OS X) it may not necessarily be named "gmake". Our configure script will determine whether the appropriate make utility is available. - perl (5.6.0 or higher recommended) Many HEASOFT scripts are written in Perl, and since Perl is free and easy to install, we recommend you make sure a valid Perl is in your path before you start. - X11 / X-Windows If you plan to use any graphical tools (XSPEC, XIMAGE, FV, etc.) you will need X11. See http://www.X11.org/ or http://www.xdarwin.org/. Prior to building HEAsoft, all users should make sure that they have included the X11 Development libraries as part of their X11 installation. For Mac OS X users, the "X11 SDK" is included in the "packages" folder of Apple's XCode developer tools, which should be on your Mac OS X CD distribution. If not, it's available from the Apple XCode website: http://developer.apple.com/tools/xcode/. or via the fink utility as the "x11-dev" package. Linux users should use the "sudo apt-get" method to install "x-dev", "libx11-dev", and "libxt-dev" packages. Some users may find it necessary to specify the location of their X11 libraries and header files to the configure script, e.g. ./configure --x-libraries=/usr/X11R6/lib --x-includes=/usr/X11R6/include In some newer operating systems, X11 is no longer found in the traditional location specified above and is in /usr/lib and /usr/include instead: ./configure --x-libraries=/usr/lib --x-includes=/usr/include ***************************************************************************** STEP BY STEP INSTALLATION INSTRUCTIONS ***************************************************************************** 1) Visit the new HEASOFT download web page: http://heasarc.gsfc.nasa.gov/lheasoft/download.html Select either the source distribution or a pre-compiled binary distribution for Linux (PC or MAC), Darwin (Intel or PPC), Solaris, or Cygwin. Then select the HEASOFT packages you wish to download. Note that selecting any of the mission-specific packages will automatically select any recommended additional packages. 2) In the directory in which you want to install the software, unpack the file you downloaded in step 1 using e.g.: gunzip -c heasoft6.10.tar.gz | tar xf - This will create a heasoft-6.10/ directory containing the software distribution. 3) Configure the software for your platform (necessary for both binary and source downloads): * If you downloaded the source distribution, go to the heasoft-6.10/BUILD_DIR directory: cd heasoft-6.10/BUILD_DIR/ * If you downloaded the binary distribution, go to the heasoft-6.10//BUILD_DIR directory: cd heasoft-6.10//BUILD_DIR/ where = e.g. "i686-pc-linux-gnu-libc2.3.4" or "i686-pc-cygwin" and run the main configure script, which will probe your system for libraries, header files, compilers, etc., and then generate the main Makefile. IMPORTANT: if building from source, please read the information below about configuration options. To produce a default configuration, the configure script may simply be invoked by (we recommend capturing the screen output from configure as below): ./configure >& config.out & (C Shell variants) ./configure > config.out 2>&1 & (Bourne Shell variants) *** If you downloaded a pre-compiled binary distribution of HEASOFT, proceed now to step 8. CONFIGURE OPTIONS FOR HEASOFT SOURCE DISTRIBUTION: By default, configure will choose a proprietary compiler (cc) for Solaris, and will choose gcc for Linux, Darwin, and Cygwin. For C++ compilers (not required for all packages), configure will choose "CC" on Solaris (recommended), and g++ everywhere else. For Fortran compilers, configure will choose g77 or gfortran on Linux, g95 on Darwin, and f90 or f95 on Solaris. To override these choices, make sure the compilers you want to use exist, are functional, and in your path, and set the CC (for C compiler) and CXX (for C++ compiler) environment variables. For example, to use supported GNU compilers, in C Shell variants, type: setenv CC gcc setenv CXX g++ setenv FC g77 and in Bourne shell variants, type: CC=gcc export CC CXX=g++ export CXX FC=g77 export FC These steps are only necessary if you wish to override configure's default choices. The configure script does accept a number of options which can be examined via "./configure --help", though most users are likely to only need or want the following: ***** VERY IMPORTANT ********************************************* In the new HEADAS build environment, there are multiple layers of installed directories, so if you prefer to delete the source code after installing HEASOFT, it is *STRONGLY* recommended that you provide a prefix to configure which installs the software outside of the source tree. ****************************************************************** --prefix=dir Denotes where the libraries, executables, help files, etc., are to be installed. NOTE that this is slightly different than the sense in which "prefix" is used in GNU software, in that an additional system-dependent subdirectory will first be appended to the prefix argument, below which the bin/, lib/, and other directories will be created. If no prefix argument is supplied to configure, the default is the main heasoft-6.10/ directory itself. * NOTE FOR DARWIN and CYGWIN USERS: If you perform the software installation on a disk which has a space or spaces in its name, i.e. ("/local/scratch G3/heasoft-6.10/") the initialization step (referred to in the INITIALIZATION AND SETUP section below) will fail because it reads that as two separate paths. Paths with underscores are okay. --enable-static Supplying this option will add the appropriate flags to your build such that all linking with HEASOFT libraries will be done statically rather than dynamically (as is the default). This option is not available for builds which include XSPEC 12, as the method by which local models are used relies on dynamic loading of the models library(ies). * NOTE FOR DARWIN and CYGWIN USERS: Libraries containing Fortran must be built statically, but this is handled internally by our configure script, so you do not need to provide this flag to configure under Darwin or Cygwin. 4) * SKIP TO STEP 8 IF YOU ARE USING A PRE-COMPILED BINARY DISTRIBUTION * This step is only necessary if you are building the source code distribution: Start the build process. We strongly recommend that you capture all output into a log file. Then, if you need to report a problem, please send us the ENTIRE log file. And since it may take some time to run (from minutes to hours, depending on the speed of your system) we recommend that you build it in the background: make >& build.log & (C Shell variants) make > build.log 2>&1 & (Bourne Shell variants) To check on the build progress in real-time (if you wish) try: tail -f build.log 5) VERY IMPORTANT: Check your build.log for errors! If a problem occurs and is discovered at this point, it may be easy to correct (contact the appropriate help address listed above). By contrast, if an error occurs, but you continue with the next step, it may make resolving the problem more complex or more time-consuming. The easiest way to check your build.log for errors is to look for occurrences of the string ***. (Most UNIX utilities which use regular expression matching require these to be "escaped" using backslashes, e.g. \*\*\*). 6) Perform the final installation of the executables, libraries, help files, calibration data, perl scripts, etc, by executing: make install >& install.log & (C Shell variants) make install > install.log 2>&1 & (Bourne Shell variants) This will create an appropriately-named system-dependent directory, e.g. sparc-sun-solaris2.9/, either under heasoft-6.10/ or, if you specified a prefix argument to configure, (see step 3 above), in the directory you selected at that time. 7) VERY IMPORTANT: Check your install.log for errors! The best method is the same as that described in step 5. 8) At this point, HEASOFT should be completely installed, either under the directory heasoft-6.10/ or under the prefix you specified to configure. Read the next section "INITIALIZATION AND SETUP" carefully to begin using the software. ******* VERY IMPORTANT ********************************************* In the new HEADAS build environment, there are multiple layers of installed directories, so if you did not provide an installation --prefix outside the source tree to the configure script in step 3, do NOT attempt to remove the HEASOFT source code after installation! ******************************************************************** If you now want to build and install for a different architecture out of the same source tree, execute: make distclean before logging into the new machine and starting again with Step 3 above. ***************************************************************************** INITIALIZATION AND SETUP ***************************************************************************** * NOTE that if you downloaded a precompiled binary distribution, you still MUST have run the configure script as described in step 3 above before performing the software initialization described here. Now that you have and installed the software, all that remains is to set up your environment to use it. To initialize the software, we recommend the following: * For users of C Shell variants (csh, tcsh): Edit your $HOME/.cshrc to include lines based on the following: setenv HEADAS /path/to/your/installed/heasoft-6.10/ alias heainit "source $HEADAS/headas-init.csh" * For users of Bourne Shell (sh, ash, ksh, and bash): Edit your $HOME/.bashrc (or $HOME/.login, or $HOME/.profile) to include lines based on the following: HEADAS=/path/to/your/installed/heasoft-6.10/ export HEADAS alias heainit=". $HEADAS/headas-init.sh" From then on, you can simply type "heainit" when you log on, and your environment will be prepared to use the software. In the examples above, reflects your machine's architecture, for example: i686-pc-linux-gnu-libc2.3.4 i386-apple-darwin10.2.0 powerpc-apple-darwin9.7.0 sparc-sun-solaris2.9 The version numbers above will vary depending on your machine. If If you are unsure what the exact name of your installed location is, simply look in the headas directory (or under the you specified as a prefix to configure) to view the correct name. If you have trouble with any part of this process, please contact the appropriate help desk for your software (see CONTACT INFORMATION above), providing as much detail about the problem as you can. Thank you for using HEASOFT! * A final note on usage: In order to view the newer HEADAS help files which are all in HTML format, you must have either Netscape or the linemode browser "lynx" installed on your system. See "fhelp -h" for more information. ***************************************************************************** ADDING LOCAL MODELS TO XSPEC 12 AFTER INSTALLATION ***************************************************************************** NOTE: Local models can only be built using the HEASOFT source distribution. Users should not remove their source distribution after installing in order for local model building to function properly (see also the *** VERY IMPORTANT *** note in steps 3 and 8). In XSPEC 12, local models are always built into shared libraries which can be loaded at xspec run-time. This is performed with two new xspec commands, 'initpackage' and 'lmod', which simplify the process in comparison with previous versions. Please refer to Appendix C of the XSPEC 12 manual for details. There is no longer an option or need to build and install xspec local models during the main HEASOFT build. Those wishing to automate the loading of their local model libraries upon xspec start-up (whether for themselves or for system-wide users), should also refer to the "Customizing XSPEC" section of the manual.