Thinking about bundles
I have been looking into the packaging of bundles - that is packages
that have multiple upstream sources. There was recently an article on
the subject:
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."
I have recently looked into a number of bundle packages. All of them
have different implementations of the debian/rules although the ones I
looked at had clearly once had a common parent. Hence I have been kept
awake at night thinking how this situation might be improved. The
following proposal draws upon the ideas I have picked up from those bundles.
All those bundles were perl ones though I think I have managed to make
this proposal language neutral.
Proposal: dh_components
Purpose: Support for additional components in debian/rules
To be activated one would need to run "dh --with components $@" and also
there would have to be a "debian/components" directory.
Directory structure
============
debian/components/ rules
" / " / copyright.in
" / " / [component1] / rules
" / " / " / control
" / " / " / copyright
" / " / " /patches
" / " / " /watch
For each component there would be directory below the debian/components
directory. Files that could be in an individual directory are as follows:
watch: Just the same as a normal watch file.
patches: Just the same as a normal quilt patches directory
copyright: This would not be a full copyright file. It would consist
only of the stanzas relevant to the component.
control: This would be in the same format as the main control file but
would only accept certain fields - namely a long description fragment
and various dependencies such a Depends, Recommends, Suggests, Conflicts
etc. Build dependencies would not be supported as there would be no way
such information could be used.
rules: This would be an executable description described in more detail
later.
Of the above file I think only the copyright and control files would be
mandatory. There would optionally be a rules file at the
debian/components directory.
The '--with' option
===========
There would need to be a 'Debian/Debhelper/Sequence/components.pm' the
sole purpose of which would be to install the 'dh_components' hook just
before 'dh_installdocs'.
The 'uscan_components' script
===================
This would be a wrapper around uscan. It would iterate through the
components and run 'uscan --watchfile [file]' specifying the components
watch file and passing on any arguments that make sense. It would make
sense to integrate this functionality into uscan, but this script would
be a work around whilst the project is experimental.
The 'dh_components' script
==================
This would have three jobs:
* Patching together the copyright file from a template
'debian/components/copyright.in' and the copyright files in the
component directories.
* Patching together various variable substitutions such as
${components:Depends}, ${components:Recommends}, ${components:Conflicts}
and notably ${components:Description} from the component control files.
These should be used in the main debian/control file.
* Running the build process for each component. The build process would
consist of the following phases:
1.) *copy* from the component source directory to a build area
2.) *patch* the source in the build area using the components patches
directory. This includes a link from [component source
copy]/debian/patches to [component patches area] so that the quilt
config which works for the main package should also work for the component.
3.) *configure* the copy in the build area
4.) *build* the source in the build area
5.) *test* the source in the build area
6.) *install* the source from the build area to the package install area
(usually debian/[package]/...).
Exactly how this would work would depend on the combination of the rules
file in the "components" directory and the component "rules" files in
each individual components directory. This would allow some components
to be handled in a standard package wide manner and others to get
special treatment -- possibly only at one build stage. There would also
be arguments to instruct dh_components to only handle certain components
and only certain tasks or build stages. This would be useful in
debugging and managing component patches (see below)
The 'rules' file
=========
The 'rules' file must be an executable script. The spec is intended to
make it easily implementable as a make file though this should not be
assumed. It should pick up the component being worked on from the
DH_COMPONENT environment variable and the build stages 1-6 should all be
targets. The rules file is not required to implement all six targets but
it must implement one extra target: 'list'. This should print out the
list of targets that it can handle.
The rule for each build stage must check if the previous stage has
completed, running that uncompleted stage if it knows how
and failing if not. On completion it must mark that the stage is
completed with a stamp file in the build area.
The build process in detail
================
For each component [component]
Check if debian/components/rules exists and is executable
Check the results of 'DH_COMPONENT=[component] debian/components/rules list'
Check if debian/components/[component]/rules exists and is executable
Check the results of 'DH_COMPONENT=[component]
debian/components/[component]/rules list'
For each [stage] in copy patch configure build test install
If debian/components/[component]/rules can handle [stage]
DH_COMPONENT=[component] debian/components/[component]/rules [stage]
Else
If debian/components/rules can handle [stage]
DH_COMPONENT=[component] debian/components/rules [stage]
Else
abort
Fi
Fi
Done
Model rules scripts
============
The package would need to come with a number of model rules scripts --
one for each of perl, python etc. So at its simplest someone packaging a
bundle of perl modules would only need to copy the model script for perl
to 'debian/components/rules' (or maybe dh-make-perl would do that?).
Working with patches
==============
Assuming just one patch
1.) dh_components -t copy [component]
2.) cd [component build area]
3.) quilt push
4.) edit files
5.) quilt refresh
6.) quilt header -e
7.) quilt pop
begin:vcard
fn:Nicholas Bamber
n:Bamber;Nicholas
org:Periapt Technologies
email;internet:nicholas@periapt.co.uk
x-mozilla-html:FALSE
url:http://www.periapt.co.uk
version:2.1
end:vcard
Reply to: