SUBMITTING 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492
  1. NOTE: Please improve this list!
  2. Dear (new) GRASS developer,
  3. when submitting C code to GRASS SVN repository, please take care of
  4. following rules:
  5. [ see SUBMITTING_PYTHON for Python code hints ]
  6. [ see SUBMITTING_WXGUI for wxPython GUI code hints ]
  7. [ see SUBMITTING_DOCS for documentation ]
  8. 1. Get and read the GRASS Programmer's Manual here:
  9. http://grass.osgeo.org/programming7/
  10. or generate it from this source code (the programmer's manual is
  11. integrated in the source code in doxygen style):
  12. make htmldocs
  13. make pdfdocs
  14. 2. Use the directory structure to place your module appropriately into
  15. the source tree
  16. - libes go into lib/
  17. - raster modules go into raster/
  18. - vector modules go into vector/
  19. - ...
  20. Consider to take a look at "GNU Coding Standards"
  21. http://www.gnu.org/prep/standards.html
  22. 3. Add a header section to each file you submit and make sure you
  23. include the copyright. The purpose section is meant to contain a
  24. general overview of the code in the file to assist other
  25. programmers that will need to make changes to your code. If you
  26. are modifying an existing file you may under no circumstances
  27. remove prior copyright or licensing text that is not your own,
  28. even for a major rewrite. If any original code or code that is in
  29. part derived from another's original work remains, it must be
  30. properly cited.
  31. Example (ficticious header for a file called color.c) :
  32. /****************************************************************************
  33. *
  34. * MODULE: g.foo
  35. * AUTHOR(S): John Doe <jdoe at somewhere org>
  36. * PURPOSE: Provide short description of module here...
  37. * COPYRIGHT: (C) 2010 by John Doe, and the GRASS Development Team
  38. *
  39. * This program is free software under the GNU General Public
  40. * License (>=v2). Read the COPYING file that comes with GRASS
  41. * for details.
  42. *
  43. *****************************************************************************/
  44. The copyright protects your rights according to GNU General Public
  45. License (www.gnu.org).
  46. 4. We don't want the $ID$ in source code any more as it causes problems
  47. for the SVN branches.
  48. 5. To ensure that the software system continues to work, please include
  49. #include <grass/config.h>
  50. in your files and make use of the various system dependencies
  51. contained therein. As one example of this, see lib/gmath/fft.c.
  52. Please refrain from declaring system functions within the
  53. software; include the proper header files (conditionally dependent
  54. on config.h macros if necessary) instead.
  55. 6. Order of include headers
  56. In general, headers should be included in the order:
  57. 1. Core system headers (stdio.h, ctype.h, ...)
  58. 2. Headers for non-core system components (X11, libraries).
  59. 3. Headers for core systems of the package being compiled (grass/gis.h, grass/glocale.h, ...)
  60. 4. Headers for the specific library/program being compiled (geodesic.h, ...)
  61. Each class of header has an obligation to be compatible with those
  62. above it in the list, but not those below it.
  63. 7. Always specify the return type for ALL functions including those that
  64. return type "void", and insert return statements for any function
  65. which returns a value.
  66. Also, use ANSI C prototypes to declare your functions.
  67. For module return values, see "Exit status" below.
  68. Examples:
  69. void G_something(void);
  70. int G_something_else(int, int);
  71. void G_something(void)
  72. {
  73. /* Snipped out code */
  74. return;
  75. }
  76. int G_something_else(int x, int y)
  77. {
  78. /* Snipped out code */
  79. return 0;
  80. }
  81. 8. Module exit status is defined as EXIT_SUCCESS or EXIT_FAILURE
  82. (declared in stdlib.h), e.g.
  83. {
  84. ...
  85. if (G_parser (argc, argv))
  86. exit (EXIT_FAILURE);
  87. ...
  88. exit (EXIT_SUCCESS);
  89. }
  90. 9. Use fprintf() instead of printf()
  91. For errors and warnings please use the G_fatal_error() and
  92. G_warning() functions. General messages for the user should use
  93. G_message() while debug messages should use G_debug() whenever
  94. possible. There are two variants to G_message(): G_verbose_message()
  95. which will only display the message if in --verbose mode, and
  96. G_important_message() which will always show the message unless
  97. the module is running in --quiet mode. G_fatal_error() and
  98. G_warning() will always be displayed regardless of verbosity setting.
  99. Messages sent to any of these functions will be printed to stderr.
  100. G_message() output is not expected to be sent to pipe or file.
  101. Always use the gettext macros with _("") for user messages,
  102. example:
  103. G_fatal_error(_("Vector map <%s> not found"), name);
  104. It is suggested to add a comment line before translatable user message
  105. to give a hint to translators about meaning or use of
  106. cumbersome or obscure message. First word in the comment must be GTC
  107. - GRASS translation comment,
  108. example:
  109. /* GTC A name of a projection */
  110. G_message(_("State Plane"));
  111. See locale/README for details.
  112. Pipe/file data output:
  113. For data output redirected to pipe or file, please use fprintf() and
  114. specify the stdout stream as follows:
  115. fprintf(stdout, ...);
  116. fflush(stdout);
  117. fflush(stdout) always required when using fprintf(stdout, ...).
  118. 10. Use the GRASS library function G_asprintf() instead of the
  119. standard C functions asprintf(), vsnprintf() and snprintf(). These
  120. functions are not portable or have other issues. Example:
  121. char *msg;
  122. G_asprintf(&msg, "%s", parameters);
  123. do_something_with_msg();
  124. G_free(msg);
  125. Note that you should free memory when G_asprintf() is used.
  126. 11. Use the following GRASS library functions instead of the standard C
  127. functions. The reason for this is that the following functions ensure
  128. good programming practice (e.g. always checking if memory was allocated)
  129. and/or improves portability. PLEASE refer to the programmers manual
  130. for the proper use (e.g. determining if any casts are needed for arguments
  131. or return values) of these library functions. They may perform a task
  132. slightly different from their corresponding C library function, and thus,
  133. their use may not be the same.
  134. G_malloc() instead of malloc()
  135. G_calloc() instead of calloc()
  136. G_realloc() instead of realloc()
  137. G_free() instead of free()
  138. G_getenv() instead of getenv()
  139. G_setenv() instead of setenv()
  140. G_unsetenv() instead of unsetenv()
  141. G_sleep() instead of sleep()
  142. Could somebody please add others (please verify that they are
  143. useful and safe first)
  144. 12. Use function names which fulfill the official GNU naming convention.
  145. http://www.gnu.org/prep/standards/html_node/Names.html#Names
  146. Instead of naming a function like: MyNewFunction() use underscores
  147. for seperation and lower case letters: my_new_function().
  148. 13. Don't use the C++ comment style! This confuses several compilers.
  149. Use instead:
  150. /* C-comments */
  151. If you want to comment code portions, use
  152. #ifdef notdef
  153. portion_to_be_commented;
  154. #endif
  155. This is safe comparing to nested /* comments */
  156. Functions in the library must be documented in doxygen style to
  157. get them into the programmer's manual (generate with
  158. make pdfdocs or
  159. make htmldocs
  160. ). See lib/gis/*.c for examples.
  161. 14. PLEASE take the time to add comments throughout your code explaining what
  162. the code is doing. It will save a HUGE amount of time and frustration for
  163. other programmers that may have to change your code in the future.
  164. 15. To promote a consistent coding style, please use the "indent" program
  165. on all new C modules using the following switches:
  166. $ indent -bad -bap -bbb -br -bli0 -bls -cli0 -ncs -fc1 -hnl -i4 \
  167. -nbbo -nbc -nbfda -nbfde -ncdb -ncdw -nce -nfca -npcs -nprs \
  168. -npsl -nsc -nsob -saf -sai -saw -sbi0 -ss -ts8 -ut main.c
  169. Existing code should not be re-indented except in extreme cases, as this
  170. will make "diff" comparisons with older versions impossible. If indent is
  171. needed, do not check in any changes other than the indentation in the same
  172. commit! Do add the indent switches and any indent warning messages to the
  173. SVN log. Any change or fix mixed in with an indent is very hard to track
  174. making it hard for others to follow the change or fix any new bugs.
  175. For your convenience use the tools/grass_indent.sh script.
  176. 16. Platform dependent code:
  177. Do not remove #ifdef __CYGWIN__ and/or #ifndef __CYGWIN__ lines and
  178. their encapsulated lines from source code (one example was that someone
  179. removed drand48 definition.)
  180. 17. Suggested compiler flags:
  181. We suggest to use very strict compiler flags to capture errors
  182. at the very beginning. Here our list of flags, please use them
  183. to configure you development version of GRASS:
  184. GNU/Linux:
  185. MYCFLAGS="-g -Wall -Werror-implicit-function-declaration -fno-common"
  186. MYCXXFLAGS="-g -Wall"
  187. CFLAGS="$MYCFLAGS" CXXFLAGS="$MYCXXFLAGS" ./configure ...
  188. MacOSX: [to be suggested]
  189. MS-Windows: [to be suggested]
  190. 18. Make sure a new line is at the end of each file and UNIX style newlines
  191. are used (\n).
  192. 19. When writing Makefiles, use the current standard.
  193. If you have to use commands, please check for:
  194. avoid | use instead
  195. ------------------+---------------
  196. make target | $(MAKE) target
  197. mkdir target | $(MKDIR) target
  198. cp (executable) | $(INSTALL) -m 755 file target
  199. cp (normal file) | $(INSTALL) -m 644 file target
  200. ar | $(AR)
  201. rm: be VERY careful with recursive remove. Also beware of
  202. removing $(FOO)* if $(FOO) has any chance of being empty.
  203. Examples: see below examples or others
  204. raster/r.info/Makefile
  205. vector/v.edit/Makefile
  206. If you are unsure, please ask on the GRASS Developers list.
  207. 20. Have a look at ./INSTALL
  208. 21. Have a function included in your module which writes to the history
  209. file of the map (e.g. command line, parameters etc.). See e.g.
  210. raster/r.patch/main.c
  211. (the same applies to vector and g3d modules!)
  212. 22. Standard parser options: use G_define_standard_option() whenever possible
  213. to define standard module command line options. This will save you time,
  214. create fewer bugs, and make things easier on the translators.
  215. See lib/gis/parser.c for details of the function definition.
  216. 23. Add/update, if required the related GUI menus:
  217. gui/wxpython/xml/menudata.xml
  218. 24. For consistency, use README rather than README.txt for any README files.
  219. 25. GRASS/Environment variables:
  220. If you add a new variable, please follow the naming convention.
  221. All variables are described in
  222. lib/init/variables.html
  223. 26. Be sure to develop on top of the LATEST GRASS code (which is in our SVN
  224. repository). You can re-check before submission with 'svn diff':
  225. Be sure to create unified ("diff -u") format. "Plain" diffs (the default
  226. format) are risky, because they will apply without warning to code which
  227. has been substantially changed; they are also harder to read than unified.
  228. Such diffs should be made from the top-level directory, e.g.
  229. "svn diff display/d.vect/main.c"; that way, the diff will
  230. include the pathname rather than just an ambiguous "main.c".
  231. 27. Try to use module names which describe shortly the intended purpose of the module.
  232. The first letters for module name should be:
  233. d. - display commands
  234. db. - database commands
  235. g. - general GIS management commands
  236. i. - imagery commands
  237. m. - miscellaneous tool commands
  238. ps. - postscript commands
  239. r. - raster commands
  240. r3. - raster3D commands
  241. v. - vector commands
  242. Some additional naming conventions
  243. * export modules: (type).out.(format) eg: r.out.arc, v.out.ascii
  244. * import module: (type).in.(format) eg: r.in.arc, v.in.ascii
  245. * conversion modules: (type).to.(type) eg: r.to.vect, v.to.rast, r3.to.rast
  246. Avoid module names with more than two dots in the name.
  247. Example:
  248. instead of r.to.rast3.elev use r.to.rast3elev
  249. 28. Use the grass test suite to test your modules.
  250. http://www-pool.math.tu-berlin.de/~soeren/grass/GRASS_TestSuite
  251. You can easily write specific tests for your modules.
  252. If your module is part of GRASS and you created some standard test
  253. cases, please contact the developers to add your tests to the
  254. default test suite. This will automatize complex test scenarios
  255. and assure to find bugs much faster, if changes were made to your
  256. modules or to the grass library.
  257. Consider to subscribe to the GRASS Quality Assessment System to
  258. get immediate notification about the code quality:
  259. http://lists.osgeo.org/mailman/listinfo/grass-qa
  260. 29. When submitting new files to the repository set SVN properties,
  261. usually for directory
  262. svn:ignore : *.tmp.html
  263. *OBJ*
  264. or e.g. for C-file
  265. svn:mime-type : text/x-csrc
  266. svn:keywords : Author Date Id
  267. svn:eol-style : native
  268. See
  269. http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
  270. To set a property:
  271. svn propset svn:keywords 'Author Date Id' <file>
  272. svn propset svn:mime-type text/x-sh grass_shellscript.sh
  273. To edit the svn:ignore property using your default text editor:
  274. svn propedit svn:ignore <directory>
  275. To set the svn:ignore property non-interactively, first create a
  276. file containing the value:
  277. echo "*.tmp.html" > ignore.txt
  278. echo "*OBJ*" >> ignore.txt
  279. then use:
  280. svn propset -F ignore.txt svn:ignore <directory>
  281. List of mime-type:
  282. C++ files (.cpp): text/x-c++src
  283. C files (.c): text/x-csrc
  284. DTD files (.dtd): text/xml-dtd
  285. GIF files (.gif): image/gif
  286. Header files (.h): text/x-chdr
  287. HTML files (.html): text/html
  288. JPEG files (.jpg): image/jpeg
  289. Makefiles: text/x-makefile
  290. PNG files (.png): image/png
  291. Python files (.py): text/x-python
  292. Shell scripts (.sh): text/x-sh
  293. Text files (.txt): text/plain
  294. XML files (.xml): text/xml
  295. (please update the list...)
  296. For your convenience use the tools/module_svn_propset.sh script.
  297. 30. Use doxygen style for source code documentation. It is required
  298. for GRASS libraries, but also recommended for GRASS modules.
  299. Do not use structural command inside documentation block since it
  300. leads to some duplication of information (e.g. do not use \fn
  301. command in comment blocks). The exception is \file command for
  302. documenting a file, in this case structural command is required.
  303. For files
  304. /*!
  305. \file snap.c
  306. \brief Vector library - Clean vector map (snap lines)
  307. (C) 2001-2008 by the GRASS Development Team
  308. This program is free software under the GNU General Public
  309. License (>=v2). Read the file COPYING that comes with GRASS
  310. for details.
  311. \author Radim Blazek
  312. */
  313. For functions
  314. /*!
  315. \brief Snap lines in vector map to existing vertex in threshold
  316. For details see Vect_snap_lines_list()
  317. \param Map pointer to input vector map
  318. \param type filter features of given type to be snap
  319. \param thresh threshold value for snapping
  320. \param[out] Err pointer to vector map where lines representing snap are written or NULL
  321. \param[out] msgout file pointer where messages will be written or NULL
  322. \return 1
  323. */
  324. 31. If you need to add support for a different library in the 'configure' script,
  325. you should first seek consent in the grass-dev mailing list (see below), then
  326. you need to expand 'configure.in' and run subsequently autoconf-2.13 (later
  327. versions will not work) to re-generate 'configure'.
  328. 32. Tell the other developers about the new code using the following e-mail:
  329. grass-dev@lists.osgeo.org
  330. To subscribe to this mailing list, see
  331. http://lists.osgeo.org/mailman/listinfo/grass-dev
  332. 33. In case of questions feel free to contact the developers at the above
  333. mailing list.
  334. http://grass.osgeo.org/devel/index.php#submission
  335. ...
  336. [please add further hints if required]
  337. "Your attention to detail is appreciated."