|
|
@@ -1,496 +1 @@
|
|
|
-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"));
|
|
|
-
|
|
|
- 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 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/development/
|
|
|
-
|
|
|
-...
|
|
|
-[please add further hints if required]
|
|
|
-
|
|
|
-
|
|
|
-"Your attention to detail is appreciated."
|
|
|
+See http://trac.osgeo.org/grass/wiki/Submitting
|
Martin Landa