Merging and Building the ZMap version of the FooCanvas

[The system for doing this was completely rewritten/restructured in March 2010 so previous code/canvas versions have been archived.]

Overview

To use Gnomes foocanvas widget for ZMap we have to make a number of modifications and additions. You will need to install this altered version of foocanvas in order to build and use zmap. This directory contains the source files, diff files and scripts used to construct our version of the foocanvas. This is not straight forward because:

We manage this using diff and patch to merge our code into the standard foocanvas.

There are two separate processes, the whole thing has to be "boot-strapped", i.e. you can't make a diff between the zmap version and the original until you have a zmap version, from then on it's an "updating" process of downloading the latest foocanvas from gnome and merging our changes into it.

There are a set of scripts that download, diff, patch and package files to produce the zmap version of foocanvas.

The scripts require a certain directory structure and should be run from the cvs directory where they are found (the root directory for the zmap version of foocanvas):

              ----- gnome_foocanvas  (contains latest gnome foocanvas, this remains an
             |                        unaltered copy for reference when the merge goes wrong)
             |
foocanvas ---|----- merged_foocanvas (after processing contains the merge of the latest
             |                        gnome foocanvas with the zmap foocanvas code)
             |
              ----- zmap_foocanvas   (held in CVS, contains diffs and all source files
                                      that are new or modified for zmap foocanvas, this remains
                                      unaltered by the merge but is updated once the merge
                                      is successful)

The scripts are:

makecvs
compares source files in zmap_foocanvas with those in merged_foocanvas, any that have changed are put back into cvs. puts any that have back into zmap cvs.checks which source have changedand diff files have changed in zmap_foocanvas following a merge and updat
makediff
does a diff on gnome_foocanvas and zmap_foocanvas to create diff files for use by makepatch
makedist
copies, tars and gzips the merged zmap foocanvas for distribution, uses a date stamp on the tar file and extracted directory to avoid version clashes.
makegnome
retrieves the latest version of the gnome foocanvas into the directory gnome_foocanvas and makes a copy of that into merged_foocanvas in preparation for merging.
makepatch
takes the diff files made by makediff and applies them to the relevant files in gnome_canvas to make an up to date zmap version of the foo canva

Bootstrapping

This needed to be done initially but shouldn't need to be done again unless either zmap or foocanvas change radically in which case a remerge by hand may be appropriate.

  1. cd ZMap/foocanvas
  2. run "makegnome" to download the latest foocanvas from gnome into gnome_foocanvas directory and make a copy in merged_foocanvas.
  3. in a separate directory called zmap_foocanvas make a copy of any foocanvas files that need to be changed and add any new ones.
  4. run the script "makediff" to do a diff for changes required to the code in merged_foocanvas to merge in the zmap_foocanvas files. This step leaves a series of *.diff files in zmap_foocanvas.
  5. run "makepatch" to check that the diff files will patch the zmap foocanvas files into the new ones correctly, this should produce a full set of merged files in merged_foocanvas from which a distribution can be made.
  6. run "makecvs" to update the copies of source and diff files in zmap_foocanvas and check them back into cvs.
  7. run "makedist" to create a gzip'd tar file that can be installed on different systems to build the zmap foocanvas.

Updating

This is the standard procedure for either updating the version of gnome foocanvas or adding new zmap code to the merged foocanvas.

  1. cd ZMap/foocanvas
  2. run "makegnome" to download the latest foocanvas from gnome into gnome_foocanvas directory and make a copy in merged_foocanvas.
  3. run "makepatch" to check that the diff files will patch the zmap foocanvas files into the new ones correctly, this should produce a full set of merged files in merged_foocanvas from which a distribution can be made.
  4. if makepatch fails it will report all merges that failed and the patches that failed will be listed in *.rej files. For files that failed:

  5. run "makecvs" to update the copies of source and diff files in zmap_foocanvas and check them back into cvs.
  6. run "makedist" to create a gzip'd tar file that can be installed on different systems to build the zmap foocanvas.

Distributing and Building zmap foocanvas

The output of "makedist" is a gzip'd file that can be moved to a system and used to build zmap foocanvas on that system. The build requires that the system has the autoconf tools installed and will not work without them. It also requires that the user has the right permissions to install the zmap foocanvas into the chosen install directories (e.g. for /usr the user may need to able to use sudo).

The build install steps are:

  1. copy the gzip'd tar file to any convenient directory on the target machine.
  2. unzip and untar the file.
  3. cd to the foocanvas directory.
  4. If your autoconf is not installed in /usr or /usr/local then:
          export ACLOCAL_FLAGS=" -I <path to autoconf tools>"  # NOTE the spaces !!!!!
    
          e.g.
          
          export ACLOCAL_FLAGS=" -I /opt/local/share/aclocal"  # NOTE the spaces !!!!!
          
  5. Run the autoconf tools to make the ./configure script:
          ./autogen.sh --prefix=<directory where you will want to install foocanvas>
    
          e.g.
          
          ./autogen.sh --prefix=/opt/local
          
  6. Build the code:
          make
          
  7. Install the code:
          make install
          

Patch versioning

We use a combination of diff and patch to manage the merge of zmap foocanvas code into gnome foocanvas code. It is possible to add versioning to diff files to stop the wrong diff's being applied. The Prereq flag can be used for this purpose:

Prereq: 1.1.1
--- old.txt	2010-03-05 09:43:46.000000000 +0000
+++ new.txt	2010-03-05 09:43:05.000000000 +0000
@@ -1,5 +1,5 @@
 
-line 1 of target
+first line of target
 
 second line of target

All files in zmap_source would need to have the version number that follows "Prereq:" embedded in them and then patch would not do the merge unless the user forced it. Currently this is not implemented because it would be tedious.

Old notes from the previous build system

Notes from the previous system which may be useful if there are problems.



Creating the tar.gz
-------------------

$ gcvs co -d libfoocanvas-VERSION foocanvas

*** additional files fix ***

now we have additional files this step is a little more difficult and makes me
think we should just distribute a fully patched tar.gz.

$ cd libfoocanvas-VERSION/libfoocanvas/
$ patch -p0 -u < ../path/to/additional_files/Makefile.am.patch
$ cp ../path/to/additional_files/*.{c,h} .
****************************

now make all the autoconf stuff.  I had to do this first.
NOT $ export AUTOMAKE=~/bin/automake
try this...
$ export AUTOMAKE=/nfs/team71/acedb/zmap/prefix/LINUX/bin/automake

aclocal needs to be told where it's m4 files are.
~zmap/prefix/LINUX/share/aclocal
~zmap/prefix/LINUX/share/aclocal-1.9
are good bets at the moment. glib-gettext.m4 seems to be a dependancy 
which breaks everything silently....

NOT $ export ACLOCAL_FLAGS="-I ~/share/aclocal -I ~/share/aclocal-1.9"
try this...
$ export ACLOCAL_FLAGS='-I /nfs/team71/acedb/zmap/prefix/LINUX/share/aclocal -I /nfs/team71/acedb/zmap/prefix/LINUX/share/aclocal-1.9'
autogen.sh also requires gnome-common 

$ gcvs co gnome-common; ./configure; make; make install

For  the  last  build  (20060326)  I  had  to  modify  autogen.sh  and
configure.in as per  build.patch. Unsure as to why,  possibly a broken
autotools setup. 

$ ./autogen.sh

$ make dist-gzip
  this uses VERSION from configure.in (currently 0.1), I was using YYYYMMDD, who knows what's best.
  to change this edit the Makefile
-distdir = $(PACKAGE)-$(VERSION)
+distdir = $(PACKAGE)-YYYYMMDD


$ mv libfoocanvas-VERSION.tar.gz ZMap/foocanvas/support/
$ cvs add -ko -m'message' libfoocanvas-VERSION.tar.gz
$ cvs commit -m'message' libfoocanvas-VERSION.tar.gz

Should alter untar_patch.sh to set the version variable to VERSION and
tag the files as libfoocanvas-VERSION.
Test by running ./untar_patch.sh and seeing no errors in patch and a complete build