All important aspects of C programming for GRASS are described in the GRASS 5.0 Programmer's Manual (PDF, 2.3MB). This section shall just give an overview how GRASS modules are usually structured. Generally, it will be helpful to look at some of the (over 350) existing modules as examples for learning (you can browse the source code via the CVS web interface). Only an "open source" GIS such as GRASS offers these deep insights into the "heart" of a GIS. The general structure of the modules is always similar, each module is stored in a directory of the GRASS source code.
The current source code structure is as follows:
GRASS GIS library (most relevant only):
internal scripts for compilation
GIS library routines
internal routines for the interactive mode of modules
Modules (standard tree):
modules for displaying maps on the GRASS monitor
file management modules
image processing modules
paint driver (PPM)
contributions of various institutions (however, many are in standard tree as well)
modules with linked simulation models and various interfaces
The existing GRASS modules are built upon the "GRASS programming library" which offers a multitude of GIS functions. It is structured as follows (square brackets contain the typical function name prefixes for the respective library routines):
database routines (GRASS file management), memory management, parser (string analysis), projections, etc. [G_]
management of area, line, and site vectors [Vect_, V2_, dig_]
raster data management [R_]
site data management [G_sites_]
graphical output to the monitor [D_]
image processing file management [I_]
segmented data management [segment_]
control of cursor keys etc. [V_]
for parallel row analysis of raster data [rowio_]
Some of the routines offered are quite substantial. For example they allow calculating geodesic distances out of given coordinate points, others perform queries on vector areas (e.g.: point-in-polygon tests).
Modules consist of the C program files (*.c), the header files (*.h) and a Gmakefile. GRASS has its own "make" routine: gmake5. The file Gmakefile contains instructions concerning the files to be compiled and the libraries to be used (GRASS and UNIX libraries). It has a specific pattern that must be respected. A simple example (important: indents with tab, not with space!) shall demonstrate the typical structure.
The line "\$(HOME)/\$(PGM)..." and the next contain the compiler instructions, above this section the variables are set. Variables not set here are defined automatically in
where $ARCH is the name of the system architecture. Starting from GRASS 5.0 this "head" file is created automatically for the used computer platform by the "configure" script, which has to be run before the first compilation. The $(HOME) variable indicates where the binary file (i.e. the module) will be copied to: in this example it is the standard path for modules that offer command line support (no limitation to interactive only usage): grass5/etc/bin/cmd/.
The actual C program should be divided by (sub-)functionality into several files which have to be listed respectively in the list of objects in the Gmakefile. For details please refer to the "GRASS Programmer's manual" as this book cannot cover a full C programming tutorial. GRASS GIS library commands can be used directly in the source code. Interactive parameter querying is made possible by GRASS-specific parameter programming. Here is a short example of a raster module.
The calculation is done row and column wise (see "for" loop). As denoted above, it is advisable to divide the entire module into individual, thematically organized files in order to facilitate program maintenance.
This will change with new versions of GRASS in an effort to put more common routines into libraries and with the integration of a completely new vector engine (see the GRASS 5.7 programmer's manual).
The code example links in this chapter go to M. Neteler, H. Mitasova, 2002. Open Source GIS: A GRASS GIS Approach.