=head1 NAME repacking - How to repackage upstream tarballs =head1 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 how to do it. =head1 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 C<+dfsg> (referring to the L, and used when non-free stuff is removed); another possibility is C<+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 F. =head1 2. REPACKAGING, the modern way The easiest way to repackage an upstream tarball is to use the I feature of L and L. =head2 2.1. Copyright file The reason for repacking should be noted in F (Debian Policy 12.5). According to L, this should be noted in the "Header paragraph" in the (Source or) B field. The files to be removed from the upstream tarball go into the B field in the "Header paragraph". Its syntax follows the one of the B stanzas, as defined in L. For an example, see "COPYRIGHT FILE EXAMPLES" in the L man page. =head2 2.2. Watch file We add a version suffix to the tarball (see L), so we also need to add repacksuffix and a dversionmangle in F: 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 L for the coverage of C.) =head2 2.3. Package upgrades From now on, B, B or B should "just work". =head1 3. REPACKAGING, in the olden days (This approach is still useful if repackaging is more than just removing files.) =head2 3.1. Repackaging scripts =head3 repack.stub Copy F (from our C package or its git repository) to the debian/ directory of the source package. It is a short shell script that calls F (also available in C). -- Note that F must be either in C<$PATH> or in F<../../scripts/repack.sh> later. F and F via the cgit web frontend: L and L. I to call C.> =head3 repack.local Create F. It is a shell fragment that gets sourced by F. You can set some variables there and use a few functions. For details see B. (Note that you can do other things in F since it is sourced by a shell script; please be careful :)) A typical F might look like: MANIFEST=1 rm docs/rfc* =head2 3.2. Watch file Since we add a version suffix we need a dversionmangle in F, and we also want to call F 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 =head2 3.3. Copyright file The reason for repacking should be noted in F (Debian Policy 12.5). According to L, this should be noted in the "Header paragraph" in the (Source or) Comment field. Add a copyright/license notice for F: Files: debian/repack.stub Copyright: 2009, Ryan Niebur License: Artistic or GPL-1+ =head2 3.4. Package upgrades From now on, B, B or B should "just work". Manually repacking is also possible with (old) repack.sh --upstream-version or (new, if C is installed) dpt repack.sh --upstream-version =head1 4. CAVEATS A common trap is to have the downloaded but not repacked tarball lying around (in F<../> or F<../tarballs/>); then B will happily stop its work, unless told so with I<--force>. =head1 AUTHORS =over =item * gregor herrmann L =back =head1 CONTRIBUTORS =over =item * Nicholas Bamber L =back =head1 COPYRIGHT/LICENSE 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 F and the Artistic License in F.