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