The Geographic Information Systems: GRASS HOWTO
Prev | C. Acquisition/Compilation of GRASS Source Code | Next

# C.1. GRASS 4.2 Quick Start

Installation Instructions

Warning
These instructions pertain to the 4.2 release of GRASS. Users are urged to consult the complete installation guide for more detailed instructions.

    $GIS/src -
    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 Mr. Murphy.

    WARNING: These instructions and scripts have been used to compile
    GRASS on various machines.  Please mail results of using this
    information for compiling GRASS on your platforms and operating
    system to:

    grass@baylor.edu

    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
                      local     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
         idefault 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 - gmake4.2.

    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:
            gmake4.2 -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
    entire compilation process takes from about 1/2 hour on the faster
    workstations to about 8 hours on the slower workstations.

    GISGEN collects all of the directory names to be compiled from lists/GRASS
    lists/$ARCH and lists/local and begins running gmake4.2 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 configuratin files

    Your compiled system may any combination of several graphics, paint, and
    digitizer drivers.  Refer to the GRASS installation instructions for
    details.

    NOTE:  If you have trouble compiling your graphics driver, go to the directory
    $GIS/src/display/devices and compile the proper drivers manually using gmake4.2.

    (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.

      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.

    ALPHA programs are found in the directory src.alpha.  You, the installer
    may visit these programs and compile any that you desire.  In directories
    that contain Gmakefile files, simply run: gmake4.2

    CONTRIB programs are in the directory src.contrib.  The state of these
    programs are varied.  Some programs may compile with gmake4.2; 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 gmake4.2 and
    the included Gmakefile files.

    The rest of the compilation should just take some time.  If you have
    already installed GRASS binaries, you should back up your system (or
    at least get the working binaries out of the way of your
    compilation!).

    Good Luck!  And be secure in the likelihood that you can use the
    compiled binaries if you bail out of a full compilation of the source
    code.

Prev | Home | Next
Acquisition/Compilation of GRASS Source Code | Up | Enhancing GRASS