mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-05-01 04:10:18 +02:00
144 lines
6.4 KiB
Text
144 lines
6.4 KiB
Text
Here are some guidelines for members of the Guile developers team.
|
|
|
|
CVS conventions ======================================================
|
|
|
|
- We use CVS to manage the Guile sources. The repository lives on
|
|
egcs.cygnus.com, in /egcs/carton/cvsfiles; you will need an account on
|
|
that machine to access the repository. Also, for security reasons,
|
|
egcs presently only supports CVS connections via the SSH protocol, so
|
|
you must first install the SSH client. Then, you should set your
|
|
CVS_RSH environment variable to ssh, and use the following as your CVS
|
|
root:
|
|
|
|
:ext:USER@egcs.cygnus.com:/egcs/carton/cvsfiles
|
|
|
|
Either set your CVSROOT environment variable to that, or give it as
|
|
the value of the global -d option to CVS when you check out a working
|
|
directory.
|
|
|
|
For more information on SSH, see http://www.cs.hut.fi/ssh.
|
|
|
|
The Guile sources live in several modules:
|
|
|
|
- guile-core --- the interpreter, QuickThreads, and ice-9
|
|
- guile-doc --- documentation in progress. When complete, this will
|
|
be incorporated into guile-core.
|
|
- guile-tcltk --- the Guile/Tk interface
|
|
- guile-tk --- the new Guile/Tk interface, based on STk's modified Tk
|
|
- guile-rgx-ctax --- the Guile/Rx interface, and the ctax implementation
|
|
- guile-scsh --- the port of SCSH to guile, talk to Gary Houston
|
|
- guile-comp --- the Hobbit compiler (talk to mdj)
|
|
- guile-emacs --- Guile/Emacs interface (talk to mdj)
|
|
- guile-oops --- The Guile Object-Oriented Programming System (talk to mdj)
|
|
- guile-www --- A Guile module for making HTTP requests.
|
|
|
|
- We check Makefile.in and configure files into CVS, as well as the
|
|
files they are built from (Makefile.am, configure.in); we do not check
|
|
in Makefiles or header files generated by configuration scripts. The
|
|
general rule is that you should be able to check out a working
|
|
directory of Guile from CVS, and then type "configure" and "make",
|
|
without running any other tools.
|
|
|
|
- Make sure your changes compile and work, at least on your own
|
|
machine, before checking them into the main branch of the Guile
|
|
repository. If you really need to check in untested changes, make a
|
|
branch.
|
|
|
|
- Include each log entry in both the ChangeLog and in the CVS logs.
|
|
If you're using Emacs, the pcl-cvs interface to CVS has features to
|
|
make this easier; it checks the ChangeLog, and generates good default
|
|
CVS log entries from that.
|
|
|
|
|
|
Coding standards =====================================================
|
|
|
|
- As for any part of Project GNU, changes to Guile should follow the
|
|
GNU coding standards. The standards are available via anonymous FTP
|
|
from prep.ai.mit.edu, as /pub/gnu/standards/standards.texi and
|
|
make-stds.texi.
|
|
|
|
- The Guile tree should compile without warnings under the following
|
|
GCC switches, which are the default in the current configure script:
|
|
-O2 -Wall -Wpointer-arith -Wmissing-prototypes
|
|
The only exceptions are the warnings about variables being clobbered
|
|
by longjmp/vfork in eval.c. (Tho' if you can figure out how to get
|
|
rid of those, too, I'd be happy.)
|
|
|
|
Note that the warnings generated vary from one version of GCC to the
|
|
next, and from one architecture to the next (apparently). To provide
|
|
a concrete common standard, Guile should compile without warnings from
|
|
GCC 2.7.2.3 in a Red Hat 5.0 i386 Linux machine. Furthermore, each
|
|
developer should pursue any additional warnings noted by on their
|
|
compiler. This means that people using more stringent compilers will
|
|
have more work to do, and assures that everyone won't switch to the
|
|
most lenient compiler they can find. :)
|
|
|
|
- When you make a user-visible change (i.e. one that should be
|
|
documented, and appear in NEWS, put an asterisk in column zero of the
|
|
start of the ChangeLog entry, like so:
|
|
|
|
Sat Aug 3 01:27:14 1996 Gary Houston <ghouston@actrix.gen.nz>
|
|
|
|
* * fports.c (scm_open_file): don't return #f, throw error.
|
|
|
|
When you've written a NEWS entry and updated the documentation, go
|
|
ahead and remove the asterisk. I will use the asterisks to find and
|
|
document changes that haven't been dealt with before a release.
|
|
|
|
- There's no need to keep a change log for documentation files. This
|
|
is because documentation is not susceptible to bugs that are hard to
|
|
fix. Documentation does not consist of parts that must interact in a
|
|
precisely engineered fashion; to correct an error, you need not know
|
|
the history of the erroneous passage. (This is copied from the GNU
|
|
coding standards.)
|
|
|
|
- Make sure you have papers from people before integrating their
|
|
changes or contributions. This is very frustrating, but very
|
|
important to do right. From maintain.texi, "Information for
|
|
Maintainers of GNU Software":
|
|
|
|
When incorporating changes from other people, make sure to follow the
|
|
correct procedures. Doing this ensures that the FSF has the legal
|
|
right to distribute and defend GNU software.
|
|
|
|
For the sake of registering the copyright on later versions ofthe
|
|
software you need to keep track of each person who makes significant
|
|
changes. A change of ten lines or so, or a few such changes, in a
|
|
large program is not significant.
|
|
|
|
*Before* incorporating significant changes, make sure that the person
|
|
has signed copyright papers, and that the Free Software Foundation has
|
|
received them.
|
|
|
|
If you receive contributions you want to use from someone, let me know
|
|
and I'll take care of the administrivia. Put the contributions aside
|
|
until we have the necessary papers.
|
|
|
|
- When you make substantial changes to a file, add the current year to
|
|
the list of years in the copyright notice at the top of the file.
|
|
|
|
|
|
Helpful hints ========================================================
|
|
|
|
- [From Mikael Djurfeldt] When working on the Guile internals, it is
|
|
quite often practical to implement a scheme-level procedure which
|
|
helps you examine the feature you're working on.
|
|
|
|
Examples of such procedures are: pt-size, debug-hand and
|
|
current-pstate.
|
|
|
|
I've now put #ifdef GUILE_DEBUG around all such procedures, so that
|
|
they are not compiled into the "normal" Guile library. Please do the
|
|
same when you add new procedures/C functions for debugging purpose.
|
|
|
|
You can define the GUILE_DEBUG flag by passing --enable-guile-debug to
|
|
the configure script.
|
|
|
|
- You'll see uses of the macro SCM_P scattered throughout the code;
|
|
those are vestiges of a time when Guile was meant to compile on
|
|
pre-ANSI compilers. Guile now requires ANSI C, so when you write new
|
|
functions, feel free to use ANSI declarations, and please provide
|
|
prototypes for everything. You don't need to use SCM_P in new code.
|
|
|
|
|
|
Jim Blandy
|