HACKING

   1 Hacking It Yourself ==================================================
   2
   3 As distributed, Guile needs only an ANSI C compiler and a Unix system
   4 to compile.  However, Guile's makefiles, configuration scripts, and a
   5 few other files are automatically generated, not written by hand.  If
   6 you want to make changes to the system (which we encourage!) you will
   7 find it helpful to have the tools we use to develop Guile.  They
   8 are the following:
   9
  10 Autoconf 2.13 --- a system for automatically generating `configure'
  11         scripts from templates which list the non-portable features a
  12         program would like to use.  Available in
  13         "ftp://ftp.gnu.org/pub/gnu/autoconf"
  14
  15 Automake 1.4 --- a system for automatically generating Makefiles that
  16         conform to the (rather Byzantine) GNU coding standards.  The
  17         nice thing is that it takes care of hairy targets like 'make
  18         dist' and 'make distclean', and automatically generates
  19         Makefile dependencies.  Automake is available in
  20         "ftp://ftp.gnu.org/pub/gnu/automake"
  21
  22         Before using automake, you may need to copy `threads.m4' and
  23         `guile.m4' from the top directory of the Guile core disty to
  24         `/usr/local/share/aclocal.
  25
  26 libtool 1.3.4 --- a system for managing the zillion hairy options needed
  27         on various systems to produce shared libraries.  Available in
  28         "ftp://ftp.gnu.org/pub/gnu/libtool"
  29
  30 You are lost in a little maze of automatically generated files, all
  31 different.
  32 >
  33
  34
  35 Contributing Your Changes ============================================
  36
  37 - If you have put together a change that meets the coding standards
  38 described below, we encourage you to submit it to Guile.  The best
  39 place to post it is guile@sourceware.cygnus.com.  Please don't send it
  40 directly to me; I often don't have time to look things over.  If you
  41 have tested your change, then you don't need to be shy.
  42
  43 - Please submit patches using either context or unified diffs (diff -c
  44 or diff -u).  Don't include a patch for ChangeLog; such patches don't
  45 apply cleanly, since we've probably changed the top of ChangeLog too.
  46 Instead, provide the unaltered text at the top of your patch.
  47
  48 Please don't include patches for generated files like configure,
  49 aclocal.m4, or any Makefile.in.  Such patches are often large, and
  50 we're just going to regenerate those files anyway.
  51
  52
  53 CVS conventions ======================================================
  54
  55 - We use CVS to manage the Guile sources.  The repository lives on
  56 egcs.cygnus.com, in /cvs/guile; you will need an
  57 account on that machine to access the repository.  Also, for security
  58 reasons, egcs presently only supports CVS connections via the SSH
  59 protocol, so you must first install the SSH client.  Then, you should
  60 set your CVS_RSH environment variable to ssh, and use the following as
  61 your CVS root:
  62
  63         :ext:USER@egcs.cygnus.com:/cvs/guile
  64
  65 Either set your CVSROOT environment variable to that, or give it as
  66 the value of the global -d option to CVS when you check out a working
  67 directory.
  68
  69 For more information on SSH, see http://www.cs.hut.fi/ssh.
  70
  71 The Guile sources live in several modules:
  72
  73   - guile-core --- the interpreter, QuickThreads, and ice-9
  74   - guile-doc --- documentation in progress.  When complete, this will
  75         be incorporated into guile-core.
  76   - guile-oops --- The Guile Object-Oriented Programming System (talk to mdj)
  77   - guile-tcltk --- the Guile/Tk interface
  78   - guile-tk --- the new Guile/Tk interface, based on STk's modified Tk
  79   - guile-rgx-ctax --- the Guile/Rx interface, and the ctax implementation
  80   - guile-scsh --- the port of SCSH to guile, talk to Gary Houston
  81   - guile-www --- A Guile module for making HTTP requests.
  82
  83 There is a mailing list for CVS commit messages; see README for details.
  84
  85 - We check Makefile.am and configure.in files into CVS, but the
  86 "autogen.sh" script must be run from the top-level to generate the
  87 actual "configure" script that then must be run to create the various
  88 Makefile-s to build guile. The general rule is that you should be able
  89 to check out a working directory of Guile from CVS, and then type
  90 "./autogen.sh", then "configure", and finally "make".  No
  91 automatically generated files should be checked into the CVS
  92 repository.
  93
  94 - The .cvsignore file is contained in the repository, to provide a
  95 reasonable list of auto-generated files that should not be checked in.
  96 This, however, prohibits one from having local additions to the
  97 .cvsignore file (yes, you can modify it and never check it in, but
  98 that doesn't seem to be a good solution to me).  To get around this
  99 problem, you might want to patch your cvs program so that it uses a
 100 .cvsignore-local file (say) instead of the one from the repository.  A
 101 patch for this can be found at the very end of this file.
 102
 103 - (Automake 1.4 only) Be sure to run automake at the top of the tree
 104 with no arguments.  Do not use `automake Makefile' to regenerate
 105 specific Makefile.in files, and do not trust the Makefile rules to
 106 rebuild them when they are out of date.  Automake 1.4 will add
 107 extraneous rules to the top-level Makefile if you specify specific
 108 Makefiles to rebuild on the command line.  Running the command
 109 `autoreconf --force' should take care of everything correctly.
 110
 111 - Make sure your changes compile and work, at least on your own
 112 machine, before checking them into the main branch of the Guile
 113 repository.  If you really need to check in untested changes, make a
 114 branch.
 115
 116 - Include each log entry in both the ChangeLog and in the CVS logs.
 117 If you're using Emacs, the pcl-cvs interface to CVS has features to
 118 make this easier; it checks the ChangeLog, and generates good default
 119 CVS log entries from that.
 120
 121
 122 Coding standards =====================================================
 123
 124 - As for any part of Project GNU, changes to Guile should follow the
 125 GNU coding standards.  The standards are available via anonymous FTP
 126 from prep.ai.mit.edu, as /pub/gnu/standards/standards.texi and
 127 make-stds.texi.
 128
 129 - The Guile tree should compile without warnings under the following
 130 GCC switches, which are the default in the current configure script:
 131     -O2 -Wall -Wpointer-arith -Wmissing-prototypes
 132 The only warnings which can be tolerated are those about variables
 133 being clobbered by longjmp/vfork in eval.c.  The variables in question
 134 are critical to the interpreter's performance; as far as I can tell,
 135 it is difficult/annoying to avoid these warnings without slowing the
 136 system down substantially.  (If you can figure out a good fix, I'd be happy to see it.)
 137
 138 Note that the warnings generated vary from one version of GCC to the
 139 next, and from one architecture to the next (apparently).  To provide
 140 a concrete common standard, Guile should compile without warnings from
 141 GCC 2.7.2.3 in a Red Hat 5.2 i386 Linux machine.  Furthermore, each
 142 developer should pursue any additional warnings noted by on their
 143 compiler.  This means that people using more stringent compilers will
 144 have more work to do, and assures that everyone won't switch to the
 145 most lenient compiler they can find.  :)
 146
 147 Note also that EGCS (as of November 3 1998) doesn't handle the
 148 `noreturn' attribute properly, so it doesn't understand that functions
 149 like scm_error won't return.  This may lead to some silly warnings
 150 about uninitialized variables.  You should look into these warnings to
 151 make sure they are indeed spurious, but you needn't correct warnings
 152 caused by this EGCS bug.
 153
 154 - If you add code which uses functions or other features that are not
 155 entirely portable, please make sure the rest of Guile will still
 156 function properly on systems where they are missing.  This usually
 157 entails adding a test to configure.in, and then adding #ifdefs to your
 158 code to disable it if the system's features are missing.
 159
 160 - When you make a user-visible change (i.e. one that should be
 161 documented, and appear in NEWS, put an asterisk in column zero of the
 162 start of the ChangeLog entry, like so:
 163
 164 Sat Aug  3 01:27:14 1996  Gary Houston  <ghouston@actrix.gen.nz>
 165
 166 *       * fports.c (scm_open_file): don't return #f, throw error.
 167
 168 When you've written a NEWS entry and updated the documentation, go
 169 ahead and remove the asterisk.  I will use the asterisks to find and
 170 document changes that haven't been dealt with before a release.
 171
 172 - Please write log entries for functions written in C under the
 173 functions' C names, and write log entries for functions written in
 174 Scheme under the functions' Scheme names.  Please don't do this:
 175
 176         * procs.c, procs.h (procedure-documentation): Moved from eval.c.
 177
 178 Entries like this make it harder to search the ChangeLogs, because you
 179 can never tell which name the entry will refer to.  Instead, write this:
 180
 181         * procs.c, procs.h (scm_procedure_documentation): Moved from eval.c.
 182
 183 Changes like adding this line are special:
 184
 185     SCM_PROC (s_serial_map, "serial-map", 2, 0, 1, scm_map);
 186
 187 Since the change here is about the name itself --- we're adding a new
 188 alias for scm_map that guarantees the order in which we process list
 189 elements, but we're not changing scm_map at all --- it's appropriate
 190 to use the Scheme name in the log entry.
 191
 192 - There's no need to keep a change log for documentation files.  This
 193 is because documentation is not susceptible to bugs that are hard to
 194 fix.  Documentation does not consist of parts that must interact in a
 195 precisely engineered fashion; to correct an error, you need not know
 196 the history of the erroneous passage.  (This is copied from the GNU
 197 coding standards.)
 198
 199 - Make sure you have papers from people before integrating their
 200 changes or contributions.  This is very frustrating, but very
 201 important to do right.  From maintain.texi, "Information for
 202 Maintainers of GNU Software":
 203
 204     When incorporating changes from other people, make sure to follow the
 205     correct procedures.  Doing this ensures that the FSF has the legal
 206     right to distribute and defend GNU software.
 207
 208     For the sake of registering the copyright on later versions ofthe
 209     software you need to keep track of each person who makes significant
 210     changes.  A change of ten lines or so, or a few such changes, in a
 211     large program is not significant.
 212
 213     *Before* incorporating significant changes, make sure that the person
 214     has signed copyright papers, and that the Free Software Foundation has
 215     received them.
 216
 217 If you receive contributions you want to use from someone, let me know
 218 and I'll take care of the administrivia.  Put the contributions aside
 219 until we have the necessary papers.
 220
 221 - When you make substantial changes to a file, add the current year to
 222 the list of years in the copyright notice at the top of the file.
 223
 224
 225 Helpful hints ========================================================
 226
 227 - [From Mikael Djurfeldt] When working on the Guile internals, it is
 228 quite often practical to implement a scheme-level procedure which
 229 helps you examine the feature you're working on.
 230
 231 Examples of such procedures are: pt-size, debug-hand and
 232 current-pstate.
 233
 234 I've now put #ifdef GUILE_DEBUG around all such procedures, so that
 235 they are not compiled into the "normal" Guile library.  Please do the
 236 same when you add new procedures/C functions for debugging purpose.
 237
 238 You can define the GUILE_DEBUG flag by passing --enable-guile-debug to
 239 the configure script.
 240
 241 - You'll see uses of the macro SCM_P scattered throughout the code;
 242 those are vestiges of a time when Guile was meant to compile on
 243 pre-ANSI compilers.  Guile now requires ANSI C, so when you write new
 244 functions, feel free to use ANSI declarations, and please provide
 245 prototypes for everything.  You don't need to use SCM_P in new code.
 246
 247
 248 Jim Blandy, and others
 249
 250
 251 Patches ===========================================================
 252
 253 This one makes cvs-1.10 consider the file $CVSDOTIGNORE instead of
 254 .cvsignore when that environment variable is set.
 255
 256 === patch start ===
 257 diff -r -u cvs-1.10/src/cvs.h cvs-1.10.ignore-hack/src/cvs.h
 258 --- cvs-1.10/src/cvs.h  Mon Jul 27 04:54:11 1998
 259 +++ cvs-1.10.ignore-hack/src/cvs.h      Sun Jan 23 12:58:09 2000
 260 @@ -516,7 +516,7 @@
 261
 262  extern int ign_name PROTO ((char *name));
 263  void ign_add PROTO((char *ign, int hold));
 264 -void ign_add_file PROTO((char *file, int hold));
 265 +int ign_add_file PROTO((char *file, int hold));
 266  void ign_setup PROTO((void));
 267  void ign_dir_add PROTO((char *name));
 268  int ignore_directory PROTO((char *name));
 269 diff -r -u cvs-1.10/src/ignore.c cvs-1.10.ignore-hack/src/ignore.c
 270 --- cvs-1.10/src/ignore.c       Mon Sep  8 01:04:15 1997
 271 +++ cvs-1.10.ignore-hack/src/ignore.c   Sun Jan 23 12:57:50 2000
 272 @@ -99,9 +99,9 @@
 273  /*
 274   * Open a file and read lines, feeding each line to a line parser. Arrange
 275   * for keeping a temporary list of wildcards at the end, if the "hold"
 276 - * argument is set.
 277 + * argument is set.  Return true when the file exists and has been handled.
 278   */
 279 -void
 280 +int
 281  ign_add_file (file, hold)
 282      char *file;
 283      int hold;
 284 @@ -149,8 +149,8 @@
 285      if (fp == NULL)
 286      {
 287         if (! existence_error (errno))
 288 -           error (0, errno, "cannot open %s", file);
 289 -       return;
 290 +         error (0, errno, "cannot open %s", file);
 291 +       return 0;
 292      }
 293      while (getline (&line, &line_allocated, fp) >= 0)
 294         ign_add (line, hold);
 295 @@ -159,6 +159,7 @@
 296      if (fclose (fp) < 0)
 297         error (0, errno, "cannot close %s", file);
 298      free (line);
 299 +    return 1;
 300  }
 301
 302  /* Parse a line of space-separated wildcards and add them to the list. */
 303 @@ -375,6 +376,7 @@
 304      struct stat sb;
 305      char *file;
 306      char *xdir;
 307 +    char *cvsdotignore;
 308
 309      /* Set SUBDIRS if we have subdirectory information in ENTRIES.  */
 310      if (entries == NULL)
 311 @@ -397,7 +399,10 @@
 312      if (dirp == NULL)
 313         return;
 314
 315 -    ign_add_file (CVSDOTIGNORE, 1);
 316 +    cvsdotignore = getenv("CVSDOTIGNORE");
 317 +    if (cvsdotignore == NULL || !ign_add_file (cvsdotignore, 1))
 318 +      ign_add_file (CVSDOTIGNORE, 1);
 319 +
 320      wrap_add_file (CVSDOTWRAPPER, 1);
 321
 322      while ((dp = readdir (dirp)) != NULL)
 323 === patch end ===
 324
 325 This one is for pcl-cvs-2.9.2, so that `i' adds to the local
 326 .cvsignore file.
 327
 328 === patch start ===
 329 --- pcl-cvs.el~ Mon Nov  1 12:33:46 1999
 330 +++ pcl-cvs.el  Tue Jan 25 21:46:27 2000
 331 @@ -1177,7 +1177,10 @@
 332    "Append the file in FILEINFO to the .cvsignore file.
 333  Can only be used in the *cvs* buffer."
 334    (save-window-excursion
 335 -    (set-buffer (find-file-noselect (expand-file-name ".cvsignore" dir)))
 336 +    (set-buffer (find-file-noselect
 337 +                (expand-file-name (or (getenv "CVSDOTIGNORE")
 338 +                                      ".cvsignore")
 339 +                                  dir)))
 340      (goto-char (point-max))
 341      (unless (zerop (current-column)) (insert "\n"))
 342      (insert str "\n")
 343 === patch end ===