← Back to branch summary

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

« back to all changes in this revision

Viewing changes to SUBMITTING

  • 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
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 C code to GRASS SVN repository, please take care of
8
 
following rules:
9
 
 
10
 
[ see SUBMITTING_SCRIPTS for shell script hints ]
11
 
[ see SUBMITTING_TCLTK for tcl and tk hints ]
12
 
[ see SUBMITTING_DOCS for documentation ]
13
 
[ see SUBMITTING_PYTHON for Python code hints ]
14
 
 
15
 
 
16
 
1.  Get and read the GRASS 6 Programmer's Manual here:
17
 
    http://grass.osgeo.org/programming6/
18
 
 
19
 
    or generate it from this source code (the programmer's manual is
20
 
    integrated in the source code in doxygen style):
21
 
      make htmldocs
22
 
      make pdfdocs
23
 
 
24
 
 
25
 
2.  Use the directory structure to place your module appropriately into
26
 
    the source tree
27
 
        - libes go into lib/
28
 
        - raster goes into raster/
29
 
        - vector goes into vector/
30
 
        - ...
31
 
 
32
 
    Consider to take a look at "GNU Coding Standards"
33
 
    http://www.gnu.org/prep/standards.html
34
 
 
35
 
    In future, there will be a centralized contribution directory.
36
 
 
37
 
 
38
 
3.  Add a header section to each file you submit and make sure you include
39
 
    the copyright. The purpose section is meant to contain a general
40
 
    overview of the code in the file to assist other programmers that will
41
 
    need to make changes to your code. If you are modifying an existing
42
 
    file you may under no circumstances remove prior copyright or licensing
43
 
    text that is not your own, even for a major rewrite. If any original
44
 
    code or code that is in part derived from another's original work
45
 
    remains, it must be properly cited.
46
 
 
47
 
    Example (ficticious header for a file called color.c) :
48
 
 
49
 
/****************************************************************************
50
 
 *
51
 
 * MODULE:       d.rast (or new higher level module name (eg GRASS core))
52
 
 * AUTHOR(S):    Original author unknown - probably CERL
53
 
 *               John Doe <jdoe at somewhere org>
54
 
 * PURPOSE:      To provide storage and manipulation of colors used for 
55
 
 *               rendering the raster. The colors are stored in a doubly linked
56
 
 *               list which must be initialized with InitColors() before it can
57
 
 *               be used. Note that most linked list functionality (add,
58
 
 *               remove, get) is supported, but there is no sorting
59
 
 *               functionality.
60
 
 * COPYRIGHT:    (C) 2010 by the GRASS Development Team
61
 
 *
62
 
 *               This program is free software under the GNU General Public
63
 
 *               License (>=v2). Read the COPYING file that comes with GRASS
64
 
 *               for details.
65
 
 *
66
 
 *****************************************************************************/
67
 
 
68
 
    The copyright protects your rights according to GNU General Public
69
 
    License (www.gnu.org).
70
 
 
71
 
 
72
 
4.  - deleted.
73
 
    We don't want the $ID$ in source code any more as it causes problems
74
 
    for the SVN branches.
75
 
 
76
 
 
77
 
5.  To ensure that the software system continues to work, please include
78
 
 
79
 
        #include <grass/config.h>
80
 
 
81
 
    in your files and make use of the various system dependencies
82
 
    contained therein.  As one example of this, see lib/gmath/fft.c.
83
 
    Please refrain from declaring system functions within the
84
 
    software; include the proper header files (conditionally dependent
85
 
    on config.h macros if necessary) instead.
86
 
 
87
 
 
88
 
6. Order of include headers
89
 
 
90
 
    In general, headers should be included in the order:
91
 
 
92
 
    1. Core system headers (stdio.h, ctype.h, ...)
93
 
    2. Headers for non-core system components (X11, libraries).
94
 
    3. Headers for core systems of the package being compiled (grass/gis.h, grass/glocale.h, ...)
95
 
    4. Headers for the specific library/program being compiled (geodesic.h, ...)
96
 
 
97
 
    Each class of header has an obligation to be compatible with those
98
 
    above it in the list, but not those below it.
99
 
 
100
 
 
101
 
7.  Always specify the return type for ALL functions including those that
102
 
    return type "void", and insert return statements for any function
103
 
    which returns a value.
104
 
    Also, use ANSI C prototypes to declare your functions. 
105
 
    For module return values, see "Exit status" below.
106
 
 
107
 
    Examples:
108
 
    
109
 
    void G_something(void);
110
 
    int G_something_else(int, int);
111
 
    
112
 
    void G_something(void)
113
 
    {
114
 
        /* Snipped out code */
115
 
    }
116
 
    
117
 
    int G_something_else(int x, int y)
118
 
    {
119
 
        /* Snipped out code */
120
 
        
121
 
        return 0;
122
 
    }
123
 
 
124
 
 
125
 
8.  Module exit status is defined as EXIT_SUCCESS or EXIT_FAILURE, e.g.
126
 
 
127
 
    {
128
 
      ...
129
 
      if (G_parser (argc, argv))
130
 
          exit (EXIT_FAILURE);
131
 
 
132
 
      ...
133
 
      exit (EXIT_SUCCESS);
134
 
    }
135
 
 
136
 
 
137
 
9.  Use fprintf instead of printf. But:
138
 
    
139
 
    For errors and warnings please use the G_fatal_error() and
140
 
    G_warning() functions. General messages for the user should use
141
 
    G_message() while debug messages should use G_debug() whenever
142
 
    possible. There are two variants to G_message(): G_verbose_message()
143
 
    which will only display the message if in verbose mode, and
144
 
    G_important_message() which will always show the message unless
145
 
    the module is running in --quiet mode. G_fatal_error() and
146
 
    G_warning() will always be displayed regardless of verbosity setting.
147
 
    Messages sent to any of these functions will be printed to stderr.
148
 
 
149
 
    G_message() output is not expected to be sent to pipe or file.
150
 
 
151
 
    Always use the gettext macros with _("") for user messages,
152
 
    example:
153
 
      G_fatal_error(_("Vector map <%s> not found"), name); 
154
 
 
155
 
 
156
 
    Pipe/file data output:
157
 
    For data output redirected to pipe or file, please use fprintf() and 
158
 
    specify the stdout stream as follows:
159
 
 
160
 
      fprintf(stdout, ...);
161
 
      fflush(stdout);
162
 
 
163
 
      fflush(stdout) always required when using fprintf(stdout, ...).
164
 
 
165
 
 
166
 
10. Use the GRASS library function G_asprintf() instead of the
167
 
    standard C functions asprintf(), vsnprintf() and snprintf(). These
168
 
    functions are not portable or have other issues.  Example:
169
 
 
170
 
    char *msg;
171
 
 
172
 
    G_asprintf(&msg, "%s", parameters);
173
 
    do_something_with_msg();
174
 
    G_free(msg);
175
 
 
176
 
    Note that you should free memory when G_asprintf() is used.
177
 
 
178
 
 
179
 
11. Use the following GRASS library functions instead of the standard C
180
 
    functions. The reason for this is that the following functions ensure
181
 
    good programming practice (e.g. always checking if memory was allocated)
182
 
    and/or improves portability. PLEASE refer to the programmers manual
183
 
    for the proper use (e.g. determining if any casts are needed for arguments
184
 
    or return values) of these library functions. They may perform a task
185
 
    slightly different from their corresponding C library function, and thus,
186
 
    their use may not be the same.
187
 
    
188
 
        G_malloc() instead of malloc()
189
 
        G_calloc() instead of calloc()
190
 
        G_realloc() instead of realloc()
191
 
        G_free() instead of free()
192
 
        G_getenv() instead of getenv()
193
 
        G_setenv() instead of setenv()
194
 
        G_unsetenv() instead of unsetenv()
195
 
        G_sleep() instead of sleep()
196
 
        G_system() instead of system()
197
 
 
198
 
        Could somebody please add others (please verify that they are
199
 
        useful and safe first)
200
 
 
201
 
 
202
 
12. Use function names which fulfill the official GNU naming convention.
203
 
    http://www.gnu.org/prep/standards/html_node/Names.html#Names
204
 
 
205
 
    Instead of naming a function like: MyNewFunction() use underscores
206
 
    for seperation and lower case letters: my_new_function().
207
 
 
208
 
 
209
 
13. Don't use the C++ comment style! This confuses several compilers.
210
 
    Use instead:
211
 
       /* C-comments */
212
 
 
213
 
    If you want to comment code portions, use
214
 
       #ifdef notdef 
215
 
            portion_to_be_commented;
216
 
       #endif
217
 
    This is safe comparing to nested /* comments */
218
 
 
219
 
    Functions in the library must be documented in doxygen style to
220
 
    get them into the programmer's manual (generate with 
221
 
      make pdfdocs  or
222
 
      make htmldocs
223
 
    ). See lib/gis/*.c for examples.
224
 
 
225
 
 
226
 
14. PLEASE take the time to add comments throughout your code explaining what
227
 
    the code is doing. It will save a HUGE amount of time and frustration for
228
 
    other programmers that may have to change your code in the future.
229
 
 
230
 
 
231
 
15. To promote a consistent coding style, please use the "indent" program
232
 
    on all new C modules using the following switches:
233
 
    
234
 
     $ indent -bad -bap -bbb -br -bli0 -bls -cli0 -ncs -fc1 -hnl -i4 \
235
 
      -nbbo -nbc -nbfda -nbfde -ncdb -ncdw -nce -nfca -npcs -nprs \
236
 
      -npsl -nsc -nsob -saf -sai -saw -sbi0 -ss -ts8 -ut main.c
237
 
 
238
 
    Existing code should not be re-indented except in extreme cases, as this
239
 
    will make "diff" comparisons with older versions impossible. If indent is 
240
 
    needed, do not check in any changes other than the indentation in the same 
241
 
    commit! Do add the indent switches and any indent warning messages to the 
242
 
    SVN log. Any change or fix mixed in with an indent is very hard to track 
243
 
    making it hard for others to follow the change or fix any new bugs.
244
 
    For your convenience use the tools/grass_indent.sh script.
245
 
 
246
 
 
247
 
16. Platform dependent code:
248
 
    Do not remove #ifdef __CYGWIN__ and/or #ifndef __CYGWIN__ lines and 
249
 
    their encapsulated lines from source code (one example was that someone
250
 
    removed drand48 definition.)
251
 
 
252
 
 
253
 
17. Suggested compiler flags:
254
 
    We suggest to use very strict compiler flags to capture errors
255
 
    at the very beginning. Here our list of flags, please use them
256
 
    to configure you development version of GRASS:
257
 
 
258
 
    GNU/Linux:
259
 
 
260
 
       MYCFLAGS="-g -Wall -Werror-implicit-function-declaration -fno-common"
261
 
       MYCXXFLAGS="-g -Wall"
262
 
       
263
 
       CFLAGS="$MYCFLAGS" CXXFLAGS="$MYCXXFLAGS" ./configure ... 
264
 
 
265
 
    MacOSX:     [to be suggested]
266
 
 
267
 
    MS-Windows: [to be suggested]
268
 
 
269
 
 
270
 
18. Make sure a new line is at the end of each file and UNIX style newlines
271
 
    are used (\n).
272
 
 
273
 
 
274
 
19. When writing Makefiles, use the current standard.
275
 
 
276
 
    If you have to use commands, please check for:
277
 
    
278
 
            avoid     | use instead
279
 
    ------------------+---------------
280
 
    make target       | $(MAKE) target
281
 
    mkdir target      | $(MKDIR) target
282
 
    cp  (executable)  | $(INSTALL) -m 755 file target
283
 
    cp  (normal file) | $(INSTALL) -m 644 file target
284
 
    ar                | $(AR)
285
 
 
286
 
    rm: be VERY careful with recursive remove. Also beware of
287
 
    removing $(FOO)* if $(FOO) has any chance of being empty.
288
 
 
289
 
    Examples: see below examples or others
290
 
              raster/r.info/Makefile
291
 
              vector/v.digit/Makefile
292
 
 
293
 
    If you are unsure, please ask on the GRASS Developers list.
294
 
 
295
 
    
296
 
20. Have a look at ./INSTALL
297
 
 
298
 
 
299
 
21. Have a function included in your module which writes to the history
300
 
    file of the map (e.g. command line, parameters etc.). See e.g.
301
 
    raster/r.patch/main.c
302
 
 
303
 
    (the same applies to vector and g3d modules!)
304
 
 
305
 
 
306
 
22. Standard parser options: use G_define_standard_option() whenever possible
307
 
    to define standard module command line options. This will save you time,
308
 
    create fewer bugs, and make things easier on the translators.
309
 
    See lib/gis/parser.c for details of the function definition.
310
 
 
311
 
 
312
 
23. Add/update, if required the related GUI menus:
313
 
     gui/tcltk/gis.m/gmmenu.tcl
314
 
     gui/wxpython/xml/menudata.xml
315
 
 
316
 
 
317
 
24. For consistency, use README rather than README.txt for any README files.
318
 
 
319
 
 
320
 
25. GRASS/Environment variables:
321
 
    If you add a new variable, please follow the naming convention.
322
 
    All variables are described in
323
 
    lib/init/variables.html
324
 
 
325
 
 
326
 
26. Be sure to develop on top of the LATEST GRASS code (which is in our SVN
327
 
    repository). You can re-check before submission with 'svn diff':
328
 
 
329
 
    Be sure to create unified ("diff -u") format. "Plain" diffs (the default
330
 
    format) are risky, because they will apply without warning to code which
331
 
    has been substantially changed; they are also harder to read than unified.
332
 
 
333
 
    Such diffs should be made from the top-level directory, e.g.
334
 
    "svn diff display/d.vect/main.c"; that way, the diff will
335
 
    include the pathname rather than just an ambiguous "main.c".
336
 
 
337
 
 
338
 
27. Try to use module names which describe shortly the intended purpose of the module.
339
 
 
340
 
    The first letters for module name should be:
341
 
        d.      - display commands
342
 
        db.     - database commands
343
 
        g.      - general GIS management commands
344
 
        i.      - imagery commands
345
 
        m.      - miscellaneous tool commands
346
 
        ps.     - postscript commands
347
 
        r.      - raster commands
348
 
        r3.     - raster3D commands
349
 
        v.      - vector commands
350
 
 
351
 
    Some additional naming conventions
352
 
    * export modules:     (type).out.(format) eg: r.out.arc, v.out.ascii
353
 
    * import module:      (type).in.(format)  eg: r.in.arc, v.in.ascii
354
 
    * conversion modules: (type).to.(type)    eg: r.to.vect, v.to.rast, r3.to.rast
355
 
 
356
 
    Avoid module names with more than two dots in the name. 
357
 
    Example:
358
 
       instead of r.to.rast3.elev use r.to.rast3elev    
359
 
 
360
 
 
361
 
28. Use the grass test suite to test your modules.
362
 
 
363
 
    http://www-pool.math.tu-berlin.de/~soeren/grass/GRASS_TestSuite
364
 
 
365
 
    You can easily write specific tests for your modules.
366
 
 
367
 
    If your module is part of GRASS and you created some standard test
368
 
    cases, please contact the developers to add your tests to the
369
 
    default test suite.  This will automatize complex test scenarios
370
 
    and assure to find bugs much faster, if changes were made to your
371
 
    modules or to the grass library.
372
 
 
373
 
    Consider to subscribe to the GRASS Quality Assessment System to
374
 
    get immediate notification about the code quality:
375
 
 
376
 
    http://grass.osgeo.org/mailman/listinfo/grass-qa
377
 
 
378
 
 
379
 
29. When submitting new files to the repository set SVN properties,
380
 
    usually for directory
381
 
 
382
 
      svn:ignore : *.tmp.html
383
 
                   *OBJ*
384
 
 
385
 
    or e.g. for C-file
386
 
    
387
 
      svn:mime-type : text/x-csrc
388
 
      svn:keywords : Author Date Id
389
 
      svn:eol-style : native
390
 
 
391
 
    See
392
 
    http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
393
 
 
394
 
    To set a property:
395
 
 
396
 
      svn propset svn:keywords 'Author Date Id' <file>
397
 
      svn propset svn:mime-type text/x-sh grass_shellscript.sh
398
 
 
399
 
    To edit the svn:ignore property using your default text editor:
400
 
 
401
 
      svn propedit svn:ignore <directory>
402
 
 
403
 
    To set the svn:ignore property non-interactively, first create a
404
 
    file containing the value:
405
 
 
406
 
      echo "*.tmp.html" > ignore.txt
407
 
      echo "*OBJ*" >> ignore.txt
408
 
 
409
 
    then use:
410
 
 
411
 
      svn propset -F ignore.txt svn:ignore <directory>
412
 
 
413
 
    List of mime-type:
414
 
      C++ files (.cpp): text/x-c++src
415
 
      C files (.c): text/x-csrc
416
 
      DTD files (.dtd): text/xml-dtd
417
 
      GIF files (.gif): image/gif
418
 
      Header files (.h): text/x-chdr
419
 
      HTML files (.html): text/html
420
 
      JPEG files (.jpg): image/jpeg
421
 
      Makefiles: text/x-makefile
422
 
      PNG files (.png): image/png
423
 
      Python files (.py): text/x-python
424
 
      Shell scripts (.sh): text/x-sh
425
 
      Text files (.txt): text/plain
426
 
      XML files (.xml): text/xml
427
 
      
428
 
      (please update the list...)
429
 
 
430
 
30. Use doxygen style for source code documentation. It is required
431
 
    for GRASS libraries, but also recommended for GRASS modules.
432
 
 
433
 
    Do not use structural command inside documentation block since it
434
 
    leads to some duplication of information (e.g. do not use \fn
435
 
    command in comment blocks). The exception is \file command for
436
 
    documenting a file, in this case structural command is required.
437
 
 
438
 
    For files
439
 
 
440
 
    /**
441
 
       \file snap.c
442
 
   
443
 
       \brief Vector library - Clean vector map (snap lines)
444
 
 
445
 
       (C) 2001-2008 by the GRASS Development Team
446
 
   
447
 
       This program is free software under the 
448
 
       GNU General Public License (>=v2). 
449
 
       Read the file COPYING that comes with GRASS
450
 
       for details.
451
 
   
452
 
       \author Radim Blazek
453
 
   
454
 
       \date 2001-2008
455
 
    */
456
 
 
457
 
    For functions
458
 
 
459
 
    /**
460
 
       \brief Snap lines in vector map to existing vertex in threshold
461
 
 
462
 
       For details see Vect_snap_lines_list()
463
 
 
464
 
       \param Map pointer to input vector map 
465
 
       \param type filter features of given type to be snap
466
 
       \param thresh threshold value for snapping
467
 
       \param[out] Err pointer to vector map where lines representing snap are written or NULL
468
 
       \param[out] msgout file pointer where messages will be written or NULL
469
 
       
470
 
       \return 1           
471
 
    */
472
 
 
473
 
 
474
 
31. Tell the other developers about the new code using the following e-mail:
475
 
    grass-dev@lists.osgeo.org
476
 
 
477
 
    To subscribe to this mailing list, see
478
 
    http://lists.osgeo.org/mailman/listinfo/grass-dev
479
 
 
480
 
 
481
 
32. In case of questions feel free to contact the developers at the above
482
 
    mailing list.
483
 
    http://grass.osgeo.org/devel/index.php#submission
484
 
 
485
 
...
486
 
[please add further hints if required]
 
1
See http://trac.osgeo.org/grass/wiki/Submitting