From f87e8d649212e9841554fb17d10b59dfef3b7c45 Mon Sep 17 00:00:00 2001 From: aba Date: Mon, 24 Jan 2005 13:51:40 +0000 Subject: [PATCH] fix build failures git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@2840 313b444b-1b9f-4f58-a734-7bb04f332e8d --- developers-reference.sgml | 387 +++++++++++++++++++------------------- 1 file changed, 195 insertions(+), 192 deletions(-) diff --git a/developers-reference.sgml b/developers-reference.sgml index e5cec45..b84e1f5 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + @@ -1217,7 +1217,7 @@ $cfg{'delayed'} = { Once you've made that change, dupload can be used to easily upload a package in one of the delayed directories: -DELAY=5 dupload --to delayed <changes-file> +DELAY=5 dupload -X-to delayed <changes-file> --> @@ -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. - - Best practices for orig.tar.gz files -

- There are two kinds of original source tarballs: Pristine source - and repackaged upstream source. -

- - Pristine source -

-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. - -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 currently distributing at any point in -time. All that can be expected is that it is identical to -something that upstream once did distribute. - -If a difference arises later (say, if upstream notices that he wasn't -using maximal comression in his original distribution and then -re-gzips 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. - -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. -

-

-There is no universally accepted guidelines that upstream authors -follow regarding to the directory structure inside their tarball, but -dpkg-source is nevertheless able to deal with most -upstream tarballs as pristine source. Its strategy is equivalent to -the following: -

-

- - -It unpacks the tarball in an empty temporary directory by doing - - -zcat path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf - + - - -If, after this, the temporary directory contains nothing but one -directory and no other files, dpkg-source renames that -directory to -<packagename>-<upstream-version>(.orig). The name -of the top-level directory in the tarball does not matter, and is -forgotten. - - -Otherwise, the upstream tarball must have been packaged without a -common top-level directory (shame on the upstream author!). In this -case, dpkg-source renames the temporary directory -itself to -<packagename>-<upstream-version>(.orig). - - -

- - - Repackaged upstream source -

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

-

-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 .diff.gz and still has -a version number composed of <upstream-version> and -<debian-revision>. -

-

-There may be cases where it is desirable to repackage the source even -though upstream distributes a .tar.gz that could in principle -be used in its pristine form. The most obvious is if -significant 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. -

-

-A repackaged .orig.tar.gz -

+

- - -

-must contain detailed information how -the repackaged source was obtained, and how this can be reproduced, in -README.Debian-source or a similar file. This file should -be in the diff.gz part of the Debian source package, -usually in the debian directory, not in the -repackaged orig.tar.gz. It is also a good idea to provide a -get-orig-source target in your debian/rules file -that repeats the process, as described in the Policy Manual, . -

- - -should not contain any file that does not come from the -upstream author(s), or whose contents has been changed by you. - -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 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. - - - -

-should, 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 debian/rules does is -to overwrite it by running a configure script. -

-

-(Rationale: 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). -

 - -should use -<packagename>-<upstream-version>.orig as the name -of the top-level directory in its tarball. This makes it possible to -distinguish pristine tarballs from repackaged ones. + - -should be gzipped with maximal compression. - - -

-

-The canonical way to meet the latter two points is to let -dpkg-source -b construct the repackaged tarball from an -unpacked directory. -

- - - Changing binary files in diff.gz -

-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, dpkg-source 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 -orig.tar.gz. Instead, include the file in the -debian directory in uuencoded (or similar) -form - -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. -. -The file would then be decoded and copied to its place during the -build process. Thus the change will be visible quite easy. -

-

-Some packages use dbs to manage patches to their upstream -source, and always create a new orig.tar.gz file that -contains the real orig.tar.gz 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 orig.tar.gz file, -besides the real one, and copy them to the right place during the -build process. -

- - - Best practices for debian/rules

@@ -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 vim 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).

The second case can be easily managed in debian/rules. 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: apt-cache search .|grep transitional. + + + Best practices for orig.tar.gz files +

+ There are two kinds of original source tarballs: Pristine source + and repackaged upstream source. +

+ + Pristine source +

+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. + +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 currently distributing at any point in +time. All that can be expected is that it is identical to +something that upstream once did distribute. + +If a difference arises later (say, if upstream notices that he wasn't +using maximal comression in his original distribution and then +re-gzips 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. + +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. +

+

+There is no universally accepted guidelines that upstream authors +follow regarding to the directory structure inside their tarball, but +dpkg-source is nevertheless able to deal with most +upstream tarballs as pristine source. Its strategy is equivalent to +the following: +

+

+ + +It unpacks the tarball in an empty temporary directory by doing + + +zcat path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf - + + + +If, after this, the temporary directory contains nothing but one +directory and no other files, dpkg-source renames that +directory to +<packagename>-<upstream-version>(.orig). The name +of the top-level directory in the tarball does not matter, and is +forgotten. + + +Otherwise, the upstream tarball must have been packaged without a +common top-level directory (shame on the upstream author!). In this +case, dpkg-source renames the temporary directory +itself to +<packagename>-<upstream-version>(.orig). + + +

+ + + Repackaged upstream source +

+You should 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. +

+

+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 .diff.gz and still has +a version number composed of <upstream-version> and +<debian-revision>. +

+

+There may be cases where it is desirable to repackage the source even +though upstream distributes a .tar.gz that could in principle +be used in its pristine form. The most obvious is if +significant 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. +

+

+A repackaged .orig.tar.gz +

+

+ + +

+must contain detailed information how +the repackaged source was obtained, and how this can be reproduced, in +README.Debian-source or a similar file. This file should +be in the diff.gz part of the Debian source package, +usually in the debian directory, not in the +repackaged orig.tar.gz. It is also a good idea to provide a +get-orig-source target in your debian/rules file +that repeats the process, as described in the Policy Manual, . +

+ + +should not contain any file that does not come from the +upstream author(s), or whose contents has been changed by you. + +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 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. + + + +

+should, 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 debian/rules does is +to overwrite it by running a configure script. +

+

+(Rationale: 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). +

 + +should use +<packagename>-<upstream-version>.orig as the name +of the top-level directory in its tarball. This makes it possible to +distinguish pristine tarballs from repackaged ones. + + +should be gzipped with maximal compression. + + +

+

+The canonical way to meet the latter two points is to let +dpkg-source -b construct the repackaged tarball from an +unpacked directory. +

+ + + Changing binary files in diff.gz +

+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, dpkg-source 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 +orig.tar.gz. Instead, include the file in the +debian directory in uuencoded (or similar) +form + +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. +. +The file would then be decoded and copied to its place during the +build process. Thus the change will be visible quite easy. +

+

+Some packages use dbs to manage patches to their upstream +source, and always create a new orig.tar.gz file that +contains the real orig.tar.gz 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 orig.tar.gz file, +besides the real one, and copy them to the right place during the +build process. +

+ + + + -- 2.30.2