| 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 === |