chiark / gitweb /
fix build failures
authoraba <aba@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Mon, 24 Jan 2005 13:51:40 +0000 (13:51 +0000)
committeraba <aba@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Mon, 24 Jan 2005 13:51:40 +0000 (13:51 +0000)
git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@2840 313b444b-1b9f-4f58-a734-7bb04f332e8d

developers-reference.sgml

index e5cec45..b84e1f5 100644 (file)
@@ -6,7 +6,7 @@
   <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!ENTITY cvs-rev "$Revision: 1.255 $">
+  <!ENTITY cvs-rev "$Revision: 1.256 $">
 
   <!-- if you are translating this document, please notate the CVS
        revision of the original developer's reference in cvs-en-rev -->
@@ -1217,7 +1217,7 @@ $cfg{'delayed'} = {
 </example>
 Once you've made that change, <prgn>dupload</prgn> can be used to
 easily upload a package in one of the delayed directories:
-<example>DELAY=5 dupload --to delayed &lt;changes-file&gt;</example>
+<example>DELAY=5 dupload -X-to delayed &lt;changes-file&gt;</example>
 -->
 
 
@@ -3494,195 +3494,6 @@ These are just some subjective hints, advice and pointers collected
 from Debian developers.  Feel free to pick and choose whatever works
 best for you.
 
-    <sect 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>
-       <sect1 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/&lt;packagename&gt;_&lt;upstream-version&gt;.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>&lt;packagename&gt;-&lt;upstream-version&gt;(.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>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</tt>.
-             </item>
-          </enumlist>
-         </p>
-         </sect1>
-         <sect1 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>&lt;upstream-version&gt;</tt> and
-<tt>&lt;debian-revision&gt;</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>&lt;packagename&gt;-&lt;upstream-version&gt;.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>
-       </sect1>
-       <sect1 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>
-       </sect1>
-    </sect>
-
     <sect id="bpp-debian-rules">
         <heading>Best practices for <file>debian/rules</file></heading>
         <p>
@@ -3776,7 +3587,7 @@ A single source package will often build several binary packages,
 either to provide several flavors of the same software (e.g.,
 the <package>vim</package> source package) or to make several small
 packages instead of a big one (e.g., if the user can install only the
-subset she needs, and thus save some disk space).
+subset needed, and thus save some disk space).
        <p>
 The second case can be easily managed in <file>debian/rules</file>.
 You just need to move the appropriate files from the build directory
@@ -4791,6 +4602,198 @@ to your short description. If you are looking for examples, just run:
   <example>apt-cache search .|grep transitional</example>.
         </sect1>
 
+
+    <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/&lt;packagename&gt;_&lt;upstream-version&gt;.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>&lt;packagename&gt;-&lt;upstream-version&gt;(.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>&lt;packagename&gt;-&lt;upstream-version&gt;(.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>&lt;upstream-version&gt;</tt> and
+<tt>&lt;debian-revision&gt;</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>&lt;packagename&gt;-&lt;upstream-version&gt;.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>
+
+
       </sect>
     </chapt>