HACKING
上传用户:zhongxx05
上传日期:2007-06-06
资源大小:33641k
文件大小:13k
- How to write code for CVS
- * Source
- Patches against the development version of CVS are most likely to be accepted:
- $ cvs -d:pserver:anoncvs@cvs.cvshome.org/cvsroot co ccvs
- * Compiler options
- If you are using GCC, you'll want to configure with -Wall, which can
- detect many programming errors. This is not the default because it
- might cause spurious warnings, but at least on some machines, there
- should be no spurious warnings. For example:
- $ CFLAGS="-g -Wall" ./configure
- Configure is not very good at remembering this setting; it will get
- wiped out whenever you do a ./config.status --recheck, so you'll need
- to use:
- $ CFLAGS="-g -Wall" ./config.status --recheck
- * Indentation style
- CVS mostly uses a consistent indentation style which looks like this:
- void
- foo (char *arg, int c)
- {
- long aflag;
- if (arg != NULL)
- {
- bar (arg);
- baz (arg);
- }
- switch (c)
- {
- case 'A':
- aflag = 1;
- break;
- }
- printf ("Literal string line 1n"
- "Literal string line 2n"
- "Literal string line 3n");
- }
- The file cvs-format.el contains settings for emacs and the NEWS file
- contains a set of options for the indent program which I haven't tried
- but which are correct as far as I know. You will find some code which
- does not conform to this indentation style; the plan is to reindent it
- as those sections of the code are changed (one function at a time,
- perhaps).
- In a submitted patch it is acceptable to refrain from changing the
- indentation of large blocks of code to minimize the size of the patch;
- the person checking in such a patch should reindent it.
- * Portability
- The general rule for portability is that it is only worth including
- portability cruft for systems on which people are actually testing and
- using new CVS releases. Without testing, CVS will fail to be portable
- for any number of unanticipated reasons.
- CVS is now assuming a freestanding C89 compiler. If you don't have one, you
- should find an old release of GCC that did not require a freestanding C89
- compiler to build, build that on your system, build a newer release of GCC
- if you wish, then build CVS using GCC as your freestanding C89 compiler.
- A freestanding C89 compiler is guaranteed to support function prototypes,
- void *, and assert().
- The following headers can be assumed and are included from lib/system.h for a
- freestanding C89 implementation: <float.h>, <limits.h>, <stdarg.h>, <stddef.h>.
- We are not assuming the other standard headers listed by C89 (hosted headers)
- because these four headers are the only headers guaranteed to be shipped with
- a C89 compiler (frestanding compiler). We are not currently assuming that the
- system the compiler is running on provides the rest of the C89 headers.
- The following C89 hosted headers can be assumed due to their presence in UNIX
- version 7 and are included from lib/system.h: <assert.h>, <ctype.h>, <errno.h>,
- <math.h>, <setjmp.h>, <signal.h>, <stdio.h>. <time.h> can also be assumed but
- is included via lib/xtime.h via lib/system.h to include some Autoconf magic
- which avoids including <time.h> and <sys/time.h> on systems that can't handle
- both.
- The following C89 headers are also assumed since we believe GCC includes them
- even on systems where it is installed as a freestanding compiler when the
- system lacks them, despite their not being required: <stdlib.h>, <string.h>.
- When the system does not lack these headers, they can sometimes not be
- standards compatible, but GCC provides a script, `fixincludes', for the purpose
- of fixing ANSI conformance problems and we think we can rely on asking users to
- either use GCC or run this script to fix conformance problems manually. A
- GNULIB developer has made a statement that if this turns out to be a problem,
- GNULIB <stdlib.h> and <string.h> substitutes could be included in GNULIB, so if
- we discover the problem, this should be discussed on <bug-gnulib@gnu.org>.
- A substitute C99 <stdbool.h> is included from GNULIB for platforms that lack
- this header. Please see the comments in the lib/stdbool_.h file for its
- limitations.
- <sys/types.h> can be assumed despite a lack of a presence in even C99, since
- it has been around nearly forever and noone has ever complained about our code
- assuming its existance.
- CVS has also been assuming <pwd.h> for some time. I am unsure of the
- rationale.
- A substitute POSIX.2 <fnmatch.h> header and fnmatch() function is provided for
- systems that lack them. Similarly for the non-standard <alloca.h> header and
- alloca() function. Other substitute headers and functions are also provided
- when needed. See the lib directory or the srclist.txt file for more
- information.
- Please do not use multi-line strings. Despite their common acceptance by many
- compilers, they are not part of the ANSI C specification. As of GCC version
- 3.3, they are no longer supported. See the Indentation Style section above for
- an example of a literal string which is not multi-line but which will print
- multiple lines.
- * Other style issues
- When composing header files, do not declare function prototypes using the
- `extern' storage-class identifier. Under C89, there is no functional
- difference between a function declaration with and without `extern', unless the
- function is declared `static'. This is NOT the case for global variables.
- Global variables declared in header files MUST be declared `extern'. For
- example:
- /* Global variables */
- extern int foo;
- extern char *bar;
- /* Function declarations */
- int make_foo(void);
- char *make_bar(int _foobar);
- * Run-time behaviors
- Use assert() to check "can't happen" conditions internal to CVS. We
- realize that there are functions in CVS which instead return NULL or
- some such value (thus confusing the meaning of such a returned value),
- but we want to fix that code. Of course, bad input data, a corrupt
- repository, bad options, etc., should always print a real error
- message instead.
- Do not use arbitrary limits (such as PATH_MAX) except perhaps when the
- operating system or some external interface requires it. We spent a
- lot of time getting rid of them, and we don't want to put them back.
- If you find any that we missed, please report it as with other bugs.
- In most cases such code will create security holes (for example, for
- anonymous readonly access via the CVS protocol, or if a WWW cgi script
- passes client-supplied arguments to CVS).
- Although this is a long-term goal, it also would be nice to move CVS
- in the direction of reentrancy. This reduces the size of the data
- segment and will allow a multi-threaded server if that is desirable.
- It is also useful to write the code so that it can be easily be made
- reentrant later. For example, if you need to pass data to some functions,
- you need a static variable, but use a single pointer so that when the function
- is fixed to pass along the argument, then the code can easily use that
- argument.
- * Coding standards in general
- Generally speaking the GNU coding standards are mostly used by CVS
- (but see the exceptions mentioned above, such as indentation style,
- and perhaps an exception or two we haven't mentioned). This is the
- file standards.text at the GNU FTP sites.
- Filenames for .c and .h files may contain _ but should not contain -
- (the latter causes Visual C++ 2.1 to create makefiles which Visual C++
- 4.0 cannot use).
- * Regenerating Build Files (UNIX)
- On UNIX, if you wish to change the Build files, you will need Autoconf and
- Automake.
- Some combinations of Automake and Autoconf versions may break the
- CVS build if file timestamps aren't set correctly and people don't
- have the same versions the developers do, so the rules to run them
- automatically aren't included in the generated Makefiles unless you run
- configure with --enable-maintainer-mode.
- The CVS Makefiles and configure script were built using Automake 1.7.9 and
- Autoconf 2.58, respectively.
- There is a known bug in Autoconf 2.57 that will prevent the configure
- scripts it generates from working on some platforms. Other combinations of
- autotool versions may or may not work. If you get other versions to work,
- please send a report to <bug-cvs@gnu.org>.
- * Regenerating Build Files (Windows)
- If for some reason you end up regenerating the *.mak files to submit a patch,
- please run windows-NT/fix-msvc-mak.pl to remove the absolute paths from the
- generated *.mak files before generating any patches.
- * Writing patches (strategy)
- Only some kinds of changes are suitable for inclusion in the
- "official" CVS. Bugfixes, where CVS's behavior contradicts the
- documentation and/or expectations that everyone agrees on, should be
- OK (strategically). For features, the desirable attributes are that
- the need is clear and that they fit nicely into the architecture of
- CVS. Is it worth the cost (in terms of complexity or any other
- tradeoffs involved)? Are there better solutions?
- If the design is not yet clear (which is true of most features), then
- the design is likely to benefit from more work and community input.
- Make a list of issues, or write documentation including rationales for
- how one would use the feature. Discuss it with coworkers, a
- newsgroup, or a mailing list, and see what other people think.
- Distribute some experimental patches and see what people think. The
- intention is arrive at some kind of rough community consensus before
- changing the "official" CVS. Features like zlib, encryption, and
- the RCS library have benefitted from this process in the past.
- If longstanding CVS behavior, that people may be relying on, is
- clearly deficient, it can be changed, but only slowly and carefully.
- For example, the global -q option was introduced in CVS 1.3 but the
- command -q options, which the global -q replaced, were not removed
- until CVS 1.6.
- * Writing patches (tactics)
- When you first distribute a patch it may be suitable to just put forth
- a rough patch, or even just an idea. But before the end of the
- process the following should exist:
- - ChangeLog entry (see the GNU coding standards for details).
- - Changes to the NEWS file and cvs.texinfo, if the change is a
- user-visible change worth mentioning.
- - Somewhere, a description of what the patch fixes (often in
- comments in the code, or maybe the ChangeLog or documentation).
- - Most of the time, a test case (see TESTS). It can be quite
- frustrating to fix a bug only to see it reappear later, and adding
- the case to the testsuite, where feasible, solves this and other
- problems. See the TESTS file for notes on writing new tests.
- If you solve several unrelated problems, it is generally easier to
- consider the desirability of the changes if there is a separate patch
- for each issue. Use context diffs or unidiffs for patches.
- Include words like "I grant permission to distribute this patch under
- the terms of the GNU Public License" with your patch. By sending a
- patch to bug-cvs@gnu.org, you implicitly grant this permission.
- Submitting a patch to bug-cvs is the way to reach the people who have
- signed up to receive such submissions (including CVS developers), but
- there may or may not be much (or any) response. If you want to pursue
- the matter further, you are probably best off working with the larger
- CVS community. Distribute your patch as widely as desired (mailing
- lists, newsgroups, web sites, whatever). Write a web page or other
- information describing what the patch is for. It is neither practical
- nor desirable for all/most contributions to be distributed through the
- "official" (whatever that means) mechanisms of CVS releases and CVS
- developers. Now, the "official" mechanisms do try to incorporate
- those patches which seem most suitable for widespread usage, together
- with test cases and documentation. So if a patch becomes sufficiently
- popular in the CVS community, it is likely that one of the CVS
- developers will eventually try to do something with it. But dealing
- with the CVS developers may be the last step of the process rather
- than the first.
- * What is the schedule for the next release?
- There isn't one. That is, upcoming releases are not announced (or
- even hinted at, really) until the feature freeze which is
- approximately 2 weeks before the final release (at this time test
- releases start appearing and are announced on info-cvs). This is
- intentional, to avoid a last minute rush to get new features in.
- * Mailing lists
- Anyone can add themselves to the following mailing lists:
- dev. Unless you are accepted as a CVS developer as
- described in the DEVEL-CVS file, you will only be able to
- read this list, not send to it. The charter of the list is
- also in DEVEL-CVS.
- cvs. The only messages sent to this list are sent
- automatically, via the CVS `loginfo' mechanism, when someone
- checks something in to the master CVS repository.
- test-results. The only messages sent to this list are sent
- automatically, daily, by a script which runs "make check"
- and "make remotecheck" on the master CVS sources.
- To subscribe to dev, cvs, or test-results, send
- a message to "<list>-subscribe@ccvs.cvshome.org" or visit
- http://ccvs.cvshome.org/servlets/ProjectMailingListList and follow the
- instructions there.
- One other list related to CVS development is bug-cvs. This is the
- list which users are requested to send bug reports to. Anyone can
- subscribe; to do so send mail to bug-cvs-request@gnu.org.
- Other CVS discussions take place on the info-cvs mailing list
- (send mail to info-cvs-request@gnu.org to subscribe) or on
- the newsgroup comp.software.config-mgmt.