HACKING

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