Please follow the instructions in "INSTALL". This file is a reference to former installation procedure. 8/99 ----------------------------------------------------------------- WELCOME TO THE GRASS INSTALLATION INSTRUCTIONS WARNING: These instructions pertain to the 5.0 release of GRASS and are not entirely in sync with older releases. This file is retained for 5.0 reference only. The user is refered to the installation guide that accompanies this release. If no guide is available contact your distributor. ----------------------------------------------------------------- This directory contains scripts and files used to compile GRASS. By running scripts and changing lists of programs you generate GRASS binaries for your system. You may mount a disk containing GRASS source on different types of machines and compile without making source code copies. You follow the following instructions for each machine. WARNING: These instructions presume that you have familiarity with UNIX, C, make, and shell scripting. Murphy's law visits GRASS regularly and your expertise in these matters will be the best defense against Murphy. WARNING: These instructions and scripts have been used to compile GRASS on the various machines. Please mail results of using this information for compiling GRASS on your platforms and operating system to: grass@baylor.edu To compile GRASS 5.0, cd to the src/CMD directory and start there. src/CMD DIRECTORY CONTENTS GISGEN script which will compile GRASS MAKELINKS script used after GISGEN to establish the user executable commands VERSION current version number and date of the GRASS release generic/ system independent files need by gmake gmake shell script which does compilations make.def make variables make.tail some additional make rules head/ gmake header file(s) for this site. Header files are created by running the utils/setup command. lists/ lists of programs to be compiled GRASS standard GRASS programs GRASS.* site specific GRASS programs ... architecture dependent GRASS programs next_step/ files used by GISGEN to keep track of how far along it is in the compilation. Used to restart GISGEN (after a failure) where it left off. utils/ contains the 'setup' script and all support scripts and files needed by 'setup' COMPILATION STEPS OVERVIEW (1) Generate files that contain location and machine specific make information. (2) Edit files containing lists of location and machine specific programs to be compiled (generally printer, digitizer, and graphics drivers). (3) Run GRASS compilation script (4) Run GRASS program linking script (5) Edit device driver configuratin files (6) Compile GRASS contributed, alpha programs. (7) Compile GRASS related and hybrid programs. COMPILATION STEPS (DETAILS) (1) Generate make support files Each machine and location needs to have GRASS compiled in ways that specify different: * compilation and load flags * system libraries * installation directories * default data bases and locations The shell script utils/setup assists you in define many of the make options and definitions that will become part of every compile-time generated makefile (about 350). It also creates your shell script for compiling individual GRASS programs - gmake5.0beta. Run "utils/setup" and answer the questions. The makefile portions are placed in the head/ under a name which you specify/approve in the utils/setup process. The executable shell script which directs compilation is placed in (by default) /usr/local/bin. Examine the just created file in head/ to make sure things are ok. A brief description for each defined variable follows: ARCH = Key name identifying the architecture of the machine on which you are compiling GRASS. GISBASE = Directory into which compiled GRASS will be contained UNIX_BIN = Local directory where the GRASS entry program and gmake will be contained DEFAULT_DATABASE= Directory where local GRASS data bases are contained DEFAULT_LOCATION= GRASS data base that users get as the first default COMPILE_FLAGS = Compilation flags LDFLAGS = Load flags TERMLIB = System library containing low-level cursor movement CURSES = System library that supports screen cursor control MATHLIB = System math library LIBRULE = Method for archiving and randomizing libraries USE_TERMIO = Flag to use the termio library if available USE_MTIO = Flag to use the mtio library if available CAN_CLEAR = Flag indicating that the terminal screen can be cleared DIGITFLAGS = Flags to set owner and priority of the v.digit program (2) Edit files containing lists of location and machine specified programs The directory lists/ contains files that list directories that will be compiled. Directory names are relative to the GRASS src directory. The file lists/GRASS lists all basic GRASS programs that get compiled at every site. The file lists/local and lists/$ARCH. ----------------------------------------------------------------- $ARCH is the architecture name you approved while running the utils/setup script. You can determine this by running: gmake5.0beta -sh | grep ARCH ----------------------------------------------------------------- There man not be a lists/$ARCH file, but you are free to create it to add names of programs you want compiled specifically for this architecture. It is an architecture-specific list which allows NFS linked source code to compile one set of programs for one machine, and another set for another machine. All machines that share the same source code via NFS mounts will compile the directories listed in lists/local. All lists may contain comment lines - indicated by a # as the first character in the line. The lists/local file contains lists of all digitizer, graphics, and paint (hard-copy map) drivers. All machine specific devices are commented out - you must uncomment those that are particular to your site or architecture. You are encouraged to move the graphics driver items to the appropriate lists/$ARCH file. (3) Run GRASS compilation program The script GISGEN drives the compilation process. If all goes well you will be able to simply enter the command GISGEN and wait. The compilation process takes from about 15 minutes on fast workstations (SUN Ultra series) to about 8 hours on slower workstations (i386). GISGEN collects all of the directory names to be compiled from lists/GRASS lists/$ARCH and lists/local and begins running gmake5.0beta in each directory. Screen output is a collection of messages from GISGEN and from the UNIX make program. Failure at any step will halt compilation. On failure you might do one of the following things: 1 - Fix a compilation problem by modifying code in the directory that failed. After modification, return to this directory and rerun GISGEN. Compilation will pick up at the failed directory and continue down the list of directories if successful. 2 - Restart GISGEN. If the failure requires modifications to code already compiled, or the compilation options you set in step 1, you must remove next_step/$ARCH (or next_step/next_step if ar architecture name was not specified in step 2. You may then rerun GISGEN. 3 - Skip the failed directory. In this case you must seek through the files list/GRASS lists/$ARCH and lists/local to determine the directory name that follows the failed directory name. The failed name is in next_step/$ARCH and must be replaced in that file with the next name. After editing, rerun GISGEN When complete GISGEN will put the word DONE into the next_step file and will print the phrase "DONE generating GIS binary code" to the screen. (4) Run GRASS program linking script The GISGEN directs a compilation process that stashes the GRASS programs away in directories unavailable to the user community. Most user commands are actually links to a single program called "front.end". Links to this program must be made for every actual GRASS program. This is done AFTER GISGEN is finished. To make (or re-make) links for all user programs run the script MAKELINKS. (5) Edit device driver configuration files Your compiled system may any combination of several graphics, paint, and digitizer drivers. Refer to the GRASS installation instructions for details. You should do this AFTER you compile the main programs. Graphics Driver Compile your xdriver software. It is located in src/display/devices. Depending on your system, use gmake to compile for your driver. Most often this will be XDRIVER, which will support 24-bit color graphics. Edit the file /your_grass_binary_location/etc/monitorcap. Uncomment your graphics drivers and be sure and point them to the proper location. Make sure the fifo's are chmod 666 permission-wise. Digitizer Drivers If you want to use the mouse as your digitizer, read the README file in the src/libes/vect32/digitizers directory. (6) Compile GRASS contributed, alpha programs. GRASS programs come in three flavors: MAIN - The programs are those compiled in step 3. They have stood the test of time and are generally reliable programs. ALPHA - Alpha programs are intended to be included with the MAIN programs in the next release. However, GRASS 5.0 does NOT have ANY alpha programs CONTRIB - Sites generate lots of special purpose programs in GRASS to get some job done, but do not polish the effort sufficiently to even be considered alpha code can be distributed in this category. CONTRIB programs are in the directory src.contrib. The state of these programs are varied. Some programs may compile with gmake5.0beta; others are suitable as a starting point for programmers who will be writing new software. (7) Compile GRASS related and hybrid programs. The GRASS user community has discovered that there are several public-domain programs that are very useful in conjunction with GRASS. These are found in the directory src.related. Compile these programs based on instructions (or lack of instructions) in the individual directories. Hybrid programs are those that mix the capabilities of GRASS with the capabilities of one or more of the "related" programs. These are found in the src.garden directory. They require successful compilation of the "related" programs and generally compile using the gmake and the included Gmakefile files. (8) Run the obj-killer script in the source directory to clean out the old OBJ files. This will reduce the amount of disk space that the source code requires.