HACKING

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