1 Hacking It Yourself ==================================================
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
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"
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"
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.
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"
30 You are lost in a little maze of automatically generated files, all
35 Contributing Your Changes ============================================
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.
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.
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.
53 CVS conventions ======================================================
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
63 :ext:USER@subversions.gnu.org:/cvs
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
69 For more information on SSH, see http://www.cs.hut.fi/ssh.
71 The Guile sources live in several modules:
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.
82 There is a mailing list for CVS commit messages; see README for details.
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
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.
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.
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
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.
121 Coding standards =====================================================
123 - Before contributing larger amounts of code to Guile, please read the
124 documents in `guile-core/devel/policy' in the CVS source tree.
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
131 - The Guile tree should compile without warnings under the following
132 GCC switches, which are the default in the current configure script:
134 -O2 -Wall -Wpointer-arith -Wmissing-prototypes
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. :)
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.
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.
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.)
167 When deprecating a definition, always follow this procedure:
169 1. Mark the definition using
171 #if (SCM_DEBUG_DEPRECATED == 0)
175 2. Write a comment at the definition explaining how a programmer
176 can manage without the deprecated definition.
178 3. Add an entry that the definition has been deprecated in NEWS
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.
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:
188 Sat Aug 3 01:27:14 1996 Gary Houston <ghouston@actrix.gen.nz>
190 * * fports.c (scm_open_file): don't return #f, throw error.
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.
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:
200 * procs.c, procs.h (procedure-documentation): Moved from eval.c.
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:
205 * procs.c, procs.h (scm_procedure_documentation): Moved from eval.c.
207 Changes like adding this line are special:
209 SCM_PROC (s_map_in_order, "map-in-order", 2, 0, 1, scm_map);
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.
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
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":
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.
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.
237 *Before* incorporating significant changes, make sure that the person
238 has signed copyright papers, and that the Free Software Foundation has
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.
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.
249 Helpful hints ========================================================
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.
255 Examples of such procedures are: pt-size, debug-hand and
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.
262 You can define the GUILE_DEBUG flag by passing --enable-guile-debug to
263 the configure script.
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.
272 Jim Blandy, and others
275 Patches ===========================================================
277 This one makes cvs-1.10 consider the file $CVSDOTIGNORE instead of
278 .cvsignore when that environment variable is set.
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
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
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"
301 + * argument is set. Return true when the file exists and has been handled.
305 ign_add_file (file, hold)
311 if (! existence_error (errno))
312 - error (0, errno, "cannot open %s", file);
314 + error (0, errno, "cannot open %s", file);
317 while (getline (&line, &line_allocated, fp) >= 0)
318 ign_add (line, hold);
321 error (0, errno, "cannot close %s", file);
326 /* Parse a line of space-separated wildcards and add them to the list. */
331 + char *cvsdotignore;
333 /* Set SUBDIRS if we have subdirectory information in ENTRIES. */
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);
344 wrap_add_file (CVSDOTWRAPPER, 1);
346 while ((dp = readdir (dirp)) != NULL)
349 This one is for pcl-cvs-2.9.2, so that `i' adds to the local
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")
364 (goto-char (point-max))
365 (unless (zerop (current-column)) (insert "\n"))