[[TOC]]
= Submitting C code =

When submitting C code to GRASS SVN repository, please take care of
following rules:

== API Manual ==

Get and read the GRASS Programmer's Manual here:[[BR]]
    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
}}}

== Directory Conventions ==

Use the directory structure to place your module appropriately into the source tree

    	* libraries go into `lib/`
    	* raster modules go into `raster/`
    	* vector modules go into `vector/`
    	* ...

    Consider to take a look at "GNU Coding Standards": http://www.gnu.org/prep/standards.html

== Headers ==

Add a header section to file main.c of your module 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:
{{{
/****************************************************************************
 *
 * MODULE:       g.foo
 * AUTHOR(S):    John Doe <jdoe at somewhere org>
 * PURPOSE:      Provide short description of module here...
 * COPYRIGHT:    (C) 2010 by John Doe, and 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 (http://www.gnu.org).

=== GRASS Config Header ===

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 source:grass/trunk/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.

=== Other Headers ===

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.

== Functions ==

=== Void ===

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 */
	
	return;
    }
    
    int G_something_else(int x, int y)
    {
    	/* Snipped out code */
	
	return 0;
    }
}}}

=== G_asprintf() ===

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.

=== Memory Allocations ===

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()
}}}
	Could somebody please add others (please verify that they are useful and safe first)

=== Naming Conventions ===

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()``.

=== Comments ===

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 source:grass/trunk/lib/gis/ for examples.

=== Documentation in Doxygen ===

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
    */
}}}
    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	   
    */
}}}

== Modules ==

=== Returning Value Of Main function ===

Module exit status is defined as `EXIT_SUCCESS` or `EXIT_FAILURE`
(declared in `stdlib.h`), e.g.

{{{
    {
      ...
      if (G_parser (argc, argv))
          exit (EXIT_FAILURE);

      ...
      exit (EXIT_SUCCESS);
    }
}}}

=== Messages ===

Use `fprintf()` instead of `printf()`. 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); 
}}}
    It is suggested to add a comment line before translatable user message to give a hint to translators about meaning or use of cumbersome or obscure message. First word in the comment must be GTC - GRASS translation comment,
 
    Example:
{{{
        /* GTC A name of a projection */
        G_message(_("State Plane"));
}}} 
    Any message with a noun in plural form has to pass _n() macro, even if for the English language it is not required!
{{{
       G_message(_n("One map", "%d maps", number), number);
}}}   
    See source:grass/trunk/locale/README for details.


    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, ...). */
}}}

=== Map History ===

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. source:grass/trunk/raster/r.patch/main.c (the same applies to vector and raster3d modules!)

=== Standardized Options and Flags ===

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 source:grass/trunk/lib/gis/parser_standard_options.c for details of the function definition.

== Indentation ==

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 source:grass/trunk/tools/grass_indent.sh script.

== Compilation ==

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.)

=== Compiler Flags ===

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 GIS.

See also http://grasswiki.osgeo.org/wiki/Compile_and_Install

==== GNU/Linux ====
{{{
       MYCFLAGS="-g -Wall -Werror-implicit-function-declaration -Wreturn-type -fno-common -fexceptions"
       MYCXXFLAGS="-g -Wall"
       MYLDFLAGS="-Wl,--no-undefined -Wl,-z,relro"

       CFLAGS="$MYCFLAGS" CXXFLAGS="$MYCXXFLAGS" LDFLAGS="$MYLDFLAGS" ./configure ... 
}}}

==== MacOSX ====

(to be suggested, see [http://trac.osgeo.org/grass/browser/grass/trunk/macosx/ReadMe.rtf macosx/ReadMe.rtf])

==== MS-Windows ====

(to be suggested, see [wiki:CompileOnWindows])

==== FreeBSD / NetBSD ====

(to be suggested)

See also http://grasswiki.osgeo.org/wiki/Compile_and_Install#FreeBSD_.2F_NetBSD

==== IBM/AIX ====

(to be suggested)

See also http://grasswiki.osgeo.org/wiki/Compile_and_Install#AIX

==== Solaris ====

(to be suggested)

See also http://grasswiki.osgeo.org/wiki/Compile_and_Install#AIX

...