/[ddp]/manuals/trunk/maint-guide/maint-guide.en.dbk
ViewVC logotype

Diff of /manuals/trunk/maint-guide/maint-guide.en.dbk

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 8719 by osamu, Sun Apr 24 13:31:28 2011 UTC revision 8731 by osamu, Tue Apr 26 15:38:19 2011 UTC
# Line 105  takes many hours.  Make no mistake, for Line 105  takes many hours.  Make no mistake, for
105  need to be both technically competent and diligent.  need to be both technically competent and diligent.
106  </para>  </para>
107  <para>  <para>
 This document will explain every little (at first maybe irrelevant) step, and  
 help you create that first package, and to gain some experience in building  
 the next releases of that and maybe other packages later on.  
 </para>  
 <para>  
108  If you need some help on packaging, please read <xref linkend="helpme"/>.  If you need some help on packaging, please read <xref linkend="helpme"/>.
109  </para>  </para>
110  <para>  <para>
# Line 120  The translations may be available in pac Line 115  The translations may be available in pac
115  <systemitem role="package">maint-guide-es</systemitem>.  <systemitem role="package">maint-guide-es</systemitem>.
116  Please note that this documentation may be slightly outdated.  Please note that this documentation may be slightly outdated.
117  </para>  </para>
118    <para>
119    Since this is a tutorial, I choose to explain each detailed step for some
120    important topics.  Some of them may look irrelevant to you.  Please be patient.
121    I have also intentionally skipped some corner cases and provided only pointers
122    to keep this document simple.
123    </para>
124  <section id="socialdynamism"><title>Social dynamics of Debian</title>  <section id="socialdynamism"><title>Social dynamics of Debian</title>
125  <para>  <para>
126  Here are some observations of Debian's social dynamics, presented in the hope  Here are some observations of Debian's social dynamics, presented in the hope
# Line 420  those made for X11, also use these progr Line 421  those made for X11, also use these progr
421  </itemizedlist>  </itemizedlist>
422  <para>  <para>
423  The short descriptions that are given above only serve to introduce you to what  The short descriptions that are given above only serve to introduce you to what
424  each package does.  Before continuing please thoroughly read the documentation  each package does.  Before continuing please read the documentation
425  of each relevant program including ones installed through the package dependency such as  of each relevant program including ones installed through the package dependency such as
426  <command>make</command>, at least, for the standard usage.  It may seem like heavy  <command>make</command>, at least, for the standard usage.  It may seem like heavy
427  going now, but later on you'll be <emphasis>very</emphasis> glad you read it.  going now, but later on you'll be <emphasis>very</emphasis> glad you read it.
 </para>  
 <para>  
428  If you have specific questions later, I would suggest re-reading the documents  If you have specific questions later, I would suggest re-reading the documents
429  mentioned above.  Since this is a tutorial, I have intentionally skipped  mentioned above.
 details and provided only pointers to keep it simple.  
430  </para>  </para>
431  </section>  </section>
432  <section id="needdocs"><title>Documentation needed for development</title>  <section id="needdocs"><title>Documentation needed for development</title>
# Line 439  you should read along with this document Line 437  you should read along with this document
437  <itemizedlist>  <itemizedlist>
438  <listitem>  <listitem>
439  <para>  <para>
 <ulink url="&autotools-tutorial;">Autotools  
 Tutorial</ulink> provides a very good tutorial for <ulink url="&gnu-build-system;">the GNU Build System known  
 as the GNU Autotools</ulink> whose most important components are Autoconf,  
 Automake, Libtool, and gettext.  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
440  <systemitem role="package">debian-policy</systemitem> - the <ulink url="&debian-policy;">Debian Policy  <systemitem role="package">debian-policy</systemitem> - the <ulink url="&debian-policy;">Debian Policy
441  Manual</ulink> includes explanations of the structure and contents of the  Manual</ulink> includes explanations of the structure and contents of the
442  Debian archive, several OS design issues, the <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink>  Debian archive, several OS design issues, the <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink>
# Line 467  when and where to upload etc.  (See the Line 457  when and where to upload etc.  (See the
457  <ulink url="&developers-refpdf;">developers-reference.pdf</ulink>.)  <ulink url="&developers-refpdf;">developers-reference.pdf</ulink>.)
458  </para>  </para>
459  </listitem>  </listitem>
460    </itemizedlist>
461    <para>
462    The following is the <emphasis>important</emphasis> documentation which
463    you should read along with this document:
464    </para>
465    <itemizedlist>
466    <listitem>
467    <para>
468    <ulink url="&autotools-tutorial;">Autotools
469    Tutorial</ulink> provides a very good tutorial for <ulink url="&gnu-build-system;">the GNU Build System known
470    as the GNU Autotools</ulink> whose most important components are Autoconf,
471    Automake, Libtool, and gettext.
472    </para>
473    </listitem>
474  <listitem>  <listitem>
475  <para>  <para>
476  <systemitem role="package">gnu-standards</systemitem> - this package contains  <systemitem role="package">gnu-standards</systemitem> - this package contains
# Line 559  is time for you to dig into the Line 563  is time for you to dig into the
563  <ulink url="&bts;">Debian Bug Tracking System</ulink>  <ulink url="&bts;">Debian Bug Tracking System</ulink>
564  and read the documentation there, to be able to  and read the documentation there, to be able to
565  deal with the reports efficiently.  I highly recommend reading the  deal with the reports efficiently.  I highly recommend reading the
566  <ulink url="&devref-bug-handling;">Debian Developer's Reference, 5.8:  <ulink url="&devref-bug-handling;">Debian Developer's Reference, 5.8.
567  "Handling bugs"</ulink>.  "Handling bugs"</ulink>.
568  </para>  </para>
569  <para>  <para>
# Line 591  specifically named files for each step a Line 595  specifically named files for each step a
595  <listitem>  <listitem>
596  <para>We obtain an upstream program file usually in a compressed tar format.</para>  <para>We obtain an upstream program file usually in a compressed tar format.</para>
597    <itemizedlist>    <itemizedlist>
598    <listitem><literal><replaceable>programname</replaceable>-<replaceable>version</replaceable>.tar.gz</literal></listitem>    <listitem><literal><replaceable>package</replaceable>-<replaceable>version</replaceable>.tar.gz</literal></listitem>
599    </itemizedlist>    </itemizedlist>
600  </listitem>  </listitem>
601  <listitem>  <listitem>
602  <para>  <para>
603  We create a non-native Debian source package in the "3.0 (quilt)" format, which refers to the set of input files for  We create a non-native Debian source package in the <literal>3.0 (quilt)</literal> format, which refers to the set of input files for
604  the Debian package building, by adding Debian package modifications to the upstream program under the <filename>debian</filename> directory.  the Debian package building, by adding Debian package modifications to the upstream program under the <filename>debian</filename> directory.
605  </para>  </para>
606    <itemizedlist>    <itemizedlist>
607    <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>.orig.tar.gz</literal></listitem>    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.orig.tar.gz</literal></listitem>
608    <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.debian.tar.gz</literal>    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.debian.tar.gz</literal>
609      <footnote><para>For the older non-native Debian source package in the "1.0" format,      <footnote><para>For the older non-native Debian source package in the <literal>1.0</literal> format,
610      <literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.diff.gz</literal>      <literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.diff.gz</literal>
611      is used instead. </para></footnote></listitem>      is used instead. </para></footnote></listitem>
612    <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.dsc</literal></listitem>    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.dsc</literal></listitem>
613    </itemizedlist>    </itemizedlist>
614  </listitem>  </listitem>
615  <listitem>  <listitem>
# Line 613  the Debian package building, by adding D Line 617  the Debian package building, by adding D
617  We build Debian binary packages, which are ordinary installable package files in <literal>.deb</literal> format (or <literal>.udeb</literal> format, used by the Debian Installer), from the Debian source package.  We build Debian binary packages, which are ordinary installable package files in <literal>.deb</literal> format (or <literal>.udeb</literal> format, used by the Debian Installer), from the Debian source package.
618  </para>  </para>
619    <itemizedlist>    <itemizedlist>
620    <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
621    </itemizedlist>    </itemizedlist>
622  </listitem>  </listitem>
623  </itemizedlist>  </itemizedlist>
624  <para>  <para>
625  Please note that the character separating  Please note that the character separating
626  <literal><replaceable>programname</replaceable></literal> and  <literal><replaceable>package</replaceable></literal> and
627  <literal><replaceable>version</replaceable></literal> was changed from  <literal><replaceable>version</replaceable></literal> was changed from
628  <literal>-</literal> (hyphen) to <literal>_</literal> (underscore).  <literal>-</literal> (hyphen) to <literal>_</literal> (underscore).
629  </para>  </para>
630  <para>  <para>
 If you are making a Debian specific package without an upstream program instead,  
 typical workflow of the Debian package building is simpler.  
 </para>  
 <itemizedlist>  
 <listitem>  
 <para>  
 We create a native Debian source package in the "3.0 (native)" format using a compressed tar format in which required files under the <filename>debian</filename> directory are also included.  
 </para>  
   <itemizedlist>  
   <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>.tar.gz</literal></listitem>  
   <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>.dsc</literal></listitem>  
   </itemizedlist>  
 </listitem>  
 <listitem>  
 <para>  
 We build Debian binary packages from the native Debian source package.  
 </para>  
   <itemizedlist>  
   <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>  
   </itemizedlist>  
 </listitem>  
 </itemizedlist>  
 <para>  
631  Here,  Here,
632  <literal><replaceable>programname</replaceable></literal> part of the file name is substituted by the  <literal><replaceable>package</replaceable></literal> part of the file name is substituted by the
633  <emphasis role="strong">package name</emphasis>,  <emphasis role="strong">package name</emphasis>,
634  <literal><replaceable>version</replaceable></literal> part of it is substituted by the  <literal><replaceable>version</replaceable></literal> part of it is substituted by the
635  <emphasis role="strong">upstream version</emphasis>,  <emphasis role="strong">upstream version</emphasis>,
# Line 668  Debian Policy Manual: <ulink url="&polic Line 649  Debian Policy Manual: <ulink url="&polic
649  and is automatically assigned by the package build process.</para></footnote>  and is automatically assigned by the package build process.</para></footnote>
650  </para>  </para>
651  <para>  <para>
652    If you are making a Debian specific package without an upstream program instead,
653    typical workflow of the Debian package building is simpler.
654    </para>
655    <itemizedlist>
656    <listitem>
657    <para>
658    We create a native Debian source package in the <literal>3.0 (quilt)</literal> format using a compressed tar format in which required files under the <filename>debian</filename> directory are also included.
659    </para>
660      <itemizedlist>
661      <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.tar.gz</literal></listitem>
662      <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.dsc</literal></listitem>
663      </itemizedlist>
664    </listitem>
665    <listitem>
666    <para>
667    We build Debian binary packages from the native Debian source package.
668    </para>
669      <itemizedlist>
670      <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
671      </itemizedlist>
672    </listitem>
673    </itemizedlist>
674    <para>
675  In the following, each step of this is explained with detailed examples.  In the following, each step of this is explained with detailed examples.
676  </para>  </para>
677  </section>  </section>
# Line 807  with the DFSG but it <emphasis role="str Line 811  with the DFSG but it <emphasis role="str
811  </listitem>  </listitem>
812  </itemizedlist>  </itemizedlist>
813  <para>  <para>
814  If you are unsure about where it should go, post the license text on <ulink url="&debian-legal-ldo;">debian-legal@lists.debian.org</ulink>  If you are unsure about where it should go, post the license text on
815    <ulink url="&debian-legal-ldo;">debian-legal@lists.debian.org</ulink>
816  and ask for advice.  and ask for advice.
817  </para>  </para>
818    <listitem>
819    <para>
820    The program should <emphasis role="strong">not</emphasis> introduce security
821    and maintenance concerns to the Debian system. As a new maintainer with no
822    experience in the security audit, it is best to keep away from risky programs.
823    </para>
824  </listitem>  </listitem>
825    <itemizedlist>
826  <listitem>  <listitem>
827  <para>  <para>
828  The program certainly should <emphasis role="strong">not</emphasis> run setuid  The program certainly should <emphasis role="strong">not</emphasis> run setuid
# Line 825  The program should not be a daemon, or g Line 837  The program should not be a daemon, or g
837  </listitem>  </listitem>
838  <listitem>  <listitem>
839  <para>  <para>
 The program should be in the binary executable form; libraries are harder to handle.  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
840  The program should be well documented and its code needs to be understandable  The program should be well documented and its code needs to be understandable
841  (i.e.  not obfuscated).  (i.e.  not obfuscated).
842  </para>  </para>
# Line 843  unmaintained software. Line 850  unmaintained software.
850  </para>  </para>
851  </listitem>  </listitem>
852  </itemizedlist>  </itemizedlist>
853    </listitem>
854    </itemizedlist>
855  <para>  <para>
856  Of course, these are just safety measures, and intended to save you from  Of course, these are just safety measures, and intended to save you from
857  enraging users if you do something wrong in some setuid daemon...  When you gain  enraging users if you do something wrong in some setuid daemon...  When you gain
858  more experience in packaging, you'll be able to package such software.  more experience in packaging, you'll be able to package such software.
859  </para>  </para>
860    <para>
861    As a new maintainer, you are encouraged to get some experience in packaging
862    with easier packages and discouraged from creating complicated packages.
863    </para>
864    <itemizedlist>
865    <listitem><para>Simple packages</para>
866      <itemizedlist>
867      <listitem><para>single binary package, arch = all (collection of data such as wallpaper graphics)</para></listitem>
868      <listitem><para>single binary package, arch = all (executable written in the POSIX shell language)</para></listitem>
869      <listitem><para>single binary package, arch = all (executable written in interpreter languages)</para></listitem>
870      <listitem><para>single binary package, arch = any (executable compiled from a C source with <filename>Makefile</filename>)</para></listitem>
871      </itemizedlist>
872    </listitem>
873    <listitem><para>Intermediate complexity packages</para>
874      <itemizedlist>
875      <listitem><para>single binary package, arch = any (executable compiled from a C source with Autotools)</para></listitem>
876      <listitem><para>multiple binary packages, arch = any + all (executable package + documentation package)</para></listitem>
877      <listitem><para>upstream source in a format other than <filename>tar.gz</filename> or <filename>tar.bz2</filename></para></listitem>
878      <listitem><para>upstream source containing undistributable contents</para></listitem>
879      <listitem><para>source package with multiple upstream sources</para></listitem>
880      </itemizedlist>
881    </listitem>
882    <listitem><para>High complexity packages</para>
883      <itemizedlist>
884      <listitem><para>interpreter module packages used by other packages</para></listitem>
885      <listitem><para>multiple binary packages containing library package</para></listitem>
886      <listitem><para>generic library package used by other packages, arch = any</para></listitem>
887      <listitem><para>kernel module packages, arch = any</para></listitem>
888      <listitem><para>kernel patch packages</para></listitem>
889      </itemizedlist>
890    </listitem>
891    </itemizedlist>
892    <para>
893    Doing so is not too hard, but it requires a bit more knowledge. You should seek
894    specific guidances for every complexities.
895    </para>
896  </section>  </section>
897  <section id="getit"><title>Get the program, and try it out</title>  <section id="getit"><title>Get the program, and try it out</title>
898  <para>  <para>
# Line 860  author's homepage.  Sources for free Uni Line 905  author's homepage.  Sources for free Uni
905  <filename>.tar.bz2</filename>, or  <filename>.tar.bz2</filename>, or
906  <command>tar</command>+<command>xz</command> format with the extension  <command>tar</command>+<command>xz</command> format with the extension
907  <filename>.tar.xz</filename>.  These usually contain a directory called  <filename>.tar.xz</filename>.  These usually contain a directory called
908  <filename><replaceable>programname</replaceable>-<replaceable>version</replaceable></filename>  <filename><replaceable>package</replaceable>-<replaceable>version</replaceable></filename>
909  with all the sources inside.  with all the sources inside.
910  </para>  </para>
911  <para>  <para>
# Line 961  system comprising <ulink url="&autoconf; Line 1006  system comprising <ulink url="&autoconf;
1006  such sources by the <filename>configure.ac</filename>,  such sources by the <filename>configure.ac</filename>,
1007  <filename>Makefile.am</filename>, and <filename>Makefile.in</filename> files.  <filename>Makefile.am</filename>, and <filename>Makefile.in</filename> files.
1008  <footnote><para>Autotools is too big to deal in this small tutorial. This  <footnote><para>Autotools is too big to deal in this small tutorial. This
1009  section is mean to provide keywords and references only.  Please make sure to read the  section is meant to provide keywords and references only.  Please make sure to read the
1010  <ulink url="&autotools-tutorial;">Autotools Tutorial</ulink> and  <ulink url="&autotools-tutorial;">Autotools Tutorial</ulink> and
1011  <ulink url="&autotools-readme;"/>, if you need to use it.</para></footnote>  <ulink url="&autotools-readme;"/>, if you need to use it.</para></footnote>
1012  </para>  </para>
# Line 990  files requires some knowledge of <comman Line 1035  files requires some knowledge of <comman
1035  The second step of the Autotools workflow is usually that the user obtains this  The second step of the Autotools workflow is usually that the user obtains this
1036  distributed source and runs <literal>./configure &amp;&amp; make</literal> in  distributed source and runs <literal>./configure &amp;&amp; make</literal> in
1037  the source directory to compile the program into a  the source directory to compile the program into a
1038  <command><replaceable>binary</replaceable> executables</command>.  <command><replaceable>binary</replaceable></command> executable.
1039  </para>  </para>
1040  <screen>  <screen>
1041  Makefile.in -----+                +-&gt; Makefile -----+-&gt; make -&gt; <replaceable>binary</replaceable>  Makefile.in -----+                +-&gt; Makefile -----+-&gt; make -&gt; <replaceable>binary</replaceable>
# Line 1032  These are used in the <filename>debian/c Line 1077  These are used in the <filename>debian/c
1077  Although this simple approach works most of the times, you may need to adjust  Although this simple approach works most of the times, you may need to adjust
1078  <emphasis role="strong">package name</emphasis> and  <emphasis role="strong">package name</emphasis> and
1079  <emphasis role="strong">upstream version</emphasis> by renaming the upstream  <emphasis role="strong">upstream version</emphasis> by renaming the upstream
1080  source to follow the Debian policy and the existing convention.  source to follow the Debian Policy and the existing convention.
1081  </para>  </para>
1082  <para>  <para>
1083  You must choose the <emphasis role="strong">package name</emphasis>  You must choose the <emphasis role="strong">package name</emphasis>
# Line 1061  If upstream source uses generic words su Line 1106  If upstream source uses generic words su
1106  its name, it is good idea to rename it not to contaminate name space for the  its name, it is good idea to rename it not to contaminate name space for the
1107  package name and to identify its contents explicitly.  package name and to identify its contents explicitly.
1108  <footnote><para>If you follow the  <footnote><para>If you follow the
1109  <ulink url="&devref-newpackage;">Developer's Reference 5.1. 'New packages'</ulink>,  <ulink url="&devref-newpackage;">Debian Developer's Reference 5.1. "New packages"</ulink>,
1110  the ITP process will usually catch this kind of issues.</para></footnote>.  the ITP process will usually catch this kind of issues.</para></footnote>
1111  </para>  </para>
1112  <para>  <para>
1113  You should choose the <emphasis role="strong">upstream version</emphasis>  You should choose the <emphasis role="strong">upstream version</emphasis>
1114  to consist only of  to consist only of
1115  alphanumerics (<literal>0-9A-Za-z</literal>), plus (<literal>+</literal>),  alphanumerics (<literal>0-9A-Za-z</literal>), plus (<literal>+</literal>),
1116  tilde (<literal>~</literal>), and periods (<literal>.</literal>). It must  tildes (<literal>~</literal>), and periods (<literal>.</literal>). It must
1117  start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter  start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter
1118  rule should help you avoid confusing file names.</para></footnote>  rule should help you avoid confusing file names.</para></footnote>
1119  It is good idea to keep its length within 8 characters if possible.  It is good idea to keep its length within 8 characters if possible.
# Line 1098  aptitude display 10 = 8char for up + 1ch Line 1143  aptitude display 10 = 8char for up + 1ch
1143  <para>  <para>
1144  If the upstream software does not use normal version system like  If the upstream software does not use normal version system like
1145  <literal>2.30.32</literal> but uses some kind of date such as  <literal>2.30.32</literal> but uses some kind of date such as
1146  <literal>09Oct23</literal>, a random codename string or a VCS hush value as a part  <literal>09Oct23</literal>, a random codename string or a VCS hash value as a part
1147  of version, make sure to remove them from the  of version, make sure to remove them from the
1148  <emphasis role="strong">upstream version</emphasis>.  Such information can be  <emphasis role="strong">upstream version</emphasis>.  Such information can be
1149  recorded in the <filename>debian/changelog</filename> file.  If you need to  recorded in the <filename>debian/changelog</filename> file.  If you need to
# Line 1113  Version strings can be compared with <ci Line 1158  Version strings can be compared with <ci
1158   $ dpkg --compare-versions <replaceable>ver1</replaceable> <replaceable>op</replaceable> <replaceable>ver2</replaceable>   $ dpkg --compare-versions <replaceable>ver1</replaceable> <replaceable>op</replaceable> <replaceable>ver2</replaceable>
1159  </screen>  </screen>
1160  <para>  <para>
1161  The version comparison rule can be summarized as the folowing.  The version comparison rule can be summarized as the following.
1162  </para>  </para>
1163  <itemizedlist>  <itemizedlist>
1164  <listitem><para>The strings are compared from the head to the tail.</para></listitem>  <listitem><para>The strings are compared from the head to the tail.</para></listitem>
1165  <listitem><para>Alphabets are larger than numbers.</para></listitem>  <listitem><para>Alphabets are larger than numbers.</para></listitem>
1166  <listitem><para>Numbers are compared as the integer.</para></listitem>  <listitem><para>Numbers are compared as the integer.</para></listitem>
1167  <listitem><para>Alphabets are compared in the ASCII code order.</para></listitem>  <listitem><para>Alphabets are compared in the ASCII code order.</para></listitem>
1168  <listitem><para>There are some special rules for periods (<literal>.</literal>), plus (<literal>+</literal>) and tilde (<literal>~</literal>) as the followings.</para>  <listitem><para>There are some special rules for periods (<literal>.</literal>), plus (<literal>+</literal>) and tildes (<literal>~</literal>) as the followings.</para>
1169    <para>    <para>
1170    <literal>0.0</literal> &lt;    <literal>0.0</literal> &lt;
1171    <literal>0.5</literal> &lt;    <literal>0.5</literal> &lt;
# Line 1144  sure that the upgrade works properly by Line 1189  sure that the upgrade works properly by
1189  <filename>gentoo-0.9.12~rc99.tar.gz</filename>.  <filename>gentoo-0.9.12~rc99.tar.gz</filename>.
1190  </para>  </para>
1191  </section>  </section>
1192  <section id="dh-make"><title>Initial Debian package</title>  <section id="dh-make"><title>Setting up <command>dh_make</command></title>
1193  <para>  <para>
1194  Set up the shell environment variables <literal>$DEBEMAIL</literal> and  Set up the shell environment variables <literal>$DEBEMAIL</literal> and
1195  <literal>$DEBFULLNAME</literal> so that various Debian maintenance  <literal>$DEBFULLNAME</literal> so that various Debian maintenance
# Line 1159  DEBEMAIL=your.email.address@example.org Line 1204  DEBEMAIL=your.email.address@example.org
1204  DEBFULLNAME=Firstname Lastname  DEBFULLNAME=Firstname Lastname
1205  export DEBEMAIL DEBFULLNAME  export DEBEMAIL DEBFULLNAME
1206  EOF  EOF
1207    $ . ~/.bashrc
1208  </screen>  </screen>
1209    </section>
1210    <section id="non-native-dh-make"><title>Initial non-native Debian package</title>
1211  <para>  <para>
1212  You can create an initial Debian package by issuing the  Normal Debian packages are non-native Debian packages made from upstream
1213  <command>dh_make</command> command as follows.  programs.  If you wish to create a non-native Debian package of an upstream
1214    source <filename>gentoo-0.9.12.tar.gz</filename>, you can create an initial
1215    non-native Debian package for it by issuing the <command>dh_make</command>
1216    command as follows.
1217  </para>  </para>
1218  <screen>  <screen>
1219  $ . ~/.bashrc  $ cd ~/gentoo
1220  $ cd ~/gentoo/gentoo-0.9.12  $ wget http://example.org/gentoo-0.9.12.tar.gz
1221    $ tar -xvzf gentoo-0.9.12.tar.gz
1222    $ cd gentoo-0.9.12
1223  $ dh_make -f ../gentoo-0.9.12.tar.gz  $ dh_make -f ../gentoo-0.9.12.tar.gz
1224  </screen>  </screen>
1225  <para>  <para>
# Line 1182  provided by the upstream for your Debian Line 1235  provided by the upstream for your Debian
1235  </para>  </para>
1236  <para>  <para>
1237  You should see some output asking you what sort of package you want  You should see some output asking you what sort of package you want
1238  to create.  Gentoo is a single-binary package - it creates only one binary package, i.e,  to create.  Gentoo is a single binary package - it creates only one binary package, i.e,
1239  one <filename>.deb</filename> file - so we will select the first option  one <filename>.deb</filename> file - so we will select the first option
1240  (with the <literal>s</literal> key), check the information on the screen, and  (with the <literal>s</literal> key), check the information on the screen, and
1241  confirm by pressing <literal><replaceable>ENTER</replaceable></literal>.  confirm by pressing <literal><replaceable>ENTER</replaceable></literal>.
1242  <footnote><para> There are several choices here: <literal>s</literal> for  <footnote><para> There are several choices here: <literal>s</literal> for
1243  Single-binary package, <literal>i</literal> for arch-Independent package, <literal>m</literal> for  Single binary package, <literal>i</literal> for arch-Independent package, <literal>m</literal> for
1244  Multiple-binary packages, <literal>l</literal> for Library package, <literal>k</literal> for  Multiple binary packages, <literal>l</literal> for Library package, <literal>k</literal> for
1245  Kernel module package, <literal>n</literal> for kernel patch package, and <literal>b</literal>  Kernel module package, <literal>n</literal> for kernel patch package, and <literal>b</literal>
1246  for <systemitem role="package">cdbs</systemitem> package.  This document focuses on the  for <systemitem role="package">cdbs</systemitem> package.  This document focuses on the
1247  use of the <command>dh</command> command (from the package  use of the <command>dh</command> command (from the package
1248  <systemitem role="package">debhelper</systemitem>) to create a single-binary package,  <systemitem role="package">debhelper</systemitem>) to create a single binary package,
1249  but also touches on how to use it for arch-independent or  but also touches on how to use it for arch-independent or
1250  multiple-binary packages.  The package  multiple binary packages.  The package
1251  <systemitem role="package">cdbs</systemitem> offers an alternative packaging script  <systemitem role="package">cdbs</systemitem> offers an alternative packaging script
1252  infrastructure to the <command>dh</command> command and is outside the scope of  infrastructure to the <command>dh</command> command and is outside the scope of
1253  this document.  </para> </footnote>  this document.  </para> </footnote>
# Line 1240  testing them (<xref linkend="checkit"/>) Line 1293  testing them (<xref linkend="checkit"/>)
1293  All the steps will be explained.  All the steps will be explained.
1294  </para>  </para>
1295  <para>  <para>
 Once again, as a new maintainer you are discouraged from creating complicated  
 packages, e.g.:  
 </para>  
 <itemizedlist>  
 <listitem>  
 <para>  
 multiple-binary packages;  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 library packages;  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 kernel module packages;  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 kernel patch packages;  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 packages with the source in a format other than <filename>tar.gz</filename> or  
 <filename>tar.bz2</filename>; or  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 packages where the source tarball contains undistributable contents.  
 </para>  
 </listitem>  
 </itemizedlist>  
 <para>  
 Doing so is not too hard, but it requires a bit more knowledge, so we won't  
 describe all of it here.  
 </para>  
 <para>  
1296  If you accidentally erased some template files while working on them, you can  If you accidentally erased some template files while working on them, you can
1297  recover them by running <command>dh_make</command> with the  recover them by running <command>dh_make</command> with the
1298  <literal>--addmissing</literal> option again in a Debian package source tree.  <literal>--addmissing</literal> option again in a Debian package source tree.
# Line 1290  Updating an existing package may get com Line 1302  Updating an existing package may get com
1302  techniques.  While learning the basics, please stick to creating a fresh  techniques.  While learning the basics, please stick to creating a fresh
1303  package; further explanations are given in <xref linkend="update"/>.  package; further explanations are given in <xref linkend="update"/>.
1304  </para>  </para>
1305    <para>
1306    Please note that the source file does not need to contain any build system
1307    discussed in <xref linkend="simplemake"/> and <xref linkend="portable"/>.  It
1308    could be just a collection of graphics data etc.  Installation of files may be
1309    enabled by <systemitem role="package">debhelper</systemitem> configuration
1310    files such as <filename>debian/install</filename> (see
1311    <xref linkend="install"/>) only.
1312    </para>
1313    </section>
1314    <section id="native-dh-make"><title>Initial native Debian package</title>
1315    <para>
1316    Debian native packages are simpler to manage if they contain source files you
1317    manage only for Debian, possibly only for local uses.  If you have source
1318    files in <filename>~/mypackage-1.0</filename>, you can create an initial native
1319    Debian package for it by issuing the <command>dh_make</command> command as
1320    follows.
1321    </para>
1322    <screen>
1323    $ cd ~/mypackage-1.0
1324    $ dh_make --native
1325    </screen>
1326    <para>
1327    Then the <filename>debian</filename> directory and its contents are created
1328    just like <xref linkend="non-native-dh-make"/>.  This does not create a tarball
1329    since this is a native Debian package.  But that is the only difference.
1330    The rest of the packaging activities are practically the same.
1331    </para>
1332  </section>  </section>
1333  </chapter>  </chapter>
1334  <chapter id="modify"><title>Modifying the source</title>  <chapter id="modify"><title>Modifying the source</title>
# Line 1433  installation.  The packaging script will Line 1472  installation.  The packaging script will
1472  <literal>$(DESTDIR)</literal> to the temporary directory.  <literal>$(DESTDIR)</literal> to the temporary directory.
1473  </para>  </para>
1474  <para>  <para>
1475  For packages of the single-binary type, the temporary directory used  For packages of the single binary type, the temporary directory used
1476  by the <command>dh_auto_install</command> command will be set to  by the <command>dh_auto_install</command> command will be set to
1477  <filename>debian/<replaceable>package</replaceable></filename>.  <filename>debian/<replaceable>package</replaceable></filename>.
1478  <footnote><para> For packages of the multiple-binary type, the  <footnote><para> For packages of the multiple binary type, the
1479  <command>dh_auto_install</command> command uses <filename>debian/tmp</filename>  <command>dh_auto_install</command> command uses <filename>debian/tmp</filename>
1480  as the temporary directory while the <command>dh_install</command> command with  as the temporary directory while the <command>dh_install</command> command with
1481  the help of  the help of
# Line 2084  English.  Translations of these descript Line 2123  English.  Translations of these descript
2123  Let's insert <literal>Vcs-*</literal> fields to document the Version Control  Let's insert <literal>Vcs-*</literal> fields to document the Version Control
2124  System (VCS) location between line 6 and 7.  System (VCS) location between line 6 and 7.
2125  <footnote><para>See  <footnote><para>See
2126  <ulink url="&devref-bpp-vcs;">Developer's Reference, 6.2.5. 'Version Control System location'</ulink>.  <ulink url="&devref-bpp-vcs;">Debian Developer's Reference, 6.2.5. "Version Control System location"</ulink>.
2127  </para></footnote>  </para></footnote>
2128  Let's assume that the <systemitem role="package">gentoo</systemitem>  Let's assume that the <systemitem role="package">gentoo</systemitem>
2129  package has its VCS located in Debian Alioth Git Service at  package has its VCS located in Debian Alioth Git Service at
# Line 2935  possible. Line 2974  possible.
2974  <para>  <para>
2975  To control most of what <systemitem role="package">debhelper</systemitem> does  To control most of what <systemitem role="package">debhelper</systemitem> does
2976  while building the package, you put optional configuration files under the  while building the package, you put optional configuration files under the
2977  <filename>debian</filename> directory.  This chapter will make an overview of  <filename>debian</filename> directory.  This chapter will provide an overview of
2978  what each of these does and its format.  Please read <ulink url="&debian-policy;">Debian Policy  what each of these does and its format.  Please read the <ulink url="&debian-policy;">Debian Policy
2979  Manual</ulink> and <ulink url="&developers-reference;">Debian Developer's  Manual</ulink> and <ulink url="&developers-reference;">Debian Developer's
2980  Reference</ulink> for guidelines for the packaging.  Reference</ulink> for guidelines for packaging.
2981  </para>  </para>
2982  <para>  <para>
2983  The <command>dh_make</command> command will create some template configuration  The <command>dh_make</command> command will create some template configuration
# Line 2949  prefixed by the binary package name such Line 2988  prefixed by the binary package name such
2988  them.  them.
2989  <footnote><para>  <footnote><para>
2990  In this chapter, files in the <filename>debian</filename> directory are  In this chapter, files in the <filename>debian</filename> directory are
2991  referred without preceding <filename>debian/</filename> for simplicity whenever  referred to without the preceding <filename>debian/</filename> for simplicity whenever
2992  they are obvious.  they are obvious.
2993  </para></footnote>  </para></footnote>
2994  </para>  </para>
2995  <para>  <para>
2996  The <command>dh_make</command> command may not create some template  Some template configuration files for <systemitem role="package">debhelper</systemitem>
2997  configuration files for <systemitem role="package">debhelper</systemitem>.  In  may not be created by the <command>dh_make</command> command.  In
2998  such cases, you need to create them with the editor.  such cases, you need to create them with an editor.
2999  </para>  </para>
3000  <para>  <para>
3001  If you wish or need to activate any of those, please do the following.  If you wish or need to activate any of these, please do the following:
3002  </para>  </para>
3003  <itemizedlist>  <itemizedlist>
3004  <listitem>  <listitem>
3005  <para>  <para>
3006  rename template files by removing the <literal>.ex</literal> or  rename template files by removing the <literal>.ex</literal> or
3007  <literal>.EX</literal> suffix if the template files have one.  <literal>.EX</literal> suffix if they have one;
3008  </para>  </para>
3009  </listitem>  </listitem>
3010  <listitem>  <listitem>
3011  <para>  <para>
3012  rename the name of these configuration files using the actual binary package  rename the configuration files to use the actual binary package
3013  name in place of <literal><replaceable>package</replaceable></literal>.  name in place of <literal><replaceable>package</replaceable></literal>;
3014  </para>  </para>
3015  </listitem>  </listitem>
3016  <listitem>  <listitem>
3017  <para>  <para>
3018  modify template file contents to suit your needs.  modify template file contents to suit your needs;
3019  </para>  </para>
3020  </listitem>  </listitem>
3021  <listitem>  <listitem>
3022  <para>  <para>
3023  remove template files which you do not need.  remove template files which you do not need;
3024  </para>  </para>
3025  </listitem>  </listitem>
3026  <listitem>  <listitem>
3027  <para>  <para>
3028  modify the <filename>control</filename> file (see <xref linkend="control"/>),  modify the <filename>control</filename> file (see <xref linkend="control"/>),
3029  if necessary.  if necessary;
3030  </para>  </para>
3031  </listitem>  </listitem>
3032  <listitem>  <listitem>
# Line 2998  necessary. Line 3037  necessary.
3037  </listitem>  </listitem>
3038  </itemizedlist>  </itemizedlist>
3039  <para>  <para>
3040  Those <systemitem role="package">debhelper</systemitem> configuration files  Any <systemitem role="package">debhelper</systemitem> configuration files
3041  without <filename><replaceable>package</replaceable></filename> prefix such as  without a <filename><replaceable>package</replaceable></filename> prefix, such as
3042  <filename>install</filename> apply to the first binary package.  When there are  <filename>install</filename>, apply to the first binary package.  When there are
3043  many binary packages, their configurations can be specified by prefixing their  many binary packages, their configurations can be specified by prefixing their
3044  name to their configuration filenames such as  name to their configuration filenames such as
3045  <filename><replaceable>package-1</replaceable>.install</filename>,  <filename><replaceable>package-1</replaceable>.install</filename>,
3046  <filename><replaceable>package-2</replaceable>.install</filename>, etc.  <filename><replaceable>package-2</replaceable>.install</filename>, etc.
3047  </para>  </para>
3048  <section id="readme"><title><filename>README.Debian</filename> file</title>  <section id="readme"><title><filename>README.Debian</filename></title>
3049  <para>  <para>
3050  Any extra details or discrepancies between the original package and your Debian  Any extra details or discrepancies between the original package and your Debian
3051  version should be documented here.  version should be documented here.
3052  </para>  </para>
3053  <para>  <para>
3054  <command>dh_make</command> created a default one, this is what it looks like:  <command>dh_make</command> created a default one; this is what it looks like:
3055  </para>  </para>
3056  <screen>  <screen>
3057  gentoo for Debian  gentoo for Debian
# Line 3026  If you have nothing to be documented, re Line 3065  If you have nothing to be documented, re
3065  </citerefentry>.  </citerefentry>.
3066  </para>  </para>
3067  </section>  </section>
3068  <section id="compat"><title><filename>compat</filename> file</title>  <section id="compat"><title><filename>compat</filename></title>
3069  <para>  <para>
3070  The <filename>compat</filename> file defines the <systemitem role="package">debhelper</systemitem> compatibility level.  Currently, you  The <filename>compat</filename> file defines the <systemitem role="package">debhelper</systemitem> compatibility level.  Currently, you
3071  should set it to the <systemitem role="package">debhelper</systemitem> V7 by  should set it to the <systemitem role="package">debhelper</systemitem> v7 as
3072  the following.  follows:
3073  </para>  </para>
3074  <screen>  <screen>
3075  $ echo 7 &gt; debian/compat  $ echo 7 &gt; debian/compat
3076  </screen>  </screen>
3077  </section>  </section>
3078  <section id="conffiles"><title><filename>conffiles</filename> file</title>  <section id="conffiles"><title><filename>conffiles</filename></title>
3079  <para>  <para>
3080  One of the most annoying things about software is when you spend a great deal  One of the most annoying things about software is when you spend a great deal
3081  of time and effort customizing a program, only to have an upgrade stomp all  of time and effort customizing a program, only to have an upgrade stomp all
# Line 3045  over your changes.  Debian solves this p Line 3084  over your changes.  Debian solves this p
3084  <manvolnum>1</manvolnum> </citerefentry> and  <manvolnum>1</manvolnum> </citerefentry> and
3085  <ulink url="&policy-conffiles;">Debian Policy Manual 'D.2.5 Conffiles'</ulink>.  <ulink url="&policy-conffiles;">Debian Policy Manual 'D.2.5 Conffiles'</ulink>.
3086  </para></footnote>  </para></footnote>
3087  When you upgrade a package, you'll be prompted whether you want to keep  When you upgrade a package, you'll be asked whether you want to keep
3088  your old configuration files or not.  your old configuration files or not.
3089  </para>  </para>
3090  <para>  <para>
3091  Since <systemitem role="package">debhelper</systemitem> V3, <citerefentry>  Since <systemitem role="package">debhelper</systemitem> v3, <citerefentry>
3092  <refentrytitle>dh_installdeb</refentrytitle> <manvolnum>1</manvolnum>  <refentrytitle>dh_installdeb</refentrytitle> <manvolnum>1</manvolnum>
3093  </citerefentry> will <emphasis>automatically</emphasis> flag any files under  </citerefentry> will <emphasis>automatically</emphasis> flag any files under
3094  the <filename>/etc</filename> directory as conffiles, so if your program only  the <filename>/etc</filename> directory as conffiles, so if your program only
3095  has conffiles there you do not need to specify them in this file.  For most  has conffiles there you do not need to specify them in this file.  For most
3096  package types, the only place there is (and should be conffiles) is under  package types, the only place conffiles should ever be is under
3097  <filename>/etc</filename> and so this file doesn't need to exist.  <filename>/etc</filename>, and so this file doesn't need to exist.
3098  </para>  </para>
3099  <para>  <para>
3100  If your program uses configuration files but also rewrites them on its own,  If your program uses configuration files but also rewrites them on its own,
3101  it's best not to make them as conffiles because <command>dpkg</command> will  it's best not to make them conffiles because <command>dpkg</command> will
3102  then prompt users to verify the changes all the time.  then prompt users to verify the changes all the time.
3103  </para>  </para>
3104  <para>  <para>
3105  If the program you're packaging requires every user to modify the configuration  If the program you're packaging requires every user to modify the configuration
3106  files in the <filename>/etc</filename> directory, there are 2 popular ways to  files in the <filename>/etc</filename> directory, there are two popular ways to
3107  make them not as conffiles to keep <command>dpkg</command> quiet.  arrange for them to not be conffiles, keeping <command>dpkg</command> quiet.
3108  </para>  </para>
3109  <itemizedlist>  <itemizedlist>
3110  <listitem>  <listitem>
3111  <para>  <para>
3112  You make a symlink under the <filename>/etc</filename> directory pointing to a  Create a symlink under the <filename>/etc</filename> directory pointing to a
3113  file under the <filename>/var</filename> directory generated by the  file under the <filename>/var</filename> directory generated by the
3114  <emphasis>maintainer scripts</emphasis>.  maintainer scripts.
3115  </para>  </para>
3116  </listitem>  </listitem>
3117  <listitem>  <listitem>
3118  <para>  <para>
3119  You make a file generated by the <emphasis>maintainer scripts</emphasis> under  Create a file generated by the maintainer scripts under the <filename>/etc</filename> directory.
 the <filename>/etc</filename> directory.  
3120  </para>  </para>
3121  </listitem>  </listitem>
3122  </itemizedlist>  </itemizedlist>
3123  <para>  <para>
3124  For more information on the <emphasis>maintainer scripts</emphasis>, see <xref linkend="maintscripts"/>.  For information on maintainer scripts, see <xref linkend="maintscripts"/>.
3125  </para>  </para>
3126  </section>  </section>
3127  <section id="crond"><title><filename><replaceable>package</replaceable>.cron.*</filename> files</title>  <section id="crond"><title><filename><replaceable>package</replaceable>.cron.*</filename></title>
3128  <para>  <para>
3129  If your package requires regularly scheduled tasks to operate properly, you can  If your package requires regularly scheduled tasks to operate properly, you can
3130  use this file to set it up.  You can either setup regular tasks that happen  use these files to set that up.  You can set up regular tasks that either happen
3131  hourly, daily, weekly or monthly or alternatively happen any other time that  hourly, daily, weekly, or monthly, or alternatively happen at any other time that
3132  you wish.  The filenames are:  you wish.  The filenames are:
3133  </para>  </para>
3134  <itemizedlist>  <itemizedlist>
3135  <listitem>  <listitem>
3136  <para>  <para>
3137  <filename>cron.hourly</filename> - Installed as  <filename><replaceable>package</replaceable>.cron.hourly</filename> - Installed as
3138  <filename>/etc/cron.hourly/<replaceable>package</replaceable></filename>: run  <filename>/etc/cron.hourly/<replaceable>package</replaceable></filename>; run
3139  once an hour every hour.  once an hour.
3140  </para>  </para>
3141  </listitem>  </listitem>
3142  <listitem>  <listitem>
3143  <para>  <para>
3144  <filename>cron.daily</filename> - Installed as  <filename><replaceable>package</replaceable>.cron.daily</filename> - Installed as
3145  <filename>/etc/cron.daily/<replaceable>package</replaceable></filename>: run  <filename>/etc/cron.daily/<replaceable>package</replaceable></filename>; run
3146  once a day, usually early morning.  once a day.
3147  </para>  </para>
3148  </listitem>  </listitem>
3149  <listitem>  <listitem>
3150  <para>  <para>
3151  <filename>cron.weekly</filename> - Installed as  <filename><replaceable>package</replaceable>.cron.weekly</filename> - Installed as
3152  <filename>/etc/cron.weekly/<replaceable>package</replaceable></filename>: run  <filename>/etc/cron.weekly/<replaceable>package</replaceable></filename>; run
3153  once a week, usually early Sunday morning.  once a week.
3154  </para>  </para>
3155  </listitem>  </listitem>
3156  <listitem>  <listitem>
3157  <para>  <para>
3158  <filename>cron.monthly</filename> - Installed as  <filename><replaceable>package</replaceable>.cron.monthly</filename> - Installed as
3159  <filename>/etc/cron.monthly/<replaceable>package</replaceable></filename>: run  <filename>/etc/cron.monthly/<replaceable>package</replaceable></filename>: run
3160  once a month, usually early morning on the first of the month.  once a month.
3161  </para>  </para>
3162  </listitem>  </listitem>
3163  <listitem>  <listitem>
3164  <para>  <para>
3165  <filename>cron.d</filename> - Installed as  <filename><replaceable>package</replaceable>.cron.d</filename> - Installed as
3166  <filename>/etc/cron.d/<replaceable>package</replaceable></filename>: for any  <filename>/etc/cron.d/<replaceable>package</replaceable></filename>: for any
3167  other time  other time.
3168  </para>  </para>
3169  </listitem>  </listitem>
3170  </itemizedlist>  </itemizedlist>
3171  <para>  <para>
3172  For the named files, the format of them is the shell script.  The different one  Most of these files are shell scripts, with the exception of
3173  is <filename><replaceable>package</replaceable>.cron.d</filename> which follows  <filename><replaceable>package</replaceable>.cron.d</filename> which follows
3174  the format of <citerefentry> <refentrytitle>crontab</refentrytitle>  the format of <citerefentry> <refentrytitle>crontab</refentrytitle>
3175  <manvolnum>5</manvolnum> </citerefentry>.  <manvolnum>5</manvolnum> </citerefentry>.
3176  </para>  </para>
3177  <para>  <para>
3178  Note that this doesn't include log rotation; for that, see <citerefentry>  No explicit <filename>cron.*</filename> file is needed to set up log rotation;
3179  <refentrytitle>dh_installlogrotate</refentrytitle> <manvolnum>1</manvolnum>  for that, see
3180  </citerefentry> and <citerefentry> <refentrytitle>logrotate</refentrytitle>  <citerefentry><refentrytitle>dh_installlogrotate</refentrytitle>
3181  <manvolnum>8</manvolnum> </citerefentry>.  <manvolnum>1</manvolnum></citerefentry> and
3182    <citerefentry><refentrytitle>logrotate</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
3183  </para>  </para>
3184  </section>  </section>
3185  <section id="dirs"><title><filename>dirs</filename> file</title>  <section id="dirs"><title><filename>dirs</filename></title>
3186  <para>  <para>
3187  This file specifies the directories which we need but the normal installation  This file specifies any directories which we need but which are not created by the normal installation
3188  procedure (<literal>make install DESTDIR=...</literal> invoked by  procedure (<literal>make install DESTDIR=...</literal> invoked by
3189  <literal>dh_auto_install</literal>) somehow doesn't create.  This generally  <literal>dh_auto_install</literal>).  This generally
3190  means there is a problem with the <filename>Makefile</filename>.  means there is a problem with the <filename>Makefile</filename>.
3191  </para>  </para>
3192  <para>  <para>
3193  Files listed in the <filename>install</filename> file doesn't need the  Files listed in an <filename>install</filename> file don't need their
3194  directories created first.  See <xref linkend="install"/>.  directories created first.  See <xref linkend="install"/>.
3195  </para>  </para>
3196  <para>  <para>
3197  It is best to try to run the installation first and only use this if you  It is best to try to run the installation first and only use this if you
3198  run into trouble.  There is no preceding slash on the directory names listed in  run into trouble.  There is no preceding slash on the directory names listed in
3199  the <filename>dirs</filename> file.  the <filename>dirs</filename> file.
3200  </para>  </para>
3201  </section>  </section>
3202  <section id="doc-base"><title><filename><replaceable>package</replaceable>.doc-base</filename> file</title>  <section id="doc-base"><title><filename><replaceable>package</replaceable>.doc-base</filename></title>
3203  <para>  <para>
3204  If your package has documentation other than manual pages and info docs, you  If your package has documentation other than manual and info pages, you
3205  should use the <systemitem role="package">doc-base</systemitem> file to  should use the <systemitem role="package">doc-base</systemitem> file to
3206  register it, so the user can find it with e.g.  <citerefentry>  register it, so the user can find it with e.g.  <citerefentry>
3207  <refentrytitle>dhelp</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,  <refentrytitle>dhelp</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,
3208  <citerefentry> <refentrytitle>dwww</refentrytitle> <manvolnum>1</manvolnum>  <citerefentry> <refentrytitle>dwww</refentrytitle> <manvolnum>1</manvolnum>
3209  </citerefentry> or <citerefentry> <refentrytitle>doccentral</refentrytitle>  </citerefentry>, or <citerefentry> <refentrytitle>doccentral</refentrytitle>
3210  <manvolnum>1</manvolnum> </citerefentry>.  <manvolnum>1</manvolnum> </citerefentry>.
3211  </para>  </para>
3212  <para>  <para>
# Line 3175  This usually includes HTML, PS and PDF f Line 3214  This usually includes HTML, PS and PDF f
3214  <filename>/usr/share/doc/<replaceable>packagename</replaceable>/</filename>.  <filename>/usr/share/doc/<replaceable>packagename</replaceable>/</filename>.
3215  </para>  </para>
3216  <para>  <para>
3217  This is how <systemitem role="package">gentoo</systemitem>'s doc-base file  This is what <systemitem role="package">gentoo</systemitem>'s doc-base file
3218  <filename>gentoo.doc-base</filename> looks like:  <filename>gentoo.doc-base</filename> looks like:
3219  </para>  </para>
3220  <screen>  <screen>
# Line 3198  manual, in <ulink url="&doc-base;">Debia Line 3237  manual, in <ulink url="&doc-base;">Debia
3237  For more details on installing additional documentation, look in <xref linkend="destdir"/>.  For more details on installing additional documentation, look in <xref linkend="destdir"/>.
3238  </para>  </para>
3239  </section>  </section>
3240  <section id="docs"><title><filename>docs</filename> file</title>  <section id="docs"><title><filename>docs</filename></title>
3241  <para>  <para>
3242  This file specifies the file names of documentation files we can have  This file specifies the file names of documentation files we can have
3243  <citerefentry> <refentrytitle>dh_installdocs</refentrytitle>  <citerefentry> <refentrytitle>dh_installdocs</refentrytitle>
# Line 3211  directory that are called <filename>BUGS Line 3250  directory that are called <filename>BUGS
3250  <filename>README*</filename>, <filename>TODO</filename> etc.  <filename>README*</filename>, <filename>TODO</filename> etc.
3251  </para>  </para>
3252  <para>  <para>
3253  For <systemitem role="package">gentoo</systemitem>, I also included some other  For <systemitem role="package">gentoo</systemitem>, some other files
3254  files:  are also included:
3255  </para>  </para>
3256  <screen>  <screen>
3257  BUGS  BUGS
# Line 3224  README.gtkrc Line 3263  README.gtkrc
3263  TODO  TODO
3264  </screen>  </screen>
3265  </section>  </section>
3266  <section id="emacsen"><title><filename>emacsen-*</filename> file</title>  <section id="emacsen"><title><filename>emacsen-*</filename></title>
3267  <para>  <para>
3268  If your package supplies Emacs files that can be bytecompiled at package  If your package supplies Emacs files that can be bytecompiled at package
3269  installation time, you can use these files to set it up.  installation time, you can use these files to set it up.
# Line 3238  They are installed into the temporary di Line 3277  They are installed into the temporary di
3277  If you don't need these, remove them.  If you don't need these, remove them.
3278  </para>  </para>
3279  </section>  </section>
3280  <section id="examples"><title><filename><replaceable>package</replaceable>.examples</filename> file</title>  <section id="examples"><title><filename><replaceable>package</replaceable>.examples</filename></title>
3281  <para>  <para>
3282  The <citerefentry> <refentrytitle>dh_installexamples</refentrytitle>  The <citerefentry> <refentrytitle>dh_installexamples</refentrytitle>
3283  <manvolnum>1</manvolnum> </citerefentry> command installs files and directories  <manvolnum>1</manvolnum> </citerefentry> command installs files and directories
3284  listed in this file as example files.  listed in this file as example files.
3285  </para>  </para>
3286  </section>  </section>
3287  <section id="initd"><title><filename><replaceable>package</replaceable>.init</filename> and <filename><replaceable>package</replaceable>.default</filename> files</title>  <section id="initd"><title><filename><replaceable>package</replaceable>.init</filename> and <filename><replaceable>package</replaceable>.default</filename></title>
3288  <para>  <para>
3289  If your package is a daemon that needs to be run at the system start-up, you've  If your package is a daemon that needs to be run at system start-up, you've
3290  obviously disregarded my initial recommendation, haven't you?  :-)  obviously disregarded my initial recommendation, haven't you?  :-)
3291  </para>  </para>
3292  <para>  <para>
3293  The <filename><replaceable>package</replaceable>.init</filename> file is  The <filename><replaceable>package</replaceable>.init</filename> file is
3294  installed as the  installed as the
3295  <filename>/etc/init.d/<replaceable>package</replaceable></filename> script  <filename>/etc/init.d/<replaceable>package</replaceable></filename> script
3296  for the <emphasis>init script</emphasis> which starts and stops a daemon.  which starts and stops the daemon.
3297  Its fairly generic skeleton template is provided by the  Its fairly generic skeleton template is provided by the
3298  <command>dh_make</command> command as <filename>init.d.ex</filename>.  You'll  <command>dh_make</command> command as <filename>init.d.ex</filename>.  You'll
3299  likely have to rename and edit it, a lot, while making sure to provide  likely have to rename and edit it, a lot, while making sure to provide
# Line 3265  gets installed into the temporary direct Line 3304  gets installed into the temporary direct
3304  </para>  </para>
3305  <para>  <para>
3306  The <filename><replaceable>package</replaceable>.default</filename> file will  The <filename><replaceable>package</replaceable>.default</filename> file will
3307  be installed into  be installed as
3308  <filename>/etc/default/<replaceable>package</replaceable></filename>.  This  <filename>/etc/default/<replaceable>package</replaceable></filename>.  This
3309  file sets defaults that are sourced by the <emphasis>init script</emphasis>.  Most times this  file sets defaults that are sourced by the init script.  This
3310  <filename><replaceable>package</replaceable>.default</filename> file is used to disable running a daemon, set some default flags or  <filename><replaceable>package</replaceable>.default</filename> file
3311  timeouts.  If your <emphasis>init script</emphasis> has certain <emphasis>settable</emphasis>  is most often used to disable running a daemon, or to set some default flags or
3312  features you want to install these into the <filename><replaceable>package</replaceable>.default</filename> file, not the <emphasis>init script</emphasis>.  timeouts.  If your init script has certain configurable
3313    features, you can set them in the <filename><replaceable>package</replaceable>.default</filename> file,
3314    instead of in the init script itself.
3315  </para>  </para>
3316  <para>  <para>
3317  If your upstream program provides a file for the <emphasis>init script</emphasis>, you can either use it or not.  If you  If your upstream program provides a file for the init script, you can either use it or not.  If you
3318  don't use their <emphasis>init script</emphasis> then create a new one in  don't use their init script then create a new one in
3319  <filename><replaceable>package</replaceable>.init</filename>.  However  <filename><replaceable>package</replaceable>.init</filename>.  However
3320  if the upstream <emphasis>init script</emphasis> looks fine and installs in the right place you  if the upstream init script looks fine and installs in the right place you
3321  still need to setup the <filename>rc*</filename> symlinks.  To do this you will  still need to set up the <filename>rc*</filename> symlinks.  To do this you will
3322  need to override <command>dh_installinit</command> in the  need to override <command>dh_installinit</command> in the
3323  <filename>rules</filename> file with the following lines:  <filename>rules</filename> file with the following lines:
3324  </para>  </para>
# Line 3289  override_dh_installinit: Line 3330  override_dh_installinit:
3330  If you don't need this, remove the files.  If you don't need this, remove the files.
3331  </para>  </para>
3332  </section>  </section>
3333  <section id="install"><title><filename>install</filename> file</title>  <section id="install"><title><filename>install</filename></title>
3334  <para>  <para>
3335  If there are files that need to be installed into your package but your  If there are files that need to be installed into your package but your
3336  standard <literal>make install</literal> won't do it, you put the filenames and  standard <literal>make install</literal> won't do it, put the filenames and
3337  destinations into this <filename>install</filename> file.  They are installed  destinations into this <filename>install</filename> file.  They are installed
3338  by <citerefentry> <refentrytitle>dh_install</refentrytitle>  by <citerefentry> <refentrytitle>dh_install</refentrytitle>
3339  <manvolnum>1</manvolnum> </citerefentry>.<footnote><para> This replaces the  <manvolnum>1</manvolnum> </citerefentry>.<footnote><para> This replaces the
# Line 3305  the <filename>docs</filename> file and n Line 3346  the <filename>docs</filename> file and n
3346  <para>  <para>
3347  This <filename>install</filename> file has one line per file installed, with  This <filename>install</filename> file has one line per file installed, with
3348  the name of the file (relative to the top build directory) then a space then  the name of the file (relative to the top build directory) then a space then
3349  the installation directory (relative to the install directory).  One example of  the installation directory (relative to the install directory).  One example of where this is used is if a binary <filename>src/<replaceable>bar</replaceable></filename> is left uninstalled; the
3350  this is when a binary executable is forgotten to be installed, the  <filename>install</filename> file might look like:
 <filename>install</filename> file would look like:  
3351  </para>  </para>
3352  <screen>  <screen>
3353  src/foo/mybin usr/bin  src/<replaceable>bar</replaceable> usr/bin
3354  </screen>  </screen>
3355  <para>  <para>
3356  This will mean when this package is installed, there will be a binary executable  This means when this package is installed, there will be a binary executable
3357  <filename>/usr/bin/mybin</filename>.  <filename>/usr/bin/<replaceable>bar</replaceable></filename>.
3358  </para>  </para>
3359  <para>  <para>
3360  Alternatively, this <filename>install</filename> can have the name of the file  Alternatively, this <filename>install</filename> can have the name of the file
3361  only without the installation directory when the relative directory path does  only without the installation directory when the relative directory path does
3362  not change.  This format is usually used for a large package that splits build  not change.  This format is usually used for a large package that splits the
3363  result into multiple binary packages using  output of its build into multiple binary packages using
3364  <filename><replaceable>package-1</replaceable>.install</filename>,  <filename><replaceable>package-1</replaceable>.install</filename>,
3365  <filename><replaceable>package-2</replaceable>.install</filename>, etc.  <filename><replaceable>package-2</replaceable>.install</filename>, etc.
3366  </para>  </para>
3367  <para>  <para>
3368  The <command>dh_install</command> command will fall back to look in  The <command>dh_install</command> command will fall back to looking in
3369  <filename>debian/tmp</filename> for files, if it doesn't find them in the  <filename>debian/tmp</filename> for files, if it doesn't find them in the
3370  current directory (or wherever you've told it to look using  current directory (or wherever you've told it to look using
3371  <literal>--sourcedir</literal>).  <literal>--sourcedir</literal>).
3372  </para>  </para>
3373  </section>  </section>
3374  <section id="info"><title><filename><replaceable>package</replaceable>.info</filename> file</title>  <section id="info"><title><filename><replaceable>package</replaceable>.info</filename></title>
3375  <para>  <para>
3376  If your package has info pages, you should install them using <citerefentry>  If your package has info pages, you should install them using <citerefentry>
3377  <refentrytitle>dh_installinfo</refentrytitle> <manvolnum>1</manvolnum>  <refentrytitle>dh_installinfo</refentrytitle> <manvolnum>1</manvolnum>
3378  </citerefentry> by listing them in the  </citerefentry> by listing them in a
3379  <filename><replaceable>package</replaceable>.info</filename> files.  <filename><replaceable>package</replaceable>.info</filename> file.
3380  </para>  </para>
3381  </section>  </section>
3382  <section id="lintian"><title><filename>{<replaceable>package</replaceable>.|source/}lintian-overrides</filename> files</title>  <section id="lintian"><title><filename>{<replaceable>package</replaceable>.,source/}lintian-overrides</filename></title>
3383  <para>  <para>
3384  If <systemitem role="package">lintian</systemitem> reports an erroneous  If <systemitem role="package">lintian</systemitem> reports an erroneous
3385  diagnostics for a case when the policy allows exceptions to some rule, you can  diagnostic for a case where Debian policy allows exceptions to some rule, you can
3386  use <filename><replaceable>package</replaceable>.lintian-overrides</filename>  use <filename><replaceable>package</replaceable>.lintian-overrides</filename>
3387  or <filename>source/lintian-overrides</filename> to quiet it.  Please read  or <filename>source/lintian-overrides</filename> to quieten it.  Please read
3388  <ulink url="&lintian-doc;">Lintian User's Manual</ulink> and refrain  <ulink url="&lintian-doc;">Lintian User's Manual</ulink> and refrain
3389  from abusing this.  from abusing this.
3390  </para>  </para>
3391  <para>  <para>
3392  <filename><replaceable>package</replaceable>.lintian-overrides</filename> is  <filename><replaceable>package</replaceable>.lintian-overrides</filename> is
3393  for the binary package named as <systemitem role="package"><replaceable>package</replaceable></systemitem> and is installed  for the binary package named <systemitem role="package"><replaceable>package</replaceable></systemitem> and is installed
3394  into  into
3395  <filename>usr/share/lintian/overrides/<replaceable>package</replaceable></filename>  <filename>usr/share/lintian/overrides/<replaceable>package</replaceable></filename>
3396  by the <command>dh_lintian</command> command.  by the <command>dh_lintian</command> command.
# Line 3360  by the <command>dh_lintian</command> com Line 3400  by the <command>dh_lintian</command> com
3400  is not installed.  is not installed.
3401  </para>  </para>
3402  </section>  </section>
3403  <section id="manpage"><title><filename>manpage.*</filename> files</title>  <section id="manpage"><title><filename>manpage.*</filename></title>
3404  <para>  <para>
3405  Your program(s) should have a manual page.  If they don't, you should create  Your program(s) should have a manual page.  If they don't, you should create
3406  them.  The <command>dh_make</command> command creates few template files for a  them.  The <command>dh_make</command> command creates some template files for
3407  manual page.  These need to be copied and edited for each command without its  manual pages.  These need to be copied and edited for each command missing its
3408  manual page.  Please make sure to remove unused templates.  manual page.  Please make sure to remove unused templates.
3409  </para>  </para>
3410  <section id="manpage1"><title><filename>manpage.1.ex</filename> file</title>  <section id="manpage1"><title><filename>manpage.1.ex</filename></title>
3411  <para>  <para>
3412  Manual pages are normally written in <citerefentry>  Manual pages are normally written in <citerefentry>
3413  <refentrytitle>nroff</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.  <refentrytitle>nroff</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.
# Line 3377  The <filename>manpage.1.ex</filename> te Line 3417  The <filename>manpage.1.ex</filename> te
3417  manual page for a brief description of how to edit such a file.  manual page for a brief description of how to edit such a file.
3418  </para>  </para>
3419  <para>  <para>
3420  The final manual page file name should include the name of the program it is  The final manual page file name should give the name of the program it is
3421  documenting, so we will rename it from <literal>manpage</literal> to  documenting, so we will rename it from <literal>manpage</literal> to
3422  <literal>gentoo</literal>.  The file name also includes <literal>.1</literal>  <literal>gentoo</literal>.  The file name also includes <literal>.1</literal>
3423  as the first suffix, which means it's a manual page for a user command.  Be  as the first suffix, which means it's a manual page for a user command.  Be
# Line 3409  So <systemitem role="package">gentoo</sy Line 3449  So <systemitem role="package">gentoo</sy
3449  <filename>gentoo.1</filename>.  If there was no <filename>gentoo.1</filename>  <filename>gentoo.1</filename>.  If there was no <filename>gentoo.1</filename>
3450  man page in the original source, you should create it by renaming the  man page in the original source, you should create it by renaming the
3451  <filename>manpage.1.ex</filename> template to <filename>gentoo.1</filename> and  <filename>manpage.1.ex</filename> template to <filename>gentoo.1</filename> and
3452  edit it by using information from the example and from upstream docs.  editing it using information from the example and from the upstream docs.
3453  </para>  </para>
3454  <para>  <para>
3455  You can use the <command>help2man</command> command to generate a man page out  You can use the <command>help2man</command> command to generate a man page out
3456  of <literal>--help</literal> and <literal>--version</literal> output of each  of the <literal>--help</literal> and <literal>--version</literal> output of each
3457  program, too.  <footnote><para> If the command is missing  program, too.  <footnote><para> Note that <command>help2man</command>'s
3458  <command>info</command> page but have documentation files in the  placeholder man page will claim that more detailed documentation is
3459  <filename>/usr/share/<replaceable>package</replaceable></filename> directory,  available in the info system. If the command is missing an
3460  you should manually edit generated the man page created by the  <command>info</command> page, you
3461    should manually edit the man page created by the
3462  <command>help2man</command> command.  </para> </footnote>  <command>help2man</command> command.  </para> </footnote>
3463  </para>  </para>
3464  </section>  </section>
3465  <section id="manpagesgml"><title><filename>manpage.sgml.ex</filename> file</title>  <section id="manpagesgml"><title><filename>manpage.sgml.ex</filename></title>
3466  <para>  <para>
3467  If on the other hand you prefer writing SGML instead of  If on the other hand you prefer writing SGML instead of
3468  <command>nroff</command>, you can use the <filename>manpage.sgml.ex</filename>  <command>nroff</command>, you can use the <filename>manpage.sgml.ex</filename>
# Line 3446  line in the <filename>control</filename> Line 3487  line in the <filename>control</filename>
3487  </listitem>  </listitem>
3488  <listitem>  <listitem>
3489  <para>  <para>
3490  add a <literal>override_dh_auto_build</literal> target to your  add an <literal>override_dh_auto_build</literal> target to your
3491  <filename>rules</filename> file:  <filename>rules</filename> file:
3492  </para>  </para>
3493  <screen>  <screen>
# Line 3457  override_dh_auto_build: Line 3498  override_dh_auto_build:
3498  </listitem>  </listitem>
3499  </itemizedlist>  </itemizedlist>
3500  </section>  </section>
3501  <section id="manpagexml"><title><filename>manpage.xml.ex</filename> file</title>  <section id="manpagexml"><title><filename>manpage.xml.ex</filename></title>
3502  <para>  <para>
3503  If you prefer XML over SGML, you can use the <literal>manpage.xml.ex</literal>  If you prefer XML over SGML, you can use the <literal>manpage.xml.ex</literal>
3504  template.  If you do this, you have to:  template.  If you do this, you have to:
# Line 3477  XSLT processor like <systemitem role="pa Line 3518  XSLT processor like <systemitem role="pa
3518  </listitem>  </listitem>
3519  <listitem>  <listitem>
3520  <para>  <para>
3521  add the <literal>docbook-xsl</literal>, <literal>docbook-xml</literal> and  add the <literal>docbook-xsl</literal>, <literal>docbook-xml</literal>, and
3522  <literal>xsltproc</literal> packages to the <literal>Build-Depends</literal>  <literal>xsltproc</literal> packages to the <literal>Build-Depends</literal>
3523  line in the <literal>control</literal> file  line in the <literal>control</literal> file
3524  </para>  </para>
3525  </listitem>  </listitem>
3526  <listitem>  <listitem>
3527  <para>  <para>
3528  add a <literal>override_dh_auto_build</literal> target to your  add an <literal>override_dh_auto_build</literal> target to your
3529  <filename>rules</filename> file:  <filename>rules</filename> file:
3530  </para>  </para>
3531  <screen>  <screen>
# Line 3506  override_dh_auto_build: Line 3547  override_dh_auto_build:
3547  <para>  <para>
3548  If your package has manual pages, you should install them using <citerefentry>  If your package has manual pages, you should install them using <citerefentry>
3549  <refentrytitle>dh_installman</refentrytitle> <manvolnum>1</manvolnum>  <refentrytitle>dh_installman</refentrytitle> <manvolnum>1</manvolnum>
3550  </citerefentry> by listing them in the  </citerefentry> by listing them in a
3551  <filename><replaceable>package</replaceable>.manpages</filename> files.  <filename><replaceable>package</replaceable>.manpages</filename> file.
3552  </para>  </para>
3553  <para>  <para>
3554  To install <filename>docs/gentoo.1</filename> for the <systemitem role="package">gentoo</systemitem> package as its manpage, you create a  To install <filename>docs/gentoo.1</filename> as a manpage for the <systemitem role="package">gentoo</systemitem> package, create a
3555  <filename>gentoo.manpages</filename> file as the following.  <filename>gentoo.manpages</filename> file as follows.
3556  </para>  </para>
3557  <screen>  <screen>
3558  docs/gentoo.1  docs/gentoo.1
3559  </screen>  </screen>
3560  </section>  </section>
3561  <section id="menu"><title><filename>menu</filename> file</title>  <section id="menu"><title><filename>menu</filename></title>
3562  <para>  <para>
3563  X Window System users usually have a window manager with a menu that can be  X Window System users usually have a window manager with a menu that can be
3564  customized to launch programs.  If they have installed the Debian <systemitem role="package">menu</systemitem> package, a set of menus for every program on  customized to launch programs.  If they have installed the Debian <systemitem role="package">menu</systemitem> package, a set of menus for every program on
# Line 3538  specifies what kind of interface the pro Line 3579  specifies what kind of interface the pro
3579  listed alternatives, e.g.  <literal>text</literal> or <literal>X11</literal>.  listed alternatives, e.g.  <literal>text</literal> or <literal>X11</literal>.
3580  </para>  </para>
3581  <para>  <para>
3582  The next is <literal>section</literal>, where the menu and submenu entry  The next is the <literal>section</literal> that the menu and submenu entry
3583  should appear in.  should appear in.
3584  <footnote><para> The current list of sections is at  <footnote><para> The current list of sections is in
3585  <ulink url="&menu-structure;">The Debian Menu sub-policy 2.1 'Preferred menu structure'</ulink>.  <ulink url="&menu-structure;">The Debian Menu sub-policy 2.1 'Preferred menu structure'</ulink>.
3586  There were a major reorganization of menu structure for <literal>squeeze</literal>.  There was a major reorganization of menu structure for <literal>squeeze</literal>.
3587  </para> </footnote>  </para> </footnote>
3588  </para>  </para>
3589  <para>  <para>
# Line 3569  You can also add other fields like <lite Line 3610  You can also add other fields like <lite
3610  </citerefentry>, <citerefentry> <refentrytitle>menufile</refentrytitle>  </citerefentry>, <citerefentry> <refentrytitle>menufile</refentrytitle>
3611  <manvolnum>5</manvolnum> </citerefentry>, <citerefentry>  <manvolnum>5</manvolnum> </citerefentry>, <citerefentry>
3612  <refentrytitle>update-menus</refentrytitle> <manvolnum>1</manvolnum>  <refentrytitle>update-menus</refentrytitle> <manvolnum>1</manvolnum>
3613  </citerefentry> and  </citerefentry>, and
3614  <ulink url="&menu-policy;">The Debian Menu sub-policy</ulink> for more  <ulink url="&menu-policy;">The Debian Menu sub-policy</ulink> for more
3615  information.  information.
3616  </para>  </para>
3617  </section>  </section>
3618  <section id="news"><title><filename>NEWS</filename> file</title>  <section id="news"><title><filename>NEWS</filename></title>
3619  <para>  <para>
3620  The <citerefentry> <refentrytitle>dh_installchangelogs</refentrytitle>  The <citerefentry> <refentrytitle>dh_installchangelogs</refentrytitle>
3621  <manvolnum>1</manvolnum> </citerefentry> command installs this.  <manvolnum>1</manvolnum> </citerefentry> command installs this.
3622  </para>  </para>
3623  </section>  </section>
3624  <section id="maintscripts"><title><filename>{post|pre}{inst|rm}</filename> files</title>  <section id="maintscripts"><title><filename>{pre,post}{inst,rm}</filename></title>
3625  <para>  <para>
3626  These <filename>postinst</filename>, <filename>preinst</filename>,  These <filename>postinst</filename>, <filename>preinst</filename>,
3627  <filename>postrm</filename>, and <filename>prerm</filename> files  <filename>postrm</filename>, and <filename>prerm</filename> files
3628  <footnote><para> Although I used Bash short hand expression to indicate these  <footnote><para> Despite this use of the <command>bash</command>
3629  files as <filename>{post|pre}{inst|rm}</filename> here, I recommend you to use  shorthand expression <filename>{pre,post}{inst,rm}</filename> to indicate these
3630  pure POSIX (non-Bash) shell for these <emphasis>maintainer scripts</emphasis>  filenames, you should use pure POSIX syntax for these maintainer scripts for
3631  as much as possible for the better compatibility.  </para> </footnote> are  compatibility with <command>dash</command> as the system shell.  </para> </footnote> are
3632  called <emphasis>maintainer scripts</emphasis>.  They are scripts which are put  called <emphasis>maintainer scripts</emphasis>.  They are scripts which are put
3633  in the control area of the package and run by <command>dpkg</command> when your  in the control area of the package and run by <command>dpkg</command> when your
3634  package is installed, upgraded or removed.  package is installed, upgraded, or removed.
3635  </para>  </para>
3636  <para>  <para>
3637  As a novice maintainer, you should avoid any manual editing of  As a novice maintainer, you should avoid any manual editing of
3638  <emphasis>maintainer scripts</emphasis> because they are problematic.  For more  maintainer scripts because they are problematic.  For more
3639  information look in the <ulink url="&policy-mantainerscripts;">Debian  information refer to the <ulink url="&policy-mantainerscripts;">Debian
3640  Policy Manual, 6 'Package maintainer scripts and installation  Policy Manual, 6 'Package maintainer scripts and installation
3641  procedure'</ulink>, and take a look at these example files provided by  procedure'</ulink>, and take a look at the example files provided by
3642  <command>dh_make</command>.  <command>dh_make</command>.
3643  </para>  </para>
3644  <para>  <para>
3645  If you did not listen to me and made your custom <emphasis>maintainer  If you did not listen to me and have created custom maintainer
3646  scripts</emphasis> for a package, you should make sure to test them not only  scripts for a package, you should make sure to test them not only
3647  for <emphasis role="strong">install</emphasis> and <emphasis role="strong">upgrade</emphasis> but also for <emphasis role="strong">remove</emphasis> and <emphasis role="strong">purge</emphasis>.  for <emphasis role="strong">install</emphasis> and
3648    <emphasis role="strong">upgrade</emphasis> but also for
3649    <emphasis role="strong">remove</emphasis> and
3650    <emphasis role="strong">purge</emphasis>.
3651  </para>  </para>
3652  <para>  <para>
3653  Upgrades to the new version should be silent and non-intrusive (existing users  Upgrades to the new version should be silent and non-intrusive (existing users
3654  should not notice the upgrade except by discovering that old bugs have been  should not notice the upgrade except by discovering that old bugs have been
3655  fixed and there perhaps are new features).  fixed and perhaps that there are new features).
3656  </para>  </para>
3657  <para>  <para>
3658  When the upgrade is necessarily intrusive (eg., config files scattered through  When the upgrade is necessarily intrusive (eg., config files scattered through
3659  various home directories with totally different structure), you may consider to  various home directories with totally different structure), you may
3660  set package to the safe default (e.g., disabled service) and provide proper  consider as the last resort switching the package to a safe fallback state
3661  documentations required by the policy (<filename>README.Debian</filename> and  (e.g., disabling a service) and providing the proper documentation
3662  <filename>NEWS.Debian</filename>) as the last resort.  Don't bother user with  required by policy (<filename>README.Debian</filename> and
3663  the <command>debconf</command> note invoked from these <emphasis>maintainer  <filename>NEWS.Debian</filename>).  Don't bother the user with
3664  scripts</emphasis> for upgrades.  <command>debconf</command> notes invoked from these maintainer scripts
3665    for upgrades.
3666  </para>  </para>
3667  <para>  <para>
3668  The <systemitem role="package">ucf</systemitem> package provides  The <systemitem role="package">ucf</systemitem> package provides a
3669  <emphasis>conffile-like</emphasis> handling infrastructure to preserve user  <emphasis>conffile-like</emphasis> handling infrastructure to preserve user
3670  changes for files that may not be labeled <emphasis>conffiles</emphasis> such  changes for files that may not be labeled as <emphasis>conffiles</emphasis> such
3671  as ones managed by the <emphasis>maintainer scripts</emphasis>.  This should  as those managed by the maintainer scripts.  This should
3672  minimize issues associated with them.  minimize issues associated with them.
3673  </para>  </para>
3674  <para>  <para>
3675  These <emphasis>maintainer scripts</emphasis> are the Debian enhancements that  These maintainer scripts are among the Debian enhancements that
3676  explain <emphasis role="strong">why people choose Debian</emphasis>.  You must  explain <emphasis role="strong">why people choose Debian</emphasis>.  You must
3677  be very careful not to annoy them with these.  be very careful not to turn them into a source of annoyance.
3678  </para>  </para>
3679  </section>  </section>
3680  <section id="todo"><title><filename>TODO</filename> file</title>  <section id="todo"><title><filename>TODO</filename></title>
3681  <para>  <para>
3682  The <citerefentry> <refentrytitle>dh_installdocs</refentrytitle>  The <citerefentry> <refentrytitle>dh_installdocs</refentrytitle>
3683  <manvolnum>1</manvolnum> </citerefentry> command installs this.  <manvolnum>1</manvolnum> </citerefentry> command installs this.
3684  </para>  </para>
3685  </section>  </section>
3686  <section id="watch"><title><filename>watch</filename> file</title>  <section id="watch"><title><filename>watch</filename></title>
3687  <para>  <para>
3688  The <filename>watch</filename> file format is documented in the <citerefentry>  The <filename>watch</filename> file format is documented in the <citerefentry>
3689  <refentrytitle>uscan</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>  <refentrytitle>uscan</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
3690  manpage.  The <filename>watch</filename> file configures the  manpage.  The <filename>watch</filename> file configures the
3691  <command>uscan</command> program (in the <systemitem role="package">devscripts</systemitem> package) to watch the site where you  <command>uscan</command> program (in the <systemitem role="package">devscripts</systemitem> package) to watch the site where you
3692  originally got the source from.  This is also used by <ulink url="&dehs;">Debian External Health Status (DEHS)</ulink>.  originally got the source from.  This is also used by the
3693    <ulink url="&dehs;">Debian External Health Status (DEHS)</ulink> service.
3694  </para>  </para>
3695  <para>  <para>
3696  Here's what I put in it:  Here are its contents:
3697  </para>  </para>
3698  <screen>  <screen>
3699  # watch control file for uscan  # watch control file for uscan
# Line 3655  version=3 Line 3701  version=3
3701  &sf-net;/gentoo/gentoo-(.+)\.tar\.gz debian uupdate  &sf-net;/gentoo/gentoo-(.+)\.tar\.gz debian uupdate
3702  </screen>  </screen>
3703  <para>  <para>
3704  Normally with this <filename>watch</filename> file, the URL at  Normally with a <filename>watch</filename> file, the URL at
3705  <literal>&sf-net;/gentoo</literal> is downloaded and searched for links of  <literal>&sf-net;/gentoo</literal> is downloaded and searched for links of
3706  the form <literal>&lt;a href=...&gt;</literal>.  The base name (just the part  the form <literal>&lt;a href=...&gt;</literal>.  The basename (just the part
3707  after the final <literal>/</literal>) of these linked URLs are matched against  after the final <literal>/</literal>) of each linked URL is compared against
3708  Perl regular expression (see <citerefentry> <refentrytitle>perlre</refentrytitle>  the Perl regular expression pattern (see <citerefentry> <refentrytitle>perlre</refentrytitle>
3709  <manvolnum>1</manvolnum> </citerefentry>) pattern  <manvolnum>1</manvolnum> </citerefentry>)
3710  <literal>gentoo-(.+)\.tar\.gz</literal>.  Out of matched files, the file with  <literal>gentoo-(.+)\.tar\.gz</literal>.  Out of the files that match, the one with
3711  the greatest version number is downloaded and the <command>uupdate</command>  the greatest version number is downloaded and the <command>uupdate</command>
3712  program is run to create the updated source tree from them.  program is run to create an updated source tree.
3713  </para>  </para>
3714  <para>  <para>
3715  Although this is true for other sites, the SourceForge download service at  Although this is true for other sites, the SourceForge download service at
3716  <ulink url="&sf-net;"/> is an exception.  When the  <ulink url="&sf-net;"/> is an exception.  When the
3717  <filename>watch</filename> file has an URL matching with the Perl regexp  <filename>watch</filename> file has an URL matching the Perl regexp
3718  <literal>^http://sf\.net/</literal>, the <command>uscan</command> program  <literal>^http://sf\.net/</literal>, the <command>uscan</command> program
3719  substitutes it with <literal>&qa-do;watch/sf.php/</literal> and  replaces it with <literal>&qa-do;watch/sf.php/</literal> and
3720  then applies this rule.  The URL redirector service at this <ulink url="&qa-do;"/> is designed to offer  then applies this rule.  The URL redirector service at <ulink url="&qa-do;"/> is designed to offer
3721  a stable redirect service to the desired file for the  a stable redirect service to the desired file for any
3722  <filename>watch</filename> file having  <filename>watch</filename> pattern of the form
3723  <literal>&sf-net;/<replaceable>project</replaceable>/<replaceable>tar-name</replaceable>-(.+)\.tar\.gz</literal>.  <literal>&sf-net;/<replaceable>project</replaceable>/<replaceable>tar-name</replaceable>-(.+)\.tar\.gz</literal>.
3724  This solves issues related to the periodically changing URL there.  This solves issues related to periodically changing SourceForge URLs.
3725  </para>  </para>
3726  </section>  </section>
3727  <section id="sourcef"><title><filename>source/format</filename> file</title>  <section id="sourcef"><title><filename>source/format</filename></title>
3728  <para>  <para>
3729  In the <filename>debian/source/format</filename> file, there should be a single  In the <filename>debian/source/format</filename> file, there should be a single
3730  line indicating the desired format for the source package (check <citerefentry>  line indicating the desired format for the source package (check <citerefentry>
# Line 3702  should say either: Line 3748  should say either:
3748  The newer <literal>3.0 (quilt)</literal> source format records modifications in  The newer <literal>3.0 (quilt)</literal> source format records modifications in
3749  a <command>quilt</command> patch series within  a <command>quilt</command> patch series within
3750  <filename>debian/patches</filename>.  Those changes are then automatically  <filename>debian/patches</filename>.  Those changes are then automatically
3751  applied during extraction of the source package.  <footnote><para> See <ulink url="&debsrc3;">DebSrc3.0</ulink> for the  applied during extraction of the source package.  <footnote><para> See
3752  summary information concerning the switch to the new <literal>3.0  <ulink url="&debsrc3;">DebSrc3.0</ulink> for a summary on the switch to the new <literal>3.0
3753  (quilt)</literal> and <literal>3.0 (native)</literal> source formats.  </para>  (quilt)</literal> and <literal>3.0 (native)</literal> source formats.  </para>
3754  </footnote> The Debian modifications are simply stored in a  </footnote> The Debian modifications are simply stored in a
3755  <filename>debian.tar.gz</filename> archive containing all files under the  <filename>debian.tar.gz</filename> archive containing all files under the
# Line 3720  When <command>dpkg-source</command> extr Line 3766  When <command>dpkg-source</command> extr
3766  the end of the extraction with the <literal>--skip-patches</literal> option.  the end of the extraction with the <literal>--skip-patches</literal> option.
3767  </para>  </para>
3768  </section>  </section>
3769  <section id="sourcel"><title><filename>source/local-options</filename> file</title>  <section id="sourcel"><title><filename>source/local-options</filename></title>
3770  <para>  <para>
3771  When you want to manage Debian packaging activities under a VCS, you typically  When you want to manage Debian packaging activities under a VCS, you typically
3772  create one branch (e.g.  <literal>upstream</literal>) tracking the upstream  create one branch (e.g.  <literal>upstream</literal>) tracking the upstream
# Line 3745  unapply-patches Line 3791  unapply-patches
3791  abort-on-upstream-changes  abort-on-upstream-changes
3792  </screen>  </screen>
3793  </section>  </section>
3794  <section id="sourceopt"><title><filename>source/options</filename> file</title>  <section id="sourceopt"><title><filename>source/options</filename></title>
3795  <para>  <para>
3796  The autogenerated files in the source tree can be quite annoying for packaging  The autogenerated files in the source tree can be quite annoying for packaging
3797  since they generate meaningless large patch files.  There are custom modules  since they generate meaningless large patch files.  There are custom modules
# Line 3760  You can provide a Perl regular expressio Line 3806  You can provide a Perl regular expressio
3806  creating the source package.  creating the source package.
3807  </para>  </para>
3808  <para>  <para>
3809  You can store such <command>dpkg-source</command> option argument in the  As a general solution to address this problem of the autogenerated files,
3810  <filename>source/options</filename> file of the source package as the generic  you can store such a <command>dpkg-source</command> option argument in the
3811  solution to address this problem of the autogenerated files.  The following  <filename>source/options</filename> file of the source package.  The following
3812  will skip creating patch files for <filename>config.sub</filename>,  will skip creating patch files for <filename>config.sub</filename>,
3813  <filename>config.guess</filename> and <filename>Makefile</filename>.  <filename>config.guess</filename>, and <filename>Makefile</filename>.
3814  </para>  </para>
3815  <screen>  <screen>
3816  extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"  extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"
3817  </screen>  </screen>
3818  </section>  </section>
3819  <section id="patches"><title><filename>patches/*</filename> files</title>  <section id="patches"><title><filename>patches/*</filename></title>
3820  <para>  <para>
3821  The old <literal>1.0</literal> source format created a single large  The old <literal>1.0</literal> source format created a single large
3822  <filename>diff.gz</filename> file which contains package maintenance files in  <filename>diff.gz</filename> file containing package maintenance files in
3823  <filename>debian</filename> and patch files to the source.  Such a package is a  <filename>debian</filename> and patch files for the source.  Such a package is a
3824  bit cumbersome to inspect and understand for each source tree modification  bit cumbersome to inspect and understand for each source tree modification
3825  later.  This is not so nice.  later.  This is not so nice.
3826  </para>  </para>
3827  <para>  <para>
3828  The newer <literal>3.0 (quilt)</literal> source format stores patches in  The newer <literal>3.0 (quilt)</literal> source format stores patches in
3829  <filename>debian/patches/*</filename> files using the <command>quilt</command>  <filename>debian/patches/*</filename> files using the <command>quilt</command>
3830  command.  These patches and other package data which are all constrained under  command.  These patches and other package data which are all contained under
3831  the <filename>debian</filename> directory are packaged as the  the <filename>debian</filename> directory are packaged as the
3832  <filename>debian.tar.gz</filename> file.  Since the  <filename>debian.tar.gz</filename> file.  Since the
3833  <command>dpkg-source</command> command can handle <command>quilt</command>  <command>dpkg-source</command> command can handle <command>quilt</command>
3834  formatted patch data in the <literal>3.0 (quilt)</literal> source without the  formatted patch data in the <literal>3.0 (quilt)</literal> source without the
3835  <systemitem role="package">quilt</systemitem> package, it does not need to  <systemitem role="package">quilt</systemitem> package, it does not need a
3836  <literal>Build-Depends</literal> on the <systemitem role="package">quilt</systemitem> package.  <footnote><para> Several methods  <literal>Build-Depends</literal> on <systemitem role="package">quilt</systemitem>.
3837  for the patch set maintenance have been proposed and are in use with Debian  <footnote><para> Several methods of patch set maintenance have been proposed and are in use for Debian
3838  packages.  The <command>quilt</command> system is the preferred maintenance  packages.  The <command>quilt</command> system is the preferred maintenance
3839  system in use.  Other ones are <command>dpatch</command>,  system in use.  Others include <command>dpatch</command>,
3840  <command>dbs</command>, <command>cdbs</command>, etc.  Many of these keep such  <command>dbs</command>, and <command>cdbs</command>.  Many of these keep such
3841  patches as <filename>debian/patches/*</filename> files.  </para> </footnote>  patches as <filename>debian/patches/*</filename> files.  </para> </footnote>
3842  </para>  </para>
3843  <para>  <para>
# Line 3800  The <command>quilt</command> command is Line 3846  The <command>quilt</command> command is
3846  It records modifications to the source as a stack of <literal>-p1</literal>  It records modifications to the source as a stack of <literal>-p1</literal>
3847  patch files in the <filename>debian/patches</filename> directory and the source  patch files in the <filename>debian/patches</filename> directory and the source
3848  tree is untouched outside of the <filename>debian</filename> directory.  The  tree is untouched outside of the <filename>debian</filename> directory.  The
3849  order of these patches are recorded in the  order of these patches is recorded in the
3850  <filename>debian/patches/series</filename> file.  You can apply (=push),  <filename>debian/patches/series</filename> file.  You can apply (=push),
3851  un-apply (=pop), and refresh patches easily.  <footnote><para> If you are  un-apply (=pop), and refresh patches easily.  <footnote><para> If you are
3852  asking a sponsor to upload your package, this kind of clear separation and  asking a sponsor to upload your package, this kind of clear separation and
3853  documentation of your changes are very important to expedite the package review  documentation of your changes is very important to expedite the package review
3854  by your sponsor.  </para> </footnote>  by your sponsor.  </para> </footnote>
3855  </para>  </para>
3856  <para>  <para>
3857  For <xref linkend="modify"/>, we created 3 patches in  For <xref linkend="modify"/>, we created three patches in
3858  <filename>debian/patches</filename>.  <filename>debian/patches</filename>.
3859  </para>  </para>
3860  <para>  <para>
3861  Since Debian patches are located in <filename>debian/patches</filename>, please  Since Debian patches are located in <filename>debian/patches</filename>, please
3862  make sure to setup the <command>dquilt</command> command properly as described  make sure to set up the <command>dquilt</command> command properly as described
3863  in <xref linkend="quiltrc"/>.  in <xref linkend="quiltrc"/>.
3864  </para>  </para>
3865  <para>  <para>
3866  When someone (including yourself) provides you with a patch  When anyone (including yourself) provides a patch
3867  <filename><replaceable>foo</replaceable>.patch</filename> to the source later,  <filename><replaceable>foo</replaceable>.patch</filename> to the source later,
3868  then the modification of a <literal>3.0 (quilt)</literal> source package is  modifying a <literal>3.0 (quilt)</literal> source package is
3869  quite simple:  quite simple:
3870  </para>  </para>
3871  <screen>  <screen>
# Line 3833  $ dquilt header -e Line 3879  $ dquilt header -e
3879  </screen>  </screen>
3880  <para>  <para>
3881  The patches stored in the newer <literal>3.0 (quilt)</literal> source format  The patches stored in the newer <literal>3.0 (quilt)</literal> source format
3882  must be <emphasis>fuzz</emphasis> free.  You should ensure it as <literal>dquilt  must be <emphasis>fuzz</emphasis> free.  You can ensure this with <literal>dquilt
3883  pop -a; while dquilt push; do dquilt refresh; done</literal>.  pop -a; while dquilt push; do dquilt refresh; done</literal>.
3884  </para>  </para>
3885  </section>  </section>
# Line 3844  We should now be ready to build the pack Line 3890  We should now be ready to build the pack
3890  </para>  </para>
3891  <section id="completebuild"><title>Complete (re)build</title>  <section id="completebuild"><title>Complete (re)build</title>
3892  <para>  <para>
3893  In order to properly make complete (re)build of a package, you have to ensure  In order to perform a complete (re)build of a package properly, you
3894  to install  need to make sure you have installed
3895  </para>  </para>
3896  <itemizedlist>  <itemizedlist>
3897  <listitem>  <listitem>
# Line 3952  people can be sure that it's really your Line 3998  people can be sure that it's really your
3998  </para>  </para>
3999  <para>  <para>
4000  This compressed tarball contains your <filename>debian</filename> directory  This compressed tarball contains your <filename>debian</filename> directory
4001  contents.  Each and every addition you made to the original source code are  contents.  Each and every addition you made to the original source code is
4002  stored as <command>quilt</command> patches in  stored as a <command>quilt</command> patch in
4003  <filename>debian/patches</filename>.  <filename>debian/patches</filename>.
4004  </para>  </para>
4005  <para>  <para>
# Line 3981  install and remove this just like any ot Line 4027  install and remove this just like any ot
4027  <filename>gentoo_0.9.12-1_i386.changes</filename>  <filename>gentoo_0.9.12-1_i386.changes</filename>
4028  </para>  </para>
4029  <para>  <para>
4030  This file describes all the changes made in the current package revision, and  This file describes all the changes made in the current package revision;
4031  it is used by the Debian FTP archive maintenance programs to install the binary  it is used by the Debian FTP archive maintenance programs to install the binary
4032  and source packages in it.  It is partly generated from the  and source packages.  It is partly generated from the
4033  <filename>changelog</filename> file and the <filename>.dsc</filename> file.  <filename>changelog</filename> file and the <filename>.dsc</filename> file.
4034  This file is GPG signed, so that people can be sure that it's really yours.  This file is GPG signed, so that people can be sure that it's really yours.
4035  </para>  </para>
4036  <para>  <para>
4037  As you keep working on the package, behavior will change and new features will  As you keep working on the package, its behavior will change and new features will
4038  be added.  People downloading your package can look at this file and quickly  be added.  People downloading your package can look at this file and quickly
4039  see what has changed.  Debian archive maintenance programs will also post the  see what has changed.  Debian archive maintenance programs will also post the
4040  contents of this file to the <ulink url="&debian-devel-announce-ldo;">debian-devel-announce@lists.debian.org</ulink>  contents of this file to the <ulink url="&debian-devel-announce-ldo;">debian-devel-announce@lists.debian.org</ulink>
# Line 3998  mailing list. Line 4044  mailing list.
4044  </itemizedlist>  </itemizedlist>
4045  <para>  <para>
4046  The long strings of numbers in the <filename>.dsc</filename> and  The long strings of numbers in the <filename>.dsc</filename> and
4047  <filename>.changes</filename> files are MD5/SHA1/SHA256 checksums for the files  <filename>.changes</filename> files are SHA1/SHA256 checksums for the files
4048  mentioned.  A person downloading your files can test them with <citerefentry>  mentioned.  Anyone downloading your files can test them with <citerefentry>
4049  <refentrytitle>md5sum</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,  <refentrytitle>sha1sum</refentrytitle> <manvolnum>1</manvolnum>
4050  <citerefentry> <refentrytitle>sha1sum</refentrytitle> <manvolnum>1</manvolnum>  </citerefentry> or <citerefentry> <refentrytitle>sha256sum</refentrytitle>
 </citerefentry>, or <citerefentry> <refentrytitle>sha256sum</refentrytitle>  
4051  <manvolnum>1</manvolnum> </citerefentry> and if the numbers don't match,  <manvolnum>1</manvolnum> </citerefentry> and if the numbers don't match,
4052  they'll know the file is corrupt or has been tampered with.  they'll know the file is corrupt or has been tampered with.
4053  </para>  </para>
# Line 4011  they'll know the file is corrupt or has Line 4056  they'll know the file is corrupt or has
4056  <para>  <para>
4057  Debian supports many <ulink url="&ports;">ports</ulink>  Debian supports many <ulink url="&ports;">ports</ulink>
4058  with the <ulink url="&buildd;">autobuilder  with the <ulink url="&buildd;">autobuilder
4059  network</ulink> running <command>buildd</command> daemons on many different  network</ulink> running <command>buildd</command> daemons on computers
4060  architecture computers.  Although you do not need to do this by yourself, you  of many different architectures.  Although you do not need to do this yourself, you
4061  should be aware of what will happen on your packages.  Let's look into roughly  should be aware of what will happen to your packages.  Let's look into roughly
4062  how your packages are rebuild for many different architectures by them.  how they rebuild your packages for multiple architectures.
4063  <footnote><para> The actual autobuilder system involves much more complicated  <footnote><para> The actual autobuilder system involves much more complicated
4064  schemes than the one documented here.  Such details are beyond the scope of  schemes than the one documented here.  Such details are beyond the scope of
4065  this document.  </para> </footnote>  this document.  </para> </footnote>
4066  </para>  </para>
4067  <para>  <para>
4068  For <literal>Architecture: any</literal> packages, the autobuilder system  For <literal>Architecture: any</literal> packages, the autobuilder system
4069  rebuild them.  It ensures to install  performs a rebuild.  It ensures the installation of
4070  </para>  </para>
4071  <itemizedlist>  <itemizedlist>
4072  <listitem>  <listitem>
# Line 4078  create and sign the upload <filename>.ch Line 4123  create and sign the upload <filename>.ch
4123  This is why you see your package for other architectures.  This is why you see your package for other architectures.
4124  </para>  </para>
4125  <para>  <para>
4126  Although packages listed in the <literal>Build-Depends-indep</literal> field  Although packages listed in the <literal>Build-Depends-Indep</literal> field
4127  are required to be installed for the normal packaging by us (see <xref linkend="completebuild"/>), they are not required to be installed for the  are required to be installed for our normal packaging work (see
4128  autobuilder system since it build only architecture dependent binary packages.  <xref linkend="completebuild"/>), they are not required to be installed for the
4129    autobuilder system since it builds only architecture dependent binary packages.
4130  <footnote><para> Unlike under the <systemitem role="package">pbuilder</systemitem> package, the <command>chroot</command>  <footnote><para> Unlike under the <systemitem role="package">pbuilder</systemitem> package, the <command>chroot</command>
4131  environment under the <systemitem role="package">sbuild</systemitem> package  environment under the <systemitem role="package">sbuild</systemitem> package
4132  used by the autobuilder system does not force the minimal system and may leave  used by the autobuilder system does not enforce the use of a minimal
4133  many packages installed.  </para> </footnote> This difference between normal  system and may have many leftover packages installed.  </para>
4134  packaging and autobuilder situation dictates whether you record such required  </footnote> This distinction between normal packaging and autobuilding
4135    procedures is what dictates whether you should record such required
4136  packages in the <literal>Build-Depends</literal> or  packages in the <literal>Build-Depends</literal> or
4137  <literal>Build-Depends-indep</literal> fields of the  <literal>Build-Depends-Indep</literal> fields of the
4138  <filename>debian/control</filename> file (see <xref linkend="control"/>).  <filename>debian/control</filename> file (see <xref linkend="control"/>).
4139  </para>  </para>
4140  </section>  </section>
# Line 4095  packages in the <literal>Build-Depends</ Line 4142  packages in the <literal>Build-Depends</
4142  <para>  <para>
4143  When you first upload the package to the archive, you need to include the  When you first upload the package to the archive, you need to include the
4144  original <filename>orig.tar.gz</filename> source, too.  If the Debian revision  original <filename>orig.tar.gz</filename> source, too.  If the Debian revision
4145  number of such package is neither <literal>1</literal> nor  number of this package is neither <literal>1</literal> nor
4146  <literal>0</literal>, you must provide <command>dpkg-buildpackage</command>  <literal>0</literal>, you must provide the <command>dpkg-buildpackage</command>
4147  command with the <literal>-sa</literal> option.  On the other hand, the  command with the <literal>-sa</literal> option.  On the other hand, the
4148  <literal>-sd</literal> option will force to exclude the original  <literal>-sd</literal> option will force the exclusion of the original
4149  <filename>orig.tar.gz</filename> source.  <filename>orig.tar.gz</filename> source.
4150  </para>  </para>
4151  </section>  </section>
4152  <section id="debuild"><title><command>debuild</command> command</title>  <section id="debuild"><title><command>debuild</command> command</title>
4153  <para>  <para>
4154  You can automate package build process of the  You can automate the <command>dpkg-buildpackage</command> command's
4155  <command>dpkg-buildpackage</command> command further with the  package build process further with the
4156  <command>debuild</command> command.  See <citerefentry>  <command>debuild</command> command.  See <citerefentry>
4157  <refentrytitle>debuild</refentrytitle> <manvolnum>1</manvolnum>  <refentrytitle>debuild</refentrytitle> <manvolnum>1</manvolnum>
4158  </citerefentry>.  </citerefentry>.
# Line 4113  You can automate package build process o Line 4160  You can automate package build process o
4160  <para>  <para>
4161  Customization of the <command>debuild</command> command can be done through  Customization of the <command>debuild</command> command can be done through
4162  <filename>/etc/devscripts.conf</filename> or  <filename>/etc/devscripts.conf</filename> or
4163  <filename>~/.devscripts</filename>.  I would suggest at least following items:  <filename>~/.devscripts</filename>.  I would suggest at least the following items:
4164  </para>  </para>
4165  <screen>  <screen>
4166  DEBSIGN_KEYID=Your_GPG_keyID  DEBSIGN_KEYID=Your_GPG_keyID
# Line 4122  DEBUILD_LINTIAN_OPTS=-i -I --show-overri Line 4169  DEBUILD_LINTIAN_OPTS=-i -I --show-overri
4169  </screen>  </screen>
4170  <para>  <para>
4171  With these, packages are signed by your specified GPG key ID (good for  With these, packages are signed by your specified GPG key ID (good for
4172  sponsoring packages) and checked by the <command>lintian</command> command in  sponsoring packages) and checked in detail by the <command>lintian</command> command.
 details.  
4173  </para>  </para>
4174  <para>  <para>
4175  Cleaning source and rebuilding package from a user account is as simple as:  Cleaning the source and rebuilding the package from your user account is as simple as:
4176  </para>  </para>
4177  <screen>  <screen>
4178  $ debuild  $ debuild
# Line 4140  source can be specified as: Line 4186  source can be specified as:
4186  $ debuild -sa  $ debuild -sa
4187  </screen>  </screen>
4188  <para>  <para>
4189  You can clean source tree as simple as:  You can clean the source tree as simply as:
4190  </para>  </para>
4191  <screen>  <screen>
4192  $ debuild clean  $ debuild clean
# Line 4150  $ debuild clean Line 4196  $ debuild clean
4196  <para>  <para>
4197  For a clean room (<command>chroot</command>) build environment to verify the  For a clean room (<command>chroot</command>) build environment to verify the
4198  build dependencies, the <systemitem role="package">pbuilder</systemitem>  build dependencies, the <systemitem role="package">pbuilder</systemitem>
4199  package is very useful.  <footnote><para> Since the <systemitem role="package">pbuilder</systemitem> package is still evolving, you have to  package is very useful.  <footnote><para> Since the <systemitem
4200    role="package">pbuilder</systemitem> package is still evolving, you should
4201  check the actual configuration situation by consulting the latest official  check the actual configuration situation by consulting the latest official
4202  documentation.</para> </footnote> This ensures a clean build from the source  documentation.</para> </footnote> This ensures a clean build from the source
4203  under the <literal>sid</literal> auto-builder for different architectures and  under the <literal>sid</literal> auto-builder for different architectures and
4204  avoids the severity serious FTBFS (Fails To Build From Source) bug which is  avoids a severity serious FTBFS (Fails To Build From Source) bug which is
4205  always in the RC (release critical) category.  always in the RC (release critical) category.
4206  <footnote><para>See <ulink url="&buildd-do;"/> for more on the  <footnote><para>See <ulink url="&buildd-do;"/> for more on
4207  auto-builder of the Debian package.</para></footnote>  Debian package auto-building.
4208    .</para></footnote>
4209  </para>  </para>
4210  <para>  <para>
4211  Let's customize the <systemitem role="package">pbuilder</systemitem> package by  Let's customize the <systemitem role="package">pbuilder</systemitem> package as
4212  the following.  follows:
4213  </para>  </para>
4214  <itemizedlist>  <itemizedlist>
4215  <listitem>  <listitem>
4216  <para>  <para>
4217  setting <filename>/var/cache/pbuilder/result</filename> directory writable by  setting the <filename>/var/cache/pbuilder/result</filename> directory writable by
4218  the user.  for your user account.
4219  </para>  </para>
4220  </listitem>  </listitem>
4221  <listitem>  <listitem>
4222  <para>  <para>
4223  creating a directory, e.g.  creating a directory, e.g.
4224  <filename><replaceable>/var/cache/pbuilder/hooks</replaceable></filename>,  <filename><replaceable>/var/cache/pbuilder/hooks</replaceable></filename>,
4225  writable by the user to place hook scripts.  writable by the user, to place hook scripts in.
4226  </para>  </para>
4227  </listitem>  </listitem>
4228  <listitem>  <listitem>
4229  <para>  <para>
4230  setting <filename>~/.pbuilderrc</filename> or  configuring <filename>~/.pbuilderrc</filename> or
4231  <filename>/etc/pbuilderrc</filename> to include as follows.  <filename>/etc/pbuilderrc</filename> to include the followsing.
4232  </para>  </para>
4233  <screen>  <screen>
4234  AUTO_DEBSIGN=yes  AUTO_DEBSIGN=yes
# Line 4193  This will allow you to sign generated pa Line 4241  This will allow you to sign generated pa
4241  <filename>~/.gnupg/</filename> directory.  <filename>~/.gnupg/</filename> directory.
4242  </para>  </para>
4243  <para>  <para>
4244  Let's then initialize the local <systemitem role="package">pbuilder</systemitem> <command>chroot</command> system first as  First let's initialize the local <systemitem role="package">pbuilder</systemitem> <command>chroot</command> system as
4245  follows.  follows.
4246  </para>  </para>
4247  <screen>  <screen>
4248  $ sudo pbuilder create  $ sudo pbuilder create
4249  </screen>  </screen>
4250  <para>  <para>
4251  If you already have the completed source packages, issue the following commands  If you already have a completed source package, issue the following commands
4252  in the directory where the  in the directory where the
4253  <filename><replaceable>foo</replaceable>.orig.tar.gz</filename>,  <filename><replaceable>foo</replaceable>.orig.tar.gz</filename>,
4254  <filename><replaceable>foo</replaceable>.debian.tar.gz</filename>, and  <filename><replaceable>foo</replaceable>.debian.tar.gz</filename>, and
# Line 4225  The newly built packages will be located Line 4273  The newly built packages will be located
4273  <filename>/var/cache/pbuilder/result/</filename> with non-root ownership.  <filename>/var/cache/pbuilder/result/</filename> with non-root ownership.
4274  </para>  </para>
4275  <para>  <para>
4276  If you already have the updated source tree without generating the matching  If you have an updated source tree but have not generated the matching
4277  source packages, issue the following commands in the source directory where the  source package, issue the following commands in the source directory where the
4278  <filename>debian</filename> directory exists, instead.  <filename>debian</filename> directory exists, instead.
4279  </para>  </para>
4280  <screen>  <screen>
# Line 4253  the <literal>chroot</literal> environmen Line 4301  the <literal>chroot</literal> environmen
4301  <filename><replaceable>/var/cache/pbuilder/hooks</replaceable>/B90lintian</filename>  <filename><replaceable>/var/cache/pbuilder/hooks</replaceable>/B90lintian</filename>
4302  configured as follows.  <footnote><para> This assumes  configured as follows.  <footnote><para> This assumes
4303  <literal>HOOKDIR=/var/cache/pbuilder/hooks</literal>.  You can find many  <literal>HOOKDIR=/var/cache/pbuilder/hooks</literal>.  You can find many
4304  examples of the hook script in the  examples of hook scripts in the
4305  <filename>/usr/share/doc/pbuilder/examples</filename> directory.  </para>  <filename>/usr/share/doc/pbuilder/examples</filename> directory.  </para>
4306  </footnote>  </footnote>
4307  </para>  </para>
# Line 4272  echo +++ end of lintian output +++ Line 4320  echo +++ end of lintian output +++
4320  </screen>  </screen>
4321  <para>  <para>
4322  You need to have access to the latest <literal>sid</literal> environment to  You need to have access to the latest <literal>sid</literal> environment to
4323  build packages properly for <literal>sid</literal>.  In reality,  build packages properly for <literal>sid</literal>.  In practice,
4324  <literal>sid</literal> may be experiencing issues which makes it not desirable  <literal>sid</literal> may be experiencing issues which makes it undesirable
4325  for you to migrate your whole system.  The <systemitem role="package">pbuilder</systemitem> package can help you to cope with this  for you to migrate your whole system.  The <systemitem role="package">pbuilder</systemitem> package can help you to cope with this
4326  kind of situation.  kind of situation.
4327  </para>  </para>
# Line 4282  You may need to update your <literal>sta Line 4330  You may need to update your <literal>sta
4330  release for <literal>stable-proposed-updates</literal>,  release for <literal>stable-proposed-updates</literal>,
4331  <literal>stable/updates</literal>, etc.  <footnote><para> There are some  <literal>stable/updates</literal>, etc.  <footnote><para> There are some
4332  restrictions for such updates of your <literal>stable</literal> package.  restrictions for such updates of your <literal>stable</literal> package.
4333  </para> </footnote> For such occasions, I am running <literal>sid</literal>  </para> </footnote> For such occasions, the fact you may be running a <literal>sid</literal>
4334  system is not good enough excuse not to update them promptly.  The <systemitem role="package">pbuilder</systemitem> package can help you to access  system is not a good enough excuse for failing to update them promptly.  The <systemitem role="package">pbuilder</systemitem> package can help you to access
4335  environments of almost any Debian derivative distributions of the same CPU  environments of almost any Debian derivative distribution of the same CPU
4336  architecture.  architecture.
4337  </para>  </para>
4338  <para>  <para>
# Line 4298  See <ulink url="&pbuilder;"/>, Line 4346  See <ulink url="&pbuilder;"/>,
4346  </section>  </section>
4347  <section id="git-buildpackage"><title><command>git-buildpackage</command> command and similars</title>  <section id="git-buildpackage"><title><command>git-buildpackage</command> command and similars</title>
4348  <para>  <para>
4349  If your upstream uses the source code management system (VCS)  If your upstream uses a source code management system (VCS)
4350  <footnote><para>See <ulink url="&debref-vcs;">Version control systems</ulink> for more.</para></footnote>  <footnote><para>See <ulink url="&debref-vcs;">Version control systems</ulink> for more.</para></footnote>
4351  to maintain their code, you should consider to use them.  That makes merging  to maintain their code, you should consider using it as well.  This makes merging
4352  and cherry-picking upstream patches much easier.  There are several specialized  and cherry-picking upstream patches much easier.  There are several specialized
4353  wrapper script packages for the Debian package building for each VCS.  wrapper script packages for Debian package building for each VCS.
4354  </para>  </para>
4355  <itemizedlist>  <itemizedlist>
4356  <listitem>  <listitem>
4357  <para>  <para>
4358  <systemitem role="package">git-buildpackage</systemitem>: Suite to help with  <systemitem role="package">git-buildpackage</systemitem>: a suite to help with
4359  Debian packages in Git repositories.  Debian packages in Git repositories.
4360  </para>  </para>
4361  </listitem>  </listitem>
# Line 4319  maintain Debian packages with Subversion Line 4367  maintain Debian packages with Subversion
4367  </listitem>  </listitem>
4368  <listitem>  <listitem>
4369  <para>  <para>
4370  <systemitem role="package">cvs-buildpackage</systemitem>: A set of Debian  <systemitem role="package">cvs-buildpackage</systemitem>: a set of Debian
4371  package scripts for CVS source trees.  package scripts for CVS source trees.
4372  </para>  </para>
4373  </listitem>  </listitem>
4374  </itemizedlist>  </itemizedlist>
4375  <para>  <para>
4376  There are packages which <emphasis>automate</emphasis> building of packages  For advanced audiences, there are packages which <emphasis>automate</emphasis>
4377  under VCS managed source tree for advanced audiences.  I will not explain them  the building of packages under a VCS-managed source tree.  I will not explain them
4378  in this tutorial.  in this tutorial.
4379  <footnote><para> Here are few web resources available for advanced audiences.  </para>  <footnote><para> Here are some web resources available for advanced audiences.  </para>
4380  <itemizedlist>  <itemizedlist>
4381  <listitem> <para> <ulink url="&git-buildpackage-doc;">Building Debian Packages with git-buildpackage</ulink> </para> </listitem>  <listitem> <para> <ulink url="&git-buildpackage-doc;">Building Debian Packages with git-buildpackage</ulink> </para> </listitem>
4382  <listitem> <para> <ulink url="&debian-packages-git;">debian packages in git</ulink> </para> </listitem>  <listitem> <para> <ulink url="&debian-packages-git;">debian packages in git</ulink> </para> </listitem>
4383  <listitem> <para> <ulink url="&git-debian-packaging;">Using Git for Debian Packaging</ulink> </para> </listitem>  <listitem> <para> <ulink url="&git-debian-packaging;">Using Git for Debian Packaging</ulink> </para> </listitem>
4384  <listitem> <para> <ulink url="&git-dpm;">git-dpm: Debian packages in Git manager</ulink> </para> </listitem>  <listitem> <para> <ulink url="&git-dpm;">git-dpm: Debian packages in Git manager</ulink> </para> </listitem>
4385  <listitem> <para> <ulink url="&topgit;">Using TopGit to generate quilt series for Debian packaging</ulink> </para> </listitem>  <listitem> <para> <ulink url="&topgit;">Using TopGit to generate quilt series for Debian packaging</ulink> </para> </listitem>
# Line 4342  in this tutorial. Line 4390  in this tutorial.
4390  <section id="quickrebuild"><title>Quick rebuild</title>  <section id="quickrebuild"><title>Quick rebuild</title>
4391  <para>  <para>
4392  With a large package, you may not want to rebuild from scratch every time while  With a large package, you may not want to rebuild from scratch every time while
4393  you tune details in <filename>debian/rules</filename>.  For testing purposes,  you're tuning details in <filename>debian/rules</filename>.  For testing purposes,
4394  you can make a <filename>.deb</filename> file without rebuilding the upstream  you can make a <filename>.deb</filename> file without rebuilding the upstream
4395  sources like this <footnote><para> Environment variables which are normally  sources like this<footnote><para> Environment variables which are normally
4396  configured to proper values are not set by this method.  Never create real  configured to proper values are not set by this method.  Never create real
4397  packages to be uploaded using this <emphasis role="strong">quick</emphasis>  packages to be uploaded using this <emphasis role="strong">quick</emphasis>
4398  method.  </para> </footnote>:  method.  </para> </footnote>:
# Line 4353  method.  </para> </footnote>: Line 4401  method.  </para> </footnote>:
4401  $ fakeroot debian/rules binary  $ fakeroot debian/rules binary
4402  </screen>  </screen>
4403  <para>  <para>
4404  Or, simply as following to see if it build or not.  Or simply do the following to see if it builds or not:
4405  </para>  </para>
4406  <screen>  <screen>
4407  $ fakeroot debian/rules build  $ fakeroot debian/rules build
# Line 4649  these options means. Line 4697  these options means.
4697  The <literal>$default_host</literal> option determines which of the upload  The <literal>$default_host</literal> option determines which of the upload
4698  queues will be used by default.  <literal>anonymous-ftp-master</literal> is the  queues will be used by default.  <literal>anonymous-ftp-master</literal> is the
4699  primary one, but it's possible that you will want to use another one.  primary one, but it's possible that you will want to use another one.
4700  <footnote><para>See <ulink url="&devref-upload;">Debian Developer's Reference 5.6. 'Uploading a package'</ulink>.</para></footnote>  <footnote><para>See <ulink url="&devref-upload;">Debian Developer's Reference 5.6. "Uploading a package"</ulink>.</para></footnote>
4701  </para>  </para>
4702  <para>  <para>
4703  While connected to the Internet, you can upload your package by the following:  While connected to the Internet, you can upload your package by the following:
Legend:
Removed from v.8719  
changed lines
  Added in v.8731
  ViewVC Help
Powered by ViewVC 1.1.5