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 2. Write a comment at the definition explaining how a programmer
 193 can manage without the deprecated definition.
 194
 195 3. Add an entry that the definition has been deprecated in NEWS
 196
 197 4. At the top of RELEASE, there is a list of releases with reminders
 198 about what to do at each release.  Add a reminder about the removal of
 199 the deprecated defintion at the appropriate release.
 200
 201 - When you make a user-visible change (i.e. one that should be
 202 documented, and appear in NEWS, put an asterisk in column zero of the
 203 start of the ChangeLog entry, like so:
 204
 205 Sat Aug  3 01:27:14 1996  Gary Houston  <ghouston@actrix.gen.nz>
 206
 207 *       * fports.c (scm_open_file): don't return #f, throw error.
 208
 209 When you've written a NEWS entry and updated the documentation, go
 210 ahead and remove the asterisk.  I will use the asterisks to find and
 211 document changes that haven't been dealt with before a release.
 212
 213 - Please write log entries for functions written in C under the
 214 functions' C names, and write log entries for functions written in
 215 Scheme under the functions' Scheme names.  Please don't do this:
 216
 217         * procs.c, procs.h (procedure-documentation): Moved from eval.c.
 218
 219 Entries like this make it harder to search the ChangeLogs, because you
 220 can never tell which name the entry will refer to.  Instead, write this:
 221
 222         * procs.c, procs.h (scm_procedure_documentation): Moved from eval.c.
 223
 224 Changes like adding this line are special:
 225
 226     SCM_PROC (s_map_in_order, "map-in-order", 2, 0, 1, scm_map);
 227
 228 Since the change here is about the name itself --- we're adding a new
 229 alias for scm_map that guarantees the order in which we process list
 230 elements, but we're not changing scm_map at all --- it's appropriate
 231 to use the Scheme name in the log entry.
 232
 233 - There's no need to keep a change log for documentation files.  This
 234 is because documentation is not susceptible to bugs that are hard to
 235 fix.  Documentation does not consist of parts that must interact in a
 236 precisely engineered fashion; to correct an error, you need not know
 237 the history of the erroneous passage.  (This is copied from the GNU
 238 coding standards.)
 239
 240 - Make sure you have papers from people before integrating their
 241 changes or contributions.  This is very frustrating, but very
 242 important to do right.  From maintain.texi, "Information for
 243 Maintainers of GNU Software":
 244
 245     When incorporating changes from other people, make sure to follow the
 246     correct procedures.  Doing this ensures that the FSF has the legal
 247     right to distribute and defend GNU software.
 248
 249     For the sake of registering the copyright on later versions ofthe
 250     software you need to keep track of each person who makes significant
 251     changes.  A change of ten lines or so, or a few such changes, in a
 252     large program is not significant.
 253
 254     *Before* incorporating significant changes, make sure that the person
 255     has signed copyright papers, and that the Free Software Foundation has
 256     received them.
 257
 258 If you receive contributions you want to use from someone, let me know
 259 and I'll take care of the administrivia.  Put the contributions aside
 260 until we have the necessary papers.
 261
 262 - When you make substantial changes to a file, add the current year to
 263 the list of years in the copyright notice at the top of the file.
 264
 265
 266 Helpful hints ========================================================
 267
 268 - [From Mikael Djurfeldt] When working on the Guile internals, it is
 269 quite often practical to implement a scheme-level procedure which
 270 helps you examine the feature you're working on.
 271
 272 Examples of such procedures are: pt-size, debug-hand and
 273 current-pstate.
 274
 275 I've now put #ifdef GUILE_DEBUG around all such procedures, so that
 276 they are not compiled into the "normal" Guile library.  Please do the
 277 same when you add new procedures/C functions for debugging purpose.
 278
 279 You can define the GUILE_DEBUG flag by passing --enable-guile-debug to
 280 the configure script.
 281
 282 - You'll see uses of the macro SCM_P scattered throughout the code;
 283 those are vestiges of a time when Guile was meant to compile on
 284 pre-ANSI compilers.  Guile now requires ANSI C, so when you write new
 285 functions, feel free to use ANSI declarations, and please provide
 286 prototypes for everything.  You don't need to use SCM_P in new code.
 287
 288
 289 Jim Blandy, and others
 290
 291
 292 Patches ===========================================================
 293
 294 This one makes cvs-1.10 consider the file $CVSDOTIGNORE instead of
 295 .cvsignore when that environment variable is set.
 296
 297 === patch start ===
 298 diff -r -u cvs-1.10/src/cvs.h cvs-1.10.ignore-hack/src/cvs.h
 299 --- cvs-1.10/src/cvs.h  Mon Jul 27 04:54:11 1998
 300 +++ cvs-1.10.ignore-hack/src/cvs.h      Sun Jan 23 12:58:09 2000
 301 @@ -516,7 +516,7 @@
 302
 303  extern int ign_name PROTO ((char *name));
 304  void ign_add PROTO((char *ign, int hold));
 305 -void ign_add_file PROTO((char *file, int hold));
 306 +int ign_add_file PROTO((char *file, int hold));
 307  void ign_setup PROTO((void));
 308  void ign_dir_add PROTO((char *name));
 309  int ignore_directory PROTO((char *name));
 310 diff -r -u cvs-1.10/src/ignore.c cvs-1.10.ignore-hack/src/ignore.c
 311 --- cvs-1.10/src/ignore.c       Mon Sep  8 01:04:15 1997
 312 +++ cvs-1.10.ignore-hack/src/ignore.c   Sun Jan 23 12:57:50 2000
 313 @@ -99,9 +99,9 @@
 314  /*
 315   * Open a file and read lines, feeding each line to a line parser. Arrange
 316   * for keeping a temporary list of wildcards at the end, if the "hold"
 317 - * argument is set.
 318 + * argument is set.  Return true when the file exists and has been handled.
 319   */
 320 -void
 321 +int
 322  ign_add_file (file, hold)
 323      char *file;
 324      int hold;
 325 @@ -149,8 +149,8 @@
 326      if (fp == NULL)
 327      {
 328         if (! existence_error (errno))
 329 -           error (0, errno, "cannot open %s", file);
 330 -       return;
 331 +         error (0, errno, "cannot open %s", file);
 332 +       return 0;
 333      }
 334      while (getline (&line, &line_allocated, fp) >= 0)
 335         ign_add (line, hold);
 336 @@ -159,6 +159,7 @@
 337      if (fclose (fp) < 0)
 338         error (0, errno, "cannot close %s", file);
 339      free (line);
 340 +    return 1;
 341  }
 342
 343  /* Parse a line of space-separated wildcards and add them to the list. */
 344 @@ -375,6 +376,7 @@
 345      struct stat sb;
 346      char *file;
 347      char *xdir;
 348 +    char *cvsdotignore;
 349
 350      /* Set SUBDIRS if we have subdirectory information in ENTRIES.  */
 351      if (entries == NULL)
 352 @@ -397,7 +399,10 @@
 353      if (dirp == NULL)
 354         return;
 355
 356 -    ign_add_file (CVSDOTIGNORE, 1);
 357 +    cvsdotignore = getenv("CVSDOTIGNORE");
 358 +    if (cvsdotignore == NULL || !ign_add_file (cvsdotignore, 1))
 359 +      ign_add_file (CVSDOTIGNORE, 1);
 360 +
 361      wrap_add_file (CVSDOTWRAPPER, 1);
 362
 363      while ((dp = readdir (dirp)) != NULL)
 364 === patch end ===
 365
 366 This one is for pcl-cvs-2.9.2, so that `i' adds to the local
 367 .cvsignore file.
 368
 369 === patch start ===
 370 --- pcl-cvs.el~ Mon Nov  1 12:33:46 1999
 371 +++ pcl-cvs.el  Tue Jan 25 21:46:27 2000
 372 @@ -1177,7 +1177,10 @@
 373    "Append the file in FILEINFO to the .cvsignore file.
 374  Can only be used in the *cvs* buffer."
 375    (save-window-excursion
 376 -    (set-buffer (find-file-noselect (expand-file-name ".cvsignore" dir)))
 377 +    (set-buffer (find-file-noselect
 378 +                (expand-file-name (or (getenv "CVSDOTIGNORE")
 379 +                                      ".cvsignore")
 380 +                                  dir)))
 381      (goto-char (point-max))
 382      (unless (zerop (current-column)) (insert "\n"))
 383      (insert str "\n")
 384 === patch end ===