+2001-08-15 Rob Browning <rlb@defaultvalue.org>
+
+ * configure.in
+ (LIBGUILE_INTERFACE_CURRENT): use libtool versioning scheme.
+ (LIBGUILE_INTERFACE_REVISION): use libtool versioning scheme.
+ (LIBGUILE_INTERFACE_AGE): use libtool versioning scheme.
+ (LIBGUILE_INTERFACE): use libtool versioning scheme.
+ (LIBGUILEQTHREADS_INTERFACE_CURRENT): use libtool versioning scheme.
+ (LIBGUILEQTHREADS_INTERFACE_REVISION): use libtool versioning scheme.
+ (LIBGUILEQTHREADS_INTERFACE_AGE): use libtool versioning scheme.
+ (LIBGUILEQTHREADS_INTERFACE): use libtool versioning scheme.
+
+ * GUILE-VERSION (GUILE_MINOR_VERSION): bump for new unstable.
+ (GUILE_MICRO_VERSION): reset for new unstable.
+ (LIBGUILE_INTERFACE_CURRENT): use libtool versioning scheme.
+ (LIBGUILE_INTERFACE_REVISION): use libtool versioning scheme.
+ (LIBGUILE_INTERFACE_AGE): use libtool versioning scheme.
+ (LIBGUILE_INTERFACE): use libtool versioning scheme.
+ (LIBGUILEQTHREADS_INTERFACE_CURRENT): use libtool versioning scheme.
+ (LIBGUILEQTHREADS_INTERFACE_REVISION): use libtool versioning scheme.
+ (LIBGUILEQTHREADS_INTERFACE_AGE): use libtool versioning scheme.
+ (LIBGUILEQTHREADS_INTERFACE): use libtool versioning scheme.
+
2001-08-07 Marius Vollmer <mvo@zagadka.ping.de>
* Makefile.am (EXTRA_DIST, SUBDIRS): Move test-suite from
+-*-text-*-
Guile Hacking Guide
Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001 Free software Foundation, Inc.
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 1.4-p4 --- 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
- 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
-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
* * 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
+ahead and remove the asterisk. The asterisks are used 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
Guile 1.4 release. If this were a Guile release, you would not see
this message. !!! [fixme: zonk on release]
-This is a 1.5 development version of Guile, Project GNU's extension
+This is a 1.7 development version of Guile, Project GNU's extension
language library. Guile is an interpreter for Scheme, packaged as a
library that you can link into your applications to give them their
own scripting language. Guile will eventually support other languages
development versions. Even middle numbers indicate stable versions.
This has been the case since the 1.3.* series.
-The next stable release will be version 1.6.0.
+The next stable release will be version 1.8.0.
Please send bug reports to bug-guile@gnu.org.
+-*-text-*-
This is a checklist for making Guile releases.
It's specific to the FSF's development environment; please don't put
it in the distribution.
Release Checklists ===================================================
-There are basically two phases to doing a release:
+There are basically three phases to doing a release:
+
+* "BRANCHING": Creating a stable development branch in CVS.
* "SPIFFING": Updating NEWS, README, INSTALL. Running tests. Getting
people to try builds on various machines. Getting everything
the FSF to put the disty on ftp.gnu.org. Posting announcements.
The "Spiffing" phase you might go through several times as you
-discover problems. The "Punting" phase you do only once.
+discover problems. The "Branching" and "Punting" phases you do only
+once.
+
+Branching checklist:
+
+* Announce when you're about to make the branch so that you have a
+ greater chance of people holding off on edits during the short
+ period while you're branching.
+
+* Make sure you're on the main trunk (see HACKING), and then create
+ the branch-root tag. i.e. -r branch-root_release-1-6. (Add the
+ exact command here next time I do it.)
+
+* Now create the branch with the branch tag. i.e. -r
+ branch_release-1-6. (Add exact command here next time I do it.)
+
+* Change the version numbers in GUILE-VERSION and README on the main
+ branch to reflect the new unstable version i.e. 1.7.0, if you're
+ currently creating the 1.6.X branch.
+Spiffing checklist:
-Spiffing checklist (NOTE: these instructions are out of date now that
-we're using cvs branches for stable vs unstable).
+* Make sure you're working on the stable branch (see HACKING for
+ details). Note that after following the branch checklist above, you
+ won't necessarily be.
-* Do a `cvs update -A', to get rid of any sticky tags in your working
- directory.
* Check for files that have changed a lot, but do not have up-to-date
copyright notices. This can be as simple as doing:
grep 'Copyright' * | grep -v 1999
and looking for files you know you've worked on a lot.
+
* Make sure NEWS, INSTALL, AUTHORS and THANKS and the docs are up to date:
+ Scan the ChangeLogs for user-visible changes, marked with an asterisk
at the left margin.
+ Fact-check INSTALL.
+ Make sure AUTHORS and THANKS are up-to-date (see also TODO).
+ Remove finished items from TODO (those marked w/ "+").
+
* Make sure the downloading addresses and filenames in README are
current. (But don't bump the version number yet. We do that below.)
+
* Check that the versions of aclocal, automake, autoconf, and autoheader
in your PATH match those given in HACKING. Note that the `make
dist' process always invokes these tools, even when all the
generated files are up to date.
Make specifically sure that the files in libltdl are generated using
the same tools as the rest.
+
* Rebuild all generated files in the source tree:
- + Install the .m4 files where aclocal will find them.
- + Run aclocal.
- + Run autoconf.
- + Run autoheader.
- + Run automake.
+ + run ./autogen.sh
+
* Verify that Guile builds and runs in your working directory.
-* Run the test suite, in guile-core/test-suite.
+
+* Run a "make check".
+
* Commit all changes to the CVS repository.
+
* Build a test distribution.
+ + update GUILE-VERSION each time you make a test distribution. For
+ example, just before the 1.6.0 release, we went through some
+ number of 1.5.X test releases.
+ BEFORE doing 'make dist', configure the source tree for build
in the same tree with configuration options
--enable-maintainer-mode --enable-debug-malloc --with-threads.
(We currently use a kludge which edits the dependencies generated
by automake so that Guile can be built in a directory separate
from the source tree also with non-GNU make programs.)
+
* Give the test disty to various people to try. Here's what you should do:
+ Unset GUILE_LOAD_PATH.
+ Remove automake and autoconf from your path, or turn off their
Once you've got a disty that seems pretty solid:
-* Choose new interface numbers for shared libraries.
-* Update the version numbers in GUILE-VERSION and README. (There are
- many places in README that need updating!) The Guile version
- number should have one of the following forms:
- N.M - a major release
- N.M.L, where L is even - a minor release
- N.M.L, where L is odd - sources from CVS or nightly snapshot
+* Make sure the shared library libtool versioning numbers are correct,
+ but first make sure you understand "Libtool's versioning system" in
+ the libtool info pages. Guile is going to be versioning it's shared
+ libraries independently, so follow the libtool rules for choosing
+ version numbers, but make sure to keep in mind that not everyone is
+ as good about this as they should be. If a library even changes the
+ layout of a data structure that's part of it's API in a backward
+ incompatible way, even if that data structure is handled as an
+ opaque object in the API, that library is probably no longer
+ compatible with previous versions.
+
+ A canonical ugly problem is this. Imagine you have libfoo and
+ libbar that both are linked against libbaz. Now imagine that you
+ create a libwhatever that uses both libfoo and libbar. What you
+ don't want to have happen is libfoo and libbar to be linked against
+ different versions of libbaz that produce incompatible instances of
+ the "same" data structure, and then have libwhatever get one version
+ of this data structure from libbaz via libfoo, and pass it back to a
+ different version of libbaz via libbar, a version of libbaz that
+ can't handle the newer/older struct from the other libbaz.
+
+* In general, there will be a number of libraries in guile that will
+ have to be versioned, and it would be best if the people who know
+ the most about the individual libs decide what the apropriate
+ CURRENT, REVISION, and AGE numbers for each one are. In general,
+ though, you have to be conservative. If no one is sure that the
+ libs are still compatible, then you *must* make the appropriate
+ changes under the assumption that they're not. Getting this wrong
+ is very BAD(TM).
+
+* Make the final update to the version numbers in GUILE-VERSION and
+ README. (There are many places in README that need updating!). See
+ HACKING for more information on how the version numbers are to be
+ chosen.
+
* Reformat the names in THANKS.
-* Do a `cvs update -A' of the whole tree, to look for any stray
+
+* Do a `cvs -z3 update -Pd' of the whole tree, to look for any stray
uncommitted or accidental changes.
+
* Commit your changes.
+
* Make one last test distribution.
Punting checklist:
* Add "Guile N.M released." entry to the top-level ChangeLog, and commit it.
-* Tag the entire source tree with a tag of the form "release_N_M"
- or "release_N_M_L".
+
+* Tag the entire source tree with a tag of the form "release_X-Y-Z",
+ i.e for release 1.6.0, use release_1-6-0
+
* Do a 'make dist'.
+
* Put the distribution up for FTP somewhere, and send mail to
ftp-upload@gnu.org, asking them to put it on prep.
+
* Send an announcement message to gnu-announce@gnu.org. Put a brief
summary of the changes in this release first, then "Obtaining
Guile", "Thanks", "About This Distribution," and "Nightly
Snapshots." If I remember correctly, the moderator will delay it
until the distribution appears on ftp.gnu.org. The announcement
text should be mostly taken from Guile's README file.
+
* Notify freshmeat.net, although they're probably watching anyway.
(They got the 1.3 release just fine.) I have no idea if
www.bowerbird.com.au will be something anyone refers to, but Guile
does have an entry there.
-* Tweak the version numbers in GUILE-VERSION, and README to indicate
- that the sources are a snapshot again. Snapshots should have
- version numbers of the form "N.M.L", where L is odd.
-* Start a new section of the NEWS file.
-* Start a new THANKS file.
+2001-08-15 Rob Browning <rlb@defaultvalue.org>
+
+ * Makefile.am (libguile_la_LDFLAGS): use libtool interface version
+ variables.
+ (libpath.h): change libguileversion to libguileinterface.
+
2001-08-07 Marius Vollmer <mvo@zagadka.ping.de>
* Makefile.am (EXTRA_DIST): Distribute ChangeLog-1996-1999 and
+2001-08-15 Rob Browning <rlb@defaultvalue.org>
+
+ * Makefile.am (libqthreads_la_LDFLAGS): use libtool interface version
+ variables.
+
2000-06-12 Mikael Djurfeldt <mdj@thalamus.nada.kth.se>
* Makefile.am (OMIT_DEPENDENCIES): Defined to contain the list of
HCoop / bpt / guile.git / commitdiff