How to customize a guile-gnome bzr distribution

[Neil Jerram]

Hi all,

I've been working sporadically for a few months on building Guile
bindings for the APIs on Nokia's 770 internet tablet, starting from
the fantastic g-wrap and guile-gnome packages.  I've hit some tricky
and interesting details along the way, so I thought it would be a good
idea to document those here, for anyone else making a similar journey
in the future.

Andy, if you think any of this would work as guile-gnome
documentation, please feel free to hack around with and incorporate
any of it that you see fit.

Regards,
        Neil


* Starting points and requirements

** guile-gnome structure

guile-gnome is structured as a framework and a collection of
"subpackages".  The subpackages are corba, atk, gtk, libglade,
gstreamer, etc., and the source code for each subpackage is contained
in a top-level subdirectory with the same name.  A subpackage can be
dependent on other subpackages (which must therefore be built first),
and guile-gnome provides a way for the subpackage's code to express
this.

Then there are also "packages".  A package is just a set of
subpackages that you plan to build and release together.  For example,
the "guile-gnome-gstreamer" package contains only the gstreamer
subpackage, while the "guile-gnome-platform" package contains all the
subpackages connected with GNOME UI work: atk, glib, gtk, libgnomeui,
libglade, and so on.  Packages are defined by the top-level PACKAGES
file, which reads (very simply) like this:

...
guile-gnome-streamer: gstreamer
guile-gnome-platform: atk glib gtk libgnomeui libglade ...
...

** guile-gnome build process

The designed build process for guile-gnome is as follows.

1. Check the guile-gnome framework out of bzr.

2. Run "scripts/get-packages <package>" to check all the subpackages
   out of bzr for whichever package it is you want to build.

3. Run "./autogen.sh --prefix=<installed Guile's prefix>".  This will:

   - create the top-level configure.ac, based on .ac fragments in all
     the present subdirectories

   - run automake, aclocal, etc. etc. - eventually creating
     "configure"

   - run "./configure --enable-maintainer-mode --prefix=<installed
     Guile's prefix>".

4. Run "make".

Then, at this point, you can either just "sudo make install", if you
only want local installation, or "make dist", if you want to
redistribute an automade distribution for your chosen package.  If you
choose the "make dist" option, you should get a
<package>-<version>.tar.gz which can be unpacked and built in the
standard "./configure; make; sudo make install" way.

** Requirements for the 770 internet tablet

The requirements for the 770 are the combination of four things.

1. Bindings for several subpackages that guile-gnome already provides:
   atk, pango, gtk, glib, libglade, dbus, gstreamer.

2. Bindings for a handful of 770-specific APIs, such as "hildon"
   (770-specific graphical widgets) and "libosso" (a 770-specific
   layer on top of D-BUS).  guile-gnome does not already provide
   these.

3. Debianization.  The 770 uses Debian packaging, so whatever I build
   needs to end up as a set of Debian packages.

4. Cross-compilation.  All packages for the 770 need to be built and
   packaged in a 770 emulation environment called scratchbox.

* Ideal customization process

After much trial and error, here's what I believe to be the optimal
process for meeting the above requirements.  In the following I use
the overall package name "guile-maemo", because the 770 platform as a
whole is known as Maemo.

1. Check the guile-gnome framework out of bzr.

2. Edit the top-level PACKAGES file to add two lines to it:

guile-maemo-bzr: atk defs glib pango gtk libglade dbus gstreamer
guile-maemo: atk defs glib pango gtk libglade dbus gstreamer hildon osso

The guile-maemo-bzr line is for scripts/get-packages and so should
include all of the subpackages that we want from the bzr repository.

The guile-maemo line is for ./autogen.sh and so should include all of
the subpackages that we want to build, including any additional ones
that did not come from bzr.

3. Run "scripts/get-packages guile-maemo-bzr" to check out all the
   subpackages that we want from the bzr repository.

4. Write (or otherwise obtain) the code for the subpackages that don't
   come from bzr.

This is a non-trivial step :-), but basically what is required is a
new top-level subdirectory for each new subpackage that you want to
add.  The best way to proceed is to use one of the existing
subpackages as a reference, and copy and modify that as appropriate.

(A lot more could be written here about what files are important at
various locations within the subtree for each new subpackage; I don't
have that ready right now though.)

5. Switch into the scratchbox emulation environment.

Empirically, it seems that all the steps from here onwards need to be
performed within the target build environment - which in my case means
the "scratchbox" emulation environment for the Nokia 770.

Theoretically, this obviously makes sense for the steps from
./configure onwards.  I think I found that it was needed for the
autoconf steps as well - I'm not sure why.  (Perhaps, in retrospect,
just because guile-gnome's ./autogen.sh automatically runs
./configure.)

6. Run "./autogen.sh --prefix=<installed Guile's prefix>".

This will create the top-level configure.ac, as already described, and
then run automake, aclocal, etc. and "./configure
--enable-maintainer-mode --prefix=<installed Guile's prefix>".

A key detail of this process is that autogen.sh will look at what
top-level directories are present, and compare this set against the
subpackage sets defined in the PACKAGES file.  The name of the package
line that matches ("guile-maemo" in our case) will be encoded in the
results of the autoconfery and will - for example - be used in the
name of the generated tarball if you do a "make dist".

7. Run "make".

I'm not sure is this is strictly needed before the next step, but it's
a good idea anyway to check at this point that everything builds
correctly.

8. Run "make dist".

This will produce <package-name>-<version>.tar.gz, which in our case
is guile-maemo-2.7.99.tar.gz.

This is what we are going to take as our starting point for the
Debianization process.  In order words, this tarball is what Debian
policy calls the "upstream source".

9. Debianization.

>From this point on, the Debianization process is completely standard -
dh_make etc. - so I won't describe it in detail.

One slightly interesting choice, however, is whether to end up with
one .deb containing all the subpackages, or one .deb for each
subpackage.  Either option can be achieved in practice just by
changing debian/control and other files in the debian directory.  My
current feeling is that one .deb per subpackage is better.  (With
correct specification of any dependencies, of course.)

- Neil Jerram <address@hidden>, January 2007