NAME

repacking - How to repackage upstream tarballs

0. INTRODUCTION

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 an easy way to do it.

1. PACKAGE VERSION

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.

2. REPACKAGING, the modern way

The easy way to repackage an upstream tarball is to use the Files-Excluded feature of uscan(1) and mk-origtargz(1).

2.1. Copyright file

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.

2.2. Watch file

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=3
    opts=dversionmangle=s/\+dfsg$//,repacksuffix=+dfsg \
    https://metacpan.org/release/The-Module    .*/The-Module-v?(\d[\d.-]+)\.(?:tar(?:\.gz|\.bz2)?|tgz|zip)$

2.3. Package upgrades

From now on, uscan, dpt import-orig or gbp import-orig --uscan should "just work".

3. REPACKAGING, in the olden days

(This approach is still useful if repackaging is more than just removing files.)

3.1. Repackaging scripts

repack.stub

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://anonscm.debian.org/cgit/pkg-perl/packages/pkg-perl-tools.git/plain/scripts/repack.sh and https://anonscm.debian.org/cgit/pkg-perl/packages/pkg-perl-tools.git/plain/examples/repack.stub.

TODO: Update repack.stub to call dpt repack.sh.

repack.local

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; just be careful :))

A typical debian/repack.local might look like:

    MANIFEST=1
    rm docs/rfc*

3.2. Watch file

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

3.3. Copyright file

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+

3.4. Package upgrades

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>

4. CAVEATS

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.

AUTHORS

CONTRIBUTORS

COPYRIGHT/LICENSE

Copyright (c) 2011-2016 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.