How to download and build NCAR Graphics® Software from source code To download the NCAR Graphics source code, follow the instructions at the URL: http://ngwww.ucar.edu/ng4.2/ The NCAR Graphics source code that you download will either be a single compressed tar file, or multiple compressed tar files. Let's assume you downloaded the multiple compressed tar files, called "ncarg4.2.3.libs.tar.gz", "ncarg4.2.3.db.tar.gz", and "ncarg4.2.3.misc.tar.gz". To get ready to build NCAR Graphics Software from these files, move them to a temporary directory where you have plenty of disk space (around 100 megabytes to hold all of the source code, object files, binaries, and so on). Then, uncompress and un-tar the files as follows: % gunzip ncarg-4.2.3.libs.tar.gz (or uncompress if the files end in ".Z") % gunzip ncarg-4.2.3.db.tar.gz % gunzip ncarg-4.2.3.misc.tar.gz % tar -xvf ncarg-4.2.3.libs.tar % tar -xvf ncarg-4.2.3.db.tar % tar -xvf ncarg-4.2.3.misc.tar The above steps will create a directory called ncarg-4.2.3. Set the environment variable NCARG to the name of this directory. For purposes of convenience, we use the notation $NCARG to mean the top level of the NCAR Graphics source tree. For example, if you untarred the files from the directory /usr/local/src, then you would do the following: setenv NCARG /usr/local/src/ncarg-4.2.3 ------------------------------------------------------------------------ Build NCAR Graphics Software from source code In order to build NCAR Graphics Software from source, you must have a Fortran 77 or 90 compiler and an ANSI C compiler. Here are the general steps for building NCAR Graphics Software from source: 1. Run Configure script 2. Modify configuration files to recognize your system (only needed if Configure doesn't recognize your system) 3. Modify system configuration file to change compiler defaults (may not be necessary) 4. Start the build and install process 5. Test the installation ------------------------------------------------------------------------ Run Configure script Before you build and install NCAR Graphics Software, you need to run a script called "Configure" to see if your system is recognized by the NCAR Graphics make system. This script will ask you several questions, and it will also allow you to specify directories for installation. Enter the following commands to run this script (you must be running csh): cd $NCARG ./Configure -v If Configure doesn't recognize your system, it will quit right away with an error message. Otherwise, it will start asking you several questions. If it quits with an error message that indicates it doesn't recognize your system, then you need to go to the section "Modify configuration files to recognize your system" before running Configure again. If Configure does recognize your system, then answer all of the questions about where you want the software installed, whether you want to use a Fortran 90 compiler, whether you want X11 support and/or HDF support, and so on. Note: if you do not have the HDF libraries installed on your system, and/or you don't think you'll be needing HDF support, then answer "no" to the question about building HDF support into the raster library. Once you have finished running Configure, you should get a message indicating that the configuration process is complete, and that you can start building and installing the software. Before you do this, however, go to the section "Modify system configuration file to change compiler defaults" to see if you need to change any of your compiler defaults. ------------------------------------------------------------------------ Modify configuration files to recognize your system You only need to read this section if the Configure script did not recognize your system. (We'll refer to this as an unsupported system.) If the Configure script recognized your system, then skip to the section "Modify system configuration file to change compiler defaults". The four steps you'll need to follow before building NCAR Graphics Software on an unsupported system are: 1. Modify the ymake file to recognize your system. 2. Set up a configuration file. 3. Modify the "c.h" include file (if necessary). 4. Modify machine-dependent routines (if necessary). Once you've completed these four steps, then you need to run the Configure script again as described in the "Run Configure script" section. 1. Modify the ymake file to recognize your system For the first step, modify the file $NCARG/config/ymake and go to the lines that read: # Figure out what kind of system we are on. We need to know the OS # and the machine architecture. Notice that the UNIX command uname is used to determine the architecture type and operating system name. Once you figure out what the various options that uname reports on your system, add your machine architecture and operating system names to the case statements that follow in the same manner as the other systems are done. You also need to come up with a name for your configuration file. This is the value you'll give to the sysincs variable. An example will be provided below after step 2. 2. Set up a configuration file For the second step, cd to $NCARG/config and prepare a configuration file for your system that has the same name you used for the sysincs variable in the ymake file. Use one of the existing configuration files as a foundation (for example, Sun4Solaris). You will notice several macros being defined in the configuration file. You only need to define a macro if you want it to be something different than what is defined in the Template file. The Template file is where all the defaults are set. For example, the default Fortran compiler is set to "f77" in the Template file. If your Fortran compiler is called "g77", then you would add the following line to your configuration file: #define FCompiler g77 To see what other macros are available and what the defaults are set to, see the Template file. In particular, you may need to change the following macros: CCompiler FCompiler ExtraSysLibraries CcOptions FcOptions Example on how to modify ymake file and set up configuration file As an example for the first two steps, suppose you are trying to build a configuration file for a Koblinsky Systems Inc. SlothStation running ChaOS version 5.4. Assume that the command uname -s returns "ChaOS" and that uname -m returns "Sloth999". Modify the file $NCARG/config/ymake and add: case ChaOS: right after the first occurrence of the statement: switch ("$foo") You should now see something like: switch ("$foo") case ChaOS: case SunOS: case AIX: ... Then, after the first occurrence of the statement: switch("$opsys") add the lines: case ChaOS: set os = $opsys set arch = $mach set sysincs = Sloth set vendor = Koblinsky breaksw and after the second occurrence add: case ChaOS: where appropriate to get the correct major and minor operating system version numbers defined. Let's further assume that this system is similar to a Sun workstation running Solaris, so use the Sun4Solaris configuration file as a foundation: cd $NCARG/config cp Sun4Solaris Sloth The filename "Sloth" is used because this is the value we gave to the "sysincs" variable above. Make any obvious changes to the file "Sloth". As mentioned above, you may need to change the following macros: CCompiler FCompiler ExtraSysLibraries CcOptions FcOptions 3. Modify the "c.h" include file NCAR Graphics code is predominantly Fortran code, but the Fortran code relies on a number of C support routines. Since not all systems support the same calling conventions (for example, some systems require an underscore after a Fortran routine name, while others require the name to be in uppercase), the installation system is programmed to apply the macro NGCALLF to all Fortran-called C code. In porting to a new system, you may need to modify this macro in the $NCARG/common/src/libncarg_c/c.h include file. The default is to add an underscore after the Fortran routine name, so if this is what your system does, you don't need to modify this file. 4. Modify machine-dependent routines There are some machine dependent routines that you may need to modify to indicate things like the standard input/output units, the number of bits per integer, the smallest positive magnitude, and so on. All of these machine-dependent requirements have been isolated in several subroutines and it may be necessary to modify these subroutines before building the software. The routines in question are: GBYTES ISHIFT G01MIO I1MACH IAND R1MACH IOR SBYTES These routines are referred to as "low-level support routines" in the remainder of this section. Complete functional descriptions for these routines appear in the section "Machine-dependent support routines". Examples of implementations of all of these subroutines except G01MIO are given in the directory: $NCARG/common/src/libncarg_c A Fortran implementation of the support routine G01MIO is contained in the directory: $NCARG/ncarg2d/src/libncarg_gks/bwi G01MIO is the basic I/O routine for NCAR's GKS package, and it is not used anywhere else but in that package. The subroutines in the above two directories are examples only. These examples may help you, and some may actually run on your machine, but care must be taken to ensure that the implemented routines satisfy the functional descriptions as given in the "Machine-dependent support routines" section. Some of the examples given are coded in C. There is source code for creating an executable for testing implementations of the low-level routines in the directory: $NCARG/ncarg2d/src/bin/impltest The source in this directory may require changes only when moving to a machine with a word size other than 32 or 64. This directory contains a program called tlocal that can be used to test the implementations of IOR, IAND, ISHIFT, GBYTES, and SBYTES. Read the prologue documentation in the code for tlocal for implementation instructions. Success or failure messages will be issued to Fortran unit 6. There are no tests for I1MACH and R1MACH, but the success of the tlocal test depends on proper implementation of I1MACH and R1MACH. Constants for I1MACH and R1MACH for a large number of computers appear in the comment cards of I1MACH and R1MACH. If constants for your host computer appear there, simply uncomment the appropriate cards for your implementation of I1MACH and R1MACH. Otherwise be very careful to implement I1MACH and R1MACH correctly since there is no test for them. The support routine G01MIO is used only by NCAR's GKS package, and no test for it is provided in tlocal. Since many of the low-level support routines are executed frequently throughout the package, efficient versions are desirable. There are portable Fortran versions of GBYTES and SBYTES in the directory: $NCARG/common/src/libncarg_c but they run very slowly. GBYTES and SBYTES are used primarily in the NCGM translator; machine-language versions of these routines could greatly speed up the translator. Machine-language versions of IAND, IOR, and ISHIFT are also desirable. ------------------------------------------------------------------------ Modify system configuration file to change compiler defaults Once you've run "./Configure" and it successfully recognizes your system, you can type: cd $NCARG make Info to make sure your configuration is set up properly. The "make Info" command will report the installation directories, what C and Fortran compilers are being used, and what options to the compilers are being set. The name of the system configuration file being used will also appear on the line that starts with "System File". If you need to change the compilers or the options used, then modify the file $NCARG/config/system_file, where system_file is the system configuration file being used. In particular, you may want to pay attention to how the following macros are being set: CCompiler FCompiler ExtraSysLibraries CcOptions FcOptions and change them as desired. If you don't see these macros being defined in your system configuration file, then that means that the default value, which is defined in the $NCARG/config/Template file, is being used. To change the default, just add it to your system configuration file with the new value. For example, on Sun systems, the default "f77" compiler is used. If you want to change this to "g77", then modify the file $NCARG/config/Sun4Solaris, and add the line: #define FCompiler g77 along with the other macro definitions. ------------------------------------------------------------------------ Start the build and install process Once you've run "Configure", and "make Info" gives you the correct information, you can initiate the build and install process by typing: cd $NCARG make Everything >& make-output & Be patient; this can take from thirty minutes to a few hours depending on your machine and its current load. During the installation, you may examine the contents of the make-output file with the command: tail -f make-output If you encounter errors during the build process, you can restart without losing any of the work already accomplished. Refer to the section "Restarting the installation" for details about recovering from errors that occur during installation. ------------------------------------------------------------------------ Set up your environment to use NCAR Graphics Software Once the build process is complete, you need to do the following before you can start using NCAR Graphics Software: 1. Set the environment variable NCARG_ROOT to the parent directory of where you installed everything. 2. Make sure "$NCARG_ROOT/bin" is on your search path. 3. Make sure "$NCARG_ROOT/man" is on your man path. Here's an example (using csh) that assumes you installed everything to the parent directory /usr/local/ncarg: setenv NCARG_ROOT /usr/local/ncarg setenv PATH $NCARG_ROOT/bin:$PATH setenv MANPATH $NCARG_ROOT/man:$MANPATH ------------------------------------------------------------------------ Test the installation After the installation process has completed without aborting, you should test the installation. Since comprehensive testing not only requires you to run test programs but also to view the resulting graphics, you should refer to the NCAR Graphics Fundamentals. It will show you how to run examples and test programs, and how to view the resulting graphics. Using the ncargex and ctrans programs is the easiest way to test the installation and become familiar with the use of NCAR Graphics Software. You can read more about running examples and viewing the resultant graphics in the chapter "Five quick steps for creating and viewing your plot" of the NCAR Graphics Fundamentals. For a quick test, try the following: ncargex example ctrans -d X11 example.ncgm The first command will copy a file called "example.f" into your current working directory, compile, link, and execute it, and create a graphics file called "example.ncgm". The second command will display the graphic on an X11 window on your screen. You must have your DISPLAY environment variable set correctly for this command to work. Right-click on the X11 window to make the graphic go away. ------------------------------------------------------------------------ General information on build process This section contains general information on building NCAR Graphics Software that you may find useful. It includes information on: * configuration files * how to restart the installation if it bombs * the ymake system * machine-dependent support routines Configuration files Configuration files contain make macros. At installation time, these macros are used by ymake to construct all of the Makefiles for the NCAR Graphics release. Any change you make in your configuration file will be distributed throughout the entire system. Refer to the "ymake" section for more information. Configuration files reside in the directory $NCARG/config. They have names like Sun4Solaris and SGI_IRIX to indicate the machine on which they operate. For example, If you are on a Sun running Solaris, you should make changes to the file $NCARG/config/SunSolaris. There is one other file, Rules, which contains make macros. Generally, you would only change this file when you attempt to port the package to a new system. A few of the macros are quite likely to change from system to system, but most are not. The Configure script allows the installer to make some of these minor changes to the configuration file without editing it. You must be running csh in order to run Configure. Restarting the installation The standard build process is initiated by telling make to build the "Everything" target, which results in a series of actions. First, a hierarchy of Makefiles is constructed, based on your system configuration. Next, all old object code is removed, dependencies are created, and then compilation, the most time-consuming step, begins. Finally, libraries and executables are built and then installed. This can take from thirty minutes to a few hours. If you encounter an error along the way, it is very important that you avoid wasting the work that has already been done. There are other targets besides "Everything". The following targets may be used to gracefully restart the installation process: Everything = (Makefiles, clean, all, install) All = (Makefiles, all, install) all = (compile and build libraries) install = (move objects to destinations) clean = (remove object files, core dumps, etc.) If a compilation fails halfway through the install process and you have already created the Makefiles, cleaned out old object code, and compiled a large number of files, you may correct the problem and restart the install process by typing: make all install >& make-output & You might get most of the way through the installation, only to discover that the installation directories in your configuration file were incorrectly specified. To cause the Makefiles to be rebuilt using the new configuration file, type: make All >& make-output & ymake A utility named ymake is used by this package to generate the Makefile hierarchy. A file named yMakefile exists in each directory and is converted to a regular Makefile using the C preprocessor and a collection of general and system-specific macros. The ymake system resides in $NCARG/config. This allows the redundant information in each Makefile to be isolated, in addition to providing Makefile conditionals. The C preprocessor knows what system it is running on. (The same technique is being employed in other systems, including MIT's X Window System.) If you need to change a Makefile, implement the changes in the yMakefile and then type: make me If you completely destroy a Makefile, you can usually recover by typing: $NCARG/config/ymkmf There is more information about ymake in the ymake man page which resides in the directory $NCARG/config. Machine-dependent support routines Following are functional descriptions of the required locally-implemented support routines. A test suite is distributed for this package so that an implementor may verify that the implementations are correct. The routine G01MIO is needed only if the NCAR GKS package is being implemented. FUNCTION I1MACH(I) This function is used to set up 16 machine constants. I1MACH(1) = the standard input unit I1MACH(2) = the standard output unit I1MACH(3) = the standard punch unit I1MACH(4) = the standard error message unit I1MACH(5) = the number of bits per integer storage unit I1MACH(6) = the number of characters per integer storage unit Assume that integers are represented in the S-digit, base-A form: SIGN*(X(S-1)*A**(S-1)+...+X(1)*A+X(0)) in which 0 .LT. X(I) .LT. A for I=0,...,S-1. I1MACH(7) = A, the base I1MACH(8) = S, the number of base-A digits I1MACH(9) = A**S-1, the largest magnitude Assume that floating-point numbers are represented in the T-digit, base-B form: SIGN*(B**E)*((X(1)/B+...+(X(T)/B**T)) in which 0 .LT. X(1), and EMIN .LE. E .LE. EMAX. I1MACH(10) = B, the base Single-precision constants I1MACH(11) = T, the number of base-B digits I1MACH(12) = EMIN, the smallest exponent E I1MACH(13) = EMAX, the largest exponent E Double-precision constants I1MACH(14) = T, the number of base-B digits I1MACH(15) = EMIN, the smallest exponent E I1MACH(16) = EMAX, the largest exponent E FUNCTION R1MACH(I) This function sets five single-precision machine constants: R1MACH(1) = B**(EMIN-1), the smallest positive magnitude R1MACH(2) = B**EMAX*(1-B**(-T)), the largest magnitude R1MACH(3) = B**(-T), the smallest relative spacing R1MACH(4) = B**(1-T), the largest relative spacing R1MACH(5) = LOG10(B) FUNCTION ISHIFT(IWORD,N) IWORD is shifted by N bits. If N > 0, a left circular shift is performed (all bits are shifted left N bits, and the bits that are shifted out of the word to the left are shifted back into the word at the right). If N < 0, a right end-off shift is performed (all bits are shifted right by N bits, and the bits that are shifted out of the right of the word are lost)-if the leftmost bit is 0, then the vacated positions are filled with zeros; if the leftmost bit is 1, then the vacated positions are undefined. The implementor may assume that IABS(N) .LE. word_length. FUNCTION IAND(K1,K2) The bit-by-bit logical product of K1 and K2. If K3 = IAND(K1,K2), then the nth bit of K3 is 0 if the nth bit of either K1 or K2 is 0; otherwise the nth bit of K3 is 1. FUNCTION IOR(K1,K2) The bit-by-bit logical sum of K1 and K2. If K3 = IOR(K1,K2), then the nth bit of K3 is 0 if and only if the nth bit of both K1 and K2 is 0. SUBROUTINE G01MIO(IOP,IUNIT,FNAME,IBUFF,LENGTH,IERROR) This output routine is the central one for the metafile generator. A Fortran implementation of this subroutine is in the directory: $NCARG/ncarg2d/src/libncarg_gks/bwi Input arguments IOP Indicates type of operation desired: IOP = 1 means OPEN workstation for output on IABS(IUNIT). IOP = 2 means CLOSE workstation for output on IABS(IUNIT). IOP = 3 means write IBUF to IABS(IUNIT). IOP = 4 means read IABS(IUNIT) into IBUF. IOP = 5 means position the record pointer to the beginning of the file. IOP = 6 means position the record pointer to the beginning of the previous record. IUNIT IABS(IUNIT) is the Fortran logical unit number on which IOP is to occur. FNAME The filename to be used for the open operation. IBUFF Buffer containing data for a read or write operation. LENGTH Length of data in IBUFF, in integer words. Output arguments IERROR Error indicator that equals 0 if no errors. SUBROUTINE GBYTES(NPACK,ISAM,IBIT,NBITS,NSKIP,ITER) This subroutine is used to unpack bit chunks from NPACK into the ISAM array. A portable Fortran version of this routine is distributed, but the Fortran version is inefficient and should be replaced with a more efficient implementation. NPACK Address of first word of the array to be unpacked. For the purposes of this subroutine, NPACK is viewed as a bit stream. ISAM Array to receive the unpacked bit chunks. They will be right justified with zero-fill in this array. ISAM should be dimensioned for ITER. IBIT A bit-count offset to be used before the first bit chunk is unpacked. For example, if IBIT=3, and NBITS=5, then 3 bits in NPACK will be skipped and the next 5 bits will be unpacked into ISAM(1). NBITS The number of bits in each bit chunk to be unpacked. An error condition occurs if NBITS is larger than the number of bits-per-word on the machine. NSKIP The number of bits to skip between each bit chunk to be unpacked. Bits are skipped only after the first bit chunk has been unpacked. ITER The number of bit chunks to be unpacked. For example: CALL GBYTES(NPB,ISB,3,6,9,2) In this call, three bits would be skipped at the beginning of NPB; the next six bits would be unpacked into ISB(1) and right-justified with zero-fill; nine bits would be skipped in NPB, and then the next six bits of NPB would be unpacked into ISB(2) and right-justified with zero-fill. SUBROUTINE SBYTES(NPACK,ISAM,IBIT,NBITS,NSKIP,ITER) This subroutine is the reverse of GBYTES as described above. NPACK-Address of first word of array to be packed. ISAM-Array to be packed into NPACK. The rightmost NBITS bits of each word will be packed. ISAM should be dimensioned for at least ITER. IBIT-A bit-count offset to be used before the first bits are packed into NPACK. For example, if IBIT=3, and NBITS=5, 3 bits in NPACK will be skipped before the rightmost 5 bits of ISAM(1) are packed into it. NBITS-The number of bits in each word of ISAM to be unpacked. An error condition occurs if NBITS exceeds the word size on the machine. NSKIP-The number of bits to skip between each bit chunk packed. ITER-The number of bit chunks to be packed. For example: CALL SBYTES(NPC,ISB,45,6,3,2) In this call, 45 bits would be skipped at the beginning of NPC; the rightmost 6 bits of ISB(1) would be packed into NPC; 3 bits would be skipped in NPC, and the rightmost 6 bits of ISB(2) would be packed into NPC. ------------------------------------------------------------------------ Trademarks: NCAR Graphics is a registered trademark of the University Corporation for Atmospheric Research. All brand and product names are trademarks or registered trademarks of their respective holders. Reference to a company or product name does not imply approval or recommendation of that company or product to the exclusion of others. Copyright 1987-2000 University Corporation for Atmospheric Research (UCAR) The use of this software is governed by a License Agreement. All rights reserved.