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.5 --- 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 - Before contributing larger amounts of code to Guile, please read the
 125 documents in `guile-core/devel/policy' in the CVS source tree.
 126
 127 - As for any part of Project GNU, changes to Guile should follow the
 128 GNU coding standards.  The standards are available via anonymous FTP
 129 from prep.ai.mit.edu, as /pub/gnu/standards/standards.texi and
 130 make-stds.texi.
 131
 132 - The Guile tree should compile without warnings under the following
 133 GCC switches, which are the default in the current configure script:
 134     -O2 -Wall -Wpointer-arith -Wmissing-prototypes
 135 The only warnings which can be tolerated are those about variables
 136 being clobbered by longjmp/vfork in eval.c.  The variables in question
 137 are critical to the interpreter's performance; as far as I can tell,
 138 it is difficult/annoying to avoid these warnings without slowing the
 139 system down substantially.  (If you can figure out a good fix, I'd be happy to see it.)
 140
 141 Note that the warnings generated vary from one version of GCC to the
 142 next, and from one architecture to the next (apparently).  To provide
 143 a concrete common standard, Guile should compile without warnings from
 144 GCC 2.7.2.3 in a Red Hat 5.2 i386 Linux machine.  Furthermore, each
 145 developer should pursue any additional warnings noted by on their
 146 compiler.  This means that people using more stringent compilers will
 147 have more work to do, and assures that everyone won't switch to the
 148 most lenient compiler they can find.  :)
 149
 150 Note also that EGCS (as of November 3 1998) doesn't handle the
 151 `noreturn' attribute properly, so it doesn't understand that functions
 152 like scm_error won't return.  This may lead to some silly warnings
 153 about uninitialized variables.  You should look into these warnings to
 154 make sure they are indeed spurious, but you needn't correct warnings
 155 caused by this EGCS bug.
 156
 157 - If you add code which uses functions or other features that are not
 158 entirely portable, please make sure the rest of Guile will still
 159 function properly on systems where they are missing.  This usually
 160 entails adding a test to configure.in, and then adding #ifdefs to your
 161 code to disable it if the system's features are missing.
 162
 163 - The normal way of removing a function, macro or variable is to mark
 164 it as "deprecated", keep it for a while, and remove it in a later
 165 release.  If a function or macro is marked as "deprecated" it
 166 indicates that people shouldn't use it in new programs, and should try
 167 to remove it in old.  Make sure that an alternative exists unless it
 168 is our purpose to remove functionality.  Don't deprecate definitions
 169 if it is unclear when they will be removed.  (This is to ensure that a
 170 valid way of implementing some functionality always exists.)
 171
 172 When deprecating a definition, always following this procedure:
 173
 174 1. Mark the definition using
 175
 176 #if (SCM_DEBUG_DEPRECATED == 0)
 177 ...
 178 #endif
 179
 180 2. Write a comment at the definition explaining how a programmer
 181 can manage without the deprecated definition.
 182
 183 3. Add an entry that the definition has been deprecated in NEWS
 184
 185 4. At the top of release, there is a list of releases with reminders
 186 about what to do at each release.  Add a reminder about the removal of
 187 the deprecated defintion at the appropriate release.
 188
 189 - When you make a user-visible change (i.e. one that should be
 190 documented, and appear in NEWS, put an asterisk in column zero of the
 191 start of the ChangeLog entry, like so:
 192
 193 Sat Aug  3 01:27:14 1996  Gary Houston  <ghouston@actrix.gen.nz>
 194
 195 *       * fports.c (scm_open_file): don't return #f, throw error.
 196
 197 When you've written a NEWS entry and updated the documentation, go
 198 ahead and remove the asterisk.  I will use the asterisks to find and
 199 document changes that haven't been dealt with before a release.
 200
 201 - Please write log entries for functions written in C under the
 202 functions' C names, and write log entries for functions written in
 203 Scheme under the functions' Scheme names.  Please don't do this:
 204
 205         * procs.c, procs.h (procedure-documentation): Moved from eval.c.
 206
 207 Entries like this make it harder to search the ChangeLogs, because you
 208 can never tell which name the entry will refer to.  Instead, write this:
 209
 210         * procs.c, procs.h (scm_procedure_documentation): Moved from eval.c.
 211
 212 Changes like adding this line are special:
 213
 214     SCM_PROC (s_serial_map, "serial-map", 2, 0, 1, scm_map);
 215
 216 Since the change here is about the name itself --- we're adding a new
 217 alias for scm_map that guarantees the order in which we process list
 218 elements, but we're not changing scm_map at all --- it's appropriate
 219 to use the Scheme name in the log entry.
 220
 221 - There's no need to keep a change log for documentation files.  This
 222 is because documentation is not susceptible to bugs that are hard to
 223 fix.  Documentation does not consist of parts that must interact in a
 224 precisely engineered fashion; to correct an error, you need not know
 225 the history of the erroneous passage.  (This is copied from the GNU
 226 coding standards.)
 227
 228 - Make sure you have papers from people before integrating their
 229 changes or contributions.  This is very frustrating, but very
 230 important to do right.  From maintain.texi, "Information for
 231 Maintainers of GNU Software":
 232
 233     When incorporating changes from other people, make sure to follow the
 234     correct procedures.  Doing this ensures that the FSF has the legal
 235     right to distribute and defend GNU software.
 236
 237     For the sake of registering the copyright on later versions ofthe
 238     software you need to keep track of each person who makes significant
 239     changes.  A change of ten lines or so, or a few such changes, in a
 240     large program is not significant.
 241
 242     *Before* incorporating significant changes, make sure that the person
 243     has signed copyright papers, and that the Free Software Foundation has
 244     received them.
 245
 246 If you receive contributions you want to use from someone, let me know
 247 and I'll take care of the administrivia.  Put the contributions aside
 248 until we have the necessary papers.
 249
 250 - When you make substantial changes to a file, add the current year to
 251 the list of years in the copyright notice at the top of the file.
 252
 253
 254 Helpful hints ========================================================
 255
 256 - [From Mikael Djurfeldt] When working on the Guile internals, it is
 257 quite often practical to implement a scheme-level procedure which
 258 helps you examine the feature you're working on.
 259
 260 Examples of such procedures are: pt-size, debug-hand and
 261 current-pstate.
 262
 263 I've now put #ifdef GUILE_DEBUG around all such procedures, so that
 264 they are not compiled into the "normal" Guile library.  Please do the
 265 same when you add new procedures/C functions for debugging purpose.
 266
 267 You can define the GUILE_DEBUG flag by passing --enable-guile-debug to
 268 the configure script.
 269
 270 - You'll see uses of the macro SCM_P scattered throughout the code;
 271 those are vestiges of a time when Guile was meant to compile on
 272 pre-ANSI compilers.  Guile now requires ANSI C, so when you write new
 273 functions, feel free to use ANSI declarations, and please provide
 274 prototypes for everything.  You don't need to use SCM_P in new code.
 275
 276
 277 Jim Blandy, and others
 278
 279
 280 Patches ===========================================================
 281
 282 This one makes cvs-1.10 consider the file $CVSDOTIGNORE instead of
 283 .cvsignore when that environment variable is set.
 284
 285 === patch start ===
 286 diff -r -u cvs-1.10/src/cvs.h cvs-1.10.ignore-hack/src/cvs.h
 287 --- cvs-1.10/src/cvs.h  Mon Jul 27 04:54:11 1998
 288 +++ cvs-1.10.ignore-hack/src/cvs.h      Sun Jan 23 12:58:09 2000
 289 @@ -516,7 +516,7 @@
 290
 291  extern int ign_name PROTO ((char *name));
 292  void ign_add PROTO((char *ign, int hold));
 293 -void ign_add_file PROTO((char *file, int hold));
 294 +int ign_add_file PROTO((char *file, int hold));
 295  void ign_setup PROTO((void));
 296  void ign_dir_add PROTO((char *name));
 297  int ignore_directory PROTO((char *name));
 298 diff -r -u cvs-1.10/src/ignore.c cvs-1.10.ignore-hack/src/ignore.c
 299 --- cvs-1.10/src/ignore.c       Mon Sep  8 01:04:15 1997
 300 +++ cvs-1.10.ignore-hack/src/ignore.c   Sun Jan 23 12:57:50 2000
 301 @@ -99,9 +99,9 @@
 302  /*
 303   * Open a file and read lines, feeding each line to a line parser. Arrange
 304   * for keeping a temporary list of wildcards at the end, if the "hold"
 305 - * argument is set.
 306 + * argument is set.  Return true when the file exists and has been handled.
 307   */
 308 -void
 309 +int
 310  ign_add_file (file, hold)
 311      char *file;
 312      int hold;
 313 @@ -149,8 +149,8 @@
 314      if (fp == NULL)
 315      {
 316         if (! existence_error (errno))
 317 -           error (0, errno, "cannot open %s", file);
 318 -       return;
 319 +         error (0, errno, "cannot open %s", file);
 320 +       return 0;
 321      }
 322      while (getline (&line, &line_allocated, fp) >= 0)
 323         ign_add (line, hold);
 324 @@ -159,6 +159,7 @@
 325      if (fclose (fp) < 0)
 326         error (0, errno, "cannot close %s", file);
 327      free (line);
 328 +    return 1;
 329  }
 330
 331  /* Parse a line of space-separated wildcards and add them to the list. */
 332 @@ -375,6 +376,7 @@
 333      struct stat sb;
 334      char *file;
 335      char *xdir;
 336 +    char *cvsdotignore;
 337
 338      /* Set SUBDIRS if we have subdirectory information in ENTRIES.  */
 339      if (entries == NULL)
 340 @@ -397,7 +399,10 @@
 341      if (dirp == NULL)
 342         return;
 343
 344 -    ign_add_file (CVSDOTIGNORE, 1);
 345 +    cvsdotignore = getenv("CVSDOTIGNORE");
 346 +    if (cvsdotignore == NULL || !ign_add_file (cvsdotignore, 1))
 347 +      ign_add_file (CVSDOTIGNORE, 1);
 348 +
 349      wrap_add_file (CVSDOTWRAPPER, 1);
 350
 351      while ((dp = readdir (dirp)) != NULL)
 352 === patch end ===
 353
 354 This one is for pcl-cvs-2.9.2, so that `i' adds to the local
 355 .cvsignore file.
 356
 357 === patch start ===
 358 --- pcl-cvs.el~ Mon Nov  1 12:33:46 1999
 359 +++ pcl-cvs.el  Tue Jan 25 21:46:27 2000
 360 @@ -1177,7 +1177,10 @@
 361    "Append the file in FILEINFO to the .cvsignore file.
 362  Can only be used in the *cvs* buffer."
 363    (save-window-excursion
 364 -    (set-buffer (find-file-noselect (expand-file-name ".cvsignore" dir)))
 365 +    (set-buffer (find-file-noselect
 366 +                (expand-file-name (or (getenv "CVSDOTIGNORE")
 367 +                                      ".cvsignore")
 368 +                                  dir)))
 369      (goto-char (point-max))
 370      (unless (zerop (current-column)) (insert "\n"))
 371      (insert str "\n")
 372 === patch end ===