Changes between Initial Version and Version 1 of Submitting/TclTk

Timestamp:

Jun 21, 2014, 5:22:07 AM (10 years ago)

Author:

martinl

Comment:

--

Submitting/TclTk

@@ +1 @@
+[[TOC]]
+= Submitting TCL/TK Code (GRASS 6 ONLY) =
+
+When submitting TCL and TK SCRIPTS to GRASS SVN repository,
+please take care of following rules:
+
+== Directory Structure ==
+
+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
+
+== Headers ==
+ 
+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).
+
+== Comments ==
+
+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.
+
+== Test Code ==
+
+Test your program with tcl/tk 8.5.
+
+== Messages ==
+
+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
+
+== Environmental Variables ==
+
+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" "$@"
+
+=== Global Variables ===
+
+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).
+
+== Source Files ==
+
+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.
+
+== Indentation ==
+
+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.
+
+== User Interface ==
+
+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
+
+== Shell Wrapper ==
+
+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.
+
+== Evaluation ==
+
+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.
+
+== Decompose Lists ==
+
+ 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.
+
+== List Functions ==
+
+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.
+
+== Tcl C Library ==
+
+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.
+
+== SVN Properties ==
+
+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