                pkg-components

PURPOSE

To provide a means of managing the build of components in a Debian package.

HISTORY

Typically there is a one-to-one correspondence between perl modules and
perl debian packages. However the ftp masters generally disallow packages
where the packaging takes up more diskspace than the code. To get round this
related modules are sometimes packaged as a bundle. The code that manages
this is copied from package to package and gets harder to maintain as it
evolves.

The most significant bit of support provided by the Debian infrastructure
for packaging bundles is described in

http://raphaelhertzog.com/2010/09/07/how-to-use-multiple-upstream-tarballs-in-debian-source-packages/

However one must notice this quote:

    The supplementary tarball is now part of the source package but
    we're not making anything useful out of it. We have to modify
    debian/rules... to install the new files in the binary package.

So this package aims to take that support to the next level. Certainly
it aims to do better than the ad hoc code currently in Debian perl packages.

Currently it only supports the core functionality of integrating the 
components into the build process. However there is nothing in the package
which is perl specific, apart from the default build stage scripts which
can easily be overridden.

TODO

* The uscan-components script is somewhat in a beta state at the moment.
* Probably ought to make the whole thing "build system" aware.
* Need better support for other bits and pieces like component changelogs.
* For components relying on Makefile.PL it seems to be necessary to set
  PERL5LIB in the testing build stage
* Eventually could do with interest from other languages .
* File::Slurp might be better than Perl6::Slurp.

INSTRUCTIONS

These instructions assume you have installed the 'pkg-components' package.

1. First prepare your core package as you would normally. So now for 
version V of your package P you have a P directory and the files:
P_V.orig.tar.gz; P_V-1.debian.tar.gz; P_V-1.dsc.

2. Now suppose you have component upstream tarballs C_A_v1.tar.gz and
C_B_v1.tar.gz. You need to choose names for these components which are purely
alphanumeric . Actually the component names can also contain the hyphen "-".
Assume that we name these ca and cb. The directory inside the source
directory corresponding to the component must be this component name
and the sub tar ball must also be renamed according to this name.
All these rules come from with the dpkg-source executable.

3. Copy the tarballs to the appropriate name
    cp C_A_v1.tar.gz P_V.orig-ca.tar.gz
    cp C_B_v1.tar.gz P_V.orig-cb.tar.gz

4. Unpack the component tarballs into those sub-directories.
    cd P
    tar -zxf ../P_V.orig-ca.tar.gz
    tar -zxf ../P_V.orig-cb.tar.gz

4. Create component sub-directories.
    mv C_A-v1 ca
    mv C_B-v1 cb

6. Make a components sub-directory and one for each component.
    mkdir debian/components
    mkdir debian/components/ca
    mkdir debian/components/cb

7. In your debian/rules file add the '--with components' argument
to the 'dh' command.

8. To build the copyright file from appropriate components
but the copyright file for the main module in debian/components/copyright.
In each debian/components/[C]/copyright put the copyright file
for that component but minus the header stanza. Also the license stanzas
can be ommitted if they are present else where. The generated copyright
files must be added to the debian/clean file.

9. You use the substvar infrastructure to manage the component dependencies
separately from the main dependencies. To do this creaate a control file
in the component directory, say debian/components/x/control .
dh_components will then create subtvar variables x:Depends, x:Breaks and so
on.

10. Make sure your build dependencies require at least pkg-components (>= 0.3).

11. You probably want to list the components and their versions in the long
description.

12. For each component directory you should have a watch file and a
version file. The latter just contains the upstream version of
the component and is maintained by the uscan-components script.

12. If you are lucky this is all you will need to do. What dpkg-buildpackage
will do with what you have done is for each component and each build stage
(one of: copy, patch, config, build, test, install) run the appropriate
little script.

13. The pkg-components package comes with an example README.source explaining
the peculiarities of a package built using pkg-components.

14. The default build stage scripts are located in
/usr/share/pkg-components/build_stages. You can vary one or more
build stages for the entire package by having an appropriately named script 
in the debian/components directory. You can vary a build stage for a specifc
component by putting the relevant script in that components directory below
debian/components.

DEPRECATED

It seems that the patch build stage is probably unncessary because of
how dpkg-source handles patches. Please consider the patch build stage
deprecated and do not use it. If this turns out not to be true please 
raise a bug report.

ISSUES

It seems to be relatively easy for a dummy patch to infect the build.
It would be nice to understand the issue in sufficient detail to be able
to defend against it. In the meantime downloading fresh correct source from the
repository and using fresh tar balls seems to resolve this issue.

The build stage scripts are currently in a state of hacky flux. There is a need
to rewrite them from scratch and to think about how to generalize them.
