*************************************************** Building a binary distribution of the SAO R&D software tree (updated: 27 May 1999) Please report any problems to: saord@cfa.harvard.edu *************************************************** The SAO R&D binary tree contains executables and support files 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 ... ******************************************************************************* 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 # configure the Unix support (SAOtng, ASSIST, etc.) for your site make Binary ****************** Building the SAO R&D binary distribution ***************** 1. The R&D binary distribution 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) 2. This will create a 'saord' directory containing the SAO R&D software tree. Enter this directory: cd saord 3. Build the SAO R&D binary distribution: make Binary That's it! This command will configure the SAO R&D scripts for your installation by running sed on the script files. 4. 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 the source tree, you can set the SAORD_ROOT environment variable to point to the new location -- or you can rerun step 3. NB: If SAORD programs have difficulty finding shared libraries, please contact us (or your system manager, who undoubtedly knows about your library setup). We have tried to use standard libraries in linking SAORD binaries, but your site's system configuration might require setting the LD_LIBRARY_PATH environment in order to find shared libraries. ****************************** 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. We managed to build the saord Solaris binary release statically at SAO, so you can use this binary distribution for all Solaris platforms. (This will not in general be the case if you build from source yourself.) Note that the above command 'make Binary' will make saord/bin.sun4-sol26 and saord/bin.sun4-sol27 links to the directory saord/bin.sun4-sol2 (where the executables are located). For safety sake, you should put the appropriate bin directory in your path for each version of Solaris, rather than just using saord/bin.sun4-sol2. ********************* NB: SGI IRIX 5.2 users ****************************** We have not had much luck with the binary distribution under IRAF 5.2. The first problem is that the correct shared libraries are not available (at least on the 5.2 system we tested). But also, a bug in X11 under IRIX 5.2 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. The crunched file is called "crunch.gui" and is in the bin directory. In building from source, you can arrange to make this crunched GUI be the default GUI by editing saord/config/Imake.rules and setting the CrunchGUI directive to 1. When using the binary distribution (assuming you have the correct libraries), you have to set up use of this crunched GUI explicitly (because the default assumes a more modern version of IRIX that does not have the bug). So if your SAOtng crashes on startup, try: saotng -gui <...>/saord/bin.sgi/crunch.gui If this works, you can set a more permanent environment variable in your home directory's .saotng file: setenv SAOTNG_GUI <...>/saord/bin.sgi/crunch.gui Please let us know if you have problems. ******************* 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. 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). 2. 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). 3. 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 xfB - 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. 4. 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!