← Back to branch summary

~ubuntu-branches/ubuntu/vivid/grass/vivid-proposed

« back to all changes in this revision

Viewing changes to SUBMITTING_TCLTK

  • Committer: Package Import Robot
  • Author(s): Bas Couwenberg
  • Date: 2015-02-20 23:12:08 UTC
  • mfrom: (8.2.6 experimental)
  • Revision ID: package-import@ubuntu.com-20150220231208-1u6qvqm84v430b10
Tags: 7.0.0-1~exp1
* New upstream release.
* Update python-ctypes-ternary.patch to use if/else instead of and/or.
* Drop check4dev patch, rely on upstream check.
* Add build dependency on libpq-dev to grass-dev for libpq-fe.h.
* Drop patches applied upstream, refresh remaining patches.
* Update symlinks for images switched from jpg to png.

Show diffs side-by-side

added added

removed removed

Lines of Context:
SUBMITTING_TCLTK
1
 
$Date: 2012-02-05 21:39:18 +0100 (Sun, 05 Feb 2012) $
2
 
 
3
 
NOTE: Please improve this list!
4
 
 
5
 
Dear (new) GRASS Developer,
6
 
 
7
 
When submitting TCL and TK SCRIPTS to GRASS SVN repository,
8
 
please take care of following rules:
9
 
 
10
 
[ see SUBMITTING for C code hints ]
11
 
[ see SUBMITTING_SCRIPTS for shell script hints ]
12
 
[ see SUBMITTING_DOCS for documentation ]
13
 
[ see SUBMITTING_PYTHON for Python code hints ]
14
 
 
15
 
 
16
 
1.  Use the directory structure to place your program appropriately into
17
 
    the source tree
18
 
        - general grass tcl/tk libraries and reusable code go into lib/gtcltk
19
 
        - user interfaces go in gui/tcltk
20
 
        - scripts go in scripts/
21
 
            Programs here must have a proper Makefile and description.html
22
 
 
23
 
 
24
 
2.  Add a header section to the script you submit and make sure you include
25
 
    the copyright. The purpose section is meant to contain a general
26
 
    overview of the code in the file to assist other programmers that will
27
 
    need to make changes to your code.
28
 
 
29
 
    Example (fictitious header for a script called r.myscript) :
30
 
 
31
 
############################################################################
32
 
#
33
 
# MODULE:       r.myscript
34
 
# AUTHOR(S):    Me <email AT some domain>
35
 
# PURPOSE:      Calculates univariate statistics from a GRASS raster map
36
 
# COPYRIGHT:    (C) 2005 by the GRASS Development Team
37
 
#
38
 
#               This program is free software under the GNU General Public
39
 
#               License (>=v2). Read the file COPYING that comes with GRASS
40
 
#               for details.
41
 
#
42
 
#############################################################################
43
 
 
44
 
    The copyright protects your rights according to GNU General Public
45
 
    License (www.gnu.org).
46
 
 
47
 
 
48
 
3.  PLEASE take the time to add comments throughout your code explaining what
49
 
    the code is doing. It will save a HUGE amount of time and frustration for
50
 
    other programmers that need to change or understand your code in the future.
51
 
    Many of the programmers working on grass are not heavily invested in tcl
52
 
    and tk, so extra documentation and explanation are greatly appreciated.
53
 
 
54
 
 
55
 
4.  Test your program with both tcl/tk 8.3 and tcl/tk 8.4.
56
 
 
57
 
 
58
 
5.  Always use the gettext macros with [G_msg "..."] for user messages.
59
 
    The string must be quoted using quotation marks, not braces, for
60
 
    xgettext to find it. The string cannot include variable ($) or
61
 
    command ([...]) substitutions. If you need substitutions use
62
 
    [format ...].
63
 
 
64
 
    Examples:
65
 
    button .ok -text [G_msg "Ok"]
66
 
 
67
 
    set statusbartext [format [G_msg "Monitor %d running"] $monitor_number]]
68
 
 
69
 
    Use positional parameters if substitutions might be rearranged in another language:
70
 
 
71
 
    format [G_msg "We produced %1\$d units in location %2\$s"] $num $city
72
 
    format [G_msg "In location %2\$s we produced %1\$d units"] $num $city
73
 
 
74
 
 
75
 
6.  Use "GRASS_TCLSH" and "GRASS_WISH" environment variables instead of
76
 
    "tclsh" and "wish" at the start of Tcl/Tk scripts. This allows users to
77
 
    override the default names, so that developers don't need worry about the
78
 
    shell names.
79
 
 
80
 
    Tcl script:
81
 
 
82
 
        #!/bin/sh
83
 
        # the next line restarts using tclsh. Note the backslash: \
84
 
        exec $GRASS_TCLSH "$0" "$@"
85
 
 
86
 
 
87
 
    Tk script:
88
 
 
89
 
        #!/bin/sh
90
 
        # the next line restarts using wish. Note the backslash: \
91
 
        exec $GRASS_WISH "$0" "$@"
92
 
 
93
 
 
94
 
7.  Do not source files that have already been sourced.
95
 
 
96
 
        gui.tcl sources:
97
 
            options.tcl 
98
 
            select.tcl
99
 
            gronsole.tcl
100
 
 
101
 
    If your code requires something to be sourced before it note so
102
 
    in a comment at the top of the file.
103
 
 
104
 
 
105
 
8.  Set tabstops in your editor to 8 spaces.
106
 
    When modifying files use the indentation style that is already present.
107
 
    Please use consistent indentation style in your new code. Whether you use
108
 
    tabs or spaces to indent please be consistent. Where tabs and spaces are
109
 
    mixed please remember that a tab is 8 spaces.
110
 
 
111
 
 
112
 
9.  Use the tk options database to control the appearance of your user interface.
113
 
    In general do not set options on tk widgets unless that option is truly
114
 
    specific to that widget. It makes them harder to customize.
115
 
 
116
 
    Example: Don't set options like -foreground or -background or -font
117
 
    when creating widgets, unless there's a really _really_ specific reason to
118
 
    have it that color (like it's demonstrating that color).
119
 
 
120
 
    If you want something like a label to look different than everything else
121
 
    of that class (other labels) give it a distinctive name, like
122
 
    .moduletitlelabel . If you have a bunch of them give them all the same 
123
 
    distinctive name. This allows them to have their options controlled by the 
124
 
    options database.
125
 
 
126
 
    You can put your options at the start of your script (before creating any
127
 
    widgets) like this:
128
 
    option add *modultitlelabel.background red
129
 
    More examples are in lib/gtcltk/options.tcl
130
 
 
131
 
    Many common options, like font, background and foreground colors,
132
 
    highlighting, scrollbar colors, and help bubble appearance are controlled
133
 
    by options.tcl. You can include it at the start of your script with:
134
 
    source $env(GISBASE)/etc/gtcltk/options.tcl
135
 
 
136
 
 
137
 
10. Avoid using global variables. Thay are a frequent source of bugs, make code
138
 
    harder to understand, and make your program difficult to reuse. Additionally,
139
 
    putting code into procs usually makes it run faster (it gets compiled).
140
 
 
141
 
 
142
 
11. For consistency, use README rather than README.txt for any README files.
143
 
 
144
 
 
145
 
12. Use of GRASS commands in shell wrapper.
146
 
 
147
 
    Any GRASS program run in an xterm (those which do interactive query) needs
148
 
    to use grass-run.sh, e.g.:
149
 
 
150
 
    exec -- $env(GISBASE)/etc/grass-xterm-wrapper -e $env(GISBASE)/etc/grass-run.sh g.proj ...
151
 
 
152
 
    You should probably also use "-T g.proj -n g.proj" to set the title
153
 
    back (otherwise it will be "grass-run.sh", which isn't particularly
154
 
    informative).
155
 
 
156
 
    The xterm will close as soon as the command completes (whether it
157
 
    succeeds or fails). You can use the -hold switch to retain the xterm
158
 
    window after the command completes, but you should only do that for
159
 
    debugging; having to manually close the xterm window each time would
160
 
    be annoying in normal use. Alternatively, redirect stdout/stderr to a
161
 
    file, to catch any error messages.
162
 
 
163
 
 
164
 
13. Be sure to develop on top of the LATEST GRASS code (which is in
165
 
    SVN repository). You can re-check before submission with 'svn
166
 
    diff':
167
 
 
168
 
    Be sure to create unified ("diff -u") format. "Plain"
169
 
    diffs (the default format) are risky, because they will apply without
170
 
    warning to code which has been substantially changed; they are also
171
 
    harder to read than unified.
172
 
 
173
 
    Such diffs should be made from the top-level directory, e.g.
174
 
    "cvs diff display/d.vect/main.c"; that way, the diff will
175
 
    include the pathname rather than just "main.c".
176
 
 
177
 
 
178
 
14. Tell the other developers about the new code using the following e-mail:
179
 
    grass-dev@lists.osgeo.org
180
 
 
181
 
    To subscribe to this mailing list, see
182
 
    http://lists.osgeo.org/mailman/listinfo/grass-dev
183
 
 
184
 
 
185
 
15. In case of questions feel free to contact the developers at the above
186
 
    mailing list.
187
 
    http://grass.osgeo.org/devel/index.php#submission
188
 
 
189
 
 
190
 
16. Try to evaluate things only once. Tcl compiles the program to bytecode which
191
 
    can be interpreted fairly quickly. If there are strings that must still be
192
 
    evaluated tcl must parse and either compile or interpret them
193
 
    each time they are encountered. In general this means put braces around
194
 
    expressions and especially regular expressions (Tcl also compiles regular
195
 
    expressions). Multiple evaluation can also lead to bugs.
196
 
 
197
 
    Expressions via expr command:
198
 
    Slow:
199
 
        set y [expr $a * $x + $b]
200
 
    Fast:
201
 
        set y [expr {$a * $x + $b}]
202
 
 
203
 
    Expressions in conditions:
204
 
    Slow:
205
 
        if [...] {...
206
 
    Fast:
207
 
        if {[...]} {...
208
 
 
209
 
    Regular expressions:
210
 
    Very slow:
211
 
        regex "x(\[0-9\]+).*not" $string trash number
212
 
    Fast:
213
 
        regex {x([0-9]+).*not} $string trash number
214
 
 
215
 
    If you really want speed:
216
 
    If a regular expression needs to be constructed from variables but used
217
 
    multiple times store it in a variable that will not be destroyed or
218
 
    changed between reuse. Tcl stores the compiled regex with the variable.
219
 
 
220
 
 
221
 
17. You might want to decompose lists in a somewhat easy way:
222
 
 
223
 
    Difficult and slow:
224
 
    # Make x1 y1 x2 y2 the first four things in the list
225
 
    set list [commandMakesList]
226
 
    set x1 [lindex $list 0]
227
 
    set y1 [lindex $list 1]
228
 
    set x2 [lindex $list 2]
229
 
    set y2 [lindex $list 3]
230
 
 
231
 
    Easier and faster:
232
 
    # Make x1 y1 x2 y2 the first four things in the list
233
 
    foreach {x1 y1 x2 y2} [commandMakesList] {break}
234
 
 
235
 
    Be sure to include a comment as to what you are doing.
236
 
 
237
 
 
238
 
18. Use the Tcl list functions (list, lappend etc) for manipulating lists.
239
 
 
240
 
    For example, use:
241
 
 
242
 
        set vals [list $foo $bar]
243
 
 
244
 
    rather than:
245
 
 
246
 
        set vals "$foo $bar"
247
 
 
248
 
    The former will always create a list with two elements, adding braces
249
 
    if necessary, while the latter will split $foo and $bar into multiple
250
 
    elements if they contain spaces. Additionally the first is faster
251
 
    because tcl is not internally converting between strings and lists.
252
 
 
253
 
    A related issue is to remember that command lines (as used by exec and
254
 
    open "|...") are lists. exec behaves like execl(), spawnl() etc, and
255
 
    not like system().
256
 
 
257
 
    Overlooking either of these points is likely to result in code which
258
 
    fails when a command argument contains a space.
259
 
 
260
 
 
261
 
19. Tcl C library:
262
 
    Memory allocated with Tcl_Alloc (such as the result of Tcl_Merge)
263
 
    must be freed with Tcl_Free. This means that the ->freeProc of
264
 
    an interpreter when returning a string using Tcl_Merge should be
265
 
    TCL_DYNAMIC. Incorrectly freeing memory with glibc free will
266
 
    cause segfaults in Tcl 8.4 and later.
267
 
 
268
 
 
269
 
20. When submitting new files to the repository set SVN properties,
270
 
    e.g.
271
 
 
272
 
      svn:executable : *
273
 
      svn:mime-type : text/x-tcl
274
 
      svn:keywords : Author Date Id
275
 
      svn:eol-style : native
276
 
 
277
 
    See
278
 
    http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
279
 
 
280
 
...
281
 
[please add further hints if required]