# How to upgrade to a new version of the boehm gc collector in Mercury.

WARNING: This process is difficult and should not be undertaken lightly. Before attempting to upgrade one should definitely discuss it on the mercury-reviews mailing list first.

Download the required version of the boehm garbage collector from the gc_source directory.

For the rest of this HOWTO we will assume that we download gc6.2alpha4.tar.gz.

Untar the archive.

    # zcat gc6.2alpha4.tar.gz | tar -xvf

Change into the directory.

    # cd gc6.2alpha4

Import the new source on to the vendor branch. Note that gc_6_2alpha4 should be a tag which corresponds to the version of the collector that you are importing.
Warning: this step can leave the repository in an inconsistent state.

    # cvs import -I \! mercury/boehm_gc gc gc_6_2alpha4

Unfortunately the last step can leave the repository in an inconsistent state. What happens is that some files have never been modified by the Mercury team, but they have been modified by various upgrades to the collector. These files live on the vendor branch. For example, before upgrading the collector the file, BCC_MAKEFILE, had the version number, 1.1.1.6. However, if the upgrade of the collector involves a modification to BCC_MAKEFILE then the new version will be 1.1.1.7 on the vendor branch and when you update boehm_gc you will get version 1.1.1.7 of BCC_MAKEFILE, which is obviously inconsistent.

How to fix this problem. Change into the boehm_gc directory of a clean check out of the Mercury system. Then issue the command

    # cvs update .
    U BCC_MAKEFILE

Note all the files which have been updated.

For each of the updated files, determine their revision number. Note it should be 1.1.1.x!

    # cvs status BCC_MAKEFILE
    ===================================================================
    File: BCC_MAKEFILE     Status: Up-to-date

       Working revision:    1.1.1.7 Tue Mar  5 10:16:49 1996
       Repository revision: 1.1.1.7 /home/mercury1/repository/mercury/boehm_gc/BCC_MAKEFILE,v
       Sticky Tag:          (none)
       Sticky Date:         (none)
       Sticky Options:      (none)

We now need to undo the update. Repeat for all the other files.

    # cvs update -j 1.1.1.7 -j 1.1.1.6 BCC_MAKEFILE

Check in the updates. The repository is now back in a consistent state.

We can now merge the new version onto the main branch. This requires that we identify the tag which was used to tag the last import of the collector.

    # cvs update -j gc_6_1alpha5 -j gc_6_2alpha4

Now resolve all of the conflicts. Bootcheck the compiler in at least asm_fast.gc and hlc.gc. Then use the new system to do an install (with non-empty LIBGRADES) and test that the installed version can compile some test programs. This is because the update may have added some new files which may not be copied into the install directories. Some build scripts may also need to be updated (in particular tools/bootcheck and scripts/prepare_tmp_dir_*).

Finally update .README.in (in the root directory of the mercury module) and bindist/bindist.README to reflect the current version of the collector being used.

Now one can check it in!

Last update was $Date: 2010-03-02 05:26:58 $ by $Author: juliensf $@cs.mu.oz.au.