to back out as a unit as bugs are fixed upstream.
</para>
<para>
-Unfortunately, the packaging system as such currently doesn't provide for
-separating the patches into several files. Nevertheless, there are ways to
-separate patches: the patch files are shipped within the Debian patch file
-(<filename>.diff.gz</filename>), usually within the
-<filename>debian/</filename> directory. The only difference is that they
-aren't applied immediately by dpkg-source,
-but by the <literal>build</literal>
-rule of <filename>debian/rules</filename>,
-through a dependency on the <literal>patch</literal> rule.
-Conversely, they are reverted in
-the <literal>clean</literal> rule,
-through a dependency on the <literal>unpatch</literal> rule.
+Fortunately, with the source format “3.0 (quilt)” it is now possible to
+keep patches separate without having to modify <filename>debian/rules</filename>
+to setup a patch system. Patches are stored in <filename>debian/patches/</filename>
+and when the source package is unpacked patches listed in
+<filename>debian/patches/series</filename> are automatically applied.
+As the name implies, patches can be managed with <command>quilt</command>.
+</para>
+<para>
+When using the older source “1.0”, it's also possible to separate patches
+but a dedicated patch system must be used: the patch files are shipped
+within the Debian patch file (<filename>.diff.gz</filename>), usually
+within the <filename>debian/</filename> directory. The only difference is
+that they aren't applied immediately by <command>dpkg-source</command>,
+but by the <literal>build</literal> rule of
+<filename>debian/rules</filename>, through a dependency on the
+<literal>patch</literal> rule. Conversely, they are reverted in the
+<literal>clean</literal> rule, through a dependency on the
+<literal>unpatch</literal> rule.
</para>
<para>
<command>quilt</command> is the recommended tool for this.
<title>Pristine source</title>
<para>
The defining characteristic of a pristine source tarball is that the
-<literal>.orig.tar.gz</literal> file is byte-for-byte identical to a tarball officially
+<literal>.orig.tar.{gz,bz2}</literal> file is byte-for-byte identical to a tarball officially
distributed by the upstream author. <footnote><para> We cannot prevent
upstream authors from changing the tarball they distribute without also
incrementing the version number, so there can be no guarantee that a pristine
If a difference arises later (say, if upstream notices that he wasn't using
maximal compression in his original distribution and then
re-<command>gzip</command>s it), that's just too bad. Since there is no good
-way to upload a new <literal>.orig.tar.gz</literal> for the same version, there is not even any
+way to upload a new <literal>.orig.tar.{gz,bz2}</literal> for the same version, there is not even any
point in treating this situation as a bug. </para> </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
that you must remove before uploading.
</para>
<para>
-In these cases the developer must construct a suitable <literal>.orig.tar.gz
+In these cases the developer must construct a suitable <literal>.orig.tar.{gz,bz2}
</literal> 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 <literal>.diff.gz</literal> and still has a version
+changes in a separate <literal>.diff.gz</literal> or <literal>.debian.tar.{gz,bz2}</literal> and still has a version
number composed of <literal><upstream-version></literal> and
<literal><debian-revision></literal>.
</para>
if you repackage source that could have been pristine.
</para>
<para>
-A repackaged <literal>.orig.tar.gz</literal>
+A repackaged <literal>.orig.tar.{gz,bz2}</literal>
</para>
<orderedlist numeration="arabic">
<listitem>
</listitem>
<listitem>
<para>
-<emphasis role="strong">should</emphasis> be gzipped with maximal compression.
+<emphasis role="strong">should</emphasis> be gzipped or bzipped with maximal compression.
</para>
</listitem>
</orderedlist>
-<para>
-The canonical way to meet the latter two points is to let <literal>dpkg-source
--b</literal> construct the repackaged tarball from an unpacked directory.
-</para>
</section>
<section id="changed-binfiles">
-<title>Changing binary files in <literal>diff.gz</literal></title>
+<title>Changing binary files</title>
<para>
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,
-<command>dpkg-source</command> 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 <filename>orig.tar.gz</filename>. Instead,
-include the file in the <filename>debian</filename> directory in
-<command>uuencode</command>d (or similar) form <footnote><para> 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.
-Note that you don't need to depend on <systemitem
-role="package">sharutils</systemitem> to get the <command>uudecode</command>
-program if you use <command>perl</command>'s <literal>pack</literal> function.
-The code could look like
-</para>
-&example-uu;
-</footnote>. The file would then be
-decoded and copied to its place during the build process. Thus the change will
-be visible quite easy.
-</para>
-<para>
-Some packages use <command>dbs</command> to manage patches to their upstream
-source, and always create a new <literal>orig.tar.gz</literal> file that
-contains the real <literal>orig.tar.gz</literal> 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 <literal>orig.tar.gz</literal> file, besides the
-real one, and copy them to the right place during the build process.
+tarball, or to add binary files that are not in it. This is fully supported
+when using source packages in “3.0 (quilt)” format, see the
+<citerefentry><refentrytitle>dpkg-source</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+manual page for details. When using the older format “1.0”, binary files
+can't be stored in the <filename>.diff.gz</filename> so you must store
+an <command>uuencode</command>d (or similar) version of the file(s)
+and decode it at build time in <filename>debian/rules</filename> (and move
+it in its official location).
</para>
</section>
* Mention docbook, POD and reST as convenient formats to write new manual
pages. Thanks to Charles Plessy and the debian-mentors list
for the idea and the patch. Closes: #557298
+ * Update several sections to take into account the new source formats “3.0
+ (quilt)” and “3.0 (native)”. Closes: #561952
+ * Drop reference to “dbs” in the section about including binary files.
-- Lucas Nussbaum <lucas@lucas-nussbaum.net> Tue, 22 Dec 2009 22:49:40 +0900
<listitem>
<para>
the (more common) packages where there's an original source tarball file
-accompanied by another file that contains the patches applied for Debian
+accompanied by another file that contains the changes made by Debian
</para>
</listitem>
</itemizedlist>
<para>
For the native packages, the source package includes a Debian source control
file (<literal>.dsc</literal>) and the source tarball
-(<literal>.tar.gz</literal>). A source package of a non-native package
+(<literal>.tar.{gz,bz2,lzma}</literal>). A source package of a non-native package
includes a Debian source control file, the original source tarball
-(<literal>.orig.tar.gz</literal>) and the Debian patches
-(<literal>.diff.gz</literal>).
+(<literal>.orig.tar.{gz,bz2,lzma}</literal>) and the Debian changes
+(<literal>.diff.gz</literal> for the source format “1.0” or
+<literal>.debian.tar.{gz,bz2,lzma}</literal> for the source format “3.0 (quilt)”).
</para>
<para>
-Whether a package is native or not is determined when it is built by
-<citerefentry> <refentrytitle>dpkg-buildpackage</refentrytitle>
-<manvolnum>1</manvolnum> </citerefentry>. The rest of this section relates
-only to non-native packages.
+With source format “1.0”, whether a package is native or not was determined
+by <command>dpkg-source</command> at build time. Nowadays it is recommended
+to be explicit about the desired source format by putting either “3.0 (quilt)”
+or “3.0 (native)” in <filename>debian/source/format</filename>.
+The rest of this section relates only to non-native packages.
</para>
<para>
The first time a version is uploaded which corresponds to a particular upstream
<para>
By default, <command>dpkg-genchanges</command> and
<command>dpkg-buildpackage</command> will include the original source tar file
-if and only if the Debian revision part of the source version number is 0 or 1,
-indicating a new upstream version. This behavior may be modified by using
+if and only if the current changelog entry has a different upstream version
+from the preceding entry. This behavior may be modified by using
<literal>-sa</literal> to always include it or <literal>-sd</literal> to always
leave it out.
</para>
</para>
<para>
Please notice that, in non-native packages, permissions on files that are not
-present in the .orig.tar.gz will not be preserved, as diff does not store file
-permissions in the patch.
+present in the .orig.tar.{gz,bz2} will not be preserved, as diff does not store file
+permissions in the patch. However when using source format “3.0 (quilt)”,
+permissions of files inside the <filename>debian</filename> directory are
+preserved since they are stored in a tar archive.
</para>
</section>
<listitem>
<para>
Be sure to use the <emphasis role="strong">exact same
-<filename>*.orig.tar.gz</filename></emphasis> as used in the
+<filename>*.orig.tar.{gz,bz2}</filename></emphasis> as used in the
normal archive, otherwise it is not possible to move the security fix into the
main archives later.
</para>
the package (see the <ulink
url="&url-debian-policy;">Debian Policy Manual</ulink> for
details). You must ensure that you include the
-<filename>.orig.tar.gz</filename> in your upload (even if you are not uploading
+<filename>.orig.tar.{gz,bz2}</filename> in your upload (even if you are not uploading
a new upstream version), or it will not appear in the new section together with
the rest of the package. If your new section is valid, it will be moved
automatically. If it does not, then contact the ftpmasters in order to
you wish to replace the upstream source tarball of your package, you will need
to upload it with a different version. An easy possibility is to replace
<filename>foo_1.00.orig.tar.gz</filename> with
-<filename>foo_1.00+0.orig.tar.gz</filename>. This restriction gives each file
-on the ftp site a unique name, which helps to ensure consistency across the
-mirror network.
+<filename>foo_1.00+0.orig.tar.gz</filename> or
+<filename>foo_1.00.orig.tar.bz2</filename>. This restriction gives each
+file on the ftp site a unique name, which helps to ensure consistency
+across the mirror network.
</para>
</section>
<literal>binary</literal> packages.
</para>
<para>
-Source packages consist of either two or three files: a
-<filename>.dsc</filename> file, and either a <filename>.tar.gz</filename> file
-or both an <filename>.orig.tar.gz</filename> and a
-<filename>.diff.gz</filename> file.
-</para>
-<para>
-If a package is developed specially for Debian and is not distributed outside
-of Debian, there is just one <filename>.tar.gz</filename> file which contains
-the sources of the program. If a package is distributed elsewhere too, the
-<filename>.orig.tar.gz</filename> file stores the so-called <literal>upstream
-source code</literal>, that is the source code that's distributed by the
-<literal>upstream maintainer</literal> (often the author of the software).
-In this case, the <filename>.diff.gz</filename> contains the changes made by
-the Debian maintainer.
+Depending on the format of the source package, it will consist
+of one or more files in addition to the mandatory <filename>.dsc</filename>
+file:
+<itemizedlist>
+<listitem><para>with format “1.0”, it has either a <filename>.tar.gz</filename>
+file or both an <filename>.orig.tar.gz</filename> and a
+<filename>.diff.gz</filename> file;</para></listitem>
+<listitem><para>with format “3.0 (quilt)”, it has a mandatory
+<filename>.orig.tar.{gz,bz2,lzma}</filename> upstream tarball,
+muliple optional <filename>.orig-<replaceable>component</replaceable>.tar.{gz,bz2,lzma}</filename> additional upstream tarballs</para> and a
+mandatory <filename>debian.tar.{gz,bz2,lzma} debian tarball</filename>;</listitem>
+<listitem><para>with format “3.0 (native)”, it has only
+a single <filename>.tar.{gz,bz2,lzma}</filename> tarball.</para></listitem>
+</itemizedlist>
+</para>
+<para>
+If a package is developed specially for Debian and is not distributed
+outside of Debian, there is just one
+<filename>.tar.{gz,bz2,lzma}</filename> file which contains the sources of
+the program, it's called a “native” source package. If a package is
+distributed elsewhere too, the
+<filename>.orig.tar.{gz,bz2,lzma}</filename> file stores the so-called
+<literal>upstream source code</literal>, that is the source code that's
+distributed by the <literal>upstream maintainer</literal> (often the
+author of the software). In this case, the <filename>.diff.gz</filename>
+or the <filename>debian.tar.{gz,bz2,lzma}</filename> contains the changes
+made by the Debian maintainer.
</para>
<para>
The <filename>.dsc</filename> file lists all the files in the source package
~ianmdlvl / developers-reference.git / commitdiff