$Id: SUBMITTING_SCRIPTS 29462 2007-12-17 13:53:55Z neteler $
NOTE: Please improve this list!
Dear (new) GRASS Developer,
When submitting SHELL scripts to GRASS SVN repositiory,
please take care of following rules:
[ see SUBMITTING for C code hints ]
[ see SUBMITTING_TCLTK for tcl and tk hints ]
[ see SUBMITTING_DOCS for documentation ]
0. Instructions for the GRASS script parser can be found in the g.parser
module's help page.
http://grass.osgeo.org/grass63/manuals/html63_user/g.parser.html
1. Use the directory structure to place your script appropriately into
the source tree
- scripts go into scripts/
Consider to take a look at [please suggest Shell tutorial].
Also add a Makefile and a description.html file into this directory.
See existing scripts for examples.
2. Add a header section to the script you submit and make sure you include
the copyright. The purpose section is meant to contain a general
overview of the code in the file to assist other programmers that will
need to make changes to your code.
Example (ficticious header for a script called r.myscript) :
#!/bin/sh
############################################################################
#
# MODULE: r.myscript
# AUTHOR(S): Me
# PURPOSE: Calculates univariate statistics from a GRASS raster map
# COPYRIGHT: (C) 2005 by the GRASS Development Team
#
# This program is free software under the GNU General Public
# License (>=v2). Read the file COPYING that comes with GRASS
# for details.
#
#############################################################################
The copyright protects your rights according to GNU General Public
License (www.gnu.org).
You can easily autogenerate the header and parameters from an existing
module using the --script flag. Example:
d.rast --script
Just select an existing module which is close to your application to save
efforts.
3. - deleted.
We don't want the $ ID $ in scripts any more as it
causes problems for the SVN branches.
4. As a general principle, shell variables should almost always be quoted.
Use only secure temp files, see g.tempfile and scripts/* for examples.
5. [This rule is currently under review] If you search for a command in $PATH, do NOT
use the "which" command or the "type -p" command. Both commands are not
supported on all platforms, thus causing problems for some people. As an
alternative, please use code similar to the following shell script snippet
which will perform the same function. In this case, the path of the grass60
command is saved if grass60 is found in $PATH. This won't recognize aliased
command name.
# Search for grass5 command in user's path
for i in `echo $PATH | sed 's/^:/.:/
s/::/:.:/g
s/:$/:./
s/:/ /g'`
do
if [ -f $i/grass5 ] ; then
# Save the path of the grass60 command
GRASS_PATH=$i/grass60
# Use the first one in user's path
break
fi
done
>
If you must use "which", use as follows:
# check if we have awk
if [ ! -x "`which awk`" ] ; then
g.message -e "awk required, please install awk or gawk first"
exit 1
fi
?>
6. Add a test to check if the user is in GRASS before starting main part
of script. Result of running the script is unpredicable otherwise.
if [ -z "$GISBASE" ] ; then
echo "You must be in GRASS GIS to run this program." 1>&2
exit 1
fi
This is the only case, where g.message module (see below) can not be used.
In all other cases, you should prefer it's usage over the 'echo' command.
7. Create and use secure temporary files and directories. Use the g.tempfile
module to do this. e.g.
# setup temporary file
TMP="`g.tempfile pid=$$`"
if [ $? -ne 0 ] || [ -z "$TMP" ] ; then
g.message -e "unable to create temporary files"
exit 1
fi
For temportary directories remove the newly created file and mkdir using
the same name. Beware of commands like "rm -f ${TMP}*" as this becomes
"rm -f *" if $TMP is unset (hence the test above).
8. Testing the existence of variables. For portability, use
if [ -z "$VARIABLE" ] ; then
instead of
if [ "$VARIABLE" == "" ] ; then
and
if [ -n "$VARIABLE" ] ; then
instead of
if [ "$VARIABLE" != "" ] ; then
9. Internationalization proofing Awk: In some areas (e.g. some European
countries) the decimal place is held with a comma instead of a dot.
When scanning variables awk doesn't understand this, so scripts need to
temporarily discard locale settings before calling awk.
# set environment so that awk works properly in all languages
unset LC_ALL
LC_NUMERIC=C
export LC_NUMERIC
awk '{print $1}'
10. Use g.findfile when there is a need to test if a map exists.
# test for input raster map
g.findfile element=cell file="$INPUT" > /dev/null
if [ $? -eq 0 ] ; then
g.message -e "Raster map not found in mapset search path"
exit 1
fi
# test for input vector map
eval `g.findfile element=vector file=$GIS_OPT_MAP`
if [ ! "$file" ] ; then
g.message -e "Vector map not found in mapset search path"
exit 1
fi
... and so forth. See 'g.manual g.findfile' for details.
11. For any informational output, use the g.message modul. This module should
be also used for error messages and warnings. You can also use it for
debugging purposes.
#normal message:
g.message "Done"
# warning:
g.message -w "No input values found, using default values"
# error:
g.message -e "No map found, exiting."
# debug output (use g.gisenv to enable/disable)
g.message -d "Our calculated value is: $value"
Try to omit any usage of the 'echo' command for informational output.
12. For consistency, use README rather than README.txt for any README files.
13. Be sure to develop on top of the LATEST GRASS code (which is in SVN).
You can re-check before submission with 'cvs diff':
Be sure to create unified ("diff -u") format. "Plain"
diffs (the default format) are risky, because they will apply without
warning to code which has been substantially changed; they are also
harder to read than unified.
Such diffs should be made from the top-level directory, e.g.
"cvs diff display/d.vect/main.c"; that way, the diff will
include the pathname rather than just "main.c".
14. Tell the other developers about the new code using the following e-mail:
grass-dev@lists.osgeo.org
To subscribe to this mailing list, see
http://lists.osgeo.org/mailman/listinfo/grass-dev
15. In case of questions feel free to contact the developers at the above
mailing list.
http://www.grass-gis.org/devel/index.php#submission
16. For portability, scripts must work on any POSIX compliant shell, and
therefore may not include any Bashisms. Test with ash for errors:
ash -n scriptname
...
[please add further hints if required]