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. REPACKING 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 gitweb: http://anonscm.debian.org/gitweb/ and http://anonscm.debian.org/gitweb/.

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. 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


4. COPYRIGHT FILE

The reason for repacking should be noted in debian/copyright (Debian Policy 12.5). According to http://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+


5. PACKAGE UPGRADES

From now on, uscan, svn-upgrade --uscan 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>


6. 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.


AUTHORS


CONTRIBUTORS


COPYRIGHT/LICENSE

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