Contributing Patches to Gambit Source Code

From Gambit wiki

Revision as of 16:02, 21 January 2008 by WikiSysop (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The Gambit source code repository is managed with the Mercurial distributed version control system.

Each developer uses a local copy of the central repository. The copies can be edited independently using any tool (editors, utility programs, etc). When a developer completes making a set of related changes they are recorded as a patch (also called a changeset). The developer can then contribute the patch by submitting it to the Gambit maintainers. If the patch is accepted then it will be applied to the repository by the Gambit maintainers and will become part of the central repository.

This page only gives the main Mercurial commands that are needed to manage the local copy of the central repository. Please read the Mercurial manual for detailed usage instructions.

Installing Mercurial

Prebuilt distributions of Mercurial and a source code distribution are available here. Please follow the installation instructions on the Mercurial web site. Note that version 0.9.1 is not recent enough; but 0.9.3 and 0.9.4 should work!

To simplify usage of Mercurial the configuration file $HOME/.hgrc should be created and contain at least your username. There are many settings that can be specified such as the editor to use for entering the comment attached to a patch. For example, to use emacs:

# Mercurial configuration file.
username = John Doe <>
editor = emacs -nw

If you want to use emacs' ediff to merge conflicting changes follow these instructions.

Obtaining a local copy of the Gambit source code

The best way to obtain a local copy of the Gambit source code is to download and unpack a recent source code release. Normally the most recent source code release should be downloaded.

tar zxf gambc-v4_0_0.tgz
mv gambc-v4_0_0 gambit

Note that in anticipation of making changes to the source code the directory has been renamed to gambit to avoid thinking it is a pristine copy of a particular release.

The system should then be prepared for modifications of the Scheme source code by creating a compiler for bootstrapping:

cd gambit
make bootstrap

This will create the gsc-comp compiler, which is executed when a Scheme source code file in the Gambit system must be compiled following a change.

Synchronizing with the central source code repository

The Mercurial pull command gets the local copy in synch with the central source code repository.

hg pull

The local source code files can then be updated to contain the latest source code with the Mercurial update command.

hg update

Note that the latest source code may be unstable. It is wise to check that it passes basic consistency checks by running the command make check.

The local source code files can be updated to a specific version with the -r option to the Mercurial update command.

hg update -r v4.0.0

Creating a patch

After making a set of related changes to the local copy of the repository, a patch is created with the command:

hg commit

This command will pop up an editor to compose a comment describing the nature of the patch. Please use a short but descriptive comment. You can save some typing by adding the comment on the command line:

hg commit -m "Fixed bug in ,b command"

To get a list of the patches (starting with the latest, i.e. the tip) use the log command:

hg log

Contributing a patch

A patch file can be created using the export command. To include only the most recent patch use:

hg export tip > my-patch

A range of patches can be included like this:

hg export 4:6 > my-patch

The patch file can then be submitted to the Gambit maintainers by sending the file by email to For example:

mail -s "[PATCH] ,b command fix" < my-patch

Releasing a new version of Gambit

This section contains some notes for the Gambit maintainers. It explains the steps to follow to release a new version of Gambit. The steps must be followed carefully or you may end up with a wedged system!

Assume the latest release of Gambit is v1.2.3 and the new release will be v4.5.6. Because Gambit is bootstrapped with itself, releasing a new version of Gambit is a two step process. The Gambit compiler must first be modified so that it generates C code which references the gambit.h file version v4.5.6. Then the gambit.h file, file, and other files with an embedded version number must be updated so they refer to version v4.5.6.

1. Creating a Gambit compiler for version v4.5.6

Make sure you have a working bootstrap compiler (gsc-comp) and save a copy just in case:

make check
make bootstrap
cp gsc-comp gsc-comp.old

Now modify the definition of compiler-version in the file gsc/_parms.scm so that it refers to v4.5.6 (using a single integer encoding of the version number):

(define (compiler-version) 405006) ;; 100000*major + 1000*minor + revision

Now create the new bootstrap compiler and commit the change with an easily identifiable comment:

make bootstrap
hg commit -m "[COMPILER CHANGES NEEDED FOR v4.5.6] Changed version in compiler"

Note that at this very point the new compiler will not pass the tests because the runtime still expects the old version number.

2. Upgrading the runtime files from version v1.2.3 to v4.5.6

For the C files generated from Scheme files the version numbers can easily be upgraded by compiling them from scratch using the new Gambit compiler. This will be done automatically by a make after a make clean. The other changes to the files are made by running the script misc/changev (this must be done first because it changes the file which produces the configure script which must be run again).

misc/changev 102003 405006
make clean
make check   # will fail test5 because version numbers have changed
mv tests/mix.c tests/test5.ok
make check   # this time all tests should pass
hg commit -m "[RUNTIME CHANGES NEEDED FOR v4.5.6] Changed version of runtime using misc/changev"
hg tag v4.5.6
hg push
3. Creating prebuilt installers for version v4.5.6

To create prebuilt installers for Mac OS and Windows you need a Mac with Xcode and Parallels workstation with Windows and the MinGW and Microsoft Visual C Express environments. The following command will build all variants of the installers (it takes about 2 hours in total):

make release

If no errors were reported then you can upload the new release to the Gambit repository using:

make publish-release

This will automatically send an announcement on the Gambit mailing list. You must manually update the main page of the Gambit Wiki so that it refers to the latest version.

Personal tools