*************************************************** Building the SAO R&D software tree (updated: 12 April 1999) Please report any problems to: saord@cfa.harvard.edu *************************************************** The SAO R&D directory tree contains source code for: XPA The XPA Messaging System (E. Mandel) SAOtng SAOimage: The Next Generation image display (E. Mandel, D. Tody, S. Mukhtar) XDir X11 directory and file browser (E. Mandel) ncl IRAF cl with tcsh-style line-editing (E. Mandel, based on the IRAF cl) and some other things ... The code has been built on the following platforms: Sun Sparc Solaris 2.5, 2.6, 2.7 OpenWindows 3.2 and X11R5/6 Sun Sparc SunOs 4.1.3, 4.1.4 X11R5/R6.1 HP9000/735 HP/UX A.10 X11R5? SGI IRIX 5.2, 5.3, 6.2 X11R5/R6 DEC Alpha OSF1 4.0 X11R6 Gateway P5-90 Slackware 2.3 X11R6 RedHat 5.0 X11R6 Most development work has been performed on the Sun platforms. Both ANSI C and K&R compilers have been used to build the code. However, stdlib.h and unistd.h are required in various modules. (We hope to use GNU configure in the future to alleviate these sort of portability problems.) We built the system using the X Consortium, Inc. distribution of X11R5 and X11R6, and with various vendor's version of X11R5 and X11R6. In all cases, you must have access to the Athena widget set (libXaw, libXmu, etc). Also, you must have a working version of imake that supports X11R5 conventions (i.e,, one that supports use of "XCOMM" as comments, which means not the X11R4 version). ******************************************************************************* Summary of BUILD instructions # unpack the tar file zcat saord.tar.Z | tar xf - # or: gunzip -c saord.tar.gz | tar xf - # enter saord directory cd saord # build the Unix support (SAOtng, ASSIST, etc.) # (Sun non-OpenWindows users edit saord/config/Imake.rules) xmkmf make -k World >& build.log & # wait for completion and grep log for errors, then ... make install >& install.log & # for iraf support (ncl, etc.) mkpkg >& mkpkg.log & # wait for completion and grep log for errors, then ... mkpkg install >& mkpkg.install & # clean up make clean mkpkg clean ********************** Building the SAO R&D software tree ******************** 1. The source code for the R&D software suite comes on a compressed (or gzip'ed) tar file named saord.tar.Z (or saord.tar.gz). The software suite will be unpacked into a top level directory called 'saord'. You first must uncompress and unpack this file: zcat saord.tar.Z | tar xf - (compressed) or gunzip -c saord.tar.gz | tar xf - (gzip'ed) You should unpack the saord directory in semi-permanent place, since you will need to have (at least part of) it around to run the programs. 2. This will create a 'saord' directory containing the SAO R&D software tree. Enter this directory: cd saord ************************** NB: All Sun Users ******************************* Important Note: You might naively think that X programs build under Solaris 2.5, 2.6, and 2.7 would be binary compatible, but this is not the case *unless* you link the X libraries statically. OpenWindows under Solaris 2.6 (at least) cannot be linked statically because of missing libraries (libICE.a and libSM.a). Therefore, unless you know how to link statically and have an X Consortium version of X, you will need to produce a separate version of saord for each Solaris version. We managed to build the saord Solaris binary release statically at SAO, so you can use that if you want one saord for all Solaris platforms. Otherwise read on ... Bowing to the inevitable, we now assume that you will be building saord against OpenWindows. For Solaris 2.6, OpenWindows seems to work pretty well. For older releases, we have attempted to work around several bugs in the OpenWindows Imake configuration files. Since OpenWindows now is assumed, if you are NOT building this software under OpenWindows, you must edit the saord/config/Imake.rules file and change the value: #define FixOpenWindows 1 to #define FixOpenWindows 0 to avoid using the OpenWindows fixes. This must be done before running imake or xmkmf at the top level. Otherwise, if you are building against OpenWindows, please note that you must have the OPENWINHOME environment variable set before starting the build. Non-Solaris (SunOS) users probably should have their LD_LIBRARY_PATH environment variable set to include ${OPENWINHOME}/lib (we don't have such a configuration, so this is a guess!). A final note: OpenWindows libraries are compiled at Sun using the Sun cc compiler. We have never had much luck linking gcc modules with Sun cc modules -- there are, for example, differences in how float arguments are passed that cause such a mixed program to give wrong results. If you are running OpenWindows but do not have the Sun cc compiler, please contact us or better yet, grab the binary release. ************* NB: Solaris 2.6 users using gcc (not using openwin) *********** If you are going to build with OpenWindows, skip this section and go to the next set of headaches ... If you are building saord using gcc ... it turns out that versions of gcc prior to gcc 2.8.0 will not compile Solaris 2.6 programs. The problem is that gcc 2.7.x uses a number of its own "standard" include files, but not quite enough of them, so that you get an incompatible mixture of Sun and gcc includes. For example, the following program does not compile because of missing CPP definitions: #include #include main(argc, argv) int argc; char **argv; { fprintf(stderr, "Hello world\n"); } We tried unsuccessfully to work around this problem for our software, but it was too much of a mess. So the solutions are: 1. upgrade to gcc 2.8.0 2. use cc (which you will get if you link against openwin) 3. use the binary distribution of saord for Solaris 2.6 Very sorry -- life is getting rougher! ********************* NB: SGI IRIX 5.2 users ****************************** We have attempted to work around a bug in X11 under IRIX 5.2 that causes SAOtng to crash immediately. The fix requires that we make the TCL GUI specification file smaller. To do this, we "crunch" the GUI file by changing the usual descriptive widget names to 2-character symbolic names, and then we use the crunched file as the default GUI spec. The crunched file is called "crunch.gui" and will be found in the SAOtng directory. If you are building this software under IRIX 5.2 you must edit the saord/config/Imake.rules file and change the value: #define CrunchGUI 0 to #define CrunchGUI 1 This must be done before running make at the top level. The above directive will cause SAOtng to be built with the crunched GUI file as the default GUI specification. So far as we can determine, users of IRIX 5.3 and above do not have to worry about this issue because X11 appears to be fixed in revisions of the OS after 5.2. However, if SAOtng crashes immediately on startup, please try the above fix -- and let us know either way, so that we can improve SGI support. **************************************************************************** 3. The SAO R&D software tree is built using imake. We use the X11 "xmkmf" script to create the top-level Makefile in the saord directory: xmkmf 4. [This step is optional.] To verify the architecture you will be building, type: make showarch The command will output a message like: Current architecture: sun4-sol2 5. Build the SAO R&D software tree and create a log of the output: make -k World >& world.log & [NB: Do not execute "make" with no arguments. This will start compilation without building Makefiles for your installation and the compile will fail.] The build will be started by setting up the appropriate architecture. A Unix "bin" link will be created that points to bin. (e.g. bin.sun4-sol2) and a "lib" link will be pointed to lib. (e.g. lib.sun4-sol2). During the build and install processes, files will be written to bin and lib and thus, to bin. and lib.. If bin. and lib. themselves do not exist (the default situation), they will be created as sub-directories of the saord directory by 'make arch'. You can, however, link bin. and/or lib. to directories existing elsewhere. This would result in the saord libraries and/or binaries being installed in the external directories. (If you do this, make sure you have write permission to the external directories). The software tree contains a large amount of code (> 300000 lines). It typically takes on the order of 1/2 hour to build on most of the platforms we have used. Of course, this depends a lot on machine load, disk access (NFS vs. direct), etc. Fast Linux PC's complete the build in less than 10 minutes! 6. If everything has proceeded reasonably, the binaries can be installed in the bin. directory: make install >& install.log & 7. If you are using ASSIST or SAOtng with IRAF, you will want to build and install the IRAF tools. (This will be the case, for example, if you want to load IRAF images directly into SAOtng without having to use the IRAF tv/display package.) The standard IRAF mkpkg is used to build these tools. Building any IRAF task requires that you set the IRAFARCH environment variable for your platform (e.g., "sparc" for SunOS, "ssun" for Solaris, "irix" for SGI, etc.) -- before trying to compile. All IRAF mkpkg commands read the iraf system file hlib$mkpkg.inc to get global flags used in the compilation, so if you don't have IRAFARCH defined properly, the wrong flags (those for SunOS) are used. (In this case, you will get a"-Bstatic" flag that is meaningless on other platforms, causing the compilation to fail). For IRAF compilation it's also a good idea to define other IRAF-related variables such as setenv iraf /iraf/iraf/ # must have trailing '/' setenv IRAFARCH irix # set system arch source $iraf/unix/hlib/irafuser.csh # pick up other handy defs Once the IRAF environment is set up, you can build the IRAF part of SAORD. For some parts of the IRAF build, mkpkg calls Imake to build C/Unix tools used with IRAF and therefore you might need to execute xmkmf before running "mkpkg": xmkmf # only if you have changed platforms since the 'make' mkpkg >& mkpkg.log & mkpkg install >& mkpkg.install & These commands will build and install a new version of the IRAF cl (with line editing) and other programs. The build requires knowledge of the path of the installed IRAF directories and compiles a fake IRAF program to determine this location. If the build fails, and especially if it cannot find the IRAF libraries, please contact us. 8. You can clean the directory tree of object files: make clean # remove .o and .a files from directory tree make strip # strip binaries of symbols to make them smaller mkpkg clean # only if you built IRAF tools as well You can remove the directories containing the source files and save even more space by running: make stripall # remove all source directories 9. Make sure the saord/bin. directory is in your search path. Run the assist, saotng, xdir, and ncl scripts to access the software. Note that if you move later the source tree, you can set the environment variable SAORD_ROOT to point to the new location -- otherwise, you need to recompile and install the scripts directory to pick up the new directory location. ************************** Notes For Linux Users **************************** The IRAF version of Linux is undergoing rapid development as Linux itself rapidly evolves. At present, we find that we are able to build the saord IRAF packages and tasks on most Linux platforms (e.g. Slackware and RedHat). If you are building the IRAF part of saord under Linux, please make sure you read the IRAF README file for Linux (which is reproduced in this directory as README.IRAF.LNUX). If you have trouble, we at SAO along with the developers at NOAO will try to help you build on new Linux platforms; eventually things will settle down. Also, we have had a lot of trouble compiling the included version of lynx (2.5) on different Linux platforms. As is appears that lynx comes with most versions of Linux, we have cut the Gordian knot by commenting out the saord build of lynx for Linux. If you do not have lynx and want to use ASSIST to read HTML files, you can edit the saord/WWW/Imakefile to remove the lines: #ifndef LinuxArchitecture #endif Again, let us know if you have problems and we will try to help. ******************* An important note about X11 resources ******************* Most X programs make use of "resources" to tailor the look of the GUI. Resources allow you to change fonts and colors and sizes, etc. In most X programs, (such as ASSIST and XDir), resources are maintained in program-specific resource files. SAOtng maintains resources in the saotng.gui TCL file. You can make your own copy of these files and edit resources to suit your own taste -- see the X man page under "RESOURCES" for more information than you would ever want. In addition to the user of application resource file, you can have global resource files, usually called either .Xresources of .Xdefaults, and usually maintained in your home directory. These files can define resources for lots of program at once; the values are read into the X server at X startup time and persist throughout an X session. The global resources defined in these files can be viewed at any time by typing the command: xrdb -query Over the years, we have had a series of problems with resources placed in these files that are "too" global -- that is, resources that unintentionally affect all programs. Such resources generally begin with a "*" and do not have a specific program name in the resource specification: *res_name: res_value e.g., *background: white *foreground: black *resizable: True *Label.internalWidth: 0 Resources such as these almost always have subtle but unintended and unwanted side effects and should be avoided. If you bring up an X program and the GUI looks peculiar or wrong, please look for global resources such as these -- they have proven to be the culprit in several cases thus far. (The solution is to remove them from the global resource file or to prefix them with specific program names.) *************** The following notes are for ASSIST installation ************** 1. If you have modified a personal copy of the AGS resource file for past releases of ASSIST, please make sure you retrieve a new copy of AGS from saord/app-defaults and merge in changes. We try to ensure that our updates to AGS are backwards-compatible, but the accumulation of changes now is causing problems with old versions of the AGS file. 2. On ASSIST startup, the IRAF task hierarchy structure is determined by accessing a file contained in the saord/AGNodes subdirectory. This file must be maintained at each site, since different site support different IRAF packages. To create the IRAF task hierarchy file, run the assist_mkhdb script in the scripts subdirectory: cd saord/bin ./assist_mkhdb cd .. This script will run the assist hdb program, which reads the IRAF help data base and generates the required task information file in the AGNodes subdirectory. Note that this file must be regenerated whenever a change is made to the IRAF tree (i.e., the addition or deletion of packages, or the installation of a new version of IRAF). 3. The ASSIST "Locate Tasks" function, which performs keyword searches through the IRAF tree, works much more quickly if a quick reference file of IRAF help can be accessed. As with the help data base file, this file must be maintained at each site, since different site support different IRAF packages. To create the IRAF quick reference file, run the assist_mkqref script in the scripts subdirectory: cd saord/bin ./assist_mkqref cd .. This script will run the IRAF references program to create a quick reference file in the AGNodes subdirectory. Note that this file must be regenerated whenever a change is made to the IRAF tree (i.e., the addition or deletion of packages, or the installation of a new version of IRAF). 4. The ASSIST help display facility will first look for an IRAF help file in the saord/IRAFHelp directory and, if it is found, will use that file instead of creating one in the user's uparm directory. This makes the display of help files much faster. The IRAFHelp directory of IRAF help is files quite large, however, and is therefore distributed separately from the ASSIST release. It can be obtained from anonymous ftp to sao-ftp.harvard.edu, in the pub/rd directory. The IRAF 2.10.3 and 2.10.4 help files are available as tar files called IRAFHelp-2.10.3.tar.Z and IRAFHelp-2.10.4.tar.Z. NB: There are approximately 2000 files in the IRAFHelp tar file. Please make sure your system quotas are high enough to handle this number of files. Once one of these tar files has been retrieved, it can be uncompressed and unpacked in the same manner as the saord tar file. This should be done in the saord directory itself, so that the IRAFHelp directory will be placed in the saord tree. cd saord zcat IRAFHelp-2.10.3.tar.Z | tar xf - An alternative to unpacking this large number of files is to create a set of IRAF help file for your site. This can be done with the hdbhelp program, which will output (to STDOUT) a very long series of IRAF commands to regenerate IRAF help files. The input to this command is the help data base file that was created using assist_mkhdb. Using this command will generate a script containing the help files for your site. The host command line for running this program is: hdbhelp {hdb file} > irafhelp.cl where {hdb file} is the IRAF task hierarchy file generated by the assist_mkhdb script. This output from this program should be edited before running, to avoid creating more help files than are reasonably needed. (The default setup only includes the most important 2000! files) One can then create help files in IRAF with the IRAF command: cl < irafhelp.cl Note that this command can be run from within IRAF or from the host shell. We have found, however, that it is necessary split the file up into a few separate scripts and run each one in a separate invocation of IRAF, in order to avoid memory problems. Because the script will tell you the name of the help file that is being created, if (or when) a memory corruption problem occurs which interrupts the script, you can see how far you got, edit the irafhelp.cl input file and restart after the last created file. 5. The ASSIST Q&A facility (activated using the "Q&A" button on each parameter editor) no longer requires that you install the Q&A reports locally. Step 12 in the instructions has been changed to: Enjoy ASSIST and SAOtng!