Developing custom GRASS programs

As the majority of the RHESSys group is using OS X, this article targets that OS. However, most of the content should apply to any operating system.

Get a compiler

Development tools are not installed by default on OS X. You can install the dev tools from any OS X installation CD. For the most recent version, go Apple's Mac Dev Center and download the latest version of XCode. You will be required to create a free account before you can download the tools.

Get the GRASS source

In order to write your own custom GRASS programs, you will need the GRASS header files and libraries. Even if you already have GRASS on your computer, these may not be installed. Additionally, the actual GRASS source code is an excellent resource for learning to write new GRASS modules, and should be downloaded even if your installation already has the necessary headers and libraries.

First, check to see if your GRASS install has the necessary headers and libraries.

1. Open a terminal window
2. cd to the folder containing your GRASS executable
3. $> ls <GRASS app name>/Contents/MacOS/include/grass
4. If you see several files ending in .h, one of which is gis.h, then you have the GRASS headers.
5. $> ls <GRASS app name>/Contents/MacOS/lib
6. You should see a long list of files ending in .dylib. Make sure that one of them is libgrass_gis.dylib.
7. If your GRASS install had both the .h and .dylib files, then you already have the necessary files and do not need to download the source.

Next, getting the GRASS source. To download the GRASS source, go to http://grass.itc.it/download/index.php. It is best to download the RC code, as svn code may have issues compiling. If you did not find the necessary .h and .dylib files, it will be necessary to compile GRASS. Unfortunately, GRASS has a long list of dependencies, and building can be rather difficult.

An explanation of building software and all it's dependancies is beyond the scope of this tutorial. However, learning to build the software yourself can be a useful skill. For example, GRASS can support NetCDF, a format we intend to use more in the future. However, most pre-built GRASS installations do not use this functionality. By building GRASS yourself, you can have access to useful tools before they become mainstream.

Examining the GRASS source

GRASS is very different than a program like MATLAB or MSWord. Where those programs are a monolithic single application, GRASS is actually a collection of very small programs. This makes reading through the source code and expanding GRASS functionality very easy. Every individual GRASS command, such as g.region, d.mon, r.mapcalc, etc. is actually a small self contained program. These smaller programs all interact with each other by accessing the GRASS map data stored in your projects LOCATION folder. One can think of this as similar to using RHESSys, where tools such as g2w, cf, and rhessys all work together to form the larger RHESSys package.

In your terminal window, browse to where you decompressed the source tarball and look around. Most of the files in the top level of the source are either documentation, or for building GRASS. The source is in several folders. display contains the code for all the tools that start with d., general contains the source for all the tools that start with g., raster for the r. tools, and so on. Lets take a look at one of these tools.

From the top of the GRASS source folder, type:
$> cd raster/r.circle
$> ls

The files of interest here are:

• main.c
• clump.c
• local_proto.h
• Makefile

The files ending in .c are C language source files. They are roughly equivalent to a .m file in MATLAB. These are what contain the actual data processing aspect of the program. main.c is a special file. This is where the main() function of your program is, and the first code to be run when executing the program. The file is not required to be called main.c, but by convention it is. If you are looking at a module and do not see a file main.c, use the command
$> ls *.c | xargs grep -H main
And look for a file that contains a line:

int main(int argc, char *argv[])