+
+ <sect1 id="bpp-origtargz">
+ <heading>Best practices for <file>orig.tar.gz</file> files</heading>
+ <p>
+ There are two kinds of original source tarballs: Pristine source
+ and repackaged upstream source.
+ </p>
+ <sect2 id="pristine source">
+ <heading>Pristine source</heading>
+ <p>
+The defining characteristic of a pristine source tarball is that the
+.orig.tar.gz file is byte-for-byte identical to a tarball officially
+distributed by the upstream author.
+<footnote>
+We cannot prevent upstream authors from changing the tarball
+they distribute without also upping the version number, so
+there can be no guarantee that a pristine tarball is identical
+to what upstream <em>currently</em> distributing at any point in
+time. All that can be expected is that it is identical to
+something that upstream once <em>did</em> distribute.
+
+If a difference arises later (say, if upstream notices that he wasn't
+using maximal comression in his original distribution and then
+re-<tt>gzip</tt>s it), that's just too bad. Since there is no good way
+to upload a new .orig.tar.gz for the same version, there is not even
+any point in treating this situation as a bug.
+</footnote>
+This makes it possible to use checksums to easily verify that all
+changes between Debian's version and upstream's are contained in the
+Debian diff. Also, if the original source is huge, upstream authors
+and others who already have the upstream tarball can save download
+time if they want to inspect your packaging in detail.
+ </p>
+ <p>
+There is no universally accepted guidelines that upstream authors
+follow regarding to the directory structure inside their tarball, but
+<prgn>dpkg-source</prgn> is nevertheless able to deal with most
+upstream tarballs as pristine source. Its strategy is equivalent to
+the following:
+ </p>
+ <p>
+ <enumlist>
+ <item>
+It unpacks the tarball in an empty temporary directory by doing
+
+<example>
+zcat path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf - +</example>
+ </item>
+ <item>
+If, after this, the temporary directory contains nothing but one
+directory and no other files, <prgn>dpkg-source</prgn> renames that
+directory to
+<tt><packagename>-<upstream-version>(.orig)</tt>. The name
+of the top-level directory in the tarball does not matter, and is
+forgotten.
+ </item>
+ <item>
+Otherwise, the upstream tarball must have been packaged without a
+common top-level directory (shame on the upstream author!). In this
+case, <prgn>dpkg-source</prgn> renames the temporary directory
+<em>itself</em> to
+<tt><packagename>-<upstream-version>(.orig)</tt>.
+ </item>
+ </enumlist>
+ </p>
+ </sect2>
+ <sect2 id="repackaged origtargz">
+ <heading>Repackaged upstream source</heading>
+ <p>
+You <strong>should</strong> upload packages with a pristine source
+tarball if possible, but there are various reasons why it might not be
+possible. This is the case if upstream does not distribute the source
+as gzipped tar at all, or if upstream's tarball contains non-DFSG-free
+material that you must remove before uploading.
+ </p>
+ <p>
+In these cases the developer must construct a suitable .orig.tar.gz
+file himself. We refer to such a tarball as a "repackaged upstream
+source". Note that a "repackaged upstream source" is different from a
+Debian-native package. A repackaged source still comes with
+Debian-specific changes in a separate <tt>.diff.gz</tt> and still has
+a version number composed of <tt><upstream-version></tt> and
+<tt><debian-revision></tt>.
+ </p>
+ <p>
+There may be cases where it is desirable to repackage the source even
+though upstream distributes a <tt>.tar.gz</tt> that could in principle
+be used in its pristine form. The most obvious is if
+<em>significant</em> space savings can be achieved by recompressing
+the tar archive or by removing genuinely useless cruft from the
+upstream archive. Use your own discretion here, but be prepared to
+defend your decision if you repackage source that could have been
+pristine.
+ </p>
+ <p>
+A repackaged .orig.tar.gz
+ </p>
+ <p>
+ <enumlist>
+ <item>
+<p>
+<strong>must</strong> contain detailed information how
+the repackaged source was obtained, and how this can be reproduced, in
+<file>README.Debian-source</file> or a similar file. This file should
+be in the <file>diff.gz</file> part of the Debian source package,
+usually in the <file>debian</file> directory, <em>not</em> in the
+repackaged <file>orig.tar.gz</file>. It is also a good idea to provide a
+<tt>get-orig-source</tt> target in your <file>debian/rules</file> file
+that repeats the process, as described in the Policy Manual, <url
+id="&url-debian-policy;ch-source.html#s-debianrules" name="Main
+building script: debian/rules">.
+</p>
+ </item>
+ <item>
+<strong>should not</strong> contain any file that does not come from the
+upstream author(s), or whose contents has been changed by you.
+<footnote>
+As a special exception, if the omission of non-free files would lead
+to the source failing to build without assistance from the Debian
+diff, it might be appropriate to instead edit the files, omitting only
+the non-free parts of them, and/or explain the situation in a
+README.Debian-source <!-- or similarly named --> file in the root of the source
+tree. But in that case please also urge the upstream author to make
+the non-free components easier seperable from the rest of the source.
+</footnote>
+ </item>
+ <item>
+<p>
+<strong>should</strong>, except where impossible for legal reasons,
+preserve the entire building and portablility infrastructure provided
+by the upstream author. For example, it is not a sufficient reason for
+omitting a file that it is used only when building on
+MS-DOS. Similarly, a Makefile provided by upstream should not be
+omitted even if the first thing your <file>debian/rules</file> does is
+to overwrite it by running a configure script.
+</p>
+<p>
+(<em>Rationale:</em> It is common for Debian users who need to build
+software for non-Debian platforms to fetch the source from a Debian
+mirror rather than trying to locate a canonical upstream distribution
+point).
+</p> </item>
+ <item>
+<strong>should</strong> use
+<tt><packagename>-<upstream-version>.orig</tt> as the name
+of the top-level directory in its tarball. This makes it possible to
+distinguish pristine tarballs from repackaged ones. + </item>
+ <item>
+<strong>should</strong> be gzipped with maximal compression.
+ </item>
+ </enumlist>
+ </p>
+ <p>
+The canonical way to meet the latter two points is to let
+<tt>dpkg-source -b</tt> construct the repackaged tarball from an
+unpacked directory.
+ </p>
+ </sect2>
+ <sect2 id="changed-binfiles">
+ <heading>Changing binary files in <tt>diff.gz</tt></heading>
+ <p>
+Sometimes it is necessary to change binary files contained in the
+original tarball, or to add binary files that are not in it.
+If this is done by simply copying the files into the debianized source
+tree, <prgn>dpkg-source</prgn> will not be able to handle this. On the
+other hand, according to the guidelines given above, you cannot
+include such a changed binary file in a repackaged
+<file>orig.tar.gz</file>. Instead, include the file in the
+<file>debian</file> directory in <prgn>uuencode</prgn>d (or similar)
+form
+<footnote>
+The file should have a name that makes it clear which binary file it
+encodes. Usually, some postfix indicating the encoding should be
+appended to the original filename.
+</footnote>.
+The file would then be decoded and copied to its place during the
+build process. Thus the change will be visible quite easy.
+</p>
+<p>
+Some packages use <prgn>dbs</prgn> to manage patches to their upstream
+source, and always create a new <tt>orig.tar.gz</tt> file that
+contains the real <tt>orig.tar.gz</tt> in its toplevel directory. This
+is questionable with respect to the preference for pristine source. On
+the other hand, it is easy to modify or add binary files in this case:
+Just put them into the newly created <tt>orig.tar.gz</tt> file,
+besides the real one, and copy them to the right place during the
+build process.
+ </p>
+ </sect2>
+ </sect1>
+
+
~ianmdlvl / developers-reference.git / commitdiff