123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492 |
- 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_PYTHON for Python code hints ]
- [ see SUBMITTING_WXGUI for wxPython GUI code hints ]
- [ see SUBMITTING_DOCS for documentation ]
- 1. Get and read the GRASS 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 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
- 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: 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 (www.gnu.org).
- 4. 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 */
-
- return;
- }
-
- 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
- (declared in stdlib.h), e.g.
- {
- ...
- if (G_parser (argc, argv))
- exit (EXIT_FAILURE);
- ...
- exit (EXIT_SUCCESS);
- }
- 9. 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"));
- See 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, ...).
- 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()
- 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.edit/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/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://lists.osgeo.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...)
- For your convenience use the tools/module_svn_propset.sh script.
- 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
- */
- 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. If you need to add support for a different library in the 'configure' script,
- you should first seek consent in the grass-dev mailing list (see below), then
- you need to expand 'configure.in' and run subsequently autoconf-2.13 (later
- versions will not work) to re-generate 'configure'.
- 32. 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
- 33. In case of questions feel free to contact the developers at the above
- mailing list.
- http://grass.osgeo.org/devel/index.php#submission
- ...
- [please add further hints if required]
- "Your attention to detail is appreciated."
|