+-*-text-*-
Guile Hacking Guide
-Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001 Free software Foundation, Inc.
+Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free software Foundation, Inc.
Permission is granted to anyone to make or distribute verbatim copies
of this document as received, in any medium, provided that the
However, to see what others have indicated as their interest (and avoid
potential wasteful duplication of effort), see file TODO. Note that
-the version you find may be out of date; a CVS checkout is recommended
-(see also file SNAPSHOTS).
+the version you find may be out of date; a CVS checkout is recommended:
+see below for details (see also the files ANON-CVS and SNAPSHOTS).
It's also a good idea to join the guile-devel@gnu.org mailing list.
See http://www.gnu.org/software/guile/mail/mail.html for more info.
Hacking It Yourself ==================================================
-As distributed, Guile needs only an ANSI C compiler and a Unix system
-to compile. However, Guile's makefiles, configuration scripts, and a
-few other files are automatically generated, not written by hand. If
-you want to make changes to the system (which we encourage!) you will
-find it helpful to have the tools we use to develop Guile. They
-are the following:
+When Guile is obtained from CVS, a few extra steps must be taken
+before the usual configure, make, make install. You will need to have
+up-to-date versions of the tools listed below, correctly installed.
+i.e., they must be found in the current PATH and not shadowed or
+otherwise broken by files left behind from other versions.
-Autoconf 2.50 --- a system for automatically generating `configure'
+"up-to-date" means the latest released versions at the time that Guile
+was obtained from CVS. Sometimes older or newer versions will work.
+(See below for versions to avoid.)
+
+Then you must run the autogen.sh script, as described below.
+
+In case of problems, it may be worth getting a fresh copy of Guile
+from CVS: synchronisation problems have been known to occur
+occasionally.
+
+The same procedure can be used to regenerate the files in released
+versions of Guile. In that case the headers of the original generated
+files (e.g., configure, Makefile.in, ltmain.sh) can be used to
+identify which tool versions may be required.
+
+Autoconf --- a system for automatically generating `configure'
scripts from templates which list the non-portable features a
program would like to use. Available in
"ftp://ftp.gnu.org/pub/gnu/autoconf"
-Automake 1.4-p2 --- a system for automatically generating Makefiles that
+Automake --- a system for automatically generating Makefiles that
conform to the (rather Byzantine) GNU coding standards. The
nice thing is that it takes care of hairy targets like 'make
dist' and 'make distclean', and automatically generates
Makefile dependencies. Automake is available in
"ftp://ftp.gnu.org/pub/gnu/automake"
- Before using automake, you may need to copy `threads.m4' and
- `guile.m4' from the top directory of the Guile core disty to
- `/usr/local/share/aclocal.
-
-libtool 1.4 --- a system for managing the zillion hairy options needed
+libtool --- a system for managing the zillion hairy options needed
on various systems to produce shared libraries. Available in
"ftp://ftp.gnu.org/pub/gnu/libtool"
-flex 2.5.4 (or newer) --- a scanner generator. earlier versions will
- most probably work too.
+gettext --- a system for rigging a program so that it can output its
+ messages in the local tongue. Guile presently only exports
+ the gettext functionality to Scheme, it does not use it
+ itself.
+
+flex --- a scanner generator. It's probably not essential to have the
+ latest version.
+
+One false move and you will be lost in a little maze of automatically
+generated files, all different.
+
+Here is the authoritative list of tool/version/platform tuples that
+have been known to cause problems, and a short description of the problem.
+
+- automake 1.4 adds extraneous rules to the top-level Makefile if
+ you specify specific Makefiles to rebuild on the command line.
+
+- automake 1.4-p4 (debian "1:1.4-p4-1.1") all platforms
+ automake "include" facility does not recognize filenames w/ "-".
+
+- libtool 1.4 uses acconfig.h, which is deprecated by newest autoconf
+ (which constructs the equivalent through 3rd arg of AC_DEFINE forms).
+
+- autoreconf from autoconf prior to 2.59 will run gettextize, which
+ will mess up the Guile tree.
+
+- (add here.)
+
+
+Sample GDB Initialization File=========================================
+
+Here is a sample .gdbinit posted by Bill Schottstaedt (modified to
+use `set' instead of `call' in some places):
-You are lost in a little maze of automatically generated files, all
-different.
+ define gp
+ set gdb_print($arg0)
+ print gdb_output
+ end
+ document gp
+ Executes (object->string arg)
+ end
+
+ define ge
+ call gdb_read($arg0)
+ call gdb_eval(gdb_result)
+ set gdb_print(gdb_result)
+ print gdb_output
+ end
+ document ge
+ Executes (print (eval (read arg))): ge "(+ 1 2)" => 3
+ end
+
+ define gh
+ call g_help(scm_str2symbol($arg0), 20)
+ set gdb_print($1)
+ print gdb_output
+ end
+ document gh
+ Prints help string for arg: gh "enved-target"
+ end
+
+Bill further writes:
+
+ so in gdb if you see something useless like:
+
+ #32 0x081ae8f4 in scm_primitive_load (filename=1112137128) at load.c:129
+
+ You can get the file name with gp:
+
+ (gdb) gp 1112137128
+ $1 = 0x40853fac "\"/home/bil/test/share/guile/1.5.0/ice-9/session.scm\""
Contributing Your Changes ============================================
the value of the global -d option to CVS when you check out a working
directory.
-For more information on SSH, see http://www.cs.hut.fi/ssh.
+For more information on SSH, see http://www.openssh.com.
The Guile sources live in several modules:
- guile-rgx-ctax --- the Guile/Rx interface, and the ctax implementation
- guile-scsh --- the port of SCSH to guile, talk to Gary Houston
- guile-www --- A Guile module for making HTTP requests.
+ - guile-statprof --- an experimental statistical profiler.
There is a mailing list for CVS commit messages; see README for details.
+- The guile-core tree is now versioned similarly to the Linux kernel.
+Guile now always uses three numbers to represent the version,
+i.e. "1.6.5". The first number, 1, is the major version number, the
+second number, 6, is the minor version number, and the third number,
+5, is the micro version number. Changes in major version number
+indicate major changes in Guile.
+
+Minor version numbers that are even denote stable releases, and odd
+minor version numbers denote development versions (which may be
+unstable). The micro version number indicates a minor sub-revision of
+a given MAJOR.MINOR release.
+
+- A default CVS checkout will get the current unstable development
+tree. However, for each stable release, a CVS branch is created so
+that release (and ongoing maintenance) of the stable version can
+proceed independent of the development of the next unstable version.
+To check out a particular stable branch, you just need to specify "-r
+branch_release-X-Y" to your CVS checkout command (or to any update).
+For example, if you wanted to check out the 1.6 stable branch, you
+would specify "-r branch_release-1-6".
+
+So, for example, during a normal development cycle, work will proceed
+on an unstable version, say 1.5.X, until it is decided that it's time
+for a stable release. At that point, a branch named
+branch_release-1-6 will be created, and the version numbers on the
+HEAD of the CVS tree (the trunk, i.e. what you get by default), will
+be changed to reflect the new unstable version 1.7.X. Then unstable
+development will proceed on the unstable version, while the stable
+1.5.X branch is fixed up for the eventual 1.6.0 release.
+
+Anytime you want to yank an existing checked out tree to the stable
+branch, you can run a command like this:
+
+ cvs -z3 update -r branch_release-1-6 -Pd
+
+This will yank the working directory over on to the stable release
+branch. Note that this directory will track that branch from then on
+unless you do something to yank it back to the main (unstable) trunk.
+
+To go back to the unstable branch, you can use
+
+ cvs -z3 update -A -Pd
+
+Note that in either case, you should probably make sure you've
+commited or removed all local changes before running the commands or
+you're likely to have some unexpected results.
+
+Finally note that one approach, should you need to work on both
+branches, is to keep two trees checked out, one stable, the other
+unstable and you can work in whichever is appropriate.
+
+To save some initial bandwidth, you can check out either the stable
+tree or the unstable tree, and then do something like this:
+
+ cp -a core-unstable core-1.5
+ cd core-1.5
+ cvs -z3 update -r branch_release-1-6 -Pd
+
+- The stable and unstable CVS trees are distinct, and no changes will
+automatically propagate between them. If you make changes that need
+to show up both places, you'll need to apply the changes both places.
+You *might* be able to do this with a cvs command, but often you'll
+probably need to apply the changes by hand or risk migrating
+superfluous modifications between the two versions. This is
+particularly important when moving a change from the unstable branch
+to the stable branch.
+
+- In general, please don't be adventurous with the stable branch. We
+mostly want bugfixes, documentation improvements, build improvements,
+etc., though exceptions will doubtless exist.
+
+- There are a few CVS tagging conventions which follow the Scheme
+convention that dashes are used to separate words within a single
+symbol, and so dashes bind more tightly than underscores. This means
+that foo-bar_baz-bax indicates that foo-bar is somehow separate from
+baz-bax. The conventions are as follows:
+
+ Branch root tags:
+ -----------------
+ anytime just before you create a branch it's a good
+ idea to create a normal tag so that you can refer to the branch point
+ on the main trunk as well as on the branch. So please use a tag of
+ the form
+
+ branch-root-release-1-X
+
+ or more generally, for other non-release branches:
+
+ branch-root_FOO
+
+ Branch tags:
+ ------------
+ for the branch tag itself please use
+
+ branch_release-1-6
+
+ or more generally, for other non-release branches:
+
+ branch_FOO
+
+ Merge tags:
+ -----------
+ Whenever you're merging a branch back into the trunk (or into another
+ branch repeatedly) you need to tag the branch each time you merge. If
+ you don't do that, you won't be able to merge repeatedly without
+ possibly tedious conflicts. For those tags, we suggest:
+
+ branch-merge_SOME-FOO_to_SOME-BAR_1
+ branch-merge_SOME-FOO_to_SOME-BAR_2
+ ..
+
+ As an example, SOME-BAR might be trunk, or even perhaps another branch
+ like branch-mvo-super-fixes :>
+
+ More mundanely, you might have
+
+ branch-merge_release-1-6_to_trunk_1
+
+ (Merging the stable branch to the trunk like this
+ will probably be much more common, when it happens, than the
+ reverse for the reasons mentioned above.
+
+ Release tags:
+ -------------
+ When releasing a new version of guile, please use:
+
+ release_X-Y-Z
+
+ i.e.
+
+ release_1-6-0
+
+- If you hack on a stable branch, please apply any relevant patches or
+fixes to the current unstable version (the main CVS trunk) as well.
+Similarly, please back-port any important fixes to the unstable CVS
+tree to the current stable branch.
+
- We check Makefile.am and configure.in files into CVS, but the
"autogen.sh" script must be run from the top-level to generate the
actual "configure" script that then must be run to create the various
- Make sure your changes compile and work, at least on your own
machine, before checking them into the main branch of the Guile
-repository. If you really need to check in untested changes, make a
-branch.
+repository. A good way for testing this is to run "make distcheck".
+If you really need to check in untested changes, make a branch.
- Include each log entry in both the ChangeLog and in the CVS logs.
If you're using Emacs, the pcl-cvs interface to CVS has features to
-O2 -Wall -Wpointer-arith -Wmissing-prototypes
+To make sure of this, you can use the --enable-error-on-warning option
+to configure. This option will make GCC fail if it hits a warning.
+
Note that the warnings generated vary from one version of GCC to the
next, and from one architecture to the next (apparently). To provide
a concrete common standard, Guile should compile without warnings from
to do at each release. Add a reminder about the removal of the
deprecated defintion at the appropriate release.
-- When you make a user-visible change (i.e. one that should be
-documented, and appear in NEWS, put an asterisk in column zero of the
-start of the ChangeLog entry, like so:
-
-Sat Aug 3 01:27:14 1996 Gary Houston <ghouston@actrix.gen.nz>
-
-* * fports.c (scm_open_file): don't return #f, throw error.
-
-When you've written a NEWS entry and updated the documentation, go
-ahead and remove the asterisk. I will use the asterisks to find and
-document changes that haven't been dealt with before a release.
-
- Please write log entries for functions written in C under the
functions' C names, and write log entries for functions written in
Scheme under the functions' Scheme names. Please don't do this:
elements, but we're not changing scm_map at all --- it's appropriate
to use the Scheme name in the log entry.
-- There's no need to keep a change log for documentation files. This
-is because documentation is not susceptible to bugs that are hard to
-fix. Documentation does not consist of parts that must interact in a
-precisely engineered fashion; to correct an error, you need not know
-the history of the erroneous passage. (This is copied from the GNU
-coding standards.)
+- There's no need to keep a change log for a ChangeLog file. For any
+other kind of file (including documentation, since our documentation
+is indeed precisely engineered -- we surpass GNU standards here), add
+an appropriate ChangeLog entry when you change it. Simple!
- Make sure you have papers from people before integrating their
changes or contributions. This is very frustrating, but very
HCoop / bpt / guile.git / blobdiff