Building Addon Modules for
Mac OS X GRASS.app
(without GEM)

GEM is a nice idea, but there are a few issues.  Not many modules are setup for GEM (there are a couple in the new SVN repository, and some by the GEM author).  It puts the resulting files in the GRASS binary folder and alters the GUI menus in the application package, and this is Not a Good Thing to do with Mac OS X applications.

The method is similar to GEM in that it uses a minimal template of the GRASS source and uses the needed headers and libraries from GRASS.app.  But there is less setup needed (for developers), and you don't need admin privileges to install and use the module, except in some more complex cases.  Though a user does need to do a little setup, unlike with GEM.

It's a bit rough right now.  It doesn't have a module registry like GEM.  It doesn't add modules to the GUI menu, though the menu is dynamically maintained by the GRASS.app startup.

I haven't tried it with a module that also includes its own library.

Note: if there is no makefile in the module source, it's probably just a script that you can simply copy to the bin folder (see Use section below).

Requirements

- Xcode - at least version 2.3 (scripts shouldn't need this).

- GRASS.app (you don't need the full GRASS source).

- Module source.  It should be compatible with the GRASS.app version you use.

- This modbuild template.

Setup

$VERSION is the major.minor GRASS version.

- copy the modbuild folder from /Library/GRASS/$VERSION/ to a location you have read/write access to.  You could use your home /Library/GRASS/$VERSION/, for example.

- Unpack the module source and put that source folder in the 'module' folder in the modbuild folder.  If the module source is setup for GEM, you'll have to dig into the src/[section] subfolder to find the module's source folder (ie src/raster/module.source.folder).  You should end up with your template folder like so:

modbuild
	dist.some-platform-version
	include
	License.rtf
	module
		module_source_folder
			description.html (this might have the module name instead)
			main.c
			makefile
			(other_src.c)
			(other_header.h)
	ReadMe.rtf
	tools

NOTE: make sure that there are no spaces in the path to the modbuild folder.

- If the module uses extra data file(s) that are stored in the etc/ folder (v.in.dwg does this), make sure it uses the new G_find_etc() function (for C modules) or the g.findetc module (for script modules) instead of the hardwired $GISBASE/etc/.  This will mean either asking the author to make this change or attempting it yourself.  See the developer documentation for usage of G_find_etc(), and the GRASS Help for usage of g.findetc.

- In a Terminal, cd to the module source folder, then:

$ make GRASS_HOME='/path/to/grass/modbuild' GRASS_APP='/path/to/GRASS.app'

The modbuild path is the path to the modbuild folder, not the module source folder.  Make sure to include the correct GRASS.app name in the GRASS_APP path (ie GRASS-6.3.app).

Use

The module files will be in the dist folder in this template.  A C source module will be in bin, script modules will be in scripts, and documentation will be in docs/html.  GRASS.app has a couple default locations for addon modules that use the same configuration as the GRASS_ADDON_PATH environment variable: /Library/GRASS/$VERSION/Modules and ~/Library/GRASS/$VERSION/Modules.  The version is the Major.minor GRASS version.  Modules that should be available to all users should be installed in /Library (requires admin privileges), and any modules in ~/Library will only be available to the user that installs them.  The user GRASS folder will be created the first time GRASS is run.

Installation is not automatic.  You must manually copy the files because the install targets in the GRASS make system only exist in the GRASS source.

- Both scripts and binary executables can be run from the same location, so install them in the bin/ folder.
- Any libraries should go in the lib/ folder.
- Documentation goes in the docs/html/ folder.
- Data files should go into etc/.

© 2006-2007 by the GRASS Development Team
This program is free software under the GNU General Public License (>=v2).

- William Kyngesburye
kyngchaos@kyngchaos.com
http://www.kyngchaos.com/