[GRASS-dev] SUBMITTING and SUBIMITTING_TCLTK patches
Maciek Sieczka
werchowyna at epf.pl
Thu Jun 22 14:14:03 EDT 2006
Hi,
I have added several notes to SUBMITTING_SCRIPTS, unidiffs attached:
1. Suggest using `basename $0` as a part of temp files names for better
control.
2. Make the Grass commands used safely quiet by redirecting output
to /dev/null.
3. Use WIND_OVERRIDE to control the region settings during the
script runtime.
4. A link to
http://mpa.itc.it/markus/grass61progman/parser_8c-source.html#l00326
for reference of what input/output variants and options are available
to use in scripts.
5. A note about WIKI Grass addons.
(Should I add the same note to SUBMITTING and SUBMITTING_TCLTK?)
I also removed a doubled note about creating safe temp files, leaving
the more detailed one.
Moreover, I re-arranged SUBMITTING_TCLTK to keep the 4 final notes at
the very end, where they belong in all SUBMITTING*.
Can somebody please take a look and apply the changes?
Thanks!
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 22 Jun 2006 18:07:48 -0000
@@ -50,7 +50,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
@@ -93,7 +92,11 @@
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
@@ -107,7 +110,16 @@
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 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 +130,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 +142,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 +151,32 @@
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 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 startup 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 +188,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 addons 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 22 Jun 2006 18:07:39 -0000
@@ -124,31 +124,7 @@
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:
@@ -216,12 +192,36 @@
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