SUBMITTING

$Date$

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://grass.osgeo.org/programming7/

    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. If you are modifying an existing
    file you may under no circumstances remove prior copyright or licensing
    text that is not your own, even for a major rewrite. If any original
    code or code that is in part derived from another's original work
    remains, it must be properly cited.

    Example (ficticious header for a file called color.c) :

/****************************************************************************
 *
 * MODULE:       d.rast (or new higher level module name (eg GRASS core))
 * AUTHOR(S):    Original author unknown - probably CERL
 *               John Doe <jdoe at somewhere 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 there is no sorting
 *               functionality.
 * COPYRIGHT:    (C) 2010 by the GRASS Development Team
 *
 *               This program is free software under the GNU General Public
 *               License (>=v2). Read the COPYING file 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 any function
    which returns a value.

    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 */
    }
    
    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()
	G_system() instead of system()

	Could somebody please add others (please verify that they are
	useful and safe first)


12. Use function names which fulfill 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 -bad -bap -bbb -br -bli0 -bls -cli0 -ncs -fc1 -hnl -i4 \
      -nbbo -nbc -nbfda -nbfde -ncdb -ncdw -nce -nfca -npcs -nprs \
      -npsl -nsc -nsob -saf -sai -saw -sbi0 -ss -ts8 -ut 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.
    For your convenience use the tools/grass_indent.sh script.


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 and UNIX style newlines
    are used (\n).


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. Also beware of
    removing $(FOO)* if $(FOO) has any chance of being empty.

    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
     gui/wxpython/xml/menudata.xml


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 our 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 an ambiguous "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

    To set a property:

      svn propset svn:keywords 'Author Date Id' <file>
      svn propset svn:mime-type text/x-sh grass_shellscript.sh

    To edit the svn:ignore property using your default text editor:

      svn propedit svn:ignore <directory>

    To set the svn:ignore property non-interactively, first create a
    file containing the value:

      echo "*.tmp.html" > ignore.txt
      echo "*OBJ*" >> ignore.txt

    then use:

      svn propset -F ignore.txt svn:ignore <directory>

    List of mime-type:
      C++ files (.cpp): text/x-c++src
      C files (.c): text/x-csrc
      DTD files (.dtd): text/xml-dtd
      GIF files (.gif): image/gif
      Header files (.h): text/x-chdr
      HTML files (.html): text/html
      JPEG files (.jpg): image/jpeg
      Makefiles: text/x-makefile
      PNG files (.png): image/png
      Python files (.py): text/x-python
      Shell scripts (.sh): text/x-sh
      Text files (.txt): text/plain
      XML files (.xml): text/xml
      
      (please update the list...)

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 Map pointer to input vector map 
       \param type filter features of given type to be snap
       \param thresh threshold value for snapping
       \param[out] Err pointer to vector map where lines representing snap are written or NULL
       \param[out] msgout file pointer where messages will be written or NULL
       
       \return 1	   
    */


31. Tell the other developers about the new code using the following e-mail:
    grass-dev@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]


"Your attention to detail is appreciated."