HACKING

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