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