[GRASS-SVN] r31203 - grass-addons
svn_grass at osgeo.org
svn_grass at osgeo.org
Fri May 2 08:08:33 EDT 2008
Author: neteler
Date: 2008-05-02 08:08:32 -0400 (Fri, 02 May 2008)
New Revision: 31203
Added:
grass-addons/SUBMITTING
grass-addons/SUBMITTING_DOCS
grass-addons/SUBMITTING_PYTHON
grass-addons/SUBMITTING_SCRIPTS
grass-addons/SUBMITTING_TCLTK
Log:
added back submitting scripts
Added: grass-addons/SUBMITTING
===================================================================
--- grass-addons/SUBMITTING (rev 0)
+++ grass-addons/SUBMITTING 2008-05-02 12:08:32 UTC (rev 31203)
@@ -0,0 +1,444 @@
+$Date: 2008-02-14 12:26:15 +0100 (Thu, 14 Feb 2008) $
+
+NOTE: Please improve this list!
+
+Dear (new) GRASS Developer,
+
+When submitting C code to GRASS SVN repository, please take care of
+following rules:
+
+[ see SUBMITTING_SCRIPTS for shell script hints ]
+[ see SUBMITTING_TCLTK for tcl and tk hints ]
+[ see SUBMITTING_DOCS for documentation ]
+[ see SUBMITTING_PYTHON for Python code hints ]
+
+
+1. Get and read the GRASS 6 Programmer's Manual here:
+ http://download.osgeo.org/grass/grass6_progman/
+
+ or generate it from this source code (the programmer's manual is
+ integrated in the source code in doxygen style):
+ make htmldocs
+ make pdfdocs
+
+
+2. Use the directory structure to place your module appropriately into
+ the source tree
+ - libes go into lib/
+ - raster goes into raster/
+ - vector goes into vector/
+ - ...
+
+ Consider to take a look at "GNU Coding Standards"
+ http://www.gnu.org/prep/standards.html
+
+ In future, there will be a centralized contribution directory.
+
+
+3. Add a header section to each file 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 file called color.c) :
+
+/****************************************************************************
+ *
+ * MODULE: d.rast (or new higher level module name (eg GRASS core)
+ * for 6.1)
+ * AUTHOR(S): Original author unknown - probably CERL
+ * John Doe - jdoe at some.where.org
+ * PURPOSE: To provide storage and manipulation of colors used for
+ * rendering the raster. The colors are stored in a doubly linked
+ * list which must be initialized with InitColors() before it can
+ * be used. Note that most linked list functionality (add,
+ * remove, get) is supported, but their is no sorting
+ * functionality.
+ * 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).
+
+
+4. - deleted.
+ We don't want the $ ID $ in source code any more as it causes problems
+ for the SVN branches.
+
+
+5. To ensure that the software system continues to work, please include
+
+ #include <grass/config.h>
+
+ in your files and make use of the various system dependencies
+ contained therein. As one example of this, see lib/gmath/fft.c.
+ Please refrain from declaring system functions within the
+ software; include the proper header files (conditionally dependent
+ on config.h macros if necessary) instead.
+
+
+6. Order of include headers
+
+ In general, headers should be included in the order:
+
+ 1. Core system headers (stdio.h, ctype.h, ...)
+ 2. Headers for non-core system components (X11, libraries).
+ 3. Headers for core systems of the package being compiled (grass/gis.h, grass/glocale.h, ...)
+ 4. Headers for the specific library/program being compiled (geodesic.h, ...)
+
+ Each class of header has an obligation to be compatible with those
+ above it in the list, but not those below it.
+
+
+7. Always specify the return type for ALL functions including those that
+ return type "void", and insert return statements for ALL functions.
+ Also, use ANSI C prototypes to declare your functions.
+ For module return values, see "Exit status" below.
+
+ Examples:
+
+ void G_something(void);
+ int G_something_else(int, int);
+
+ void G_something(void)
+ {
+ /* Snipped out code */
+
+ return;
+ }
+
+ int G_something_else(int x, int y)
+ {
+ /* Snipped out code */
+
+ return(0);
+ }
+
+
+8. Module exit status is defined as EXIT_SUCCESS or EXIT_FAILURE, e.g.
+
+ {
+ ...
+ if (G_parser (argc, argv))
+ exit (EXIT_FAILURE);
+
+ ...
+ exit (EXIT_SUCCESS);
+ }
+
+
+9. Use fprintf instead of printf. But:
+
+ For errors and warnings please use the G_fatal_error() and
+ G_warning() functions. General messages for the user should use
+ G_message() while debug messages should use G_debug() whenever
+ possible. There are two variants to G_message(): G_verbose_message()
+ which will only display the message if in verbose mode, and
+ G_important_message() which will always show the message unless
+ the module is running in --quiet mode. G_fatal_error() and
+ G_warning() will always be displayed regardless of verbosity setting.
+ Messages sent to any of these functions will be printed to stderr.
+
+ G_message() output is not expected to be sent to pipe or file.
+
+ Always use the gettext macros with _("") for user messages,
+ example:
+ G_fatal_error (_("Vector map <%s> not found"), name);
+
+
+ Pipe/file data output:
+ For data output redirected to pipe or file, please use fprintf() and
+ specify the stdout stream as follows:
+
+ fprintf(stdout, ...);
+ fflush(stdout);
+
+ fflush(stdout) always required when using fprintf(stdout, ...).
+
+
+10. Use the GRASS library function G_asprintf() instead of the
+ standard C functions asprintf(), vsnprintf() and snprintf(). These
+ functions are not portable or have other issues. Example:
+
+ char *msg;
+
+ G_asprintf(&msg, "%s", parameters);
+ do_something_with_msg();
+ G_free(msg);
+
+ Note that you should free memory when G_asprintf() is used.
+
+
+11. Use the following GRASS library functions instead of the standard C
+ functions. The reason for this is that the following functions ensure
+ good programming practice (e.g. always checking if memory was allocated)
+ and/or improves portability. PLEASE refer to the programmers manual
+ for the proper use (e.g. determining if any casts are needed for arguments
+ or return values) of these library functions. They may perform a task
+ slightly different from their corresponding C library function, and thus,
+ their use may not be the same.
+
+ G_malloc() instead of malloc()
+ G_calloc() instead of calloc()
+ G_realloc() instead of realloc()
+ G_free() instead of free()
+ G_getenv() instead of getenv()
+ G_setenv() instead of setenv()
+ G_unsetenv() instead of unsetenv()
+ G_sleep() instead of sleep()
+
+ Could somebody please add others (please verify that they are
+ useful and safe first)
+
+
+12. Use function names which fulfil the official GNU naming convention.
+ http://www.gnu.org/prep/standards/html_node/Names.html#Names
+
+ Instead of naming a function like: MyNewFunction() use underscores
+ for seperation and lower case letters: my_new_function().
+
+
+13. Don't use the C++ comment style! This confuses several compilers.
+ Use instead:
+ /* C-comments */
+
+ If you want to comment code portions, use
+ #ifdef notdef
+ portion_to_be_commented;
+ #endif
+ This is safe comparing to nested /* comments */
+
+ Functions in the library must be documented in doxygen style to
+ get them into the programmer's manual (generate with
+ make pdfdocs or
+ make htmldocs
+ ). See lib/gis/*.c for examples.
+
+
+14. PLEASE take the time to add comments throughout your code explaining what
+ the code is doing. It will save a HUGE amount of time and frustration for
+ other programmers that may have to change your code in the future.
+
+
+15. To promote a consistent coding style, please use the "indent" program
+ on all new C modules using the following switches:
+
+ $ indent -nbad -bap -bbb -nbbo -nbc -br -bli1 -bls -cbi0 -ncdb -nce \
+ -ci4 -cli0 -ncs -d0 -di0 -fc1 -nfca -hnl -i4 -ip4 -l80 -lc80 -lp \
+ -npcs -pi4 -nprs -npsl -sbi0 -sc -nsob -ss -ts8 main.c
+
+ Existing code should not be re-indented except in extreme cases, as this
+ will make "diff" comparisons with older versions impossible. If indent is
+ needed, do not check in any changes other than the indentation in the same
+ commit! Do add the indent switches and any indent warning messages to the
+ SVN log. Any change or fix mixed in with an indent is very hard to track
+ making it hard for others to follow the change or fix any new bugs.
+
+
+16. Platform dependent code:
+ Do not remove #ifdef __CYGWIN__ and/or #ifndef __CYGWIN__ lines and
+ their encapsulated lines from source code (one example was that someone
+ removed drand48 definition.)
+
+
+17. Suggested compiler flags:
+ We suggest to use very strict compiler flags to capture errors
+ at the very beginning. Here our list of flags, please use them
+ to configure you development version of GRASS:
+
+ GNU/Linux:
+
+ MYCFLAGS="-g -Wall -Werror-implicit-function-declaration -fno-common"
+ MYCXXFLAGS="-g -Wall"
+
+ CFLAGS="$MYCFLAGS" CXXFLAGS="$MYCXXFLAGS" ./configure ...
+
+ MacOSX: [to be suggested]
+
+ MS-Windows: [to be suggested]
+
+
+18. Make sure a new line is at the end of each file.
+
+
+19. When writing Makefiles, use the current standard.
+
+ If you have to use commands, please check for:
+
+ avoid | use instead
+ ------------------+---------------
+ make target | $(MAKE) target
+ mkdir target | $(MKDIR) target
+ cp (executable) | $(INSTALL) -m 755 file target
+ cp (normal file) | $(INSTALL) -m 644 file target
+ ar | $(AR)
+
+ rm: be VERY careful with recursive remove.
+
+ Examples: see below examples or others
+ raster/r.info/Makefile
+ vector/v.digit/Makefile
+
+ If you are unsure, please ask on the GRASS Developers list.
+
+
+20. Have a look at ./INSTALL
+
+
+21. Have a function included in your module which writes to the history
+ file of the map (e.g. command line, parameters etc.). See e.g.
+ raster/r.patch/main.c
+
+ (the same applies to vector and g3d modules!)
+
+
+22. Standard parser options: use G_define_standard_option() whenever possible
+ to define standard module command line options. This will save you time,
+ create fewer bugs, and make things easier on the translators.
+ See lib/gis/parser.c for details of the function definition.
+
+
+23. Add/update, if required the related GUI menus:
+ gui/tcltk/gis.m/gmmenu.tcl
+
+
+24. For consistency, use README rather than README.txt for any README files.
+
+
+25. GRASS/Environment variables:
+ If you add a new variable, please follow the naming convention.
+ All variables are described in
+ lib/init/variables.html
+
+
+26. Be sure to develop on top of the LATEST GRASS code (which is in SVN repository).
+ You can re-check before submission with 'svn 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.
+ "svn diff display/d.vect/main.c"; that way, the diff will
+ include the pathname rather than just "main.c".
+
+
+27. Try to use module names which describe shortly the intended purpose of the module.
+
+ The first letters for module name should be:
+ d. - display commands
+ db. - database commands
+ g. - general GIS management commands
+ i. - imagery commands
+ m. - miscellaneous tool commands
+ ps. - postscript commands
+ r. - raster commands
+ r3. - raster3D commands
+ v. - vector commands
+
+ Some additional naming conventions
+ * export modules: (type).out.(format) eg: r.out.arc, v.out.ascii
+ * import module: (type).in.(format) eg: r.in.arc, v.in.ascii
+ * conversion modules: (type).to.(type) eg: r.to.vect, v.to.rast, r3.to.rast
+
+ Avoid module names with more than two dots in the name.
+ Example:
+ instead of r.to.rast3.elev use r.to.rast3elev
+
+
+28. Use the grass test suite to test your modules.
+
+ http://www-pool.math.tu-berlin.de/~soeren/grass/GRASS_TestSuite
+
+ You can easily write specific tests for your modules.
+
+ If your module is part of GRASS and you created some standard test
+ cases, please contact the developers to add your tests to the
+ default test suite. This will automatize complex test scenarios
+ and assure to find bugs much faster, if changes were made to your
+ modules or to the grass library.
+
+ Consider to subscribe to the GRASS Quality Assessment System to
+ get immediate notification about the code quality:
+
+ http://www.grass-gis.org/mailman/listinfo/grass-qa
+
+
+29. When submitting new files to the repository set SVN properties,
+ usually for directory
+
+ svn:ignore : *.tmp.html
+ *OBJ*
+
+ or e.g. for C-file
+
+ svn:mime-type : text/x-csrc
+ svn:keywords : Author Date Id
+ svn:eol-style : native
+
+ See
+ http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+
+30. Use doxygen style for source code documentation. It is required
+ for GRASS libraries, but also recommended for GRASS modules.
+
+ Do not use structural command inside documentation block since it
+ leads to some duplication of information (e.g. do not use \fn
+ command in comment blocks). The exception is \file command for
+ documenting a file, in this case structural command is required.
+
+ For files
+
+ /**
+ \file snap.c
+
+ \brief Vector library - Clean vector map (snap lines)
+
+ (C) 2001-2008 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.
+
+ \author Radim Blazek
+
+ \date 2001-2008
+ */
+
+ For functions
+
+ /**
+ \brief Snap lines in vector map to existing vertex in threshold
+
+ For details see Vect_snap_lines_list()
+
+ \param[in] Map input vector map
+ \param[in] type type of lines to be snap
+ \param[in] thresh threshold value for snapping
+ \param[out] Err vector map where lines representing snap are written or NULL
+ \param[out] msgout file pointer where messages will be written or NULL
+
+ \return
+ */
+
+
+31. Tell the other developers about the new code using the following e-mail:
+ grass-dev at lists.osgeo.org
+
+ To subscribe to this mailing list, see
+ http://lists.osgeo.org/mailman/listinfo/grass-dev
+
+
+32. In case of questions feel free to contact the developers at the above
+ mailing list.
+ http://www.grass-gis.org/devel/index.php#submission
+
+...
+[please add further hints if required]
Added: grass-addons/SUBMITTING_DOCS
===================================================================
--- grass-addons/SUBMITTING_DOCS (rev 0)
+++ grass-addons/SUBMITTING_DOCS 2008-05-02 12:08:32 UTC (rev 31203)
@@ -0,0 +1,77 @@
+$Date: 2008-02-26 03:58:34 +0100 (Tue, 26 Feb 2008) $
+
+NOTE: Please improve this list!
+
+Dear (new) GRASS Developer,
+
+When submitting documentation to GRASS SVN repository, please take
+care of following rules:
+
+[ see SUBMITTING for C hints ]
+[ see SUBMITTING_SCRIPTS for shell script hints ]
+[ see SUBMITTING_TCLTK for tcl and tk hints ]
+[ see SUBMITTING_PYTHON for Python code hints ]
+
+
+1. Editing of HTML pages
+ To avoid insertion of too complicated HTML tags (see also below),
+ we strongly suggest to use a plain text editor rather than a
+ HTML editor for editing.
+
+
+2. Module manual page:
+ Place the documentation in HTML format into 'description.html'.
+ The easiest way to do this is to study an existing HTML page
+ (to get the page style, e.g. vector/v.to.db/description.html).
+ With a few exceptions header and footer are NOT allowed.
+ You can add figures (PNG format), the figure name prefix should be the
+ module name. See raster/r.terraflow/description.html for an example.
+
+ Note that the parameter information is auto-generated upon
+ compilation. This is done by running module in a virtual session
+ after compilation (see the output of 'make'). To subsequently
+ verify the final HTML page, check the resulting HTML pages which
+ will be stored with the name of the module.
+
+ Examples (please add some) should be coded like this:
+
+ <div class="code"><pre>
+ v.to.db map=soils type=area option=area col=area_size unit=h
+ </pre></div>
+
+ The online WWW man pages is updated every Saturday (from SVN
+ repository).
+
+
+3. Usage of limited HTML tags
+ Since the MAN conversion of g.html2man is limited, please use
+ no other HTML tags than:
+ <A> <B> <BLINK> <BODY> <BR> <CODE> <DD> <DL> <DT> <EM>
+ <H2> <H3> <H4> <HEAD> <HEADER> <HR> <I> <IMG> <LI> <OL> <P>
+ <PRE> <SUP> <TABLE> <TD> <TH> <TITLE> <TR> <UL>
+
+
+4. Suggested HTML markup protocol:
+ Module names (i.e., v.category) should be emphsized with <em>,
+ and boldface <b> for flags and parameter names. Shell commands,
+ names, values, etc. should use <tt>. Empahsized phrases should use
+ italics <i>. The SEE ALSO section of each page should also be
+ alphabetized.
+
+
+5. When submitting new files to the repository set SVN properties,
+ e.g. for HTML file
+
+ svn:mime-type : text/html
+ svn:keywords : Author Date Id
+ svn:eol-style : native
+
+ See
+ http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+
+6. See also
+ http://grass.gdf-hannover.de/wiki/Updating_GRASS_Documentation
+
+...
+[please add further hints if required]
Added: grass-addons/SUBMITTING_PYTHON
===================================================================
--- grass-addons/SUBMITTING_PYTHON (rev 0)
+++ grass-addons/SUBMITTING_PYTHON 2008-05-02 12:08:32 UTC (rev 31203)
@@ -0,0 +1,109 @@
+$Date: 2008-01-06 12:42:32 +0100 (Sun, 06 Jan 2008) $
+
+NOTE: Please improve this list!
+
+Dear (new) GRASS Developer,
+
+When submitting Python code to GRASS SVN repository, please take
+care of following rules:
+
+[ see SUBMITTING for C hints ]
+[ see SUBMITTING_SCRIPTS for shell script hints ]
+[ see SUBMITTING_TCLTK for tcl and tk hints ]
+[ see SUBMITTING_DOCS for documentation ]
+
+
+1. Indentation
+
+ As Python determines nesting based upon indentation, it
+ isn't just a stylistic issue.
+
+ Please use 4-space indentation (GNU Emacs python-mode default).
+
+ See also "Python Style Guide" by Guido van Rossum
+ http://www.python.org/doc/essays/styleguide.html
+
+
+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 over view of the code in the file to assist other
+ programmers that will need to make changes to your code. For this
+ purpose use Python Docstring, see
+ http://epydoc.sourceforge.net/docstrings.html
+
+ Example (fictitious header for a script called r.myscript):
+
+"""
+MODULE: r.myscript
+
+AUTHOR(S): Me <email AT some domain>
+
+PURPOSE: Calculates univariate statistics from a GRASS raster map
+
+COPYRIGHT: (C) 2007 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).
+
+
+3. - deleted.
+ We don't want the $ ID $ in source code any more as it causes problems
+ for the branches.
+
+
+4. PLEASE take the time to add comments throughout your code explaining what
+ the code is doing. It will save a HUGE amount of time and frustration for
+ other programmers that may have to change your code in the future.
+
+
+5. Make sure a new line is at the end of each file.
+
+
+6. For consistency, use README rather than README.txt for any README files.
+
+
+7. Be sure to develop on top of the LATEST GRASS code (which is in SVN repository).
+ You can re-check before submission with 'svn 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.
+ "svn diff gui/wxpython/wxgui.py"; that way, the diff will
+ include the pathname rather than just "wxgui.py".
+
+
+8. When submitting new files to the repository set SVN properties,
+ usually for directory
+
+ svn:ignore : *.pyc
+
+ or e.g. for Python file
+
+ svn:mime-type : text/python
+ svn:keywords : Author Date Id
+ svn:eol-style : native
+
+ See
+ http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+
+8. Tell the other developers about the new code using the following e-mail:
+ grass-dev at lists.osgeo.org
+
+ To subscribe to this mailing list, see
+ http://lists.osgeo.org/mailman/listinfo/grass-dev
+
+
+9. In case of questions feel free to contact the developers at the above
+ mailing list.
+ http://www.grass-gis.org/devel/index.php#submission
+
+...
+[please add further hints if required]
Added: grass-addons/SUBMITTING_SCRIPTS
===================================================================
--- grass-addons/SUBMITTING_SCRIPTS (rev 0)
+++ grass-addons/SUBMITTING_SCRIPTS 2008-05-02 12:08:32 UTC (rev 31203)
@@ -0,0 +1,247 @@
+$Date: 2008-01-06 12:42:32 +0100 (Sun, 06 Jan 2008) $
+
+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 ]
+[ see SUBMITTING_PYTHON for Python code hints ]
+
+
+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 <email AT some domain>
+# 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 <$GIS_OPT_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 <$GIS_OPT_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. 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
+
+
+15. When submitting new files to the repository set SVN properties,
+ usually for directory
+
+ svn:ignore : *.tmp.html
+
+ or e.g. for script file
+
+ svn:executable : *
+ svn:mime-type : text/x-sh
+ svn:keywords : Author Date Id
+ svn:eol-style : native
+
+ See
+ http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+
+16. Tell the other developers about the new code using the following e-mail:
+ grass-dev at lists.osgeo.org
+
+ To subscribe to this mailing list, see
+ http://lists.osgeo.org/mailman/listinfo/grass-dev
+
+
+17. In case of questions feel free to contact the developers at the above
+ mailing list.
+ http://www.grass-gis.org/devel/index.php#submission
+
+...
+[please add further hints if required]
Added: grass-addons/SUBMITTING_TCLTK
===================================================================
--- grass-addons/SUBMITTING_TCLTK (rev 0)
+++ grass-addons/SUBMITTING_TCLTK 2008-05-02 12:08:32 UTC (rev 31203)
@@ -0,0 +1,281 @@
+$Date: 2008-01-06 12:42:32 +0100 (Sun, 06 Jan 2008) $
+
+NOTE: Please improve this list!
+
+Dear (new) GRASS Developer,
+
+When submitting TCL and TK SCRIPTS to GRASS SVN repository,
+please take care of following rules:
+
+[ see SUBMITTING for C code hints ]
+[ see SUBMITTING_SCRIPTS for shell script hints ]
+[ see SUBMITTING_DOCS for documentation ]
+[ see SUBMITTING_PYTHON for Python code hints ]
+
+
+1. Use the directory structure to place your program appropriately into
+ the source tree
+ - general grass tcl/tk libraries and reusable code go into lib/gtcltk
+ - user interfaces go in gui/tcltk
+ - scripts go in scripts/
+ Programs here must have a proper Makefile and description.html
+
+
+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 (fictitious header for a script called r.myscript) :
+
+############################################################################
+#
+# MODULE: r.myscript
+# AUTHOR(S): Me <email AT some domain>
+# 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).
+
+
+3. PLEASE take the time to add comments throughout your code explaining what
+ the code is doing. It will save a HUGE amount of time and frustration for
+ other programmers that need to change or understand your code in the future.
+ Many of the programmers working on grass are not heavily invested in tcl
+ and tk, so extra documentation and explanation are greatly appreciated.
+
+
+4. Test your program with both tcl/tk 8.3 and tcl/tk 8.4.
+
+
+5. Always use the gettext macros with [G_msg "..."] for user messages.
+ The string must be quoted using quotation marks, not braces, for
+ xgettext to find it. The string cannot include variable ($) or
+ command ([...]) substitutions. If you need substitutions use
+ [format ...].
+
+ Examples:
+ button .ok -text [G_msg "Ok"]
+
+ set statusbartext [format [G_msg "Monitor %d running"] $monitor_number]]
+
+ Use positional parameters if substitutions might be rearranged in another language:
+
+ format [G_msg "We produced %1\$d units in location %2\$s"] $num $city
+ format [G_msg "In location %2\$s we produced %1\$d units"] $num $city
+
+
+6. Use "GRASS_TCLSH" and "GRASS_WISH" environment variables instead of
+ "tclsh" and "wish" at the start of Tcl/Tk scripts. This allows users to
+ override the default names, so that developers don't need worry about the
+ shell names.
+
+ Tcl script:
+
+ #!/bin/sh
+ # the next line restarts using tclsh. Note the backslash: \
+ exec $GRASS_TCLSH "$0" "$@"
+
+
+ Tk script:
+
+ #!/bin/sh
+ # the next line restarts using wish. Note the backslash: \
+ exec $GRASS_WISH "$0" "$@"
+
+
+7. Do not source files that have already been sourced.
+
+ gui.tcl sources:
+ options.tcl
+ select.tcl
+ gronsole.tcl
+
+ If your code requires something to be sourced before it note so
+ in a comment at the top of the file.
+
+
+8. Set tabstops in your editor to 8 spaces.
+ When modifying files use the indentation style that is already present.
+ Please use consistent indentation style in your new code. Whether you use
+ tabs or spaces to indent please be consistent. Where tabs and spaces are
+ mixed please remember that a tab is 8 spaces.
+
+
+9. Use the tk options database to control the appearance of your user interface.
+ In general do not set options on tk widgets unless that option is truly
+ specific to that widget. It makes them harder to customize.
+
+ Example: Don't set options like -foreground or -background or -font
+ when creating widgets, unless there's a really _really_ specific reason to
+ have it that color (like it's demonstrating that color).
+
+ If you want something like a label to look different than everything else
+ of that class (other labels) give it a distinctive name, like
+ .moduletitlelabel . If you have a bunch of them give them all the same
+ distinctive name. This allows them to have their options controlled by the
+ options database.
+
+ You can put your options at the start of your script (before creating any
+ widgets) like this:
+ option add *modultitlelabel.background red
+ More examples are in lib/gtcltk/options.tcl
+
+ Many common options, like font, background and foreground colors,
+ highlighting, scrollbar colors, and help bubble appearance are controlled
+ 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
+ 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. Use of GRASS commands in shell wrapper.
+
+ Any GRASS program run in an xterm (those which do interactive query) needs
+ to use grass-run.sh, e.g.:
+
+ exec -- $env(GISBASE)/etc/grass-xterm-wrapper -e $env(GISBASE)/etc/grass-run.sh g.proj ...
+
+ You should probably also use "-T g.proj -n g.proj" to set the title
+ back (otherwise it will be "grass-run.sh", which isn't particularly
+ informative).
+
+ The xterm will close as soon as the command completes (whether it
+ succeeds or fails). You can use the -hold switch to retain the xterm
+ window after the command completes, but you should only do that for
+ debugging; having to manually close the xterm window each time would
+ be annoying in normal use. Alternatively, redirect stdout/stderr to a
+ file, to catch any error messages.
+
+
+13. Be sure to develop on top of the LATEST GRASS code (which is in
+ SVN repository). You can re-check before submission with 'svn
+ 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 at 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. 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
+ expressions and especially regular expressions (Tcl also compiles regular
+ expressions). Multiple evaluation can also lead to bugs.
+
+ Expressions via expr command:
+ Slow:
+ set y [expr $a * $x + $b]
+ Fast:
+ set y [expr {$a * $x + $b}]
+
+ Expressions in conditions:
+ Slow:
+ if [...] {...
+ Fast:
+ if {[...]} {...
+
+ Regular expressions:
+ Very slow:
+ regex "x(\[0-9\]+).*not" $string trash number
+ Fast:
+ regex {x([0-9]+).*not} $string trash number
+
+ If you really want speed:
+ If a regular expression needs to be constructed from variables but used
+ multiple times store it in a variable that will not be destroyed or
+ changed between reuse. Tcl stores the compiled regex with the variable.
+
+
+17. 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
+ set list [commandMakesList]
+ set x1 [lindex $list 0]
+ set y1 [lindex $list 1]
+ set x2 [lindex $list 2]
+ set y2 [lindex $list 3]
+
+ Easier and faster:
+ # Make x1 y1 x2 y2 the first four things in the list
+ foreach {x1 y1 x2 y2} [commandMakesList] {break}
+
+ Be sure to include a comment as to what you are doing.
+
+
+18. Use the Tcl list functions (list, lappend etc) for manipulating lists.
+
+ For example, use:
+
+ set vals [list $foo $bar]
+
+ rather than:
+
+ set vals "$foo $bar"
+
+ The former will always create a list with two elements, adding braces
+ if necessary, while the latter will split $foo and $bar into multiple
+ elements if they contain spaces. Additionally the first is faster
+ 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
+ not like system().
+
+ Overlooking either of these points is likely to result in code which
+ fails when a command argument contains a space.
+
+
+19. 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.
+
+
+20. When submitting new files to the repository set SVN properties,
+ e.g.
+
+ svn:executable : *
+ svn:mime-type : text/x-tcl
+ svn:keywords : Author Date Id
+ svn:eol-style : native
+
+ See
+ http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+...
+[please add further hints if required]
More information about the grass-commit
mailing list