repacking - How to repackage upstream tarballs
Sometimes it is necessary to repack an upstream tarball. This should happen rarely and only with good reasons -- usually in order to remove non-free material.
This how-to provides an overview about how to do it.
First of all, decide about the version suffix.
Repacked tarballs are denoted by adding a suffix to the upstream version number,
the most prominent example being +dfsg (referring to the DFSG,
and used when non-free stuff is removed); another possibility is +ds for "Debian Source",
sometimes used when e.g.
included third-party libraries are removed or when the upstream distribution has a debian directory.
When you have chosen your version suffix, add it to the topmost entry in debian/changelog.
The easiest way to repackage an upstream tarball is to use the Files-Excluded feature of uscan(1) and mk-origtargz(1).
The reason for repacking should be noted in debian/copyright (Debian Policy 12.5). According to https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/, this should be noted in the "Header paragraph" in the (Source or) Comment field.
The files to be removed from the upstream tarball go into the Files-Excluded field in the "Header paragraph". Its syntax follows the one of the Files stanzas, as defined in Copyright-Format 1.0.
For an example, see "COPYRIGHT FILE EXAMPLES" in the uscan(1) man page.
We add a version suffix to the tarball (see above), so we also need to add repacksuffix and a dversionmangle in debian/watch:
Change your watch file to something like:
version=4
opts=dversionmangle=auto,repacksuffix=+dfsg \
https://metacpan.org/release/The-Module .*/The-Module-v?@ANY_VERSION@@ARCHIVE_EXT@$
(Check uscan(1) for the coverage of auto.)
From now on, uscan, dpt import-orig or gbp import-orig --uscan should "just work".
(This approach is still useful if repackaging is more than just removing files.)
Copy repack.stub (from our pkg-perl-tools package or its git repository) to the debian/ directory of the source package.
It is a short shell script that calls repack.sh (also available in pkg-perl-tools). -- Note that repack.sh must be either in $PATH or in ../../scripts/repack.sh later.
repack.sh and repack.stub via the cgit web frontend: https://salsa.debian.org/perl-team/modules/packages/pkg-perl-tools/raw/master/scripts/repack.sh and https://salsa.debian.org/perl-team/modules/packages/pkg-perl-tools/raw/master/examples/repack.stub.
TODO: Update repack.stub to call dpt repack.sh.
Create debian/repack.local. It is a shell fragment that gets sourced by repack.sh.
You can set some variables there and use a few functions. For details see perldoc repack.stub.
(Note that you can do other things in debian/repack.local since it is sourced by a shell script; please be careful :))
A typical debian/repack.local might look like:
MANIFEST=1
rm docs/rfc*
Since we add a version suffix we need a dversionmangle in debian/watch, and we also want to call debian/repack.stub automatically.
Change your watch file to something like:
version=3
opts=dversionmangle=s/\+dfsg$// \
https://metacpan.org/release/The-Module .*/The-Module-v?(\d[\d.-]+)\.(?:tar(?:\.gz|\.bz2)?|tgz|zip)$ \
debian sh debian/repack.stub
The reason for repacking should be noted in debian/copyright (Debian Policy 12.5). According to https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/, this should be noted in the "Header paragraph" in the (Source or) Comment field.
Add a copyright/license notice for debian/repack.stub:
Files: debian/repack.stub
Copyright: 2009, Ryan Niebur <ryan@debian.org>
License: Artistic or GPL-1+
From now on, uscan, dpt import-orig or gbp import-orig --uscan should "just work".
Manually repacking is also possible with (old)
repack.sh --upstream-version <ver> <downloaded file>
or (new, if pkg-perl-tools is installed)
dpt repack.sh --upstream-version <ver> <downloaded file>
A common trap is to have the downloaded but not repacked tarball lying around (in ../ or ../tarballs/); then uscan will happily stop its work, unless told so with --force.
Copyright (c) 2011-2018 by the individual authors and contributors noted above. All rights reserved. This document is free software; you may redistribute it and/or modify it under the same terms as Perl itself.
Perl is distributed under your choice of the GNU General Public License or the Artistic License. On Debian systems, the complete text of version 1 of the GNU General Public License can be found in /usr/share/common-licenses/GPL-1 and the Artistic License in /usr/share/common-licenses/Artistic.