$Id$ NOTE: Please improve this list! Dear (new) GRASS Developer, When submitting C code to GRASS CVS repository, please take care of following rules: [ see SUBMITTING_SCRIPTS for shell script hints ] [ see SUBMITTING_TCLTK for tcl and tk hints ] 1. Get and read the GRASS 6 Programmer's Manual here: http://grass.itc.it/devel/index.php#prog 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@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 CVS branches. 5. To ensure that the software system continues to work, please include #include 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. 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. 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 file [%s] not available"), 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 (eg always checking if memory was allocated) and/or improves portability. PLEASE refer to the programmers manual for the proper use (eg 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 CVS 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 eg 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. 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: 
    v.to.db map=soils type=area option=area col=area_size unit=h
The online WWW man pages will be updated every Saturday by CVS. 24. Add/update, if required the related GUI menus: gui/tcltk/menus/menu.tcl 25. For consistency, use README rather than README.txt for any README files. 26. GRASS/Environment variables: If you add a new variable, please follow the naming convention. All variables are described in lib/init/variables.html 27. 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". 28. 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 commands i. - imagery commands p. - paint 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://grass.itc.it/mailman/listinfo/grass-qa 29. Tell the other developers about the new code using the following e-mail: grass-dev@grass.itc.it To subscribe to this mailing list, see http://grass.itc.it/devel/index.php 30. 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]