HACKING

   1 Here are some guidelines for members of the Guile developers team.
   2
   3 CVS conventions ======================================================
   4
   5 - We use CVS to manage the Guile sources.  The repository lives on
   6 egcs.cygnus.com, in /cvs/guile; you will need an
   7 account on that machine to access the repository.  Also, for security
   8 reasons, egcs presently only supports CVS connections via the SSH
   9 protocol, so you must first install the SSH client.  Then, you should
  10 set your CVS_RSH environment variable to ssh, and use the following as
  11 your CVS root:
  12
  13         :ext:USER@egcs.cygnus.com:/cvs/guile
  14
  15 Either set your CVSROOT environment variable to that, or give it as
  16 the value of the global -d option to CVS when you check out a working
  17 directory.
  18
  19 For more information on SSH, see http://www.cs.hut.fi/ssh.
  20
  21 The Guile sources live in several modules:
  22
  23   - guile-core --- the interpreter, QuickThreads, and ice-9
  24   - guile-doc --- documentation in progress.  When complete, this will
  25         be incorporated into guile-core.
  26   - guile-tcltk --- the Guile/Tk interface
  27   - guile-tk --- the new Guile/Tk interface, based on STk's modified Tk
  28   - guile-rgx-ctax --- the Guile/Rx interface, and the ctax implementation
  29   - guile-scsh --- the port of SCSH to guile, talk to Gary Houston
  30   - guile-comp --- the Hobbit compiler (talk to mdj)
  31   - guile-emacs --- Guile/Emacs interface (talk to mdj)
  32   - guile-oops --- The Guile Object-Oriented Programming System (talk to mdj)
  33   - guile-www --- A Guile module for making HTTP requests.
  34
  35 There is a mailing list for CVS commit messages; see README for details.
  36
  37
  38 - We check Makefile.in and configure files into CVS, as well as the
  39 files they are built from (Makefile.am, configure.in); we do not check
  40 in Makefiles or header files generated by configuration scripts.  The
  41 general rule is that you should be able to check out a working
  42 directory of Guile from CVS, and then type "configure" and "make",
  43 without running any other tools.
  44
  45 - Make sure your changes compile and work, at least on your own
  46 machine, before checking them into the main branch of the Guile
  47 repository.  If you really need to check in untested changes, make a
  48 branch.
  49
  50 - Include each log entry in both the ChangeLog and in the CVS logs.
  51 If you're using Emacs, the pcl-cvs interface to CVS has features to
  52 make this easier; it checks the ChangeLog, and generates good default
  53 CVS log entries from that.
  54
  55
  56 Coding standards =====================================================
  57
  58 - As for any part of Project GNU, changes to Guile should follow the
  59 GNU coding standards.  The standards are available via anonymous FTP
  60 from prep.ai.mit.edu, as /pub/gnu/standards/standards.texi and
  61 make-stds.texi.
  62
  63 - The Guile tree should compile without warnings under the following
  64 GCC switches, which are the default in the current configure script:
  65     -O2 -Wall -Wpointer-arith -Wmissing-prototypes
  66 The only exceptions are the warnings about variables being clobbered
  67 by longjmp/vfork in eval.c.  (Tho' if you can figure out how to get
  68 rid of those, too, I'd be happy.)
  69
  70 Note that the warnings generated vary from one version of GCC to the
  71 next, and from one architecture to the next (apparently).  To provide
  72 a concrete common standard, Guile should compile without warnings from
  73 GCC 2.7.2.3 in a Red Hat 5.0 i386 Linux machine.  Furthermore, each
  74 developer should pursue any additional warnings noted by on their
  75 compiler.  This means that people using more stringent compilers will
  76 have more work to do, and assures that everyone won't switch to the
  77 most lenient compiler they can find.  :)
  78
  79 Note also that EGCS (as of November 3 1998) doesn't handle the
  80 `noreturn' attribute properly, so it doesn't understand that functions
  81 like scm_error won't return.  This may lead to some silly warnings
  82 about uninitialized variables.  You should look into these warnings to
  83 make sure they are indeed spurious, but you needn't correct warnings
  84 caused by this EGCS bug.
  85
  86
  87 - When you make a user-visible change (i.e. one that should be
  88 documented, and appear in NEWS, put an asterisk in column zero of the
  89 start of the ChangeLog entry, like so:
  90
  91 Sat Aug  3 01:27:14 1996  Gary Houston  <ghouston@actrix.gen.nz>
  92
  93 *       * fports.c (scm_open_file): don't return #f, throw error.
  94
  95 When you've written a NEWS entry and updated the documentation, go
  96 ahead and remove the asterisk.  I will use the asterisks to find and
  97 document changes that haven't been dealt with before a release.
  98
  99 - Please write log entries for functions written in C under the
 100 functions' C names, and write log entries for functions written in
 101 Scheme under the functions' Scheme names.  Please don't do this:
 102
 103         * procs.c, procs.h (procedure-documentation): Moved from eval.c.
 104
 105 Entries like this make it harder to search the ChangeLogs, because you
 106 can never tell which name the entry will refer to.  Instead, write this:
 107
 108         * procs.c, procs.h (scm_procedure_documentation): Moved from eval.c.
 109
 110 Changes like adding this line are special:
 111
 112     SCM_PROC (s_serial_map, "serial-map", 2, 0, 1, scm_map);
 113
 114 Since the change here is about the name itself --- we're adding a new
 115 alias for scm_map that guarantees the order in which we process list
 116 elements, but we're not changing scm_map at all --- it's appropriate
 117 to use the Scheme name in the log entry.
 118
 119
 120 - There's no need to keep a change log for documentation files.  This
 121 is because documentation is not susceptible to bugs that are hard to
 122 fix.  Documentation does not consist of parts that must interact in a
 123 precisely engineered fashion; to correct an error, you need not know
 124 the history of the erroneous passage.  (This is copied from the GNU
 125 coding standards.)
 126
 127 - Make sure you have papers from people before integrating their
 128 changes or contributions.  This is very frustrating, but very
 129 important to do right.  From maintain.texi, "Information for
 130 Maintainers of GNU Software":
 131
 132     When incorporating changes from other people, make sure to follow the
 133     correct procedures.  Doing this ensures that the FSF has the legal
 134     right to distribute and defend GNU software.
 135
 136     For the sake of registering the copyright on later versions ofthe
 137     software you need to keep track of each person who makes significant
 138     changes.  A change of ten lines or so, or a few such changes, in a
 139     large program is not significant.
 140
 141     *Before* incorporating significant changes, make sure that the person
 142     has signed copyright papers, and that the Free Software Foundation has
 143     received them.
 144
 145 If you receive contributions you want to use from someone, let me know
 146 and I'll take care of the administrivia.  Put the contributions aside
 147 until we have the necessary papers.
 148
 149 - When you make substantial changes to a file, add the current year to
 150 the list of years in the copyright notice at the top of the file.
 151
 152
 153 Helpful hints ========================================================
 154
 155 - [From Mikael Djurfeldt] When working on the Guile internals, it is
 156 quite often practical to implement a scheme-level procedure which
 157 helps you examine the feature you're working on.
 158
 159 Examples of such procedures are: pt-size, debug-hand and
 160 current-pstate.
 161
 162 I've now put #ifdef GUILE_DEBUG around all such procedures, so that
 163 they are not compiled into the "normal" Guile library.  Please do the
 164 same when you add new procedures/C functions for debugging purpose.
 165
 166 You can define the GUILE_DEBUG flag by passing --enable-guile-debug to
 167 the configure script.
 168
 169 - You'll see uses of the macro SCM_P scattered throughout the code;
 170 those are vestiges of a time when Guile was meant to compile on
 171 pre-ANSI compilers.  Guile now requires ANSI C, so when you write new
 172 functions, feel free to use ANSI declarations, and please provide
 173 prototypes for everything.  You don't need to use SCM_P in new code.
 174
 175
 176 Jim Blandy