/[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 8704 by osamu, Thu Apr 21 16:16:35 2011 UTC revision 8728 by osamu, Tue Apr 26 13:43:45 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 148  that it will prepare you for interaction Line 149  that it will prepare you for interaction
149      </itemizedlist></listitem>      </itemizedlist></listitem>
150  </itemizedlist>  </itemizedlist>
151  <para>  <para>
152  Since we focus only on technical aspects of packaging in this document,  There are several types of people interacting around Debian with different
153  please refer to the following to learn how Debian functions and how you can get involved.  roles.
154  </para>  </para>
155  <itemizedlist>  <itemizedlist>
156  <listitem><para><ulink url="&logiciellibre;">Debian: 17 years of Free Software, "do-ocracy", and democracy</ulink> (Introductory slides) </para> </listitem>  <listitem>
157  <listitem><para><ulink url="&debianorghelp;">How can you help Debian?</ulink> (official) </para> </listitem>  <para>
158  <listitem><para><ulink url="&debianfaqhelp;">The Debian GNU/Linux FAQ, Chapter 13 - 'Contributing to the Debian Project'</ulink> (semi-official) </para> </listitem>  <emphasis role="strong">upstream author</emphasis>: the person who made the
159  <listitem><para><ulink url="&debianwikihelp;">Debian Wiki, HelpDebian</ulink> (supplemental) </para> </listitem>  original program.
160  <listitem><para><ulink url="&nm-do;">Debian New Maintainer site</ulink> (official) </para> </listitem>  </para>
161  <listitem><para><ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink> (supplemental) </para> </listitem>  </listitem>
162    <listitem>
163    <para>
164    <emphasis role="strong">upstream maintainer</emphasis>: the person who
165    currently maintains the program.
166    </para>
167    </listitem>
168    <listitem>
169    <para>
170    <emphasis role="strong">maintainer</emphasis>: the person making the Debian
171    package of the program.
172    </para>
173    </listitem>
174    <listitem>
175    <para>
176    <emphasis role="strong">sponsor</emphasis>: a person who helps maintainers to
177    upload packages to the official Debian package archive (after checking their
178    contents).
179    </para>
180    </listitem>
181    <listitem>
182    <para>
183    <emphasis role="strong">mentor</emphasis>: a person who helps novice
184    maintainers with packaging etc.
185    </para>
186    </listitem>
187    <listitem>
188    <para>
189    <emphasis role="strong">Debian Developer</emphasis> (DD): a member of
190    the Debian project with full upload rights to the official Debian package
191    archive.
192    </para>
193    </listitem>
194    <listitem>
195    <para>
196    <emphasis role="strong">Debian Maintainer</emphasis> (DM): a person with
197    limited upload rights to the official Debian package archive.
198    </para>
199    </listitem>
200  </itemizedlist>  </itemizedlist>
 </section>  
 <section id="debiandeveloper"><title>Official Debian Developer</title>  
201  <para>  <para>
202  You cannot become an official  Please note that you cannot become an official
203  <emphasis role="strong">Debian Developer</emphasis> (DD) overnight, because it  <emphasis role="strong">Debian Developer</emphasis> (DD) overnight, because it
204  takes more than technical skill.  Please do not be discouraged by this.  If it  takes more than technical skill.  Please do not be discouraged by this.  If it
205  is useful to others, you can still upload your package either as a  is useful to others, you can still upload your package either as a
# Line 176  official Debian Developer.  Contributing Line 213  official Debian Developer.  Contributing
213  path to becoming an official Debian Developer too.  There are many packages  path to becoming an official Debian Developer too.  There are many packages
214  waiting for good maintainers (see <xref linkend="choose"/>).  waiting for good maintainers (see <xref linkend="choose"/>).
215  </para>  </para>
216    <para>
217    Since we focus only on technical aspects of packaging in this document,
218    please refer to the following to learn how Debian functions and how you can get involved.
219    </para>
220    <itemizedlist>
221    <listitem><para><ulink url="&logiciellibre;">Debian: 17 years of Free Software, "do-ocracy", and democracy</ulink> (Introductory slides) </para> </listitem>
222    <listitem><para><ulink url="&debianorghelp;">How can you help Debian?</ulink> (official) </para> </listitem>
223    <listitem><para><ulink url="&debianfaqhelp;">The Debian GNU/Linux FAQ, Chapter 13 - 'Contributing to the Debian Project'</ulink> (semi-official) </para> </listitem>
224    <listitem><para><ulink url="&debianwikihelp;">Debian Wiki, HelpDebian</ulink> (supplemental) </para> </listitem>
225    <listitem><para><ulink url="&nm-do;">Debian New Maintainer site</ulink> (official) </para> </listitem>
226    <listitem><para><ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink> (supplemental) </para> </listitem>
227    </itemizedlist>
228  </section>  </section>
229  <section id="needprogs"><title>Programs you need for development</title>  <section id="needprogs"><title>Programs you need for development</title>
230  <para>  <para>
# Line 372  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 program, at least, for the standard usage.  It may seem like heavy  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
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 390  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 418  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 439  are correct.  Please file a bug report o Line 492  are correct.  Please file a bug report o
492  <command>reportbug</command>.  <command>reportbug</command>.
493  </para>  </para>
494  </section>  </section>
 <section id="terminology"><title>Basic terminology</title>  
 <para>  
 There are two types of packages.  
 </para>  
 <itemizedlist>  
 <listitem>  
 <para>  
 <emphasis role="strong">source package</emphasis>: a source package is a set of  
 files which contain code and data which you can compile and process into  
 executable programs and formatted documents.  It usually comes as a combination  
 of <filename>*.orig.tar.gz</filename>, <filename>*.debian.tar.gz</filename> (or  
 <filename>*.diff.gz</filename>), and <filename>*.dsc</filename>.  Some other  
 archiving and compression methods may be used, too.  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 <emphasis role="strong">binary package</emphasis>: a binary package contains  
 executable programs and formatted documents.  It usually comes as  
 <filename>*.deb</filename> for the normal Debian system and as  
 <filename>*.udeb</filename> for the Debian Installer.  
 </para>  
 </listitem>  
 </itemizedlist>  
 <para>  
 Don't confuse terms like source of the program and the source package of the  
 program!  
 </para>  
 <para>  
 There are several official names used within Debian to refer to different  
 roles.  
 </para>  
 <itemizedlist>  
 <listitem>  
 <para>  
 <emphasis role="strong">upstream author</emphasis>: the person who made the  
 original program.  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 <emphasis role="strong">upstream maintainer</emphasis>: the person who  
 currently maintains the program.  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 <emphasis role="strong">maintainer</emphasis>: the person making the Debian  
 package of the program.  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 <emphasis role="strong">sponsor</emphasis>: a person who helps maintainers to  
 upload packages to the official Debian package archive (after checking their  
 contents).  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 <emphasis role="strong">mentor</emphasis>: a person who helps novice  
 maintainers with packaging etc.  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 <emphasis role="strong">Debian Developer</emphasis> (DD): a member of  
 the Debian project with full upload rights to the official Debian package  
 archive.  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 <emphasis role="strong">Debian Maintainer</emphasis> (DM): a person with  
 limited upload rights to the official Debian package archive.  
 </para>  
 </listitem>  
 </itemizedlist>  
 <para>  
 There are several version names<footnote><para>See <ulink url="&policy-control;#s-f-Version">Debian Policy  Manual: 5.6.12 Version</ulink>.</para></footnote> used around Debian.  
 </para>  
 <itemizedlist>  
 <listitem>  
 <para>  
 <emphasis role="strong">upstream source version</emphasis>: The upstream source  
 version is referred as <literal><replaceable>version</replaceable></literal>.  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 <emphasis role="strong">Debian revision</emphasis>: The revision by Debian on  
 package is referred as <literal><replaceable>revision</replaceable></literal>.  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 <emphasis role="strong">Debian package version</emphasis>: The Debian package  
 version is referred as the following.  
 </para>  
 <itemizedlist>  
 <listitem>  
 <para>  
 <literal><replaceable>version</replaceable></literal> for the native Debian  
 binary package and for the Debian source package.  
 </para>  
 </listitem>  
 <listitem>  
 <para>  
 <literal><replaceable>version</replaceable>-<replaceable>revision</replaceable></literal>  
 for the non-native Debian binary package.  
 </para>  
 </listitem>  
 </itemizedlist>  
 </listitem>  
 </itemizedlist>  
 <para>  
 Please read the other manuals if you need more details on terminology.  
 <footnote><para>See lists in <xref linkend="socialdynamism"/> and <xref linkend="needdocs"/>.</para></footnote>  
 </para>  
 </section>  
495  <section id="helpme"><title>Where to ask for help</title>  <section id="helpme"><title>Where to ask for help</title>
496  <para>  <para>
497  Before you decide to ask your question in some public place, please read the fine documentation.  Before you decide to ask your question in some public place, please read the fine documentation.
# Line 630  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 652  documentation</emphasis> for details). Line 585  documentation</emphasis> for details).
585  Let's start by creating a package of your own (or, even better,  Let's start by creating a package of your own (or, even better,
586  adopting an existing one).  adopting an existing one).
587  </para>  </para>
588    <section id="workflow"><title>Workflow of the Debian package building</title>
589    <para>
590    If you are making a Debian package with an upstream program,
591    typical workflow of the Debian package building involves generating several
592    specifically named files for each step as the following.
593    </para>
594    <itemizedlist>
595    <listitem>
596    <para>We obtain an upstream program file usually in a compressed tar format.</para>
597      <itemizedlist>
598      <listitem><literal><replaceable>package</replaceable>-<replaceable>version</replaceable>.tar.gz</literal></listitem>
599      </itemizedlist>
600    </listitem>
601    <listitem>
602    <para>
603    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.
605    </para>
606      <itemizedlist>
607      <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.orig.tar.gz</literal></listitem>
608      <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 <literal>1.0</literal> format,
610        <literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.diff.gz</literal>
611        is used instead. </para></footnote></listitem>
612      <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.dsc</literal></listitem>
613      </itemizedlist>
614    </listitem>
615    <listitem>
616    <para>
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.
618    </para>
619      <itemizedlist>
620      <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
621      </itemizedlist>
622    </listitem>
623    </itemizedlist>
624    <para>
625    Please note that the character separating
626    <literal><replaceable>package</replaceable></literal> and
627    <literal><replaceable>version</replaceable></literal> was changed from
628    <literal>-</literal> (hyphen) to <literal>_</literal> (underscore).
629    </para>
630    <para>
631    Here,
632    <literal><replaceable>package</replaceable></literal> part of the file name is substituted by the
633    <emphasis role="strong">package name</emphasis>,
634    <literal><replaceable>version</replaceable></literal> part of it is substituted by the
635    <emphasis role="strong">upstream version</emphasis>,
636    <literal><replaceable>revision</replaceable></literal> part of it is substituted by the
637    <emphasis role="strong">Debian revision</emphasis>,
638    <literal><replaceable>arch</replaceable></literal> part of it is substituted by the
639    <emphasis role="strong">package architecture</emphasis>.
640    <footnote><para>
641    The <emphasis role="strong">package name</emphasis>, <emphasis
642    role="strong">upstream version</emphasis>, and <emphasis role="strong">Debian
643    revision</emphasis> must be adjusted to comply with the Debian Policy Manual:
644    <ulink url="&policy-source;">5.6.1 Source</ulink>,
645    <ulink url="&policy-package;">5.6.7 Package</ulink>, and
646    <ulink url="&policy-version;">5.6.12 Version</ulink>.
647    The <emphasis role="strong">package architecture</emphasis> follows the
648    Debian Policy Manual: <ulink url="&policy-architecture;">5.6.8 Architecture</ulink>
649    and is automatically assigned by the package build process.</para></footnote>
650    </para>
651    <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.
676    </para>
677    </section>
678  <section id="choose"><title>Choose your program</title>  <section id="choose"><title>Choose your program</title>
679  <para>  <para>
680  You have probably chosen the package you want to create.  The first thing you  You have probably chosen the package you want to create.  The first thing you
# Line 806  The program should not be a daemon, or g Line 829  The program should not be a daemon, or g
829  </listitem>  </listitem>
830  <listitem>  <listitem>
831  <para>  <para>
832  The program should be in binary executable form; libraries are harder to handle.  The program should be in the binary executable form; libraries are harder to handle.
833  </para>  </para>
834  </listitem>  </listitem>
835  <listitem>  <listitem>
# Line 836  So the first thing to do is to find and Line 859  So the first thing to do is to find and
859  Presumably you already have the source file that you picked up at the  Presumably you already have the source file that you picked up at the
860  author's homepage.  Sources for free Unix programs usually come in  author's homepage.  Sources for free Unix programs usually come in
861  <command>tar</command>+<command>gzip</command> format with the extension  <command>tar</command>+<command>gzip</command> format with the extension
862  <filename>.tar.gz</filename>, or  <filename>.tar.gz</filename>,
863  <command>tar</command>+<command>bzip2</command> format with the extension  <command>tar</command>+<command>bzip2</command> format with the extension
864  <filename>.tar.bz2</filename>.  These usually contain a directory called  <filename>.tar.bz2</filename>, or
865  <filename><replaceable>programname</replaceable>-<replaceable>version</replaceable></filename>  <command>tar</command>+<command>xz</command> format with the extension
866    <filename>.tar.xz</filename>.  These usually contain a directory called
867    <filename><replaceable>package</replaceable>-<replaceable>version</replaceable></filename>
868  with all the sources inside.  with all the sources inside.
869  </para>  </para>
870  <para>  <para>
# Line 874  case).  Place the downloaded archive in Line 899  case).  Place the downloaded archive in
899  xzf gentoo-0.9.12.tar.gz</literal>).  Make sure there are no warning  xzf gentoo-0.9.12.tar.gz</literal>).  Make sure there are no warning
900  messages, even <emphasis>irrelevant</emphasis> ones, because other  messages, even <emphasis>irrelevant</emphasis> ones, because other
901  people's unpacking tools may or may not ignore these anomalies, so they  people's unpacking tools may or may not ignore these anomalies, so they
902  may have problems unpacking them.  Your shell commandline may look  may have problems unpacking them.  Your shell command line may look
903  something like this:  something like this:
904  </para>  </para>
905  <screen>  <screen>
# Line 896  install to the <filename>/usr/local/bin< Line 921  install to the <filename>/usr/local/bin<
921  that, but more on that later in <xref linkend="destdir"/>).  that, but more on that later in <xref linkend="destdir"/>).
922  </para>  </para>
923  <para>  <para>
924    You should start packaging with a completely clean (pristine) source directory,
925    or simply with freshly unpacked sources.
926    </para>
927    </section>
928    <section id="simplemake"><title>Simple build systems</title>
929    <para>
930  Simple programs come with a <filename>Makefile</filename> and can  Simple programs come with a <filename>Makefile</filename> and can
931  be compiled just by invoking <literal>make</literal>.<footnote><para>  be compiled just by invoking <literal>make</literal>.<footnote><para>
932  Many modern programs come with a script <filename>configure</filename> which  Many modern programs come with a script <filename>configure</filename> which
# Line 916  there's even a <literal>make uninstall</ Line 947  there's even a <literal>make uninstall</
947  all the installed files.  all the installed files.
948  </para>  </para>
949  </section>  </section>
950  <section id="portable"><title>Free portable programs</title>  <section id="portable"><title>Popular portable build systems</title>
951  <para>  <para>
952  A lot of free software is written in the <ulink url="&c-program;">C</ulink> and  A lot of free software programs are written in the <ulink url="&c-program;">C</ulink> and
953  <ulink url="&cxx;">C++</ulink> languages.  Many of  <ulink url="&cxx;">C++</ulink> languages.  Many of these use Autotools or
954  these use Autotools or CMake to make them portable across different platforms.  CMake to make them portable across different platforms.  These build tools need
955  These tools are used to generate the <filename>Makefile</filename> and other  to be used to generate the <filename>Makefile</filename> and other
956  required source files.  Then, such programs are built using the usual  required source files first.  Then, such programs are built using the usual
957  <literal>make; make install</literal>.  <literal>make; make install</literal>.
958  </para>  </para>
959  <para>  <para>
# Line 933  system comprising <ulink url="&autoconf; Line 964  system comprising <ulink url="&autoconf;
964  <ulink url="&gettext;">gettext</ulink>.  You can recognize  <ulink url="&gettext;">gettext</ulink>.  You can recognize
965  such sources by the <filename>configure.ac</filename>,  such sources by the <filename>configure.ac</filename>,
966  <filename>Makefile.am</filename>, and <filename>Makefile.in</filename> files.  <filename>Makefile.am</filename>, and <filename>Makefile.in</filename> files.
967  <footnote><para> See the <ulink url="&autotools-tutorial;">Autotools Tutorial</ulink>  <footnote><para>Autotools is too big to deal in this small tutorial. This
968  and <ulink url="&autotools-readme;"/>.  </para> </footnote>  section is meant to provide keywords and references only.  Please make sure to read the
969    <ulink url="&autotools-tutorial;">Autotools Tutorial</ulink> and
970    <ulink url="&autotools-readme;"/>, if you need to use it.</para></footnote>
971  </para>  </para>
972  <para>  <para>
973  The first step of the Autotools workflow is usually that upstream runs  The first step of the Autotools workflow is usually that upstream runs
# Line 961  files requires some knowledge of <comman Line 994  files requires some knowledge of <comman
994  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
995  distributed source and runs <literal>./configure &amp;&amp; make</literal> in  distributed source and runs <literal>./configure &amp;&amp; make</literal> in
996  the source directory to compile the program into a  the source directory to compile the program into a
997  <command><replaceable>binary</replaceable></command>.  <command><replaceable>binary</replaceable></command> executable.
998  </para>  </para>
999  <screen>  <screen>
1000  Makefile.in -----+                +-&gt; Makefile -----+-&gt; make -&gt; <replaceable>binary</replaceable>  Makefile.in -----+                +-&gt; Makefile -----+-&gt; make -&gt; <replaceable>binary</replaceable>
# Line 992  build system.  You can recognize such so Line 1025  build system.  You can recognize such so
1025  </section>  </section>
1026  <section id="namever"><title>Package name and version</title>  <section id="namever"><title>Package name and version</title>
1027  <para>  <para>
1028  You should start packaging with a completely clean (pristine) source directory,  If the upstream source comes as <filename>gentoo-0.9.12.tar.gz</filename>, you can
1029  or simply with freshly unpacked sources.  consider
1030    <emphasis role="strong">package name</emphasis> to be <literal>gentoo</literal> and
1031    <emphasis role="strong">upstream version</emphasis> to be <literal>0.9.12</literal>.
1032    These are used in the <filename>debian/changelog</filename> file described later in
1033    <xref linkend="changelog"/>, too.
1034    </para>
1035    <para>
1036    Although this simple approach works most of the times, you may need to adjust
1037    <emphasis role="strong">package name</emphasis> and
1038    <emphasis role="strong">upstream version</emphasis> by renaming the upstream
1039    source to follow the Debian Policy and the existing convention.
1040    </para>
1041    <para>
1042    You must choose the <emphasis role="strong">package name</emphasis>
1043    to consist only of lower case letters (<literal>a-z</literal>), digits
1044    (<literal>0-9</literal>), plus (<literal>+</literal>) and minus
1045    (<literal>-</literal>) signs, and periods (<literal>.</literal>). It must be
1046    at least two characters long, must start with an alphanumeric character, and
1047    must not be the same as existing ones.
1048    It is good idea to keep its length within 30 characters and should not exceed
1049    40 characters.
1050    </para>
1051    <!--
1052    Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):
1053    === stat for package name string length ===
1054    11 1947 36.9%   mode
1055    14 1717 54.7%  50% median
1056    23 611 91.0%   90%
1057    32 89 99.0%    99%
1058    41 12 99.9%    99.9%
1059    52 1 100.0%
1060    Previous 20 chars is becoming too short for 17% of packages
1061    Default aptitude setting display up to 30 chars (98.3%).
1062    -->
1063    <para>
1064    If upstream source uses generic words such as <literal>test-suite</literal> as
1065    its name, it is good idea to rename it not to contaminate name space for the
1066    package name and to identify its contents explicitly.
1067    <footnote><para>If you follow the
1068    <ulink url="&devref-newpackage;">Debian Developer's Reference 5.1. "New packages"</ulink>,
1069    the ITP process will usually catch this kind of issues.</para></footnote>
1070    </para>
1071    <para>
1072    You should choose the <emphasis role="strong">upstream version</emphasis>
1073    to consist only of
1074    alphanumerics (<literal>0-9A-Za-z</literal>), plus (<literal>+</literal>),
1075    tildes (<literal>~</literal>), and periods (<literal>.</literal>). It must
1076    start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter
1077    rule should help you avoid confusing file names.</para></footnote>
1078    It is good idea to keep its length within 8 characters if possible.
1079    </para>
1080    <!--
1081    Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):
1082    === stat for upstream version string length ===
1083    5 9765 60.2%  50% median and mode
1084    6 3765 73.3%
1085    7 2789 82.9%
1086    8 1158 86.9%
1087    9 501 88.6%
1088    10 773 91.3%  90%
1089    18 55 99.1%   99%
1090    27 11 99.9%    99.9
1091    35 6 100.0%
1092    === stat for debian revision string length ===
1093    1 22556 83.3%  50% median and mode
1094    2 1106 87.2%
1095    3 1312 91.7%   90%
1096    4 2127 99.1%   99%
1097    7 14 99.9%     99.9%
1098    
1099    aptitude display 10 = 8char for up + 1char (for -) + 1char for deb
1100    90chars as max for file name of binary debs (package+up+deb+arch+.deb)
1101    -->
1102    <para>
1103    If the upstream software does not use normal version system like
1104    <literal>2.30.32</literal> but uses some kind of date such as
1105    <literal>09Oct23</literal>, a random codename string or a VCS hash value as a part
1106    of version, make sure to remove them from the
1107    <emphasis role="strong">upstream version</emphasis>.  Such information can be
1108    recorded in the <filename>debian/changelog</filename> file.  If you need to
1109    invent a version string, use the <literal>YYYYMMDD</literal> format such as
1110    <literal>20110429</literal> as upstream version.  This ensures that
1111    <command>dpkg</command> properly sees later versions as upgrades.
1112    </para>
1113    <para>
1114    Version strings can be compared with <citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry> as the following.
1115  </para>  </para>
1116    <screen>
1117     $ dpkg --compare-versions <replaceable>ver1</replaceable> <replaceable>op</replaceable> <replaceable>ver2</replaceable>
1118    </screen>
1119  <para>  <para>
1120  For the package to be built correctly, you must make the program's original  The version comparison rule can be summarized as the following.
 name lowercase (if it isn't already), and you should move the source directory  
 to  
 <filename><replaceable>packagename</replaceable>-<replaceable>version</replaceable></filename>.  
 </para>  
 <para>  
 If the program name consists of more than one word, contract them to one word,  
 or make an abbreviation.  For example, a package of the program "John's little  
 editor for X" might be named <systemitem role="package">johnledx</systemitem>, or  
 <systemitem role="package">jle4x</systemitem>, or whatever you decide, as long  
 as it's under some reasonable length limit, e.g. 20 characters.  
 </para>  
 <para>  
 Also check for the exact version of the program (to be included in the package  
 version).  If this piece of software is not numbered with versions like  
 <literal>X.Y.Z</literal>, but with some kind of date, feel free to use that  
 date as the version number, as long as newer version numbers will look larger.  
 While it is best to use the same version numbering as upstream, if it is  
 in the format of <literal>09Oct23</literal> you may need to convert it to  
 <literal>YYYYMMDD</literal> format, which would be <literal>20091023</literal>,  
 to ensure that <command>dpkg</command> sees later versions as  
 upgrades.<footnote><para> Version strings can be compared with <literal>dpkg  
 --compare-versions <replaceable>ver1</replaceable>  
 <replaceable>op</replaceable> <replaceable>ver2</replaceable></literal>.  See  
 <citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum>  
 </citerefentry>.  </para> </footnote>  
1121  </para>  </para>
1122    <itemizedlist>
1123    <listitem><para>The strings are compared from the head to the tail.</para></listitem>
1124    <listitem><para>Alphabets are larger than numbers.</para></listitem>
1125    <listitem><para>Numbers are compared as the integer.</para></listitem>
1126    <listitem><para>Alphabets are compared in the ASCII code order.</para></listitem>
1127    <listitem><para>There are some special rules for periods (<literal>.</literal>), plus (<literal>+</literal>) and tildes (<literal>~</literal>) as the followings.</para>
1128      <para>
1129      <literal>0.0</literal> &lt;
1130      <literal>0.5</literal> &lt;
1131      <literal>0.10</literal> &lt;
1132      <literal>0.99</literal> &lt;
1133      <literal>1</literal> &lt;
1134      <literal>1.0~rc1</literal> &lt;
1135      <literal>1.0</literal> &lt;
1136      <literal>1.0+b1</literal> &lt;
1137      <literal>1.0+nmu1</literal> &lt;
1138      <literal>1.1</literal> &lt;
1139      <literal>2.0</literal>
1140      </para>
1141    </listitem>
1142    </itemizedlist>
1143  <para>  <para>
1144  Some programs won't be numbered at all, in which case you should contact the  One of the tricky case happens when the upstream releases
1145  upstream maintainer to see if they've got some other revision-tracking method.  <filename>gentoo-0.9.12-ReleaseCandidate-99.tar.gz</filename> as the
1146    pre-release of <filename>gentoo-0.9.12.tar.gz</filename>.  You need to make
1147    sure that the upgrade works properly by renaming the upstream source to
1148    <filename>gentoo-0.9.12~rc99.tar.gz</filename>.
1149  </para>  </para>
1150  </section>  </section>
1151  <section id="dh-make"><title>Initial Debian package</title>  <section id="dh-make"><title>Setting up <command>dh_make</command></title>
1152  <para>  <para>
1153  Set up the shell environment variables <literal>$DEBEMAIL</literal> and  Set up the shell environment variables <literal>$DEBEMAIL</literal> and
1154  <literal>$DEBFULLNAME</literal> so that various Debian maintenance  <literal>$DEBFULLNAME</literal> so that various Debian maintenance
1155  tools recognize your email address and name to use for packages.<footnote><para> The  tools recognize your email address and name to use for packages. <footnote><para> The
1156  following text assumes you are using Bash as your login shell.  If you use  following text assumes you are using Bash as your login shell.  If you use
1157  some other login shell such as Z shell, use their corresponding  some other login shell such as Z shell, use their corresponding
1158  configuration files instead of <filename>~/.bashrc</filename>. </para> </footnote>.  configuration files instead of <filename>~/.bashrc</filename>. </para> </footnote>
1159  </para>  </para>
1160  <screen>  <screen>
1161  $ cat &gt;&gt;~/.bashrc &lt;&lt;EOF  $ cat &gt;&gt;~/.bashrc &lt;&lt;EOF
# Line 1043  DEBEMAIL=your.email.address@example.org Line 1163  DEBEMAIL=your.email.address@example.org
1163  DEBFULLNAME=Firstname Lastname  DEBFULLNAME=Firstname Lastname
1164  export DEBEMAIL DEBFULLNAME  export DEBEMAIL DEBFULLNAME
1165  EOF  EOF
1166    $ . ~/.bashrc
1167  </screen>  </screen>
1168    </section>
1169    <section id="non-native-dh-make"><title>Initial non-native Debian package</title>
1170  <para>  <para>
1171  You can create an initial Debian package by issuing the  Normal Debian packages are non-native Debian packages made from upstream
1172  <command>dh_make</command> command as follows.  programs.  If you wish to create a non-native Debian package of an upstream
1173    source <filename>gentoo-0.9.12.tar.gz</filename>, you can create an initial
1174    non-native Debian package for it by issuing the <command>dh_make</command>
1175    command as follows.
1176  </para>  </para>
1177  <screen>  <screen>
1178  $ . ~/.bashrc  $ cd ~/gentoo
1179  $ cd ~/gentoo/gentoo-0.9.12  $ wget http://example.org/gentoo-0.9.12.tar.gz
1180    $ tar -xvzf gentoo-0.9.12.tar.gz
1181    $ cd gentoo-0.9.12
1182  $ dh_make -f ../gentoo-0.9.12.tar.gz  $ dh_make -f ../gentoo-0.9.12.tar.gz
1183  </screen>  </screen>
1184  <para>  <para>
# Line 1066  provided by the upstream for your Debian Line 1194  provided by the upstream for your Debian
1194  </para>  </para>
1195  <para>  <para>
1196  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
1197  to create.  Gentoo is a single binary package - it creates only one binary, and  to create.  Gentoo is a single binary package - it creates only one binary package, i.e,
1198  thus one <filename>.deb</filename> file - so we will select the first option  one <filename>.deb</filename> file - so we will select the first option
1199  (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
1200  confirm by pressing <literal><replaceable>ENTER</replaceable></literal>.  confirm by pressing <literal><replaceable>ENTER</replaceable></literal>.
1201  <footnote><para> There are several choices here: <literal>s</literal> for Single  <footnote><para> There are several choices here: <literal>s</literal> for
1202  binary, <literal>i</literal> for arch-Independent, <literal>m</literal> for  Single binary package, <literal>i</literal> for arch-Independent package, <literal>m</literal> for
1203  Multiple binary, <literal>l</literal> for Library, <literal>k</literal> for  Multiple binary packages, <literal>l</literal> for Library package, <literal>k</literal> for
1204  Kernel module, <literal>n</literal> for kernel patch, and <literal>b</literal>  Kernel module package, <literal>n</literal> for kernel patch package, and <literal>b</literal>
1205  for <systemitem role="package">cdbs</systemitem>.  This document focuses on the  for <systemitem role="package">cdbs</systemitem> package.  This document focuses on the
1206  use of the <command>dh</command> command (from the package  use of the <command>dh</command> command (from the package
1207  <systemitem role="package">debhelper</systemitem>) to create a single-binary package,  <systemitem role="package">debhelper</systemitem>) to create a single binary package,
1208  but also touches on how to use it for arch-independent or  but also touches on how to use it for arch-independent or
1209  multiple-binary packages.  The package  multiple binary packages.  The package
1210  <systemitem role="package">cdbs</systemitem> offers an alternative packaging script  <systemitem role="package">cdbs</systemitem> offers an alternative packaging script
1211  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
1212  this document.  </para> </footnote>  this document.  </para> </footnote>
# Line 1174  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 1182  Please note that there isn't space here Line 1337  Please note that there isn't space here
1337  details of fixing upstream sources, but here are some basic steps and problems  details of fixing upstream sources, but here are some basic steps and problems
1338  people often run across.  people often run across.
1339  </para>  </para>
1340  <section id="quiltrc"><title>Set up <command>quilt</command></title>  <section id="quiltrc"><title>Setting up <command>quilt</command></title>
1341  <para>  <para>
1342  The <command>quilt</command> program offers the basic method to record  The program <command>quilt</command> offers a basic method for recording
1343  modification to the source for the Debian packaging.  Since slightly different  modifications to the upstream source for Debian packaging.  It's
1344  default is desirable, let's create an alias <command>dquilt</command> for  useful to have a slightly customized default, so let's create an alias
1345  Debian packaging by adding the following line to <filename>~/.bashrc</filename>.  <command>dquilt</command> for Debian packaging by adding the following
1346    line to <filename>~/.bashrc</filename>.
1347  </para>  </para>
1348  <screen>  <screen>
1349  alias dquilt="quilt --quiltrc=~/.quiltrc-dpkg"  alias dquilt="quilt --quiltrc=~/.quiltrc-dpkg"
# Line 1198  Then let's create <filename>~/.quiltrc-d Line 1354  Then let's create <filename>~/.quiltrc-d
1354  <screen>  <screen>
1355  d=. ; while [ ! -d $d/debian -a `readlink -e $d` != / ]; do d=$d/..; done  d=. ; while [ ! -d $d/debian -a `readlink -e $d` != / ]; do d=$d/..; done
1356  if [ -d $d/debian ] &amp;&amp; [ -z $QUILT_PATCHES ]; then  if [ -d $d/debian ] &amp;&amp; [ -z $QUILT_PATCHES ]; then
1357      # Debian packaging case and unset $QUILT_PATCHES      # if in Debian packaging tree with unset $QUILT_PATCHES
1358      QUILT_PATCHES="debian/patches"      QUILT_PATCHES="debian/patches"
1359      QUILT_PATCH_OPTS="--reject-format=unified"      QUILT_PATCH_OPTS="--reject-format=unified"
1360      QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"      QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
# Line 1210  fi Line 1366  fi
1366  <para>  <para>
1367  See <citerefentry> <refentrytitle>quilt</refentrytitle>  See <citerefentry> <refentrytitle>quilt</refentrytitle>
1368  <manvolnum>1</manvolnum> </citerefentry> and  <manvolnum>1</manvolnum> </citerefentry> and
1369  <ulink url="&quilt-pdf;">quilt.pdf</ulink> for how to use  <ulink url="&quilt-pdf;">quilt.pdf</ulink> on how to use
1370  <command>quilt</command>.  <command>quilt</command>.
1371  </para>  </para>
1372  </section>  </section>
1373  <section id="fixupstream"><title>Fixing upstream bug</title>  <section id="fixupstream"><title>Fixing upstream bugs</title>
1374  <para>  <para>
1375  Let's assume you find an error in the upstream <filename>Makefile</filename>  Let's assume you find an error in the upstream <filename>Makefile</filename>
1376  file as follows where <literal>install: gentoo</literal> should have been  as follows where <literal>install: gentoo</literal> should have been
1377  <literal>install: gentoo-target</literal>.  <literal>install: gentoo-target</literal>.
1378  </para>  </para>
1379  <screen>  <screen>
# Line 1227  install: gentoo Line 1383  install: gentoo
1383          install gentoorc-example $(HOME)/.gentoorc          install gentoorc-example $(HOME)/.gentoorc
1384  </screen>  </screen>
1385  <para>  <para>
1386  Let's fix this and record this with the <command>dquilt</command> command as  Let's fix this and record it with the <command>dquilt</command> command as
1387  <filename>fix-gentoo-target.patch</filename>.  <footnote><para> The  <filename>fix-gentoo-target.patch</filename>.  <footnote><para> The
1388  <filename>debian/patches</filename> directory should exist now if you run  <filename>debian/patches</filename> directory should exist now if you ran
1389  <command>dh_make</command> as described before.  This example operation creates  <command>dh_make</command> as described before.  This example operation creates
1390  it just in case you are updating the existing package.  </para> </footnote>  it just in case you are updating an existing package.  </para> </footnote>
1391  </para>  </para>
1392  <screen>  <screen>
1393  $ mkdir debian/patches  $ mkdir debian/patches
# Line 1248  install: gentoo-target Line 1404  install: gentoo-target
1404          install gentoorc-example $(HOME)/.gentoorc          install gentoorc-example $(HOME)/.gentoorc
1405  </screen>  </screen>
1406  <para>  <para>
1407  Ask <command>dquilt</command> to refresh the patch to create  Ask <command>dquilt</command> to generate the patch to create
1408  <filename>debian/patches/fix-gentoo-target.patch</filename> and add its  <filename>debian/patches/fix-gentoo-target.patch</filename> and add its
1409  description following <ulink url="&dep3;">DEP-3: Patch Tagging Guidelines</ulink>.  description following <ulink url="&dep3;">DEP-3: Patch Tagging Guidelines</ulink>.
1410  </para>  </para>
# Line 1258  $ dquilt header -e Line 1414  $ dquilt header -e
1414  ... describe patch  ... describe patch
1415  </screen>  </screen>
1416  </section>  </section>
1417    <section id="destdir"><title>Installation of files to their destination</title>
 <section id="destdir"><title>Installation of files to the destination</title>  
1418  <para>  <para>
1419  Normally, programs install themselves in the <filename>/usr/local</filename>  Most third-party software installs itself in the <filename>/usr/local</filename>
1420  subdirectory.  Since it is reserved for system administrator's (or user's)  directory hierarchy.  On Debian this is reserved for private use
1421  private use, Debian packages must not use that directory but should use system  by the system administrator, so packages must not use directories such
1422  directories such as the <filename>/usr/bin</filename> subdirectory following  as <filename>/usr/local/bin</filename> but should instead use system
1423  the <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink> (FHS).  directories such as <filename>/usr/bin</filename>, obeying the
1424    <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink> (FHS).
1425  </para>  </para>
1426  <para>  <para>
1427  Normally, <citerefentry> <refentrytitle>make</refentrytitle>  Normally, <citerefentry> <refentrytitle>make</refentrytitle>
1428  <manvolnum>1</manvolnum> </citerefentry> is used to automate building the  <manvolnum>1</manvolnum> </citerefentry> is used to automate building the
1429  program and the execution of <literal>make install</literal> installs programs  program, and executing <literal>make install</literal> installs programs
1430  directly to the desired destination by the <literal>install</literal> target of  directly to the desired destination (following the
1431  the <filename>Makefile</filename> file.  In order for Debian to provide binary  <literal>install</literal> target in the
1432  packages, the build system installs programs to the file tree image created  <filename>Makefile</filename>).  In order for Debian to provide
1433  under a temporary directory instead to the actual destination.  pre-built installable packages, it modifies the build system to install
1434    programs into a file tree image created under a temporary directory
1435    instead of the actual destination.
1436  </para>  </para>
1437  <para>  <para>
1438  These 2 differences between (1) the normal program installation and (2) the  These two differences between normal program installation on one hand and the
1439  Debian packaging can be transparently addressed by the <systemitem role="package">debhelper</systemitem> package through the  Debian packaging system on the other can be transparently addressed by the
1440    <systemitem role="package">debhelper</systemitem> package through the
1441  <command>dh_auto_configure</command> and <command>dh_auto_install</command>  <command>dh_auto_configure</command> and <command>dh_auto_install</command>
1442  commands if the following conditions are met.  commands if the following conditions are met.
1443  </para>  </para>
1444  <itemizedlist>  <itemizedlist>
1445  <listitem>  <listitem>
1446  <para>  <para>
1447  The <filename>Makefile</filename> file follows the GNU conventions to support  The <filename>Makefile</filename> must follow GNU conventions and
1448  <literal>$(DESTDIR)</literal> variable.  support the <literal>$(DESTDIR)</literal> variable.
1449  <footnote><para> See <ulink url="&gnu-destdir;">GNU Coding Standards: 7.2.4 DESTDIR: Support for Staged Installs</ulink>.</para></footnote>  <footnote><para> See <ulink url="&gnu-destdir;">GNU Coding Standards: 7.2.4 DESTDIR: Support for Staged Installs</ulink>.</para></footnote>
1450  </para>  </para>
1451  </listitem>  </listitem>
1452  <listitem>  <listitem>
1453  <para>  <para>
1454  The source follows the Filesystem Hierarchy Standard (FHS).  The source must follow the Filesystem Hierarchy Standard (FHS).
1455  </para>  </para>
1456  </listitem>  </listitem>
1457  </itemizedlist>  </itemizedlist>
1458  <para>  <para>
1459  Programs that use GNU <command>autoconf</command>  Programs that use GNU <command>autoconf</command> follow the GNU conventions
1460  <emphasis>automatically</emphasis> follow the GNU conventions and their  automatically, so they can be trivial to package.  On the basis of
1461  packaging is almost <emphasis>automatic</emphasis>.  With this and other  this and other heuristics, it is estimated that the
1462  heuristics, the <systemitem role="package">debhelper</systemitem> package  <systemitem role="package">debhelper</systemitem> package will work for
1463  estimates that it works for about 90% of packages without making any intrusive  about 90% of packages without making any intrusive changes to their
1464  changes to their build system.  So the packaging is not as complicated as it  build system.  So packaging is not as complicated as it may seem.
 may seem.  
1465  </para>  </para>
1466  <para>  <para>
1467  If you need to make changes in the <filename>Makefile</filename> file, you  If you need to make changes in the <filename>Makefile</filename>, you
1468  should make sure to support these <literal>$(DESTDIR)</literal> variable.  The  should be careful to support the <literal>$(DESTDIR)</literal>
1469  <literal>$(DESTDIR)</literal> variable is unset in it and is prepended to each  variable.  Although it is unset by default, the <literal>$(DESTDIR)</literal>
1470  file path used for the program installation.  The packaging script will set  variable is prepended to each file path used for the program
1471  <literal>$(DESTDIR)</literal> to the temporary directory.  installation.  The packaging script will set
1472    <literal>$(DESTDIR)</literal> to the temporary directory.
1473  </para>  </para>
1474  <para>  <para>
1475  The temporary directory used by the <command>dh_auto_install</command> command  For packages of the single binary type, the temporary directory used
1476  is chosen as <filename>debian/<replaceable>package</replaceable></filename> for  by the <command>dh_auto_install</command> command will be set to
1477  single binary packages.  <footnote><para> For multiple binary packages, the  <filename>debian/<replaceable>package</replaceable></filename>.
1478    <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
1482  <filename>debian/<replaceable>package-1</replaceable>.install</filename> and  <filename>debian/<replaceable>package-1</replaceable>.install</filename> and
1483  <filename>debian/<replaceable>package-2</replaceable>.install</filename> files  <filename>debian/<replaceable>package-2</replaceable>.install</filename> files
1484  will split contents of <filename>debian/tmp</filename> into  will split the contents of <filename>debian/tmp</filename> into
1485  <filename>debian/<replaceable>package-1</replaceable></filename> and  <filename>debian/<replaceable>package-1</replaceable></filename> and
1486  <filename>debian/<replaceable>package-2</replaceable></filename> temporary  <filename>debian/<replaceable>package-2</replaceable></filename> temporary
1487  directories to create multiple binary <filename>*.deb</filename> packages.  directories, to create
1488    <filename><replaceable>package-1</replaceable>_*.deb</filename> and
1489    <filename><replaceable>package-2</replaceable>_*.deb</filename> binary
1490    packages.
1491  </para> </footnote> Everything that is contained in the temporary directory  </para> </footnote> Everything that is contained in the temporary directory
1492  will be installed on a user's system when they install your package, the only  will be installed on users' systems when they install your package; the only
1493  difference is that <command>dpkg</command> will be installing the files in the  difference is that <command>dpkg</command> will be installing the
1494  root directory.  files to paths relative to the root directory rather than your working
1495    directory.
1496  </para>  </para>
1497  <para>  <para>
1498  Bear in mind that even though your program installs in  Bear in mind that even though your program installs in
1499  <filename>debian/<replaceable>package</replaceable></filename>, it still needs  <filename>debian/<replaceable>package</replaceable></filename>, it still needs
1500  to behave correctly when placed in the root directory, i.e.  when installed  to behave correctly when installed from the <filename>.deb</filename>
1501  from the <filename>.deb</filename> package.  So you must not allow the build  package under the root directory.  So you must not allow the build
1502  system to hardcode strings like  system to hardcode strings like
1503  <literal>/home/me/deb/<replaceable>package</replaceable>-<replaceable>version</replaceable>/usr/share/<replaceable>package</replaceable></literal>  <literal>/home/me/deb/<replaceable>package</replaceable>-<replaceable>version</replaceable>/usr/share/<replaceable>package</replaceable></literal>
1504  into the package file.  into files in the package.
1505  </para>  </para>
1506  <para>  <para>
1507  Here's the relevant part of <systemitem role="package">gentoo</systemitem>'s  Here's the relevant part of <systemitem role="package">gentoo</systemitem>'s
1508  <filename>Makefile</filename> file <footnote><para> This is just an example to  <filename>Makefile</filename><footnote><para> This is just an example to
1509  show how the <filename>Makefile</filename> file should look like.  If the  show what a <filename>Makefile</filename> should look like.  If the
1510  <filename>Makefile</filename> file is created by the  <filename>Makefile</filename> is created by the
1511  <command>./configure</command> command, the correct way to fix this kind of  <command>./configure</command> command, the correct way to fix this kind of
1512  <filename>Makefile</filename> is to executed the <command>./configure</command>  <filename>Makefile</filename> is to execute <command>./configure</command>
1513  command from the <command>dh_auto_configure</command> command with default  from the <command>dh_auto_configure</command> command with default
1514  options including <literal>--prefix=/usr</literal>.  </para> </footnote>:  options including <literal>--prefix=/usr</literal>.  </para> </footnote>:
1515  </para>  </para>
1516  <screen>  <screen>
1517  # Where to put binary on 'make install'?  # Where to put binary executables on 'make install'?
1518  BIN     = /usr/local/bin  BIN     = /usr/local/bin
1519  # Where to put icons on 'make install'?  # Where to put icons on 'make install'?
1520  ICONS   = /usr/local/share/gentoo  ICONS   = /usr/local/share/gentoo
1521  </screen>  </screen>
1522  <para>  <para>
1523  We see that the files are set to install under <filename>/usr/local</filename>.  We see that the files are set to install under <filename>/usr/local</filename>.
1524  Change those paths to:  As explained above, that directory hierarchy is reserved for local use on
1525    Debian, so change those paths to:
1526  </para>  </para>
1527  <screen>  <screen>
1528  # Where to put binary on 'make install'?  # Where to put binary executables on 'make install'?
1529  BIN     = $(DESTDIR)/usr/bin  BIN     = $(DESTDIR)/usr/bin
1530  # Where to put icons on 'make install'?  # Where to put icons on 'make install'?
1531  ICONS   = $(DESTDIR)/usr/share/gentoo  ICONS   = $(DESTDIR)/usr/share/gentoo
1532  </screen>  </screen>
1533  <para>  <para>
1534  But why in that directory, and not some other?  Because Debian packages never  The exact locations that should be used for binaries, icons,
1535  install files beneath <filename>/usr/local</filename> -- that tree is reserved  documentation, etc. are specified in the Filesystem Hierarchy Standard
1536  for the system administrator's use.  Such files on Debian systems go under  (FHS).  You should browse through it and read the sections relevant to
1537  <filename>/usr</filename> instead.  your package.
 </para>  
 <para>  
 The more exact locations for binaries, icons, documentation etc.  are specified  
 in the Filesystem Hierarchy Standard (FHS).  I recommend you  
 browse it and read the sections that might concern your package.  
1538  </para>  </para>
1539  <para>  <para>
1540  So, we should install the binary in <filename>/usr/bin</filename> instead of  So, we should install binary executables in <filename>/usr/bin</filename> instead of
1541  <filename>/usr/local/bin</filename>, the manual page in  <filename>/usr/local/bin</filename>, the manual page in
1542  <filename>/usr/share/man/man1</filename> instead of  <filename>/usr/share/man/man1</filename> instead of
1543  <filename>/usr/local/man/man1</filename> etc.  Notice how there's no manual  <filename>/usr/local/man/man1</filename>, and so on.  Notice how there's no manual
1544  page mentioned in <systemitem role="package">gentoo</systemitem>'s  page mentioned in <systemitem role="package">gentoo</systemitem>'s
1545  <filename>Makefile</filename>, but since the Debian Policy requires that every  <filename>Makefile</filename>, but since Debian Policy requires that every
1546  program has one, we'll make one later and install it in  program has one, we'll make one later and install it in
1547  <filename>/usr/share/man/man1</filename>.  <filename>/usr/share/man/man1</filename>.
1548  </para>  </para>
# Line 1393  to fix them to use the right locations. Line 1553  to fix them to use the right locations.
1553  for?  You can find this out by issuing:  for?  You can find this out by issuing:
1554  </para>  </para>
1555  <screen>  <screen>
1556  $ grep -nr -e 'usr/local/lib' --include='*.[c|h]' .  $ grep -nr --include='*.[c|h]' -e 'usr/local/lib' .
1557  </screen>  </screen>
1558  <para>  <para>
1559  <command>grep</command> will run recursively through the source tree and tell  <command>grep</command> will run recursively through the source tree and tell
# Line 1404  Edit those files and in those lines repl Line 1564  Edit those files and in those lines repl
1564  with <literal>usr/lib</literal>.  This can be done automatically as follows:  with <literal>usr/lib</literal>.  This can be done automatically as follows:
1565  </para>  </para>
1566  <screen>  <screen>
1567  $ vim '+argdo %s/usr\/local\/lib/usr\/lib/gce|update' +q \  $ sed -i -e 's#usr/local/lib#usr/lib#g' \
1568        $(find . -type f -name '*.[c|h]')        $(find . -type f -name '*.[c|h]')
1569  </screen>  </screen>
1570  <para>  <para>
1571  Be careful that you don't mess up the rest of the code!  :-)  If you want to confirm each substitution instead, this can be done interactively as follows:
1572  </para>  </para>
1573    <screen>
1574    $ vim '+argdo %s#usr/local/lib#usr/lib#gce|update' +q \
1575          $(find . -type f -name '*.[c|h]')
1576    </screen>
1577    
1578  <para>  <para>
1579  After that you should find the install target (search for line that starts with  Next you should find the <literal>install</literal> target (searching
1580  <literal>install:</literal>, that will usually work) and rename all references  for the line that starts with <literal>install:</literal> will usually
1581  to directories other than ones defined at the top of the  work) and rename all references to directories other than ones defined
1582  <filename>Makefile</filename>.  at the top of the <filename>Makefile</filename>.
1583  </para>  </para>
1584  <para>  <para>
1585  Before your upstream bug fix, <systemitem role="package">gentoo</systemitem>'s  Originally, <systemitem role="package">gentoo</systemitem>'s
1586  install target said:  install target said:
1587  </para>  </para>
1588  <screen>  <screen>
# Line 1427  install: gentoo-target Line 1592  install: gentoo-target
1592          install gentoorc-example $(HOME)/.gentoorc          install gentoorc-example $(HOME)/.gentoorc
1593  </screen>  </screen>
1594  <para>  <para>
1595  Let's fix this and record this with the <command>dquilt</command> command as  Let's fix this upstream bug and record it with the <command>dquilt</command> command as
1596  <filename>debian/patches/install.patch</filename>.  <filename>debian/patches/install.patch</filename>.
1597  </para>  </para>
1598  <screen>  <screen>
# Line 1435  $ dquilt new install.patch Line 1600  $ dquilt new install.patch
1600  $ dquilt add Makefile  $ dquilt add Makefile
1601  </screen>  </screen>
1602  <para>  <para>
1603  Let's change this for Debian package as following using the editor:  In your editor, change this for the Debian package as follows:
1604  </para>  </para>
1605  <screen>  <screen>
1606  install: gentoo-target  install: gentoo-target
# Line 1445  install: gentoo-target Line 1610  install: gentoo-target
1610          install -m644 gentoorc-example $(DESTDIR)/etc/gentoorc          install -m644 gentoorc-example $(DESTDIR)/etc/gentoorc
1611  </screen>  </screen>
1612  <para>  <para>
1613  You've surely noticed that there's now a <literal>install -d</literal> command  You'll have noticed that there's now an <literal>install -d</literal> command
1614  before the other commands in the rule.  The original  before the other commands in the rule.  The original
1615  <filename>Makefile</filename> didn't have it because usually the  <filename>Makefile</filename> didn't have it because usually
1616  <literal>/usr/local/bin</literal> and other directories already exist on the  <literal>/usr/local/bin</literal> and other directories already exist on the
1617  system where one runs <literal>make install</literal>.  However, since we will  system where you are running <literal>make install</literal>.  However, since we will
1618  install into our own empty (or even nonexistent) directory, we will have to  be installing into a newly created private directory tree, we will have to
1619  create each and every one of those directories.  create each and every one of those directories.
1620  </para>  </para>
1621  <para>  <para>
# Line 1462  of additional documentation that the ups Line 1627  of additional documentation that the ups
1627          cp -a docs/* $(DESTDIR)/usr/share/doc/gentoo/html          cp -a docs/* $(DESTDIR)/usr/share/doc/gentoo/html
1628  </screen>  </screen>
1629  <para>  <para>
1630  After careful check, if everything is fine, ask <command>dquilt</command> to  Check carefully, and if everything is okay, ask <command>dquilt</command> to
1631  refresh the patch to create <filename>debian/patches/install.patch</filename>  generate the patch to create <filename>debian/patches/install.patch</filename>
1632  and add its description.  and add its description.
1633  </para>  </para>
1634  <screen>  <screen>
# Line 1491  Debian specific packaging modification: Line 1656  Debian specific packaging modification:
1656  Whenever you make changes that are not specifically related to Debian package  Whenever you make changes that are not specifically related to Debian package
1657  such as <filename>debian/patches/fix-gentoo-target.patch</filename>, be sure to  such as <filename>debian/patches/fix-gentoo-target.patch</filename>, be sure to
1658  send them to the upstream maintainer so they can be included in the next  send them to the upstream maintainer so they can be included in the next
1659  program revision and be useful to everyone else.  Also remember to make your  revision of the program and be useful to everyone else.  Also remember
1660  fixes not specific to Debian or Linux (or even Unix!) prior to sending them --  to avoid making your fixes specific to Debian or Linux - or even Unix!
1661  make them portable.  This will make your fixes much easier to apply.  Make them portable.  This will make your fixes much easier to apply.
1662  </para>  </para>
1663  <para>  <para>
1664  Note that you don't have to send the <filename>debian/*</filename> files  Note that you don't have to send the <filename>debian/*</filename> files
# Line 1504  upstream. Line 1669  upstream.
1669  <para>  <para>
1670  There is one other common problem: libraries are often different from platform  There is one other common problem: libraries are often different from platform
1671  to platform.  For example, a <filename>Makefile</filename> can contain a  to platform.  For example, a <filename>Makefile</filename> can contain a
1672  reference to a library which doesn't exist on Debian systems.  In that case, we  reference to a library which doesn't exist on the Debian system.  In that case, we
1673  need to change it to a library which does exist in Debian, and serves the same  need to change it to a library which does exist in Debian, and serves the same
1674  purpose.  purpose.
1675  </para>  </para>
1676  <para>  <para>
1677  So, if there is a line in your program's <filename>Makefile</filename> (or  Let's assume a line in your program's <filename>Makefile</filename> (or
1678  <filename>Makefile.in</filename>) that says something like this (and your  <filename>Makefile.in</filename>) as the following.
 program doesn't compile) <footnote><para> The author realizes that this is not  
 the best example considering our <systemitem role="package">libncurses</systemitem> package now ships with a  
 <filename>libcurses.so</filename> symlink, but he couldn't think of a better  
 one.  Suggestions very welcome :-) </para> </footnote>:  
1679  </para>  </para>
1680  <screen>  <screen>
1681  LIBS = -lcurses -lsomething -lsomethingelse  LIBS = -lfoo -lbar
1682  </screen>  </screen>
1683  <para>  <para>
1684  Let's fix this as <filename>debian/patches/ncurse.patch</filename> by changing  If your program doesn't compile since the <literal>foo</literal> library
1685  <literal>curses</literal> into <literal>ncurses</literal>.  doesn't exist and its equivalent is provided by the <literal>foo2</literal>
1686    library on the Debian system, you can fix this build problem as
1687    <filename>debian/patches/foo2.patch</filename> by changing
1688    <literal>foo</literal> into <literal>foo2</literal>.<footnote><para>If there
1689    are API changes from the <literal>foo</literal> library to the
1690    <literal>foo2</literal> library, required changes to the source code need to be
1691    made to match the new API.</para> </footnote>
1692  </para>  </para>
1693  <screen>  <screen>
1694  $ dquilt new ncurse.patch  $ dquilt new foo2.patch
1695  $ dquilt add Makefile  $ dquilt add Makefile
1696  $ sed -i -e s/-lcurses/-lncurses/g Makefile  $ sed -i -e 's/-lfoo/-lfoo2/g' Makefile
1697  $ dquilt refresh  $ dquilt refresh
1698  $ dquilt header -e  $ dquilt header -e
1699  ... describe patch  ... describe patch
# Line 1659  Build-Conflicts-Indep'</ulink>.</para></ Line 1826  Build-Conflicts-Indep'</ulink>.</para></
1826  <systemitem role="package">build-essential</systemitem> package are implied.  If you need  <systemitem role="package">build-essential</systemitem> package are implied.  If you need
1827  to have other tools to build your package, you should add them to these fields.  to have other tools to build your package, you should add them to these fields.
1828  Multiple entries are separated with commas; read on for the explanation of  Multiple entries are separated with commas; read on for the explanation of
1829  binary dependencies to find out more about the syntax of these lines.  binary package dependencies to find out more about the syntax of these lines.
1830  </para>  </para>
1831  <itemizedlist>  <itemizedlist>
1832  <listitem>  <listitem>
# Line 1956  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 3178  the <filename>docs</filename> file and n Line 3345  the <filename>docs</filename> file and n
3345  This <filename>install</filename> file has one line per file installed, with  This <filename>install</filename> file has one line per file installed, with
3346  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
3347  the installation directory (relative to the install directory).  One example of  the installation directory (relative to the install directory).  One example of
3348  where this is used is where a binary is forgotten to be installed, the  this is when a binary executable is forgotten to be installed, the
3349  <filename>install</filename> file would look like:  <filename>install</filename> file would look like:
3350  </para>  </para>
3351  <screen>  <screen>
3352  src/foo/mybin usr/bin  src/foo/mybin usr/bin
3353  </screen>  </screen>
3354  <para>  <para>
3355  This will mean when this package is installed, there will be a binary file  This will mean when this package is installed, there will be a binary executable
3356  <filename>/usr/bin/mybin</filename>.  <filename>/usr/bin/mybin</filename>.
3357  </para>  </para>
3358  <para>  <para>
# Line 3581  summary information concerning the switc Line 3748  summary information concerning the switc
3748  <filename>debian.tar.gz</filename> archive containing all files under the  <filename>debian.tar.gz</filename> archive containing all files under the
3749  <filename>debian</filename> directory.  This new format supports inclusion of  <filename>debian</filename> directory.  This new format supports inclusion of
3750  binary files such as PNG icons by the package maintainer without requiring  binary files such as PNG icons by the package maintainer without requiring
3751  tricks.  <footnote><para> Actually, this new format also supports multiple  tricks.  <footnote><para>Actually, this new format also supports multiple
3752  upstream tarballs and more compression methods.  These are beyond the scope of  upstream tarballs and more compression methods.  These are beyond the scope of
3753  this document.  </para> </footnote>  this document.</para> </footnote>
3754  </para>  </para>
3755  <para>  <para>
3756  When <command>dpkg-source</command> extracts a source package in <literal>3.0  When <command>dpkg-source</command> extracts a source package in <literal>3.0
# Line 4485  a public archive to share it. Line 4652  a public archive to share it.
4652  <para>  <para>
4653  Once you become an official developer,  Once you become an official developer,
4654  <footnote><para>  <footnote><para>
4655  See <xref linkend="debiandeveloper"/>.  See <xref linkend="socialdynamism"/>.
4656  </para></footnote>  </para></footnote>
4657  you can upload the package to the Debian archive.  you can upload the package to the Debian archive.
4658  <footnote><para>  <footnote><para>
# Line 4521  these options means. Line 4688  these options means.
4688  The <literal>$default_host</literal> option determines which of the upload  The <literal>$default_host</literal> option determines which of the upload
4689  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
4690  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.
4691  <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>
4692  </para>  </para>
4693  <para>  <para>
4694  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.8704  
changed lines
  Added in v.8728
  ViewVC Help
Powered by ViewVC 1.1.5