HACKING
上传用户:zhongxx05
上传日期:2007-06-06
资源大小:33641k
文件大小:13k
源码类别:

Symbian

开发平台:

C/C++

  1. How to write code for CVS
  2. * Source
  3. Patches against the development version of CVS are most likely to be accepted:
  4. $ cvs -d:pserver:anoncvs@cvs.cvshome.org/cvsroot co ccvs
  5. * Compiler options
  6. If you are using GCC, you'll want to configure with -Wall, which can
  7. detect many programming errors.  This is not the default because it
  8. might cause spurious warnings, but at least on some machines, there
  9. should be no spurious warnings.  For example:
  10. $ CFLAGS="-g -Wall" ./configure
  11. Configure is not very good at remembering this setting; it will get
  12. wiped out whenever you do a ./config.status --recheck, so you'll need
  13. to use:
  14. $ CFLAGS="-g -Wall" ./config.status --recheck
  15. * Indentation style
  16. CVS mostly uses a consistent indentation style which looks like this:
  17. void
  18. foo (char *arg, int c)
  19. {
  20.     long aflag;
  21.     if (arg != NULL)
  22.     {
  23. bar (arg);
  24. baz (arg);
  25.     }
  26.     switch (c)
  27.     {
  28. case 'A':
  29.     aflag = 1;
  30.     break;
  31.     }
  32.     printf ("Literal string line 1n"
  33.     "Literal string line 2n"
  34.     "Literal string line 3n");
  35. }
  36. The file cvs-format.el contains settings for emacs and the NEWS file
  37. contains a set of options for the indent program which I haven't tried
  38. but which are correct as far as I know.  You will find some code which
  39. does not conform to this indentation style; the plan is to reindent it
  40. as those sections of the code are changed (one function at a time,
  41. perhaps).
  42. In a submitted patch it is acceptable to refrain from changing the
  43. indentation of large blocks of code to minimize the size of the patch;
  44. the person checking in such a patch should reindent it.
  45. * Portability
  46. The general rule for portability is that it is only worth including
  47. portability cruft for systems on which people are actually testing and
  48. using new CVS releases.  Without testing, CVS will fail to be portable
  49. for any number of unanticipated reasons.
  50. CVS is now assuming a freestanding C89 compiler.  If you don't have one, you
  51. should find an old release of GCC that did not require a freestanding C89
  52. compiler to build, build that on your system, build a newer release of GCC
  53. if you wish, then build CVS using GCC as your freestanding C89 compiler.
  54. A freestanding C89 compiler is guaranteed to support function prototypes,
  55. void *, and assert().
  56. The following headers can be assumed and are included from lib/system.h for a
  57. freestanding C89 implementation: <float.h>, <limits.h>, <stdarg.h>, <stddef.h>.
  58. We are not assuming the other standard headers listed by C89 (hosted headers)
  59. because these four headers are the only headers guaranteed to be shipped with
  60. a C89 compiler (frestanding compiler).  We are not currently assuming that the
  61. system the compiler is running on provides the rest of the C89 headers.
  62. The following C89 hosted headers can be assumed due to their presence in UNIX
  63. version 7 and are included from lib/system.h: <assert.h>, <ctype.h>, <errno.h>,
  64. <math.h>, <setjmp.h>, <signal.h>, <stdio.h>.  <time.h> can also be assumed but
  65. is included via lib/xtime.h via lib/system.h to include some Autoconf magic
  66. which avoids including <time.h> and <sys/time.h> on systems that can't handle
  67. both.
  68. The following C89 headers are also assumed since we believe GCC includes them
  69. even on systems where it is installed as a freestanding compiler when the
  70. system lacks them, despite their not being required: <stdlib.h>, <string.h>.
  71. When the system does not lack these headers, they can sometimes not be
  72. standards compatible, but GCC provides a script, `fixincludes', for the purpose
  73. of fixing ANSI conformance problems and we think we can rely on asking users to
  74. either use GCC or run this script to fix conformance problems manually.  A
  75. GNULIB developer has made a statement that if this turns out to be a problem,
  76. GNULIB <stdlib.h> and <string.h> substitutes could be included in GNULIB, so if
  77. we discover the problem, this should be discussed on <bug-gnulib@gnu.org>.
  78. A substitute C99 <stdbool.h> is included from GNULIB for platforms that lack
  79. this header.  Please see the comments in the lib/stdbool_.h file for its
  80. limitations.
  81. <sys/types.h> can be assumed despite a lack of a presence in even C99, since
  82. it has been around nearly forever and noone has ever complained about our code
  83. assuming its existance.
  84. CVS has also been assuming <pwd.h> for some time.  I am unsure of the
  85. rationale.
  86. A substitute POSIX.2 <fnmatch.h> header and fnmatch() function is provided for
  87. systems that lack them.  Similarly for the non-standard <alloca.h> header and
  88. alloca() function.  Other substitute headers and functions are also provided
  89. when needed.  See the lib directory or the srclist.txt file for more
  90. information.
  91. Please do not use multi-line strings.  Despite their common acceptance by many
  92. compilers, they are not part of the ANSI C specification.  As of GCC version
  93. 3.3, they are no longer supported.  See the Indentation Style section above for
  94. an example of a literal string which is not multi-line but which will print
  95. multiple lines.
  96. * Other style issues
  97. When composing header files, do not declare function prototypes using the
  98. `extern' storage-class identifier.  Under C89, there is no functional
  99. difference between a function declaration with and without `extern', unless the 
  100. function is declared `static'.  This is NOT the case for global variables.
  101. Global variables declared in header files MUST be declared `extern'.  For
  102. example:
  103. /* Global variables */
  104. extern int foo;
  105. extern char *bar;
  106. /* Function declarations */
  107. int make_foo(void);
  108. char *make_bar(int _foobar);
  109. * Run-time behaviors
  110. Use assert() to check "can't happen" conditions internal to CVS.  We
  111. realize that there are functions in CVS which instead return NULL or
  112. some such value (thus confusing the meaning of such a returned value),
  113. but we want to fix that code.  Of course, bad input data, a corrupt
  114. repository, bad options, etc., should always print a real error
  115. message instead.
  116. Do not use arbitrary limits (such as PATH_MAX) except perhaps when the
  117. operating system or some external interface requires it.  We spent a
  118. lot of time getting rid of them, and we don't want to put them back.
  119. If you find any that we missed, please report it as with other bugs.
  120. In most cases such code will create security holes (for example, for
  121. anonymous readonly access via the CVS protocol, or if a WWW cgi script
  122. passes client-supplied arguments to CVS).
  123. Although this is a long-term goal, it also would be nice to move CVS
  124. in the direction of reentrancy.  This reduces the size of the data
  125. segment and will allow a multi-threaded server if that is desirable.
  126. It is also useful to write the code so that it can be easily be made
  127. reentrant later.  For example, if you need to pass data to some functions,
  128. you need a static variable, but use a single pointer so that when the function
  129. is fixed to pass along the argument, then the code can easily use that
  130. argument.
  131. * Coding standards in general
  132. Generally speaking the GNU coding standards are mostly used by CVS
  133. (but see the exceptions mentioned above, such as indentation style,
  134. and perhaps an exception or two we haven't mentioned).  This is the
  135. file standards.text at the GNU FTP sites.
  136. Filenames for .c and .h files may contain _ but should not contain -
  137. (the latter causes Visual C++ 2.1 to create makefiles which Visual C++
  138. 4.0 cannot use).
  139. * Regenerating Build Files (UNIX)
  140. On UNIX, if you wish to change the Build files, you will need Autoconf and
  141. Automake.
  142. Some combinations of Automake and Autoconf versions may break the
  143. CVS build if file timestamps aren't set correctly and people don't
  144. have the same versions the developers do, so the rules to run them
  145. automatically aren't included in the generated Makefiles unless you run
  146. configure with --enable-maintainer-mode.
  147. The CVS Makefiles and configure script were built using Automake 1.7.9 and
  148. Autoconf 2.58, respectively.
  149. There is a known bug in Autoconf 2.57 that will prevent the configure
  150. scripts it generates from working on some platforms.  Other combinations of
  151. autotool versions may or may not work.  If you get other versions to work,
  152. please send a report to <bug-cvs@gnu.org>.
  153. * Regenerating Build Files (Windows)
  154. If for some reason you end up regenerating the *.mak files to submit a patch,
  155. please run windows-NT/fix-msvc-mak.pl to remove the absolute paths from the
  156. generated *.mak files before generating any patches.
  157. * Writing patches (strategy)
  158. Only some kinds of changes are suitable for inclusion in the
  159. "official" CVS.  Bugfixes, where CVS's behavior contradicts the
  160. documentation and/or expectations that everyone agrees on, should be
  161. OK (strategically).  For features, the desirable attributes are that
  162. the need is clear and that they fit nicely into the architecture of
  163. CVS.  Is it worth the cost (in terms of complexity or any other
  164. tradeoffs involved)?  Are there better solutions?
  165. If the design is not yet clear (which is true of most features), then
  166. the design is likely to benefit from more work and community input.
  167. Make a list of issues, or write documentation including rationales for
  168. how one would use the feature.  Discuss it with coworkers, a
  169. newsgroup, or a mailing list, and see what other people think.
  170. Distribute some experimental patches and see what people think.  The
  171. intention is arrive at some kind of rough community consensus before
  172. changing the "official" CVS.  Features like zlib, encryption, and
  173. the RCS library have benefitted from this process in the past.
  174. If longstanding CVS behavior, that people may be relying on, is
  175. clearly deficient, it can be changed, but only slowly and carefully.
  176. For example, the global -q option was introduced in CVS 1.3 but the
  177. command -q options, which the global -q replaced, were not removed
  178. until CVS 1.6.
  179. * Writing patches (tactics)
  180. When you first distribute a patch it may be suitable to just put forth
  181. a rough patch, or even just an idea.  But before the end of the
  182. process the following should exist:
  183.   - ChangeLog entry (see the GNU coding standards for details).
  184.   - Changes to the NEWS file and cvs.texinfo, if the change is a
  185.     user-visible change worth mentioning.
  186.   - Somewhere, a description of what the patch fixes (often in
  187.     comments in the code, or maybe the ChangeLog or documentation).
  188.   - Most of the time, a test case (see TESTS).  It can be quite
  189.     frustrating to fix a bug only to see it reappear later, and adding
  190.     the case to the testsuite, where feasible, solves this and other
  191.     problems.  See the TESTS file for notes on writing new tests.
  192. If you solve several unrelated problems, it is generally easier to
  193. consider the desirability of the changes if there is a separate patch
  194. for each issue.  Use context diffs or unidiffs for patches.
  195. Include words like "I grant permission to distribute this patch under
  196. the terms of the GNU Public License" with your patch.  By sending a
  197. patch to bug-cvs@gnu.org, you implicitly grant this permission.
  198. Submitting a patch to bug-cvs is the way to reach the people who have
  199. signed up to receive such submissions (including CVS developers), but
  200. there may or may not be much (or any) response.  If you want to pursue
  201. the matter further, you are probably best off working with the larger
  202. CVS community.  Distribute your patch as widely as desired (mailing
  203. lists, newsgroups, web sites, whatever).  Write a web page or other
  204. information describing what the patch is for.  It is neither practical
  205. nor desirable for all/most contributions to be distributed through the
  206. "official" (whatever that means) mechanisms of CVS releases and CVS
  207. developers.  Now, the "official" mechanisms do try to incorporate
  208. those patches which seem most suitable for widespread usage, together
  209. with test cases and documentation.  So if a patch becomes sufficiently
  210. popular in the CVS community, it is likely that one of the CVS
  211. developers will eventually try to do something with it.  But dealing
  212. with the CVS developers may be the last step of the process rather
  213. than the first.
  214. * What is the schedule for the next release?
  215. There isn't one.  That is, upcoming releases are not announced (or
  216. even hinted at, really) until the feature freeze which is
  217. approximately 2 weeks before the final release (at this time test
  218. releases start appearing and are announced on info-cvs).  This is
  219. intentional, to avoid a last minute rush to get new features in.
  220. * Mailing lists
  221. Anyone can add themselves to the following mailing lists:
  222.     dev.  Unless you are accepted as a CVS developer as
  223.       described in the DEVEL-CVS file, you will only be able to
  224.       read this list, not send to it.  The charter of the list is
  225.       also in DEVEL-CVS.
  226.     cvs.  The only messages sent to this list are sent
  227.       automatically, via the CVS `loginfo' mechanism, when someone
  228.       checks something in to the master CVS repository.
  229.     test-results.  The only messages sent to this list are sent
  230.       automatically, daily, by a script which runs "make check"
  231.       and "make remotecheck" on the master CVS sources.
  232. To subscribe to dev, cvs, or test-results, send
  233. a message to "<list>-subscribe@ccvs.cvshome.org" or visit
  234. http://ccvs.cvshome.org/servlets/ProjectMailingListList and follow the
  235. instructions there.
  236. One other list related to CVS development is bug-cvs.  This is the
  237. list which users are requested to send bug reports to.  Anyone can
  238. subscribe; to do so send mail to bug-cvs-request@gnu.org.
  239. Other CVS discussions take place on the info-cvs mailing list
  240. (send mail to info-cvs-request@gnu.org to subscribe) or on
  241. the newsgroup comp.software.config-mgmt.