[GRASS-dev] SUBMITTING_SCRIPTS and SUBIMITTING_TCLTK patches
Maciek Sieczka
werchowyna at epf.pl
Sun Jun 25 07:34:01 EDT 2006
On Sat, 24 Jun 2006 12:53:17 +0200
Markus Neteler <neteler at itc.it> wrote:
> Hi Maciek,
>
> there are still typos, maybe you submit again?
Done. Several typos spotted and fixed.
Also added 2 links for straighforward BASH tutorials which helped me a
lot.
Maciek
------------------------------------------------------------------------
CIEP?E KRAJE - CIEP?E MORZA. Szukasz atrakcyjnego wypoczynku w przyst?pnej cenie, zapoznaj si? z nasz? ofert?.
ZAPRASZAMY
www.skarpatravel.pl
-------------- next part --------------
Index: SUBMITTING_SCRIPTS
===================================================================
RCS file: /home/grass/grassrepository/grass6/SUBMITTING_SCRIPTS,v
retrieving revision 1.6
diff -u -r1.6 SUBMITTING_SCRIPTS
--- SUBMITTING_SCRIPTS 18 May 2006 04:37:03 -0000 1.6
+++ SUBMITTING_SCRIPTS 25 Jun 2006 11:25:21 -0000
@@ -4,7 +4,7 @@
Dear (new) GRASS Developer,
-When submitting SHELL SCRIPTS to GRASS CVS repositiory,
+When submitting SHELL SCRIPTS to GRASS CVS repository,
please take care of following rules:
[ see SUBMITTING for C code hints ]
@@ -18,14 +18,16 @@
the source tree
- scripts go into scripts/
- Consider to take a look at [please suggest Shell tutorial]
+ Consider taking a look at the following BASH tutorials:
+ http://steve-parker.org/sh/sh.shtml
+ http://www.linuxfocus.org/English/September2001/article216.shtml
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) :
+ Example (fictitious header for a script called r.myscript) :
#!/bin/sh
@@ -50,7 +52,6 @@
causes problems for the CVS 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. If you search for a command in $PATH, do NOT
use the "which" command or the "type -p" command. Both commands are not
@@ -86,28 +87,42 @@
</?>
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.
+ of script. Result of running the script is unpredictable otherwise.
if [ -z "$GISBASE" ] ; then
echo "You must be in GRASS GIS to run this program." 1>&2
exit 1
fi
-7. Create and use secure temporary files and directories. Use the g.tempfile
+7. See what input/output variants and options are available for you to
+ use in your script at
+ http://mpa.itc.it/markus/grass61progman/parser_8c-source.html#l00326
+
+8. Create and use secure temporary files and directories. Use the g.tempfile
module to do this. e.g.
- # setup temporary file
+ # set up temporary file
TMP="`g.tempfile pid=$$`"
if [ $? -ne 0 ] || [ -z "$TMP" ] ; then
echo "ERROR: unable to create temporary files" 1>&2
exit 1
fi
- For temportary directories remove the newly created file and mkdir using
+ For temporary 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
+ Also, a good idea is to include your script's name in the temporary files
+ names. It makes it easy to spot orphans. E.g.:
+
+ # set a variable according to your script's name
+ PROG=`basename $0`
+
+ # now create temp files e.g. like this:
+ v.out.ascii input="${OUTPUT}" format=standard > $TMP.${PROG}.out
+
+
+9. Testing the existence of variables. For portability, use
if [ -z "$VARIABLE" ] ; then
instead of
if [ "$VARIABLE" == "" ] ; then
@@ -118,8 +133,7 @@
instead of
if [ "$VARIABLE" != "" ] ; then
-
-9. Internationalization proofing Awk: In some areas (e.g. some European
+10. 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.
@@ -131,7 +145,7 @@
awk '{print $1}'
-10. Use g.findfile when there is a need to test if a map exists.
+11. 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
@@ -140,12 +154,34 @@
exit 1
fi
-11. Send solely informational output to stderr, not stdout.
- echo "Done." 1>&2
+12. Send solely informational output to stderr, not stdout, e.g.:
+
+ echo "Done." 1>&2
+
+13. In order to prevent your script from being too verbose, redirect command's
+ output to /dev/null, e.g.:
+
+ g.remove vect="${OUTPUT}_temp" > /dev/null
+
+ The command's output will be filtered letting only warnings and errors get
+ through.
+
+14. If the same region is required for subsequent Grass commands, export
+ WIND_OVERRIDE Grass variable. E.g.:
+
+ # save the region at script start up and make it obligatory during the
+ # whole script runtime:
+
+ region=$TMP.${PROG}.region
+ g.region save=$region
+ export WIND_OVERRIDE=$region
+
+ Refer to "GRASS variables and environment variables" documentation section
+ for more info.
-12. For consistency, use README rather than README.txt for any README files.
+15. 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 CVS).
+16. Be sure to develop on top of the LATEST GRASS code (which is in CVS).
You can re-check before submission with 'cvs diff':
Be sure to create unified ("diff -u") format. "Plain"
@@ -157,13 +193,16 @@
"cvs diff -u 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:
+17. Tell the other developers about the new code using the following e-mail:
grass-dev at grass.itc.it
To subscribe to this mailing list, see
http://grass.itc.it/devel/index.php
-15. In case of questions feel free to contact the developers at the above
+18. Consider submitting your script to Grass add-ons WIKI section:
+ http://grass.gdf-hannover.de/wiki/GRASS_AddOns#GRASS_6.x
+
+19. In case of questions feel free to contact the developers at the above
mailing list.
http://grass.itc.it/devel/index.php#submission
-------------- next part --------------
Index: SUBMITTING_TCLTK
===================================================================
RCS file: /home/grass/grassrepository/grass6/SUBMITTING_TCLTK,v
retrieving revision 1.4
diff -u -r1.4 SUBMITTING_TCLTK
--- SUBMITTING_TCLTK 5 May 2006 18:36:43 -0000 1.4
+++ SUBMITTING_TCLTK 25 Jun 2006 11:31:13 -0000
@@ -120,35 +120,11 @@
by options.tcl. You can include it at the start of your script with:
source $env(GISBASE)/etc/gtcltk/options.tcl
-10. Avoid using global variables. Thay are a frequent source of bugs, make code
+10. Avoid using global variables. They are a frequent source of bugs, make code
harder to understand, and make your program difficult to reuse. Additionally,
putting code into procs usually makes it run faster (it gets compiled).
-11. For consistency, use README rather than README.txt for any README files.
-
-12. Be sure to develop on top of the LATEST GRASS code (which is in CVS).
- 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 -u display/d.vect/main.c"; that way, the diff will
- include the pathname rather than just "main.c".
-
-13. Tell the other developers about the new code using the following e-mail:
- grass-dev at grass.itc.it
-
- To subscribe to this mailing list, see
- http://grass.itc.it/devel/index.php
-
-14. In case of questions feel free to contact the developers at the above
- mailing list.
- http://grass.itc.it/devel/index.php#submission
-
-15. Try to evaluate things only once. Tcl compiles the program to bytecode which
+11. Try to evaluate things only once. Tcl compiles the program to bytecode which
can be interpreted fairly quickly. If there are strings that must still be
evaluated tcl must parse and either compile or interpret them
each time they are encountered. In general this means put braces around
@@ -178,7 +154,7 @@
multiple times store it in a variable that will not be destroyed or
changed between reuse. Tcl stores the compiled regex with the variable.
-16. You might want to decompose lists in a somewhat easy way:
+12. You might want to decompose lists in a somewhat easy way:
Difficult and slow:
# Make x1 y1 x2 y2 the first four things in the list
@@ -194,7 +170,7 @@
Be sure to include a comment as to what you are doing.
-17. Use the Tcl list functions (list, lappend etc) for manipulating lists.
+13. Use the Tcl list functions (list, lappend etc.) for manipulating lists.
For example, use:
@@ -210,18 +186,42 @@
because tcl is not internally converting between strings and lists.
A related issue is to remember that command lines (as used by exec and
- open "|...") are lists. exec behaves like execl(), spawnl() etc, and
+ open "|...") are lists. exec behaves like execl(), spawnl() etc., and
not like system().
Overlooking either of these points is likely to result in code which
fails when a command argument contains a space.
-18. Tcl C library:
+14. Tcl C library:
Memory allocated with Tcl_Alloc (such as the result of Tcl_Merge)
must be freed with Tcl_Free. This means that the ->freeProc of
an interpreter when returning a string using Tcl_Merge should be
TCL_DYNAMIC. Incorrectly freeing memory with glibc free will
cause segfaults in Tcl 8.4 and later.
+
+15. For consistency, use README rather than README.txt for any README files.
+
+16. Be sure to develop on top of the LATEST GRASS code (which is in CVS).
+ 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 -u display/d.vect/main.c"; that way, the diff will
+ include the pathname rather than just "main.c".
+
+17. Tell the other developers about the new code using the following e-mail:
+ grass-dev at grass.itc.it
+
+ To subscribe to this mailing list, see
+ http://grass.itc.it/devel/index.php
+
+18. In case of questions feel free to contact the developers at the above
+ mailing list.
+ http://grass.itc.it/devel/index.php#submission
...
[please add further hints if required]
More information about the grass-dev
mailing list