Installing HEAsoft (For Source or Binary Distribution) ***************************************************************************** HEASOFT 6.6.2 - 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.6.2 (includes FTOOLS 6.6, FV 5.2.1, HEATOOLS 2.5, SUZAKU 12, SWIFT 3.2, XIMAGE 4.4.1, XRONOS 5.22, XSPEC versions 12.5.0 and 11.3.2ag, and XSTAR 2.1kn8) 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 The latest version of this document can be obtained online at: http://heasarc.gsfc.nasa.gov/lheasoft/install.html or by anonymous ftp from: ftp://heasarc.gsfc.nasa.gov/software/lheasoft/release/HEASOFT-INSTALL.TXT ***************************************************************************** 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 HEASOFT should build from source code on any of the following platforms and operating systems except where noted, using the compilers indicated. Intel PC / Linux ---------------- - Recommended compilers: GNU compiler collection v3.3 or higher. Intel compilers are also supported. - Tested at LHEA on: Scientific Linux 5.1 - GNU compilers v4.1.2, perl v5.8.8 Scientific Linux 4.0 - GNU compilers v3.4.6, perl v5.8.6 - Pre-compiled binaries built at LHEA on: Scientific Linux 4.0 - GNU compilers v3.4.6, perl v5.8.6 Intel PC / Linux (64-bit) ------------------------- - Recommended compilers: GNU compiler collection v3.3 or higher. Intel compilers are also supported. - Tested at LHEA on: Scientific Linux 5.2 - GNU compilers v4.1.2, perl v5.8.8 Scientific Linux 4.4 - GNU compilers v3.4.6 & 4.1.0, perl v5.8.5 - Pre-compiled binaries built at LHEA on: Scientific Linux 4.4 - GNU compilers v3.4.6, perl v5.8.5 Intel PC / Cygwin for Windows ----------------------------- - Recommended compilers: GNU compiler collection v3.3 or higher - Tested at LHEA on: Cygwin DLL 1.5.25 - GNU compilers v3.4.4 (cygming special), perl v5.8.7 - Pre-compiled binaries built at LHEA on: Cygwin DLL 1.5.25 - GNU compilers v3.4.4 (cygming special), perl v5.8.7 Intel Macintosh / OS X ---------------------- - Recommended compilers: Mac OS 10.5.x / Darwin 9.x / Leopard: * Apple XCode gcc/g++ 4.0.1 with g95 (fink-installed or from www.g95.org) or * Fink-installed GNU Compiler Collection Version 4.2 ("gcc42") or 4.3 ("gcc43") consisting of "gcc-4", "g++-4", and "gfortran". Mac OS 10.4.x / Darwin 8.x / Tiger: * Apple XCode gcc/g++ 4.0.1 with g95 (fink-installed or from www.g95.org) or * Fink-installed GNU Compiler Collection Version 4.2 ("gcc42") or 4.3 ("gcc43") consisting of "gcc-4", "g++-4", and "gfortran". - Tested at LHEA on: Intel Macintosh / OS X (Darwin 9.3.0 / Leopard) - GNU gcc/g++ v4.0.1 [Apple XCode], g95 v4.0.3 [from www.g95.org], perl 5.8.8 - Pre-compiled binaries built at LHEA on: Intel Macintosh / OS X (Darwin 9.3.0 / Leopard) - GNU gcc/g++ v4.0.1 [Apple XCode], g95 v4.0.3 [from www.g95.org], perl 5.8.8 Intel Macintosh / OS X (Darwin 8.11.1 / Tiger) - GNU gcc/g++ v4.0.1 [Apple XCode], g95 v4.0.3 [from www.g95.org], perl 5.8.8 PowerPC Macintosh / OS X ------------------------ - Recommended compilers: Mac OS 10.5.x / Darwin 9.x / Leopard: * Apple XCode gcc/g++ 4.0.1 with g95 (fink-installed or from www.g95.org) or * Fink-installed GNU Compiler Collection Version 4.2 ("gcc42") or 4.3 ("gcc43") consisting of "gcc-4", "g++-4", and "gfortran". Mac OS 10.4.x / Darwin 8.x / Tiger: * Apple XCode gcc/g++ 4.0.1 with g95 (fink-installed or from www.g95.org) or * Fink-installed GNU Compiler Collection Version 4.2 ("gcc42") or 4.3 ("gcc43") consisting of "gcc-4", "g++-4", and "gfortran". Mac OS 10.3.x / Darwin 7.x / Panther: Apple XCode gcc/g++ 3.3, fink-installed g77 3.4 - Tested at LHEA on: Macintosh PPC / OS X (Darwin 9.6.0 / Leopard) - GNU gcc/g++ v4.0.1 [Apple XCode], gfortran v4.2.1 [fink], perl 5.8.8 Macintosh PPC / OS X (Darwin 8.11.0 / Tiger) - GNU gcc/g++ v4.0.1 [Apple XCode], g95 v4.0.3 [g95.org], perl 5.8.6 Macintosh PPC / OS X (Darwin 7.9.0 / Panther) - GNU gcc/g++ v3.3 [Apple XCode], g77 v3.3 [fink], perl 5.8.1-RC3 - Pre-compiled binaries built at LHEA on: Macintosh PPC / OS X (Darwin 9.6.0 / Leopard) - GNU gcc/g++ v4.0.1 [Apple XCode], gfortran v4.1.1 [fink], perl 5.8.8 Macintosh PPC / OS X (Darwin 8.11.0 / Tiger) - GNU gcc/g++ v4.0.1 [Apple XCode], g95 v4.0.3 [g95.org], perl 5.8.6 Macintosh PPC / OS X (Darwin 7.9.0 / Panther) - GNU gcc/g++ v3.3 [Apple XCode], g77 v3.3 [fink], perl 5.8.1-RC3 Sparc / SunOS v5.6 (Solaris v2.6) and higher -------------------------------------------- SunStudio12 compilers Sun Workshop compilers GNU compilers v4.0 or higher (gcc/g++/gfortran only - g77 not supported) - Tested at LHEA on: Sparc / SunOS v5.9 - SunStudio12 cc/CC/f95, perl 5.8.8 - Pre-compiled binaries built at LHEA on: Sparc / SunOS v5.9 - SunStudio12 cc/CC/f95, perl 5.8.8 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ADDITIONAL NOTES ABOUT PLATFORMS AND COMPILERS +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ PERL / PERL MODULES: -------------------- - Wherever possible, different versions of Perl (ranging from v5.005_03 to v5.8.8) were tested on the various platforms. With the exception of problems on Solaris using v5.005_03 (where a few tools failed) all versions worked fine. Most modern machines should come equipped with v5.6.0 or higher so Perl version should not be an issue for users. - Please note that CFITSIO.pm, like all Perl modules, has its own configuration process, one which will preferentially select the compiler, flags, etc. that were used to build Perl itself, instead of using the ones you may have chosen for the HEAdas build. This can lead to portability problems in some cases and we continue to explore how to best handle this issue. - Please also note that portability of the pre-compiled HEASOFT binaries is limited by portability of the Perl modules. Users are likely to have problems running our pre-compiled Perl tasks unless they have installed the same version of Perl which was used at LHEA to generate the binaries (see details for the binaries above). Please see the following web page for more information: http://heasarc.gsfc.nasa.gov/lheasoft/perl_libs.html MAC OS X / DARWIN: ------------------ There is a known pitfall in building the software under OS X regarding the "vfork" or "fork" system tools which are used for spawning child processes of a given task (in this case the HEADAS build). The maximum number of processes by a single user (here, "maxproc") may sometimes be exceeded due to the flexible build paradigm used in HEADAS. Users who are running a large number of other programs are advised to exit some of these tasks before building HEADAS to avoid hitting the "fork" error during the build. You may also increase maxproc to help avoid this error. The method for changing this limit depends on your OS: OS 10.3.x (Panther): maxproc may be altered using the "sysctl" command, or by creating /etc/sysctl.conf (if it doesn't already exist) with the contents: > cat /etc/sysctl.conf # Turn up maxproc kern.maxproc=2048 # Turn up the maxproc per user kern.maxprocperuid=512 OS 10.4.x (Tiger): The launchctl utility can be used to set/alter resource limits. You can check the current settings by running launchctl limit. To change the settings you need to create /etc/launchd.conf (if it doesn't already exist) with the contents: > cat /etc/launchd.conf limit maxproc 512 2048 The first number is the soft limit and the second is the hard limit. SUNOS/SOLARIS: -------------- Builds on SunOS using non-GNU compilers now have Fortran optimization turned off by default, due to runtime problems when using the SunStudio Fortran compiler. Users who wish to increase optimization for e.g. the Workshop Fortran compiler may configure HEASOFT using the '--with-fopt=' option. CYGWIN: ------- We continue to try to improve support for all packages under Cygwin, but the FV/GUIs package in HEASOFT is not yet supported. FV may be obtained as a stand-alone application via http://heasarc.gsfc.nasa.gov/lheasoft/ftools/fv/fv_download.html PPC/LINUX: ---------- Support for PPC Linux has been discontinued as of the HEASOFT 6.5 release. ALPHA/OSF: ---------- Support for Alpha/OSF/HP/Tru64 Unix has been discontinued as of the HEASOFT 6.1.2 release. SGI/IRIX: --------- SGI/IRIX is no longer supported as of HEAsoft v6.0. A GENERAL CAVEAT ABOUT COMPILERS: --------------------------------- The pace of development of new compilers (particularly GNU products) is quite fast, and given the number of platforms on which this software is supported, it is virtually impossible for our development team to try every combination -- especially compiler versions which are released *after* our release! It is recommended that users check our website: http://heasarc.gsfc.nasa.gov/lheasoft/supported_platforms.html for the latest information about compiler problems, BEFORE attempting to build our software. The information given below, and in the listing above is correct and current, as far as we know, as of the release date. ***************************************************************************** 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 (g77 or gfortran) compiler is recommended. * On Mac OS X, g95 (fink-installed or from http://www.g95.org/) is recommended, but gfortran (fink-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.6.2<src|arch>.tar.gz | tar xf - This will create a heasoft-6.6.2/ 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.6.2/BUILD_DIR directory: cd heasoft-6.6.2/BUILD_DIR/ * If you downloaded the binary distribution, go to the heasoft-6.6.2/<PLATFORM>/BUILD_DIR directory: cd heasoft-6.6.2/<PLATFORM>/BUILD_DIR/ where <PLATFORM> = 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 9. 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.6.2/ 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, ie. ("/local/scratch G3/heasoft-6.6.2/") 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 9 IF YOU ARE USING A PRE-COMPILED BINARY DISTRIBUTION * * SKIP TO STEP 5 UNLESS YOU ARE INSTALLING XSPEC 11 WITH LOCAL MODELS * XSPEC 12 uses a different method for local models, so please see the last section of this document if you are using XSPEC 12 instead of 11. * PLEASE NOTE: XSPEC local models can only be built using the HEASOFT source distribution. There are two ways to include local models in XSPEC 11: A) It is possible for users to add local models *after* XSPEC 11 is completely installed. This is useful if the same installation of XSPEC will be used by scientists who wish to use different sets of local models. To use this option, make sure that your LMODDIR environment variable is *not* set, and go on to step 5. However, it is recommended that you at least skim the section below (at the end of this document) titled "ADDING LOCAL MODELS TO XSPEC 11 AFTER INSTALLATION" before you attempt this method. B) The other option is much simpler, and is strongly recommended if the same local models will be used by all users of a given XSPEC 11 installation. Instructions for this option are given here (note that this method is no longer used with XSPEC 12): Create a directory with all the local model source code files (IMPORTANT: do not use the same directory for xspec v12 models), and a matching lmodel.dat file (see the XSPEC 11 documentation for further information about local model coding). Then set the environment variable LMODDIR to point to this directory. In csh or tcsh, type: setenv LMODDIR /path/to/local/model/code In sh or bash, type: LMODDIR=/path/to/local/model/code export LMODDIR Then proceed to step 5. Users will automatically have access to the local models after the installation finishes, and need not take any special actions. 5) 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 6) 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. \*\*\*). 7) 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.6.2/ or, if you specified a prefix argument to configure, (see Step 4 above), in the directory you selected at that time. Please note that if you are building local models for xspec 11 (as in step 4-B), you should ensure that the value of $LMODDIR has not changed in your environment since you performed the build (step 5). 8) VERY IMPORTANT: Check your install.log for errors! The best method is the same as that described in step 6. 9) At this point, HEASOFT should be completely installed, either under the directory heasoft-6.6.2/ or under the prefix <dir> 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.6.2/<PLATFORM> alias heainit "source $HEADAS/headas-init.csh" * For users of Bourne Shell (sh, ash, ksh, and bash): Edit your $HOME/.login to include lines based on the following: HEADAS=/path/to/your/installed/heasoft-6.6.2/<PLATFORM> 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, <PLATFORM> reflects your machine's architecture, for example: i686-pc-linux-gnu-libc2.3.4 sparc-sun-solaris2.9 powerpc-apple-darwin8.9.0 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 <dir> 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 11 AFTER INSTALLATION ***************************************************************************** ** NOTE: XSPEC local models can only be built using the HEASOFT source code distribution. ** XSPEC 12 users: see below for information about installing local models with XSPEC 12 Because XSPEC 11 uses a shared library to house local models, it is possible for users to add their own local models, simply by creating new versions of that shared library. This obviates the need for users to build their own private copies of the xspec binary, because the new shared library may be loaded without re-linking xspec. To add local models after installation, follow these steps: LM1) Create a directory with all the local model source code files (IMPORTANT: do not use the same directory for xspec v12 models), and a matching lmodel.dat file (see the XSPEC 11 documentation for further information about local model coding). Then set the environment variable LMODDIR to point to this directory. In csh or tcsh, type: setenv LMODDIR /path/to/local/model/code In sh or bash, type: LMODDIR=/path/to/local/model/code export LMODDIR LM2) Go to the $LMODDIR directory, and copy all the files from the directory local_mod/ into $LMODDIR: cd $LMODDIR cp $HEADAS/../spectral/xspec/src/local_mod/* . Note that this will copy a Makefile, a copy of xspec.inc, and a copy of model.dat into the local directory. LM3) Still in $LMODDIR, type hmake hmake install "hmake" should build the local model library in $LMODDIR, and "hmake install" should copy it into the installed location. Note that hmake will compile all *.f and *.c files in the directory but xspec will only call functions referred to in the lmodel.dat file. (The user is of course responsible for his/her own programming errors!) Important note for Mac OS X users: ---------------------------------- Currently, since we cannot compile a shared version of the local model library (as it contains Fortran code) on Mac OS X, you must perform an extra step in the source code tree in order to re-link xspec11 with your new static library. First, change directory to the top of the HEASoft source tree (which, by default, is $HEADAS/../): cd $HEADAS/../ (or cd /path/to/your/heasoft-6.6.2/ if you gave a prefix to configure) cd ftools/spectral/xspec/src/ rm local_mod/libxspec_lfn* rm xspec11 hmake xspec11 hmake install After these steps are completed, the local models should be available. ***************************************************************************** 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 9). 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. Help lines: FTOOLS or xanprob@athena.gsfc.nasa.gov Web page maintained by Bryan K. Irby HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public Last modified: Monday, 06-Apr-2009 14:26:38 EDT