trunk/maint-guide/maint-guide.en.dbk

<?xml version="1.0" encoding="UTF-8"?>
<!-- -*- DocBook -*- -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % trans    SYSTEM "po4a/maint-guide.en.ent">   %trans;
<!ENTITY % common   SYSTEM "common.ent">   %common;
<!ENTITY % version  SYSTEM "version.ent">  %version;
]>
<book lang="en">
<!-- This is UTF-8 encoded. -->
<!--
This is reorganized to make this document robust for translation 
when some externally referenced information changes.

If you want to add extra contents to this document, please do so by
 * adding tag like &othercredit; in English and provide it for each language.
 * add extra content within msgstr but within <footnote>...</footnote>
Please note there will be content checker to match tags of msgid and msgstr.
The second rule is a way to get exception to this rule.

Please try to correct something in translation.  If you think contents needs fix,
Let's fix it in the root cause.

Please understand to keep this document focused.  Not everything you think important 
for new maintainer should be written down.  Something social needs to be elsewhere.
Some thing should be left to the practice.  Something needs to be left for exercise 
for people to check official documentations.
-->
<title>Debian New Maintainers' Guide</title>
<bookinfo>
<authorgroup>
<!-- do not use firstname and surname tags it braks Japanese.  The same with othercredit -->
<author> <personname>Josip Rodin</personname> <email>joy-mg@debian.org</email> <contrib>original contents</contrib> </author>
<author> <personname>Osamu Aoki</personname> <email>osamu@debian.org</email> <contrib>updated contents</contrib> </author>
<!-- translator credits in po4a/translator.*.ent -->
&othercredit;
</authorgroup>
<releaseinfo>version &docversion;</releaseinfo>
<pubdate>&docisodate;</pubdate>
<copyright><year>1998-2002</year> <holder>Josip Rodin</holder></copyright>
<copyright><year>2005-2011</year> <holder>Osamu Aoki</holder></copyright>
<copyright><year>2010</year>      <holder>Craig Small</holder></copyright>
<copyright><year>2010</year>      <holder>Raphaël Hertzog</holder></copyright>
<legalnotice>
<para>
This document may be used under the terms the GNU General Public License
version 2 or higher.
</para>
<para>
This document was made using with these two documents as examples:
</para>
<itemizedlist>
<listitem>
<para>
Making a Debian Package (AKA the Debmake Manual), copyright © 1997 Jaldhar
Vyas.
</para>
</listitem>
<listitem>
<para>
The New-Maintainer's Debian Packaging Howto, copyright © 1997 Will Lowe.
</para>
</listitem>
</itemizedlist>
</legalnotice>
<!-- toc -->
</bookinfo>
<chapter id="start"><title>Getting started The Right Way</title>
<para>
This document tries to describe the building of a Debian package to ordinary
Debian users and prospective developers.  It uses fairly non-technical language, and
it's well covered with working examples.  There is an old Latin saying:
<emphasis>Longum iter est per praecepta, breve et efficax per
exempla</emphasis> (It's a long way by the rules, but short and efficient with
examples).
</para>
<para>
This document has been updated for the Debian <literal>&base-release;</literal>
release.
<footnote><para> The document assumes you are using a
<literal>&base-release;</literal> or newer system.  If you need to follow this
text in an older system (including an older Ubuntu system etc.), you must
install backported <systemitem role="package">dpkg</systemitem> and 
<systemitem role="package">debhelper</systemitem> packages, at least.
</para> </footnote>
</para>
<para>
One of the things that makes Debian such a top-notch distribution is its
package system.  While there is a vast quantity of software already in the
Debian format, sometimes you need to install software that isn't.  You may be
wondering how you can make your own packages; and perhaps you think it is a very
difficult task.  Well, if you are a real novice on Linux, it is hard, but if
you were a rookie, you wouldn't be reading this document now&nbsp;:-)
You do need to know a little about Unix programming but you certainly
don't need to be a wizard.
<footnote><para>
You can learn about the basic handling of a Debian system from the
<ulink url="&debref;">Debian Reference</ulink>.  It contains some pointers to
learn about Unix programming, too.
</para></footnote>
</para>
<para>
One thing is certain, though: to properly create and maintain Debian packages
takes many hours.  Make no mistake, for our system to work the maintainers
need to be both technically competent and diligent.
</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>
If you need some help on packaging, please read <xref linkend="helpme"/>.
</para>
<para>
Newer versions of this document should always be available online at 
<ulink url="&maint-guide;"/> and in the 
<systemitem role="package">maint-guide</systemitem> package.
The translations may be available in packages such as
<systemitem role="package">maint-guide-es</systemitem>.
Please note that this documentation may be slightly outdated.
</para>
<section id="socialdynamism"><title>Social dynamics of Debian</title>
<para>
Here are some observations of Debian's social dynamics, presented in the hope
that it will prepare you for interactions with Debian.
</para>
<itemizedlist>
<listitem><para>We all are volunteers.</para>
    <itemizedlist>
    <listitem><para>You cannot impose on others what to do.</para></listitem>
    <listitem><para>You should be motivated to do things by yourself.</para></listitem>
    </itemizedlist></listitem>
<listitem><para>Friendly cooperation is the driving force.</para>
    <itemizedlist>
    <listitem><para>Your contribution should not overstrain others.</para></listitem>
    <listitem><para>Your contribution is valuable only when others appreciate it.</para></listitem>
    </itemizedlist></listitem>
<listitem><para>Debian is not your school where you get automatic attention of teachers.</para>
    <itemizedlist>
    <listitem><para>You should be able to learn many things by yourself.</para></listitem>
    <listitem><para>Attention from other volunteers is a very scarce resource.</para></listitem>
    </itemizedlist></listitem>
<listitem><para>Debian is constantly improving.</para>
    <itemizedlist>
    <listitem><para>You are expected to make high quality packages.</para></listitem>
    <listitem><para>You should adapt yourself to change.</para></listitem>
    </itemizedlist></listitem>
</itemizedlist>
<para>
There are several types of people interacting around Debian with 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>
Please note that you cannot become an official
<emphasis role="strong">Debian Developer</emphasis> (DD) overnight, because it
takes more than technical skill.  Please do not be discouraged by this.  If it
is useful to others, you can still upload your package either as a 
<emphasis role="strong">maintainer</emphasis> through a 
<emphasis role="strong">sponsor</emphasis> or as a 
<emphasis role="strong">Debian Maintainer</emphasis>.
</para>
<para>
Please note that you do not need to create any new package to become an
official Debian Developer.  Contributing to the existing packages can provide a
path to becoming an official Debian Developer too.  There are many packages
waiting for good maintainers (see <xref linkend="choose"/>).
</para>
<para>
Since we focus only on technical aspects of packaging in this document,
please refer to the following to learn how Debian functions and how you can get involved.
</para>
<itemizedlist>
<listitem><para><ulink url="&logiciellibre;">Debian: 17 years of Free Software, "do-ocracy", and democracy</ulink> (Introductory slides) </para> </listitem>
<listitem><para><ulink url="&debianorghelp;">How can you help Debian?</ulink> (official) </para> </listitem>
<listitem><para><ulink url="&debianfaqhelp;">The Debian GNU/Linux FAQ, Chapter 13 - 'Contributing to the Debian Project'</ulink> (semi-official) </para> </listitem>
<listitem><para><ulink url="&debianwikihelp;">Debian Wiki, HelpDebian</ulink> (supplemental) </para> </listitem>
<listitem><para><ulink url="&nm-do;">Debian New Maintainer site</ulink> (official) </para> </listitem>
<listitem><para><ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink> (supplemental) </para> </listitem>
</itemizedlist>
</section>
<section id="needprogs"><title>Programs you need for development</title>
<para>
Before you start anything, you should make sure that you have properly
installed some additional packages needed for development.  Note that the list
doesn't contain any packages marked <literal>essential</literal> or
<literal>required</literal> - we expect that you have those installed already.
</para>
<para>
The following packages come with the standard Debian installation, so you
probably have them already (along with any additional packages they depend on).
Still, you should check it with <literal>aptitude show
<replaceable>package</replaceable></literal>
or with <literal>dpkg -s <replaceable>package</replaceable></literal>.
</para>
<para>
The most important package to install on your development system is the
<systemitem role="package">build-essential</systemitem> package.  Once you try
to install that, it will <emphasis>pull in</emphasis> other packages required to
have a basic build environment.
</para>
<para>
For some types of packages, that is all you will require; however, there is
another set of packages that while not essential for all package builds are
useful to have installed or may be required by your package:
</para>
<itemizedlist>
<listitem>
<para>
<systemitem role="package">autoconf</systemitem>, <systemitem
role="package">automake</systemitem>, and <systemitem
role="package">autotools-dev</systemitem> - many newer programs use configure
scripts and <filename>Makefile</filename> files preprocessed with the help of
programs like these (see <literal>info autoconf</literal>, <literal>info
automake</literal>).  <systemitem role="package">autotools-dev</systemitem>
keeps up-to-date versions of certain auto files and has documentation about the
best way to use those files.
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">debhelper</systemitem> and
<systemitem role="package">dh-make</systemitem> -
<systemitem role="package">dh-make</systemitem> is necessary to create
the skeleton of our example package, and it will use some of the
<systemitem role="package">debhelper</systemitem> tools for creating
packages.  They are not essential for this purpose, but are
<emphasis>highly</emphasis> recommended for new maintainers.  It makes
the whole process very much easier to start, and to control afterwards.
(See <citerefentry> <refentrytitle>dh_make</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>, <citerefentry>
<refentrytitle>debhelper</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>.) <footnote><para> There are also some more specialized
but similar packages such as
<systemitem role="package">dh-make-perl</systemitem>,
<systemitem role="package">dh-make-php</systemitem>, etc.  </para>
</footnote>
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">devscripts</systemitem> - this package contains some
useful scripts that can be helpful for maintainers, but they are also
not necessary for building packages.  Packages recommended and suggested
by this package are worth looking into.  (See <ulink url="&devscripts-readme;"/>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">fakeroot</systemitem> - this utility lets you
emulate being root which is necessary for some parts of the build process.
(See <citerefentry> <refentrytitle>fakeroot</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">file</systemitem> - this handy program can determine
what type a file is.  (See <citerefentry> <refentrytitle>file</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">gfortran</systemitem> - the GNU Fortran 95 compiler,
necessary if your program is written in Fortran.  (See <citerefentry>
<refentrytitle>gfortran</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">git</systemitem> - this package provides a popular
version control system designed to handle very large projects with speed and
efficiency; it is used for many high profile open source projects, most notably
the Linux kernel.  (See <citerefentry> <refentrytitle>git</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>,
<ulink url="&git-doc;">git Manual</ulink>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">gnupg</systemitem> - a tool that enables you to
digitally <emphasis>sign</emphasis> packages.  This is especially important if
you want to distribute it to other people, and you will certainly be doing that
when your work gets included in the Debian distribution.  (See <citerefentry>
<refentrytitle>gpg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">gpc</systemitem> - the GNU Pascal compiler,
necessary if your program is written in Pascal.  Worthy of note here is
<systemitem role="package">fp-compiler</systemitem>, the Free Pascal Compiler,
which is also good at this task.  (See <citerefentry>
<refentrytitle>gpc</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,
<citerefentry> <refentrytitle>ppc386</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">lintian</systemitem> - this is the Debian package
checker, which can let you know of any common mistakes after you build the
package, and explains the errors found.  (See <citerefentry>
<refentrytitle>lintian</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>,
<ulink url="&lintian-doc;">Lintian User's Manual</ulink>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">patch</systemitem> - this very useful utility will
take a file containing a difference listing (produced by the
<command>diff</command> program) and apply it to the original file, producing a
patched version.  (See <citerefentry> <refentrytitle>patch</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">patchutils</systemitem> - this package contains some
utilities to work with patches such as the <command>lsdiff</command>,
<command>interdiff</command> and <command>filterdiff</command> commands.
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">pbuilder</systemitem> - this package contains
programs which are used for creating and maintaining <command>chroot</command>
environment.  Building Debian package in this <command>chroot</command>
environment verifies the proper build dependency and avoid FTBFS (Fails To
Build From Source) bugs.  (see <citerefentry>
<refentrytitle>pbuilder</refentrytitle> <manvolnum>8</manvolnum>
</citerefentry> and <citerefentry> <refentrytitle>pdebuild</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">perl</systemitem> - Perl is one of the most used
interpreted scripting languages on today's Unix-like systems, often referred to
as Unix's Swiss Army Chainsaw. (See <citerefentry>
<refentrytitle>perl</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">python</systemitem> - Python is another of the most
used interpreted scripting languages on the Debian system, combining
remarkable power with very clear syntax. (See <citerefentry>
<refentrytitle>python</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">quilt</systemitem> - this package helps you to
manage large numbers of patches by keeping track of the changes each patch
makes. Patches can be applied, un-applied, refreshed, and more.  (See
<citerefentry> <refentrytitle>quilt</refentrytitle> <manvolnum>1</manvolnum></citerefentry>, 
<ulink url="&quilt-pdf;">quilt.pdf</ulink>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">xutils-dev</systemitem> - some programs, usually
those made for X11, also use these programs to generate
<filename>Makefile</filename> files from sets of macro functions.  (See
<citerefentry> <refentrytitle>imake</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>, <citerefentry> <refentrytitle>xmkmf</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.)
</para>
</listitem>
</itemizedlist>
<para>
The short descriptions that are given above only serve to introduce you to what
each package does.  Before continuing please thoroughly read the documentation
of each program, at least, for the standard usage.  It may seem like heavy
going now, but later on you'll be <emphasis>very</emphasis> glad you read it.
</para>
<para>
If you have specific questions later, I would suggest re-reading the documents
mentioned above.  Since this is a tutorial, I have intentionally skipped
details and provided only pointers to keep it simple.
</para>
</section>
<section id="needdocs"><title>Documentation needed for development</title>
<para>
The following is the <emphasis>very important</emphasis> documentation which
you should read along with this document:
</para>
<itemizedlist>
<listitem>
<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>
<systemitem role="package">debian-policy</systemitem> - the <ulink url="&debian-policy;">Debian Policy
Manual</ulink> includes explanations of the structure and contents of the
Debian archive, several OS design issues, the <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink>
(FHS, which says where each file and directory should be), etc.  For you, the most
important thing is that it describes requirements that each package must
satisfy to be included in the distribution (see the local copies of
<ulink url="&policy-pdf;">policy.pdf</ulink> and <ulink url="&fhs-pdf;">fhs-2.3.pdf</ulink>).
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">developers-reference</systemitem> 
- the <ulink url="&developers-reference;">Debian Developer's Reference</ulink> 
describes all matters not specifically about the technical
details of packaging, like the structure of the archive, how to rename, orphan,
or adopt packages, how to do NMUs, how to manage bugs, best packaging practices,
when and where to upload etc.  (See the local copy of
<ulink url="&developers-refpdf;">developers-reference.pdf</ulink>.)
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">gnu-standards</systemitem> - this package contains
two pieces of documentation from the GNU project: 
<ulink url="&gnu-standard;">GNU Coding Standards</ulink>, and 
<ulink url="&gnu-maintainer;">Information for Maintainers of GNU Software</ulink>.
Although Debian does not require these to
be followed, these are still helpful as guidelines and common sense.
(See the local copies of
<ulink url="&gnu-standard-pdf;">standards.pdf</ulink> and
<ulink url="&gnu-maintainer-pdf;">maintain.pdf</ulink>.)
</para>
</listitem>
</itemizedlist>
<para>
If this document contradicts any of the documents mentioned above, they
are correct.  Please file a bug report on the
<systemitem role="package">maint-guide</systemitem> package using
<command>reportbug</command>.
</para>
</section>
<section id="helpme"><title>Where to ask for help</title>
<para>
Before you decide to ask your question in some public place, please read the fine documentation.
</para>
<itemizedlist>
<listitem>
<para>
files in <filename>/usr/share/doc/<replaceable>package</replaceable></filename> for all pertinent packages
</para>
</listitem>
<listitem>
<para>
contents of <literal><command>man</command> <replaceable>command</replaceable></literal> for all pertinent commands
</para>
</listitem>
<listitem>
<para>
contents of <literal><command>info</command> <replaceable>command</replaceable></literal> for all pertinent commands
</para>
</listitem>
<listitem>
<para>
contents of <ulink url="&debian-mentors-ldo;">debian-mentors@lists.debian.org mailing list archive</ulink>
</para>
</listitem>
<listitem>
<para>
contents of <ulink url="&debian-devel-ldo;">debian-devel@lists.debian.org mailing list archive</ulink>
</para>
</listitem>
</itemizedlist>
<para>
You can use web search engines more effectively by including search strings
such as <literal>site:lists.debian.org</literal> to limit the domain.
</para>
<para>
Making a small test package is a good way to learn details of packaging.
Inspecting existing well maintained packages is the best way to learn how other
people make packages.
</para>
<para>
If you still have questions about packaging that you couldn't find answers to
in the available documentation and web resources, you can ask them interactively.
</para>
<itemizedlist>
<listitem>
<para>
<ulink url="&debian-mentors-ldo;">debian-mentors@lists.debian.org mailing list</ulink>. (This mailing list is for the novice.)
</para>
</listitem>
<listitem>
<para>
<ulink url="&debian-devel-ldo;">debian-devel@lists.debian.org mailing list</ulink>. (This mailing list is for the expert.)
</para>
</listitem>
<listitem>
<para>
<ulink url="&irc-debian;">IRC</ulink> such as <literal>#debian-mentors</literal>.
</para>
</listitem>
</itemizedlist>
<para>
The more experienced Debian developers will gladly help you, if you ask
properly after making your required efforts.
</para>
<para>
When you receive a bug report (yes, actual bug reports!), you will know that it
is time for you to dig into the 
<ulink url="&bts;">Debian Bug Tracking System</ulink> 
and read the documentation there, to be able to
deal with the reports efficiently.  I highly recommend reading the 
<ulink url="&devref-bug-handling;">Debian Developer's Reference, 5.8:
"Handling bugs"</ulink>.
</para>
<para>
Even if it all worked well, it's time to start praying.  Why?  Because in just
a few hours (or days) users from all around the world will start to use your
package, and if you made some critical error you'll get mailbombed by numerous
angry Debian users...  Just kidding.  :-)
</para>
<para>
Relax and be ready for bug reports, because there is a lot more work to be done
before your package will be fully in line with Debian policies and its best
practice guidelines (once again, read the <emphasis>real
documentation</emphasis> for details).  Good luck!
</para>
</section>
</chapter>
<chapter id="first"><title>First steps</title>
<para>
Let's start by creating a package of your own (or, even better,
adopting an existing one).
</para>
<section id="workflow"><title>Workflow of the Debian package building</title>
<para>
The workflow of the Debian package building involves generating several
specifically named files for each step as the following.
</para>
<itemizedlist>
<listitem>
<para>We obtain an upstream program file usually in a compressed tar format.</para>
  <itemizedlist>
  <listitem><literal><replaceable>programname</replaceable>-<replaceable>version</replaceable>.tar.gz</literal></listitem>
  </itemizedlist>
</listitem>
<listitem>
<para>
We create an Debian source package, which reffers to the set of input files for
the Debian package building, by adding Debian package modifications to the upstream program.
</para>
  <itemizedlist>
  <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>.orig.tar.gz</literal></listitem>
  <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.debian.tar.gz</literal>
    <footnote><para>This is for the new source format 3.0.  For the older source format 1.0,
    <literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.diff.gz</literal>
    is used. </para></footnote></listitem>
  <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.dsc</literal></listitem>
  </itemizedlist>
</listitem>
<listitem>
<para>
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.
</para>
  <itemizedlist>
  <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
  </itemizedlist>
</listitem>
</itemizedlist>
<para>
Here,
<literal><replaceable>programname</replaceable></literal> part of the file name is substituted by the
<emphasis role="strong">package name</emphasis>,
<literal><replaceable>version</replaceable></literal> part of it is substituted by the
<emphasis role="strong">upstream version</emphasis>,
<literal><replaceable>revision</replaceable></literal> part of it is substituted by the
<emphasis role="strong">Debian revision</emphasis>,
<literal><replaceable>arch</replaceable></literal> part of it is substituted by the
<emphasis role="strong">package architecture</emphasis>.
<footnote><para>
The <emphasis role="strong">package name</emphasis>, <emphasis
role="strong">upstream version</emphasis>, and <emphasis role="strong">Debian
revision</emphasis> must be adjusted to comply with the Debian Policy Manual:
<ulink url="&policy-source;">5.6.1 Source</ulink>, 
<ulink url="&policy-package;">5.6.7 Package</ulink>,
<ulink url="&policy-architecture;">5.6.8 Architecture</ulink>, and
<ulink url="&policy-version;">5.6.12 Version</ulink>.
</para></footnote>
</para>
<para>
You should chose the <emphasis role="strong">package name</emphasis> 
which consists only of lower case letters (<literal>a-z</literal>), digits
(<literal>0-9</literal>), plus (<literal>+</literal>) and minus
(<literal>-</literal>) signs, and periods (<literal>.</literal>). They must be
at least two characters long and must start with an alphanumeric character.
</para>
<para>
You should use the <emphasis role="strong">upstream version</emphasis> and the
<emphasis role="strong">Debian revision</emphasis> which consists only of
alphanumerics (<literal>a-zA-Z0-9</literal>), plus (<literal>+</literal>),
tilde (<literal>~</literal>), and periods (<literal>.</literal>). They must
start with a digit (<literal>0-9</literal>).
</para>
<para>
In the following, each step of this is explained with detailed examples.
</para>
</section>
<section id="choose"><title>Choose your program</title>
<para>
You have probably chosen the package you want to create.  The first thing you
need to do is check if the package is in the distribution archive already by
using the following.
</para>
<itemizedlist>
<listitem>
<para>the <command>aptitude</command> command</para>
</listitem>
<listitem>
<para>the <ulink url="&packages-do;">Debian packages</ulink> web page</para>
</listitem>
<listitem>
<para>the <ulink url="&packages-qa-do;">Debian Package Tracking System</ulink> web page</para>
</listitem>
</itemizedlist>
<para>
If the package already exists, well, install it!  :-) If it happens to be
<emphasis role="strong">orphaned</emphasis> (that is, if its
maintainer is set to <ulink url="&qa-do;">Debian QA Group</ulink>),
you may be able to pick it up if it's still available.  You may also
adopt a package whose maintainer has filed a Request for Adoption
(<emphasis role="strong">RFA</emphasis>).<footnote> <para>See
<ulink url="&devref-adopt;">Debian Developer's Reference 5.9.5.
"Adopting a package"</ulink>.</para> </footnote>
</para>
<para>
There are several package ownership status resources.
</para>
<itemizedlist>
<listitem>
<para> <ulink url="&wnpp-do;">Work-Needing and Prospective Packages</ulink> </para>
</listitem>
<listitem>
<para> <ulink url="&wnpp-bts;">Debian Bug report logs: Bugs in pseudo-package <systemitem role="package">wnpp</systemitem> in <literal>unstable</literal></ulink> </para>
</listitem>
<listitem>
<para> <ulink url="&wnpp-dn;">Debian Packages that Need Lovin'</ulink> </para>
</listitem>
<listitem>
<para> <ulink url="&wnpp-debtags;">Browse <systemitem role="package">wnpp</systemitem> bugs based on debtags</ulink> </para>
</listitem>
</itemizedlist>
<para>
As a side note, it's important to point out that Debian already has packages
for most kinds of programs, and the number of packages already in the Debian
archive is much larger than that of contributors with upload rights.  Thus,
contributions to packages already in the archive are far more appreciated (and
more likely to receive sponsorship) by other developers <footnote><para> Having
said that, there will of course always be new programs that are worth
packaging.  </para> </footnote>.  You can contribute in various ways.
</para>
<itemizedlist>
<listitem>
<para>
taking over orphaned, yet actively used, packages
</para>
</listitem>
<listitem>
<para>
joining <ulink url="&teams;">packaging teams</ulink>
</para>
</listitem>
<listitem>
<para>
triaging bugs of very popular packages
</para>
</listitem>
<listitem>
<para>
preparing <ulink url="&devref-nmu;">QA or NMU uploads</ulink>
</para>
</listitem>
</itemizedlist>
<para>
If you are able to adopt the package, get the sources (with something like
<literal>apt-get source <replaceable>packagename</replaceable></literal>) and
examine them.  This document unfortunately doesn't include comprehensive
information about adopting packages.  Thankfully you shouldn't have a hard time
figuring out how the package works since someone has already done the initial
setup for you.  Keep reading, though; a lot of the advice below will still be
applicable for your case.
</para>
<para>
If the package is new, and you decide you'd like to see it in Debian, proceed
as follows:
</para>
<itemizedlist>
<listitem>
<para>
First, you must know that the program works, and have tried it for some time to
confirm its usefulness.
</para>
</listitem>
<listitem>
<para>
You must check that no one else is already working on the package on the
<ulink url="&wnpp-do;">Work-Needing and Prospective Packages</ulink> site.  
If no one else is working on it, file an ITP (Intent
To Package) bug report to the <systemitem role="package">wnpp</systemitem>
pseudo-package using <command>reportbug</command>.  If someone's already on it,
contact them if you feel you need to.  If not - find another interesting
program that nobody is maintaining.
</para>
</listitem>
<listitem>
<para>
The software <emphasis role="strong">must have a license</emphasis>.
</para>
<itemizedlist>
<listitem>
<para>
For the <literal>main</literal> section, Debian Policy requires it
<emphasis role="strong">to be fully compliant with the Debian Free Software
Guidelines</emphasis> (<ulink url="&dfsg;">DFSG</ulink>)
and <emphasis role="strong">not to require a package outside of
<literal>main</literal></emphasis> for compilation or execution.  This
is the desired case.
</para>
</listitem>
<listitem>
<para>
For the <literal>contrib</literal> section, it must comply with the
DFSG but it may require a package outside of <literal>main</literal> for
compilation or execution.
</para>
</listitem>
<listitem>
<para>
For the <literal>non-free</literal> section, it may be non-compliant
with the DFSG but it <emphasis role="strong">must be distributable</emphasis>.
</para>
</listitem>
</itemizedlist>
<para>
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>
and ask for advice.
</para>
</listitem>
<listitem>
<para>
The program certainly should <emphasis role="strong">not</emphasis> run setuid
root, or even better, it shouldn't need to be setuid or setgid to anything.
</para>
</listitem>
<listitem>
<para>
The program should not be a daemon, or go in an
<filename>*/sbin</filename> directory, or open a port as root.
</para>
</listitem>
<listitem>
<para>
The program should be in binary executable form; libraries are harder to handle.
</para>
</listitem>
<listitem>
<para>
The program should be well documented and its code needs to be understandable
(i.e.  not obfuscated).
</para>
</listitem>
<listitem>
<para>
You should contact the program's author(s) to check if they agree with packaging it
and are amicable to Debian.  It is important to be able to consult with the author(s)
in case of any problems with the program, so don't try to package
unmaintained software.
</para>
</listitem>
</itemizedlist>
<para>
Of course, these are just safety measures, and intended to save you from
enraging users if you do something wrong in some setuid daemon...  When you gain
more experience in packaging, you'll be able to package such software.
</para>
</section>
<section id="getit"><title>Get the program, and try it out</title>
<para>
So the first thing to do is to find and download the original source code.
Presumably you already have the source file that you picked up at the
author's homepage.  Sources for free Unix programs usually come in
<command>tar</command>+<command>gzip</command> format with the extension
<filename>.tar.gz</filename>, or
<command>tar</command>+<command>bzip2</command> format with the extension
<filename>.tar.bz2</filename>.  These usually contain a directory called
<filename><replaceable>programname</replaceable>-<replaceable>version</replaceable></filename>
with all the sources inside.
</para>
<para>
If the latest version of the source is available through a VCS such as Git,
Subversion, or CVS, you need to get it with <literal>git
clone</literal>, <literal>svn co</literal>, or <literal>cvs co</literal> and
repack it into <command>tar</command>+<command>gzip</command> format yourself
by using the <literal>--exclude-vcs</literal> option.
</para>
<para>
If your program's source comes as some other sort of archive (for instance, the
filename ends in <filename>.Z</filename> or
<filename>.zip</filename><footnote><para> You can identify the archive format
using the <command>file</command> command when the file extension is not
enough.  </para> </footnote>), you should also unpack it with the
appropriate tools and repack it.
</para>
<para>
As an example, I'll use a program called <command>gentoo</command>, a GTK+
file manager.
<footnote><para> This program is already packaged. The
<ulink url="&gentoo-package;">current version</ulink> uses Autotools as its
build structure and is substantially different from the following examples,
which were based on version 0.9.12.</para>
</footnote>
</para>
<para>
Create a subdirectory under your home directory named
<filename>debian</filename> or <filename>deb</filename> or anything you find
appropriate (e.g.  just <filename>~/gentoo</filename> would do fine in this
case).  Place the downloaded archive in it, and extract it (with <literal>tar
xzf gentoo-0.9.12.tar.gz</literal>).  Make sure there are no warning
messages, even <emphasis>irrelevant</emphasis> ones, because other
people's unpacking tools may or may not ignore these anomalies, so they
may have problems unpacking them.  Your shell commandline may look
something like this:
</para>
<screen>
$ mkdir ~/gentoo ; cd ~/gentoo
$ wget http://<replaceable>www.example.org</replaceable>/gentoo-0.9.12.tar.gz
$ tar xvzf gentoo-0.9.12.tar.gz
$ ls -F
gentoo-0.9.12/
gentoo-0.9.12.tar.gz
</screen>
<para>
Now you have another subdirectory, called <filename>gentoo-0.9.12</filename>.
Change to that directory and <emphasis>thoroughly</emphasis> read the provided
documentation.  Usually there are files named <filename>README*</filename>,
<filename>INSTALL*</filename>, <filename>*.lsm</filename> or
<filename>*.html</filename>.  You must find instructions on how to
compile and install the program (most probably they'll assume you want to
install to the <filename>/usr/local/bin</filename> directory; you won't be doing
that, but more on that later in <xref linkend="destdir"/>).
</para>
<para>
Simple programs come with a <filename>Makefile</filename> and can
be compiled just by invoking <literal>make</literal>.<footnote><para>
Many modern programs come with a script <filename>configure</filename> which
when executed creates a <filename>Makefile</filename> customized for
your system.</para></footnote> Some of them support
<literal>make check</literal>, which runs included self-tests.  Installation
to the destination directories is usually done with <literal>make
install</literal>.
</para>
<para>
Now try to compile and run your program, to make sure it works properly and
doesn't break something else while it's installing or running.
</para>
<para>
Also, you can usually run <literal>make clean</literal> (or better
<literal>make distclean</literal>) to clean up the build directory.  Sometimes
there's even a <literal>make uninstall</literal> which can be used to remove
all the installed files.
</para>
</section>
<section id="portable"><title>Free portable build system</title>
<para>
A lot of free software is written in the <ulink url="&c-program;">C</ulink> and
<ulink url="&cxx;">C++</ulink> languages.  Many of
these use Autotools or CMake to make them portable across different platforms.
These tools are used to generate the <filename>Makefile</filename> and other
required source files.  Then, such programs are built using the usual
<literal>make; make install</literal>.
</para>
<para>
<ulink url="&gnu-build-system;">Autotools</ulink> is the GNU build
system comprising <ulink url="&autoconf;">Autoconf</ulink>,
<ulink url="&automake;">Automake</ulink>,
<ulink url="&libtool;">Libtool</ulink>, and
<ulink url="&gettext;">gettext</ulink>.  You can recognize
such sources by the <filename>configure.ac</filename>,
<filename>Makefile.am</filename>, and <filename>Makefile.in</filename> files.
<footnote><para> See the <ulink url="&autotools-tutorial;">Autotools Tutorial</ulink>
and <ulink url="&autotools-readme;"/>.  </para> </footnote>
</para>
<para>
The first step of the Autotools workflow is usually that upstream runs
<literal>autoreconf -i -f</literal> in the source directory and
distributes the generated files along with the source.
</para>
<screen>
configure.ac-----+-&gt; autoreconf -+-&gt; configure
Makefile.am -----+        |      +-&gt; Makefile.in
src/Makefile.am -+        |      +-&gt; src/Makefile.in
                          |      +-&gt; config.h.in
                      automake
                      aclocal
                      aclocal.m4
                      autoheader
</screen>
<para>
Editing <filename>configure.ac</filename> and <filename>Makefile.am</filename>
files requires some knowledge of <command>autoconf</command> and
<command>automake</command>.  See <literal>info autoconf</literal> and
<literal>info automake</literal>.
</para>
<para>
The second step of the Autotools workflow is usually that the user obtains this
distributed source and runs <literal>./configure &amp;&amp; make</literal> in
the source directory to compile the program into a
<command><replaceable>binary</replaceable></command>.
</para>
<screen>
Makefile.in -----+                +-&gt; Makefile -----+-&gt; make -&gt; <replaceable>binary</replaceable>
src/Makefile.in -+-&gt; ./configure -+-&gt; src/Makefile -+
config.h.in -----+                +-&gt; config.h -----+
                          |
           config.status -+
           config.guess --+
</screen>
<para>
You can change many things in the <filename>Makefile</filename>; for
instance you can change the default location for file installation
using the option <command>./configure --prefix=/usr</command>.
</para>
<para>
Although it is not required, updating the <filename>configure</filename> and
other files with <literal>autoreconf -i -f</literal> may improve
the compatibility of the source.
<footnote><para>You can automate this by using 
<systemitem role="package">dh-autoreconf</systemitem> package.  
See <xref linkend="customrules"/>.</para></footnote>
</para>
<para>
<ulink url="&cmake;">CMake</ulink> is an alternative
build system.  You can recognize such sources by the
<filename>CMakeLists.txt</filename> file.
</para>
</section>
<section id="namever"><title>Package name and version</title>
<para>
You should start packaging with a completely clean (pristine) source directory,
or simply with freshly unpacked sources.
</para>
<para>
For the package to be built correctly, you must make the program's original
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>
</para>
<para>
Some programs won't be numbered at all, in which case you should contact the
upstream maintainer to see if they've got some other revision-tracking method.
</para>
</section>
<section id="dh-make"><title>Initial Debian package</title>
<para>
Set up the shell environment variables <literal>$DEBEMAIL</literal> and
<literal>$DEBFULLNAME</literal> so that various Debian maintenance
tools recognize your email address and name to use for packages.<footnote><para> The
following text assumes you are using Bash as your login shell.  If you use
some other login shell such as Z shell, use their corresponding
configuration files instead of <filename>~/.bashrc</filename>. </para> </footnote>.
</para>
<screen>
$ cat &gt;&gt;~/.bashrc &lt;&lt;EOF
DEBEMAIL=your.email.address@example.org
DEBFULLNAME=Firstname Lastname
export DEBEMAIL DEBFULLNAME
EOF
</screen>
<para>
You can create an initial Debian package by issuing the
<command>dh_make</command> command as follows.
</para>
<screen>
$ . ~/.bashrc
$ cd ~/gentoo/gentoo-0.9.12
$ dh_make -f ../gentoo-0.9.12.tar.gz
</screen>
<para>
Of course, replace the filename with the name of your original source archive.
<footnote><para> If the upstream source provides the
<filename>debian</filename> directory and its contents, run the
<command>dh_make</command> command with the extra option
<literal>--addmissing</literal>.  The new source <literal>3.0 (quilt)</literal> format is
robust enough not to break even for these packages.  You may need to update the contents
provided by the upstream for your Debian package.  </para> </footnote> See
<citerefentry> <refentrytitle>dh_make</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> for details.
</para>
<para>
You should see some output asking you what sort of package you want
to create.  Gentoo is a single binary package - it creates only one binary, and
thus one <filename>.deb</filename> file - so we will select the first option
(with the <literal>s</literal> key), check the information on the screen, and
confirm by pressing <literal><replaceable>ENTER</replaceable></literal>.
<footnote><para> There are several choices here: <literal>s</literal> for Single
binary, <literal>i</literal> for arch-Independent, <literal>m</literal> for
Multiple binary, <literal>l</literal> for Library, <literal>k</literal> for
Kernel module, <literal>n</literal> for kernel patch, and <literal>b</literal>
for <systemitem role="package">cdbs</systemitem>.  This document focuses on the
use of the <command>dh</command> command (from the package
<systemitem role="package">debhelper</systemitem>) to create a single-binary package,
but also touches on how to use it for arch-independent or
multiple-binary packages.  The package
<systemitem role="package">cdbs</systemitem> offers an alternative packaging script
infrastructure to the <command>dh</command> command and is outside the scope of
this document.  </para> </footnote>
</para>
<para>
This execution of <command>dh_make</command> creates a copy of the upstream
tarball as <filename>gentoo_0.9.12.orig.tar.gz</filename> in the
parent directory to accommodate the creation of the non-native Debian source
package with the name <filename>debian.tar.gz</filename> later.
</para>
<screen>
$ cd ~/gentoo ; ls -F
gentoo-0.9.12/
gentoo-0.9.12.tar.gz
gentoo_0.9.12.orig.tar.gz
</screen>
<para>
Please note two key features of this filename
<filename>gentoo_0.9.12.orig.tar.gz</filename>:
</para>
<itemizedlist>
<listitem>
<para>
Package name and version are separated by the character <literal>_</literal>
(underscore).
</para>
</listitem>
<listitem>
<para>
The string <filename>.orig</filename> is inserted before the
<filename>.tar.gz</filename>.
</para>
</listitem>
</itemizedlist>
<para>
You should also notice that many template files are created in the source under
the <filename>debian</filename> directory.  These will be explained in
<xref linkend="dreq"/> and <xref linkend="dother"/>.  You should also understand
that packaging cannot be a fully automated process.  You will need to modify the upstream
source for Debian (see <xref linkend="modify"/>).  After this, you need to
use the proper methods for building Debian packages (<xref linkend="build"/>),
testing them (<xref linkend="checkit"/>), and uploading them (<xref linkend="upload"/>).
All the steps will be explained.
</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>
If you accidentally erased some template files while working on them, you can
recover them by running <command>dh_make</command> with the
<literal>--addmissing</literal> option again in a Debian package source tree.
</para>
<para>
Updating an existing package may get complicated since it may be using older
techniques.  While learning the basics, please stick to creating a fresh
package; further explanations are given in <xref linkend="update"/>.
</para>
</section>
</chapter>
<chapter id="modify"><title>Modifying the source</title>
<para>
Please note that there isn't space here to go into <emphasis>all</emphasis> the
details of fixing upstream sources, but here are some basic steps and problems
people often run across.
</para>
<section id="quiltrc"><title>Set up <command>quilt</command></title>
<para>
The <command>quilt</command> program offers the basic method to record
modification to the source for the Debian packaging.  Since slightly different
default is desirable, let's create an alias <command>dquilt</command> for
Debian packaging by adding the following line to <filename>~/.bashrc</filename>.
</para>
<screen>
alias dquilt="quilt --quiltrc=~/.quiltrc-dpkg"
</screen>
<para>
Then let's create <filename>~/.quiltrc-dpkg</filename> as follows.
</para>
<screen>
d=. ; while [ ! -d $d/debian -a `readlink -e $d` != / ]; do d=$d/..; done
if [ -d $d/debian ] &amp;&amp; [ -z $QUILT_PATCHES ]; then
    # Debian packaging case and unset $QUILT_PATCHES
    QUILT_PATCHES="debian/patches"
    QUILT_PATCH_OPTS="--reject-format=unified"
    QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
    QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
    QUILT_COLORS="diff_hdr=1;32:diff_add=1;34:diff_rem=1;31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33"
    if ! [ -d $d/debian/patches ]; then mkdir $d/debian/patches; fi
fi
</screen>
<para>
See <citerefentry> <refentrytitle>quilt</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> and
<ulink url="&quilt-pdf;">quilt.pdf</ulink> for how to use
<command>quilt</command>.
</para>
</section>
<section id="fixupstream"><title>Fixing upstream bug</title>
<para>
Let's assume you find an error in the upstream <filename>Makefile</filename>
file as follows where <literal>install: gentoo</literal> should have been
<literal>install: gentoo-target</literal>.
</para>
<screen>
install: gentoo
        install ./gentoo $(BIN)
        install icons/* $(ICONS)
        install gentoorc-example $(HOME)/.gentoorc
</screen>
<para>
Let's fix this and record this with the <command>dquilt</command> command as
<filename>fix-gentoo-target.patch</filename>.  <footnote><para> The
<filename>debian/patches</filename> directory should exist now if you run
<command>dh_make</command> as described before.  This example operation creates
it just in case you are updating the existing package.  </para> </footnote>
</para>
<screen>
$ mkdir debian/patches
$ dquilt new fix-gentoo-target.patch
$ dquilt add Makefile
</screen>
<para>
You change the <filename>Makefile</filename> file as follows.
</para>
<screen>
install: gentoo-target
        install ./gentoo $(BIN)
        install icons/* $(ICONS)
        install gentoorc-example $(HOME)/.gentoorc
</screen>
<para>
Ask <command>dquilt</command> to refresh the patch to create
<filename>debian/patches/fix-gentoo-target.patch</filename> and add its
description following <ulink url="&dep3;">DEP-3: Patch Tagging Guidelines</ulink>.
</para>
<screen>
$ dquilt refresh
$ dquilt header -e
... describe patch
</screen>
</section>

<section id="destdir"><title>Installation of files to the destination</title>
<para>
Normally, programs install themselves in the <filename>/usr/local</filename>
subdirectory.  Since it is reserved for system administrator's (or user's)
private use, Debian packages must not use that directory but should use system
directories such as the <filename>/usr/bin</filename> subdirectory following
the <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink> (FHS).
</para>
<para>
Normally, <citerefentry> <refentrytitle>make</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> is used to automate building the
program and the execution of <literal>make install</literal> installs programs
directly to the desired destination by the <literal>install</literal> target of
the <filename>Makefile</filename> file.  In order for Debian to provide binary
packages, the build system installs programs to the file tree image created
under a temporary directory instead to the actual destination.
</para>
<para>
These 2 differences between (1) the normal program installation and (2) the
Debian packaging can be transparently addressed by the <systemitem role="package">debhelper</systemitem> package through the
<command>dh_auto_configure</command> and <command>dh_auto_install</command>
commands if the following conditions are met.
</para>
<itemizedlist>
<listitem>
<para>
The <filename>Makefile</filename> file follows the GNU conventions to support
<literal>$(DESTDIR)</literal> variable.
<footnote><para> See <ulink url="&gnu-destdir;">GNU Coding Standards: 7.2.4 DESTDIR: Support for Staged Installs</ulink>.</para></footnote>
</para>
</listitem>
<listitem>
<para>
The source follows the Filesystem Hierarchy Standard (FHS).
</para>
</listitem>
</itemizedlist>
<para>
Programs that use GNU <command>autoconf</command>
<emphasis>automatically</emphasis> follow the GNU conventions and their
packaging is almost <emphasis>automatic</emphasis>.  With this and other
heuristics, the <systemitem role="package">debhelper</systemitem> package
estimates that it works for about 90% of packages without making any intrusive
changes to their build system.  So the packaging is not as complicated as it
may seem.
</para>
<para>
If you need to make changes in the <filename>Makefile</filename> file, you
should make sure to support these <literal>$(DESTDIR)</literal> variable.  The
<literal>$(DESTDIR)</literal> variable is unset in it and is prepended to each
file path used for the program installation.  The packaging script will set
<literal>$(DESTDIR)</literal> to the temporary directory.
</para>
<para>
The temporary directory used by the <command>dh_auto_install</command> command
is chosen as <filename>debian/<replaceable>package</replaceable></filename> for
single binary packages.  <footnote><para> For multiple binary packages, the
<command>dh_auto_install</command> command uses <filename>debian/tmp</filename>
as the temporary directory while the <command>dh_install</command> command with
the help of
<filename>debian/<replaceable>package-1</replaceable>.install</filename> and
<filename>debian/<replaceable>package-2</replaceable>.install</filename> files
will split contents of <filename>debian/tmp</filename> into
<filename>debian/<replaceable>package-1</replaceable></filename> and
<filename>debian/<replaceable>package-2</replaceable></filename> temporary
directories to create multiple binary <filename>*.deb</filename> packages.
</para> </footnote> Everything that is contained in the temporary directory
will be installed on a user's system when they install your package, the only
difference is that <command>dpkg</command> will be installing the files in the
root directory.
</para>
<para>
Bear in mind that even though your program installs in
<filename>debian/<replaceable>package</replaceable></filename>, it still needs
to behave correctly when placed in the root directory, i.e.  when installed
from the <filename>.deb</filename> package.  So you must not allow the build
system to hardcode strings like
<literal>/home/me/deb/<replaceable>package</replaceable>-<replaceable>version</replaceable>/usr/share/<replaceable>package</replaceable></literal>
into the package file.
</para>
<para>
Here's the relevant part of <systemitem role="package">gentoo</systemitem>'s
<filename>Makefile</filename> file <footnote><para> This is just an example to
show how the <filename>Makefile</filename> file should look like.  If the
<filename>Makefile</filename> file is created by the
<command>./configure</command> command, the correct way to fix this kind of
<filename>Makefile</filename> is to executed the <command>./configure</command>
command from the <command>dh_auto_configure</command> command with default
options including <literal>--prefix=/usr</literal>.  </para> </footnote>:
</para>
<screen>
# Where to put binary on 'make install'?
BIN     = /usr/local/bin
# Where to put icons on 'make install'?
ICONS   = /usr/local/share/gentoo
</screen>
<para>
We see that the files are set to install under <filename>/usr/local</filename>.
Change those paths to:
</para>
<screen>
# Where to put binary on 'make install'?
BIN     = $(DESTDIR)/usr/bin
# Where to put icons on 'make install'?
ICONS   = $(DESTDIR)/usr/share/gentoo
</screen>
<para>
But why in that directory, and not some other?  Because Debian packages never
install files beneath <filename>/usr/local</filename> -- that tree is reserved
for the system administrator's use.  Such files on Debian systems go under
<filename>/usr</filename> instead.
</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.
</para>
<para>
So, we should install the binary in <filename>/usr/bin</filename> instead of
<filename>/usr/local/bin</filename>, the manual page in
<filename>/usr/share/man/man1</filename> instead of
<filename>/usr/local/man/man1</filename> etc.  Notice how there's no manual
page mentioned in <systemitem role="package">gentoo</systemitem>'s
<filename>Makefile</filename>, but since the Debian Policy requires that every
program has one, we'll make one later and install it in
<filename>/usr/share/man/man1</filename>.
</para>
<para>
Some programs don't use <filename>Makefile</filename> variables to define paths
such as these.  This means you might have to edit some real C sources in order
to fix them to use the right locations.  But where to search, and exactly what
for?  You can find this out by issuing:
</para>
<screen>
$ grep -nr -e 'usr/local/lib' --include='*.[c|h]' .
</screen>
<para>
<command>grep</command> will run recursively through the source tree and tell
you the filename and the line number for all matches.
</para>
<para>
Edit those files and in those lines replace <literal>usr/local/lib</literal>
with <literal>usr/lib</literal>.  This can be done automatically as follows:
</para>
<screen>
$ vim '+argdo %s/usr\/local\/lib/usr\/lib/gce|update' +q \
      $(find . -type f -name '*.[c|h]')
</screen>
<para>
Be careful that you don't mess up the rest of the code!  :-)
</para>
<para>
After that you should find the install target (search for line that starts with
<literal>install:</literal>, that will usually work) and rename all references
to directories other than ones defined at the top of the
<filename>Makefile</filename>.
</para>
<para>
Before your upstream bug fix, <systemitem role="package">gentoo</systemitem>'s
install target said:
</para>
<screen>
install: gentoo-target
        install ./gentoo $(BIN)
        install icons/* $(ICONS)
        install gentoorc-example $(HOME)/.gentoorc
</screen>
<para>
Let's fix this and record this with the <command>dquilt</command> command as
<filename>debian/patches/install.patch</filename>.
</para>
<screen>
$ dquilt new install.patch
$ dquilt add Makefile
</screen>
<para>
Let's change this for Debian package as following using the editor:
</para>
<screen>
install: gentoo-target
        install -d $(BIN) $(ICONS) $(DESTDIR)/etc
        install ./gentoo $(BIN)
        install -m644 icons/* $(ICONS)
        install -m644 gentoorc-example $(DESTDIR)/etc/gentoorc
</screen>
<para>
You've surely noticed that there's now a <literal>install -d</literal> command
before the other commands in the rule.  The original
<filename>Makefile</filename> didn't have it because usually the
<literal>/usr/local/bin</literal> and other directories already exist on the
system where one runs <literal>make install</literal>.  However, since we will
install into our own empty (or even nonexistent) directory, we will have to
create each and every one of those directories.
</para>
<para>
We can also add in other things at the end of the rule, like the installation
of additional documentation that the upstream authors sometimes omit:
</para>
<screen>
        install -d $(DESTDIR)/usr/share/doc/gentoo/html
        cp -a docs/* $(DESTDIR)/usr/share/doc/gentoo/html
</screen>
<para>
After careful check, if everything is fine, ask <command>dquilt</command> to
refresh the patch to create <filename>debian/patches/install.patch</filename>
and add its description.
</para>
<screen>
$ dquilt refresh
$ dquilt header -e
... describe patch
</screen>
<para>
Now you have a series of patches.
</para>
<orderedlist numeration="arabic">
<listitem>
<para>
Upstream bug fix: <filename>debian/patches/fix-gentoo-target.patch</filename>
</para>
</listitem>
<listitem>
<para>
Debian specific packaging modification:
<filename>debian/patches/install.patch</filename>
</para>
</listitem>
</orderedlist>
<para>
Whenever you make changes that are not specifically related to Debian package
such as <filename>debian/patches/fix-gentoo-target.patch</filename>, be sure to
send them to the upstream maintainer so they can be included in the next
program revision and be useful to everyone else.  Also remember to make your
fixes not specific to Debian or Linux (or even Unix!) prior to sending them --
make them portable.  This will make your fixes much easier to apply.
</para>
<para>
Note that you don't have to send the <filename>debian/*</filename> files
upstream.
</para>
</section>
<section id="difflibs"><title>Differing libraries</title>
<para>
There is one other common problem: libraries are often different from platform
to platform.  For example, a <filename>Makefile</filename> can contain a
reference to a library which doesn't exist on Debian systems.  In that case, we
need to change it to a library which does exist in Debian, and serves the same
purpose.
</para>
<para>
So, if there is a line in your program's <filename>Makefile</filename> (or
<filename>Makefile.in</filename>) that says something like this (and your
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>:
</para>
<screen>
LIBS = -lcurses -lsomething -lsomethingelse
</screen>
<para>
Let's fix this as <filename>debian/patches/ncurse.patch</filename> by changing
<literal>curses</literal> into <literal>ncurses</literal>.
</para>
<screen>
$ dquilt new ncurse.patch
$ dquilt add Makefile
$ sed -i -e s/-lcurses/-lncurses/g Makefile
$ dquilt refresh
$ dquilt header -e
... describe patch
</screen>
</section>
</chapter>
<chapter id="dreq"><title>Required files under the <filename>debian</filename> directory</title>
<para>
There is a new subdirectory under the program's source directory, it's called
<filename>debian</filename>.  There are a number of files in this directory
that we should edit in order to customize the behavior of the package.  The
most important of them are <filename>control</filename>,
<filename>changelog</filename>, <filename>copyright</filename> and
<filename>rules</filename>, which are required for all packages.
<footnote><para>
In this chapter, files in the <filename>debian</filename> directory are
referred without preceding <filename>debian/</filename> for simplicity whenever
they are obvious.
</para></footnote>
</para>
<section id="control"><title><filename>control</filename> file</title>
<para>
This file contains various values which <command>dpkg</command>,
<command>dselect</command>, <command>apt-get</command>,
<command>apt-cache</command>, <command>aptitude</command>, and other package
management tools will use to manage the package.  It is defined by the <ulink url="&policy-control;">Debian
Policy Manual, 5 'Control files and their fields'</ulink>.
</para>
<para>
Here is the <filename>control</filename> file <command>dh_make</command>
created for us:
</para>
<screen>
 1 Source: gentoo
 2 Section: unknown
 3 Priority: extra
 4 Maintainer: Josip Rodin &lt;joy-mg@debian.org&gt;
 5 Build-Depends: debhelper (&gt;= 7.0.50~)
 6 Standards-Version: 3.8.4
 7 Homepage: &lt;insert the upstream URL, if relevant&gt;
 8
 9 Package: gentoo
10 Architecture: any
11 Depends: ${shlibs:Depends}, ${misc:Depends}
12 Description: &lt;insert up to 60 chars description&gt;
13  &lt;insert long description, indented with spaces&gt;
</screen>
<para>
(I've added the line numbers.)
</para>
<para>
Lines 1-7 are the control information for the source package.
Lines 9-13 are the control information for the binary package.
</para>
<para>
Line 1 is the name of the source package.
</para>
<para>
Line 2 is the section of the distribution the source package goes into.
</para>
<para>
As you may have noticed, Debian archive is divided in sections:
<literal>main</literal> (the free software), <literal>non-free</literal> (the
not really free software) and <literal>contrib</literal> (free software that
depends on non-free software).  Under those, there are logical subsections that
describe in short what packages are in.  So we have <literal>admin</literal>
for administrator-only programs, <literal>base</literal> for the basic tools,
<literal>devel</literal> for programmer tools, <literal>doc</literal> for
documentation, <literal>libs</literal> for libraries, <literal>mail</literal>
for e-mail readers and daemons, <literal>net</literal> for network apps and
daemons, <literal>x11</literal> for X11 programs that don't fit anywhere else,
and many more.
<footnote> <para>See 
<ulink url="&policy-subsections;">Debian Policy Manual, 2.4 'Sections'</ulink> and 
<ulink url="&sections-unstable;">List of sections in <literal>sid</literal></ulink>.</para>
</footnote>
</para>
<para>
Let's change it then to x11.  (A <literal>main/</literal> prefix is implied so
we can omit it.)
</para>
<para>
Line 3 describes how important it is that the user installs this package.
<footnote> <para>See 
<ulink url="&policy-priorities;">Debian Policy Manual, 2.5 'Priorities'</ulink>.
</para>
</footnote>
</para>
<itemizedlist>
<listitem>
<para>
The <literal>optional</literal> priority will usually work for new packages
that do not conflict with others with <literal>required</literal>,
<literal>important</literal> or <literal>standard</literal> priorities.
</para>
</listitem>
<listitem>
<para>
The <literal>extra</literal> priority will usually work for new packages that
conflict with others with non-<literal>extra</literal> priorities.
</para>
</listitem>
</itemizedlist>
<para>
Section and priority are used by the frontends like <command>aptitude</command>
when they sort packages and select defaults.  Once you upload the package to
Debian, the value of these two fields can be overridden by the archive
maintainers, in which case you will be notified by email.
</para>
<para>
As this is a normal priority package and doesn't conflict with anything else,
we will change the priority to <literal>optional</literal>.
</para>
<para>
Line 4 is the name and email address of the maintainer.  Make sure that this
field includes a valid <literal>To</literal> header for an email, because after
you upload it, the bug tracking system will use it to deliver bug emails to
you.  Avoid using commas, ampersands and parenthesis.
</para>
<para>
The 5th line includes the list of packages required to build your package as
the <literal>Build-Depends</literal> field.  You can also have the
<literal>Build-Depends-Indep</literal> field as an additional line, here.
<footnote><para>See <ulink url="&policy-relationships;#s-sourcebinarydeps">Debian
Policy Manual, 7.7 'Relationships between source and binary packages -
Build-Depends, Build-Depends-Indep, Build-Conflicts,
Build-Conflicts-Indep'</ulink>.</para></footnote>  Some packages like 
<systemitem role="package">gcc</systemitem> and 
<systemitem role="package">make</systemitem> which are required by the 
<systemitem role="package">build-essential</systemitem> package are implied.  If you need
to have other tools to build your package, you should add them to these fields.
Multiple entries are separated with commas; read on for the explanation of
binary dependencies to find out more about the syntax of these lines.
</para>
<itemizedlist>
<listitem>
<para>
For all packages packaged with the <command>dh</command> command in the
<filename>debian/rules</filename> file, you must have <literal>debhelper
(&gt;=7.0.50~)</literal> in the <literal>Build-Depends</literal> field to
satisfy the Debian Policy requirement for the <literal>clean</literal> target.
</para>
</listitem>
<listitem>
<para>
For source packages which have some binary packages with <literal>Architecture:
any</literal>, they are rebuild by the autobuilder.  Since this autobuilder
procedure runs <literal>debian/rules build</literal> in it while installing
only packages listed in the <literal>Build-Depends</literal> field (see <xref linkend="autobuilder"/>), the <literal>Build-Depends</literal> field needs to
list practically all the required packages and the
<literal>Build-Depends-indep</literal> is rarely used.
</para>
</listitem>
<listitem>
<para>
For source packages which have binary packages only with <literal>Architecture:
all</literal>, the <literal>Build-Depends-Indep</literal> field may list all
the required packages unless they are already listed in the
<literal>Build-Depends</literal> field to satisfy the Debian Policy requirement
for the <literal>clean</literal> target.
</para>
</listitem>
</itemizedlist>
<para>
If you are not sure which one should be used, use the
<literal>Build-Depends</literal> field to be on the safe side.
<footnote><para> This somewhat strange situation is a feature well documented
in the <ulink url="&policy-build-depends-indep;">Debian Policy
Manual, Footnotes 48</ulink>.  This is not due to the use of the
<command>dh</command> command in the <filename>debian/rules</filename> file but
due to how the <command>dpkg-buildpackage</command> works.  The same situation
applies to the <ulink url="https://bugs.launchpad.net/launchpad-buildd/+bug/238141">auto build system
for Ubuntu</ulink>.  </para> </footnote>
</para>
<para>
To find out what packages your package needs to be built run the command:
</para>
<screen>
$ dpkg-depcheck -d ./configure
</screen>
<para>
To manually find exact build dependency for
<command><replaceable>/usr/bin/foo</replaceable></command>, you execute
</para>
<screen>
$ objdump -p <replaceable>/usr/bin/foo</replaceable> | grep NEEDED
</screen>
<para>
and for each library listed, e.g., <command>libfoo.so.6</command>, execute
</para>
<screen>
$ dpkg -S libfoo.so.6
</screen>
<para>
Then you just take <literal>-dev</literal> version of every package as
<literal>Build-Depends</literal> entry.  If you use <command>ldd</command> for
this purpose, it will report indirect lib dependencies as well, resulting in
the problem of excessive build dependencies.
</para>
<para>
<systemitem role="package">gentoo</systemitem> also happens to require
<systemitem role="package">xlibs-dev</systemitem>, <systemitem role="package">libgtk1.2-dev</systemitem> and <systemitem role="package">libglib1.2-dev</systemitem> to build, so we'll add them here
next to <systemitem role="package">debhelper</systemitem>.
</para>
<para>
Line 6 is the version of the <ulink url="&debian-policy;">Debian Policy
Manual</ulink> standards this package follows, the one you read while making
your package.
</para>
<para>
On line 7 you can put the URL of the homepage for the upstream program.
</para>
<para>
Line 9 is the name of the binary package.  This is usually the same as the name
of the source package, but it doesn't necessarily have to be that way.
</para>
<para>
Line 10 describes the CPU architecture the binary package can be compiled for.
We'll leave this as <literal>any</literal> because <citerefentry>
<refentrytitle>dpkg-gencontrol</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> will fill in the appropriate value for any machine this package
gets compiled on.
</para>
<para>
If your package is architecture independent (for example, a shell or Perl
script, or a document), change this to <literal>all</literal>, and read later
in <xref linkend="rules"/> about using the <literal>binary-indep</literal> rule
instead of <literal>binary-arch</literal> for building the package.
</para>
<para>
Line 11 shows one of the most powerful features of the Debian packaging system.
Packages can relate to each other in various ways.  Apart from
<literal>Depends</literal>, other relationship fields are
<literal>Recommends</literal>, <literal>Suggests</literal>,
<literal>Pre-Depends</literal>, <literal>Breaks</literal>,
<literal>Conflicts</literal>, <literal>Provides</literal>, and
<literal>Replaces</literal>.
</para>
<para>
The package management tools usually behave the same way when dealing with
these relations; if not, it will be explained.  (see <citerefentry>
<refentrytitle>dpkg</refentrytitle> <manvolnum>8</manvolnum> </citerefentry>,
<citerefentry> <refentrytitle>dselect</refentrytitle> <manvolnum>8</manvolnum>
</citerefentry>, <citerefentry> <refentrytitle>apt</refentrytitle>
<manvolnum>8</manvolnum> </citerefentry>, <citerefentry>
<refentrytitle>aptitude</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> etc.)
</para>
<para>
Here is a simplified description of package relationships.
<footnote><para>See 
<ulink url="&policy-relationships;">Debian Policy Manual, 7 'Declaring relationships between packages'</ulink>.
</para></footnote>
</para>
<itemizedlist>
<listitem>
<para>
<literal>Depends</literal>
</para>
<para>
The package will not be installed unless the packages it depends on are
installed.  Use this if your program absolutely will not run (or will cause
severe breakage) unless a particular package is present.
</para>
</listitem>
<listitem>
<para>
<literal>Recommends</literal>
</para>
<para>
Use this for packages that are not strictly necessary but are typically used
with your program.  When a user installs your program, all frontends will
likely prompt them to install the recommended packages.
<command>aptitude</command> and <command>apt-get</command> install recommended
packages along with your package (but the user can disable this default
behaviour).  <command>dpkg</command> will ignore this field.
</para>
</listitem>
<listitem>
<para>
<literal>Suggests</literal>
</para>
<para>
Use this for packages which will work nicely with your program but are not at
all necessary.  When a user installs your program, all frontends will likely
prompt them to install the suggested packages.  <command>aptitude</command> can
be configured to install suggested packages along with your package but this is
not its default.  <command>dpkg</command> and <command>apt-get</command> will
ignore this field.
</para>
</listitem>
<listitem>
<para>
<literal>Pre-Depends</literal>
</para>
<para>
This is stronger than <literal>Depends</literal>.  The package will not be
installed unless the packages it pre-depends on are installed and
<emphasis>correctly configured</emphasis>.  Use this <emphasis>very</emphasis>
sparingly and only after discussing it on the <ulink url="&debian-devel-ldo;">debian-devel@lists.debian.org</ulink>
mailing list.  Read: don't use it at all.  :-)
</para>
</listitem>
<listitem>
<para>
<literal>Conflicts</literal>
</para>
<para>
The package will not be installed until all the packages it conflicts with have
been removed.  Use this if your program absolutely will not run or will cause
severe problems if a particular package is present.
</para>
</listitem>
<listitem>
<para>
<literal>Breaks</literal>
</para>
<para>
The package will be installed while all the listed packages will be broken.
Normally a <literal>Breaks</literal> entry has an earlier than version clause.
The resolution is generally to upgrade the listed packages by the higher-level
package management tools.
</para>
</listitem>
<listitem>
<para>
<literal>Provides</literal>
</para>
<para>
For some types of packages where there are multiple alternatives virtual names
have been defined.  You can get the full list in the
<ulink url="&virtual-package;">virtual-package-names-list.txt.gz</ulink>
file.  Use this if your program provides a function of an existing virtual
package.
</para>
</listitem>
<listitem>
<para>
<literal>Replaces</literal>
</para>
<para>
Use this when your program replaces files from another package, or completely
replaces another package (used in conjunction with
<literal>Conflicts</literal>).  Files from the named packages will be
overwritten with the files from your package.
</para>
</listitem>
</itemizedlist>
<para>
All these fields have uniform syntax.  They are a list of package names
separated by commas.  These package names may also be lists of alternative
package names, separated by vertical bar symbols <literal>|</literal> (pipe
symbols).
</para>
<para>
The fields may restrict their applicability to particular versions of each
named package.  These versions are listed in parentheses after each individual
package name, and they should contain a relation from the list below followed
by the version number.  The relations allowed are: <literal>&lt;&lt;</literal>,
<literal>&lt;=</literal>, <literal>=</literal>, <literal>&gt;=</literal> and
<literal>&gt;&gt;</literal> for strictly lower, lower or equal, exactly equal,
greater or equal and strictly greater, respectively.  For example,
</para>
<screen>
Depends: foo (&gt;= 1.2), libbar1 (= 1.3.4)
Conflicts: baz
Recommends: libbaz4 (&gt;&gt; 4.0.7)
Suggests: quux
Replaces: quux (&lt;&lt; 5), quux-foo (&lt;= 7.6)
</screen>
<para>
The last feature you need to know about is
<literal>${shlibs:Depends}</literal>, <literal>${perl:Depends}</literal>,
<literal>${misc:Depends}</literal>, etc.
</para>
<para>
<citerefentry> <refentrytitle>dh_shlibdeps</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> calculates shared library dependencies
for binary packages.  It generates a list of ELF executables and shared
libraries it has found for each binary package.  Such list is used for
substituting <literal>${shlibs:Depends}</literal>.
</para>
<para>
<citerefentry> <refentrytitle>dh_perl</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> calculates Perl dependencies.  It generates a list of a
dependency on <literal>perl</literal> or <literal>perlapi</literal> for each binary package.  Such list is used for
substituting <literal>${perl:Depends}</literal>.
</para>
<para>
Some <systemitem role="package">debhelper</systemitem> commands may make the
generated package need to depend on some other packages.  All such commands
generate a list of required packages for each binary package.
Such list is used for substituting <literal>${misc:Depends}</literal>.
</para>
<para>
<citerefentry> <refentrytitle>dh_gencontrol</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> generates
<filename>DEBIAN/control</filename> for each binary package while
substituting <literal>${shlibs:Depends}</literal>,
<literal>${perl:Depends}</literal>, <literal>${misc:Depends}</literal>, etc.
</para>
<para>
Having said all that, we can leave the <literal>Depends</literal> field exactly
as it is now, and insert another line after it saying <literal>Suggests:
file</literal>, because <systemitem role="package">gentoo</systemitem> can use
some features provided by that <systemitem role="package">file</systemitem>
package.
</para>
<para> Line 9 is the Homepage URL.  Let's assume this to be at 
<ulink url="&gentoo;"/>.
</para>
<para>
Line 12 is the short description.  Most people screens are 80 columns wide so
this shouldn't be longer than about 60 characters.  I'll change it to
<literal>fully GUI-configurable, two-pane X file manager</literal>.
</para>
<para>
Line 13 is where the long description goes.  This should be a paragraph which
gives more details about the package.  Column 1 of each line should be empty.
There must be no blank lines, but you can put a single <literal>.</literal>
(dot) in a column to simulate that.  Also, there must be no more than one blank
line after the long description. <footnote><para>These descriptions are in
English.  Translations of these descriptions are provided by 
<ulink url="&ddtp;">The Debian Description Translation Project - DDTP</ulink>.</para></footnote>
</para>
<para>
Let's insert <literal>Vcs-*</literal> fields to document the Version Control
System (VCS) location between line 6 and 7.
<footnote><para>See 
<ulink url="&devref-bpp-vcs;">Developer's Reference, 6.2.5. 'Version Control System location'</ulink>.
</para></footnote>
Let's assume that the <systemitem role="package">gentoo</systemitem>
package has its VCS located in Debian Alioth Git Service at
<literal>git://git.debian.org/git/collab-maint/gentoo.git</literal>.
</para>
<para>
Finally, here is the updated <filename>control</filename> file:
</para>
<screen>
 1 Source: gentoo
 2 Section: x11
 3 Priority: optional
 4 Maintainer: Josip Rodin &lt;joy-mg@debian.org&gt;
 5 Build-Depends: debhelper (&gt;= 7.0.5), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
 6 Standards-Version: 3.8.4
 7 Vcs-Git: git://git.debian.org/git/collab-maint/gentoo.git
 8 Vcs-browser: http://git.debian.org/?p=collab-maint/gentoo.git
 9 Homepage: &gentoo;
10
11 Package: gentoo
12 Architecture: any
13 Depends: ${shlibs:Depends}, ${misc:Depends}
14 Suggests: file
15 Description: fully GUI-configurable, two-pane X file manager
16  gentoo is a two-pane file manager for the X Window System. gentoo lets the
17  user do (almost) all of the configuration and customizing from within the
18  program itself. If you still prefer to hand-edit configuration files,
19  they're fairly easy to work with since they are written in an XML format.
20  .
21  gentoo features a fairly complex and powerful file identification system,
22  coupled to a object-oriented style system, which together give you a lot
23  of control over how files of different types are displayed and acted upon.
24  Additionally, over a hundred pixmap images are available for use in file
25  type descriptions.
26  .
29  gentoo was written from scratch in ANSI C, and it utilises the GTK+ toolkit
30  for its interface.
</screen>
<para>
(I've added the line numbers.)
</para>
</section>
<section id="copyright"><title><filename>copyright</filename> file</title>
<para>
This file contains the information about package upstream resources, copyright
and license information.  
<ulink url="&policy-copyright;">Debian Policy Manual, 12.5 'Copyright information'</ulink> 
dictates its content and 
<ulink url="&dep5;">DEP-5: Machine-parseable <filename>debian/copyright</filename></ulink> 
provides guidelines for its format.
</para>
<para>
<command>dh_make</command> can give you a template
<filename>copyright</filename> file.  Let's use the <literal>--copyright
gpl2</literal> option here to get a template file for the <systemitem role="package">gentoo</systemitem> package released under GPL-2.
</para>
<para>
You must fill in missing information such as the place you got the package
from, the actual copyright notice and their license to complete this file.  For
the common free software licenses such as GNU GPL-1, GNU GPL-2, GNU GPL-3,
LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0 or the Artistic
license, you can just refer to the appropriate file in
<filename>/usr/share/common-licenses/</filename> directory that exists on every
Debian system.  Otherwise, you must include the complete license.
</para>
<para>
In short, here's how <systemitem role="package">gentoo</systemitem>'s
<filename>copyright</filename> file should look like:
</para>
<screen>
 1 Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&amp;rev=135
 2 Name: gentoo
 3 Maintainer: Josip Rodin &lt;joy-mg@debian.org&gt;
 4 Source: http://sourceforge.net/projects/gentoo/files/
 5
 6 Copyright: 1998-2010 Emil Brink &lt;emil@obsession.se&gt;
 7 License: GPL-2+
 8
 9 Files: icons/*
10 Copyright: 1998 Johan Hanson &lt;johan@tiq.com&gt;
11 License: GPL-2+
12
13 Files: debian/*
14 Copyright: 1998-2010 Josip Rodin &lt;joy-mg@debian.org&gt;
15 License: GPL-2+
16
17 License: GPL-2+
18  This program is free software; you can redistribute it and/or modify
19  it under the terms of the GNU General Public License as published by
20  the Free Software Foundation; either version 2 of the License, or
21  (at your option) any later version. 
22  .
23  This program is distributed in the hope that it will be useful,
24  but WITHOUT ANY WARRANTY; without even the implied warranty of
25  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
26  GNU General Public License for more details.
27 .
28  You should have received a copy of the GNU General Public License along
29  with this program; if not, write to the Free Software Foundation, Inc.,
30  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
31  .
32  On Debian systems, the full text of the GNU General Public
33  License version 2 can be found in the file
34  `/usr/share/common-licenses/GPL-2'.
</screen>
<para>
(I've added the line numbers.)
</para>
<para>
Please follow the HOWTO provided by ftpmasters and sent to
debian-devel-announce: <ulink url="&howto-copyright;"/>.
</para>
</section>
<section id="changelog"><title><filename>changelog</filename> file</title>
<para>
This is a required file, which has a special format described in the 
<ulink url="&policy-dpkgchangelog;">Debian Policy Manual, 4.4 'debian/changelog'</ulink>.
This format is used by <command>dpkg</command> and other programs to obtain the
version number, revision, distribution and urgency of your package.
</para>
<para>
For you, it is also important, since it is good to have documented all changes
you have done.  It will help people downloading your package to see whether
there are issues with the package that they should know about.  It will be
saved as <filename>/usr/share/doc/gentoo/changelog.Debian.gz</filename> in the
binary package.
</para>
<para>
<command>dh_make</command> created a default one, and this is how it looks
like:
</para>
<screen>
1  gentoo (0.9.12-1) unstable; urgency=low
2
3   * Initial release (Closes: #<replaceable>nnnn</replaceable>)  &lt;<replaceable>nnnn</replaceable> is the bug number of your ITP&gt;
4
5  -- Josip Rodin &lt;joy-mg@debian.org&gt;  Mon, 22 Mar 2010 00:37:31 +0100
6
</screen>
<para>
(I've added the line numbers.)
</para>
<para>
Line 1 is the package name, version, distribution, and urgency.  The name must
match the source package name, distribution should be either
<literal>unstable</literal> (or even <literal>experimental</literal>)
<footnote><para> Some people use invalid distribution values such as
<literal>UNRELEASED</literal> to prevent a package to be accidentally uploaded
when updating a package in a shared VCS.  </para> </footnote>, and urgency
shouldn't be changed to anything higher than <literal>low</literal>.  :-)
</para>
<para>
Lines 3-5 are a log entry, where you document changes made in this package
revision (not the upstream changes - there is special file for that purpose,
created by the upstream authors, which you will later install as
<filename>/usr/share/doc/gentoo/changelog.gz</filename>).  Let's assume your
ITP (Intent To Package) bug report number was <literal>12345</literal>.  New
lines must be inserted just before the uppermost line that begins with
<literal>*</literal> (asterisk).  You can do it with <citerefentry>
<refentrytitle>dch</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>, or
manually with a text editor.
</para>
<para>
You will end up with something like this:
</para>
<screen>
1  gentoo (0.9.12-1) unstable; urgency=low
2
3   * Initial Release. Closes: #12345
4   * This is my first Debian package.
5   * Adjusted the Makefile to fix $(DESTDIR) problems.
6
7  -- Josip Rodin &lt;joy-mg@debian.org&gt;  Mon, 22 Mar 2010 00:37:31 +0100
8
</screen>
<para>
(I've added the line numbers.)
</para>
<para>
You can read more about updating the <filename>changelog</filename> file later
in <xref linkend="update"/>.
</para>
</section>
<section id="rules"><title><filename>rules</filename> file</title>
<para>
Now we need to take a look at the exact rules which <citerefentry>
<refentrytitle>dpkg-buildpackage</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> will use to actually create the package.  This file is actually
another <filename>Makefile</filename>, but different from the one(s) in the
upstream source.  Unlike other files in <filename>debian</filename>, this one
is marked as executable.
</para>
<section id="targets"><title>Targets of <filename>rules</filename> file</title>
<para>
Every <filename>rules</filename> file, as any other
<filename>Makefile</filename>, consists of several targets and their rules
specifying how to handle the source.  <ulink url="&policy-debianrules;">Debian
Policy Manual, 4.9 'Main building script: debian/rules'</ulink> explains its
details.
</para>
<para>
The simplified explanation of targets are the following.
</para>
<itemizedlist>
<listitem>
<para>
<literal>clean</literal> target: to clean all compiled, generated, and useless
files in the build-tree.  (required)
</para>
</listitem>
<listitem>
<para>
<literal>build</literal> target: to build the source into compiled programs and
formatted documents in the build-tree.  (required)
</para>
</listitem>
<listitem>
<para>
<literal>install</literal> target: to install files into a file tree for each
binary package under the <filename>debian</filename> directory.  If defined,
<literal>binary*</literal> targets effectively depend on this target.
(optional)
</para>
</listitem>
<listitem>
<para>
<literal>binary</literal> target: to create all binary packages (effectively
combination of <literal>binary-arch</literal> and
<literal>binary-indep</literal> targets).  (required)<footnote><para> This
target is used by <literal>dpkg-buildpackage</literal> as in <xref linkend="completebuild"/>.  </para> </footnote>
</para>
</listitem>
<listitem>
<para>
<literal>binary-arch</literal> target: to create arch-dependent
(<literal>Architecture: any</literal>) binary packages in the parent directory.
(required)<footnote><para> This target is used by <literal>dpkg-buildpackage
-B</literal> as in <xref linkend="autobuilder"/>.  </para> </footnote>
</para>
</listitem>
<listitem>
<para>
<literal>binary-indep</literal> target: to create arch-independent
(<literal>Architecture: all</literal>) binary packages in the parent directory.
(required)<footnote><para> This target is used by <literal>dpkg-buildpackage
-A</literal>.  </para> </footnote>
</para>
</listitem>
<listitem>
<para>
<literal>get-orig-source</literal> target: to obtain the most recent version of
the original source package from upstream archive site.  (optional)
</para>
</listitem>
</itemizedlist>
<para>
Rules that you want to execute are invoked as command line arguments (for
example, <literal>./debian/rules build</literal> or <literal>fakeroot make -f
debian/rules binary</literal>).  After the target name, you can name the
dependency, program or file that the rule depends on.  After that, there can be
any number of commands, indented with
<literal><replaceable>TAB</replaceable></literal>.  A new rule begins with the
target declaration in the first column.  Empty lines and lines beginning with
<literal>#</literal> (hash) are treated as comments and ignored.
</para>
<para>
You are probably confused now, but it will all be clear upon examination of the
<filename>rules</filename> file that <command>dh_make</command> gives us as a
default.  You should also read <literal>info make</literal> for more
information.
</para>
</section>
<section id="defaultrules"><title>Default <filename>rules</filename> file</title>
<para>
Newer <command>dh_make</command> generates a very simple but powerful default
<filename>rules</filename> file using the <command>dh</command> command:
</para>
<screen>
 1 #!/usr/bin/make -f
 2 # -*- makefile -*-
 3 # Sample debian/rules that uses debhelper.
 4 # This file was originally written by Joey Hess and Craig Small.
 5 # As a special exception, when this file is copied by dh-make into a
 6 # dh-make output file, you may use that output file without restriction.
 7 # This special exception was added by Craig Small in version 0.37 of dh-make.
 8
 9 # Uncomment this to turn on verbose mode.
10 #export DH_VERBOSE=1
11
12 %:
13        dh $@
</screen>
<para>
(I've added the line numbers.  In the actual <filename>rules</filename> file,
the leading white spaces are TAB codes.)
</para>
<para>
You are probably familiar with lines like line 1 from shell and Perl scripts.
It tells the operating system that this file is to be processed with
<filename>/usr/bin/make</filename>.
</para>
<para>
Line 11 can be uncommented to set <literal>DH_VERBOSE</literal> variable to 1.
Then, the <command>dh</command> command will output which
<command>dh_*</command> commands are executed by the <command>dh</command>
command.  You can also add <literal>export DH_OPTIONS=-v</literal> line here.
Then each <command>dh_*</command> command will output which commands are
executed by each <command>dh_*</command> command.  This helps you to understand
what exactly is going on behind this simple <filename>rules</filename> file and
to debug its problems.  This new <command>dh</command> is a core part of the
<systemitem role="package">debhelper</systemitem> tools and does not hide
anything from you.
</para>
<para>
Lines 12 and 13 are where all the work is done.  The percent sign means any
targets which then call a single program, <command>dh</command> with the target
name.  <footnote><para> This uses the new <systemitem role="package">debhelper</systemitem> V7 features.  Its design concepts are
explained in <ulink url="&debhelper-slides;">Not Your
Grandpa's Debhelper</ulink> presented at Debconf9 by the <systemitem role="package">debhelper</systemitem> upstream.  Under
<literal>lenny</literal>, <command>dh_make</command> created a much more
complicated <filename>rules</filename> file with many <command>dh_*</command>
scripts listed for each required explicit targets and frozen them to the state
when it was initially packaged.  This new <command>dh</command> command is
simpler and frees us from this constrain.  You still have full power to
customize this with <literal>override_dh_*</literal> targets.  See <xref linkend="customrules"/>.  It is based only on the <systemitem role="package">debhelper</systemitem> package and does not obfuscate the
package building process like the <systemitem role="package">cdbs</systemitem>
package.  </para> </footnote> The <command>dh</command> command is a wrapper
script which runs appropriate sequences of <command>dh_*</command> programs
depending on its argument.  <footnote><para> You can verify actual sequences of
<command>dh_*</command> programs invoked for a given
<literal><replaceable>target</replaceable></literal> as <literal>dh --no-act
<replaceable>target</replaceable></literal> or <literal>debian/rules --
'--no-act <replaceable>target</replaceable>'</literal> without really running
them.  </para> </footnote>
</para>
<itemizedlist>
<listitem>
<para>
<literal>debian/rules clean</literal> runs <literal>dh clean</literal>; which
in turn runs the following:
</para>
<screen>
dh_testdir
dh_auto_clean
dh_clean
</screen>
</listitem>
<listitem>
<para>
<literal>debian/rules build</literal> runs <literal>dh build</literal>; which
in turn runs the following:
</para>
<screen>
dh_testdir
dh_auto_configure
dh_auto_build
dh_auto_test
</screen>
</listitem>
<listitem>
<para>
<literal>fakeroot debian/rules binary</literal> runs <literal>fakeroot dh
binary</literal>; which in turn runs the following<footnote><para> This assumes
that the <systemitem role="package">python-support</systemitem> package is
installed on the system.  </para> </footnote>:
</para>
<screen>
dh_testroot
dh_prep
dh_installdirs
dh_auto_install
dh_install
dh_installdocs
dh_installchangelogs
dh_installexamples
dh_installman
dh_installcatalogs
dh_installcron
dh_installdebconf
dh_installemacsen
dh_installifupdown
dh_installinfo
dh_pysupport
dh_installinit
dh_installmenu
dh_installmime
dh_installmodules
dh_installlogcheck
dh_installlogrotate
dh_installpam
dh_installppp
dh_installudev
dh_installwm
dh_installxfonts
dh_bugfiles
dh_lintian
dh_gconf
dh_icons
dh_perl
dh_usrlocal
dh_link
dh_compress
dh_fixperms
dh_strip
dh_makeshlibs
dh_shlibdeps
dh_installdeb
dh_gencontrol
dh_md5sums
dh_builddeb
</screen>
</listitem>
<listitem>
<para>
<literal>fakeroot debian/rules binary-arch</literal> runs <literal>fakeroot dh
binary-arch</literal>; which in turn runs the same sequence as
<literal>fakeroot dh binary</literal> but with the <literal>-a</literal> option
appended for each command.
</para>
</listitem>
<listitem>
<para>
<literal>fakeroot debian/rules binary-indep</literal> runs <literal>fakeroot dh
binary-indep</literal>; which in turn runs almost the same sequence as
<literal>fakeroot dh binary</literal> but excluding
<command>dh_strip</command>, <command>dh_makeshlibs</command>, and
<command>dh_shlibdeps</command> with the <literal>-i</literal> option appended
for each remaining command.
</para>
</listitem>
</itemizedlist>
<para>
The function of <command>dh_*</command> commands are almost self-evident from
their names.  <footnote><para> For complete information on what do all these
<command>dh_*</command> scripts exactly do, and what their other options are,
please read their respective manual pages and the <systemitem role="package">debhelper</systemitem> documentation.  </para> </footnote> There
are few notable ones worth making (over)simplified explanation here assuming
typical build environment based on <filename>Makefile</filename>.
<footnote><para> These commands support other build environments such as
<filename>setup.py</filename> which can be listed by executing
<literal>dh_auto_build --list</literal> in a package source directory.  </para>
</footnote>
</para>
<itemizedlist>
<listitem>
<para>
<command>dh_auto_clean</command> usually executes the following if
<filename>Makefile</filename> exists with the <literal>distclean</literal>
target.  <footnote><para> It actually looks for the first available target of
<literal>distclean</literal>, <literal>realclean</literal> or
<literal>clean</literal> in <filename>Makefile</filename> and execute it.
</para> </footnote>
</para>
<screen>
make distclean
</screen>
</listitem>
<listitem>
<para>
<command>dh_auto_configure</command> usually executes the following if
<filename>./configure</filename> exists (arguments abbreviated for
readability).
</para>
<screen>
./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var ...
</screen>
</listitem>
<listitem>
<para>
<command>dh_auto_build</command> usually executes the following to execute the
first target of <filename>Makefile</filename> if it exists.
</para>
<screen>
make
</screen>
</listitem>
<listitem>
<para>
<command>dh_auto_test</command> usually executes the following if
<filename>Makefile</filename> exists with the <literal>test</literal> target.
<footnote><para> It actually looks for the first available target of
<literal>test</literal> or <literal>check</literal> in
<filename>Makefile</filename> and execute it.  </para> </footnote>
</para>
<screen>
make test
</screen>
</listitem>
<listitem>
<para>
<command>dh_auto_install</command> usually executes the following if
<filename>Makefile</filename> exists with the <literal>install</literal> target
(line folded for readability).
</para>
<screen>
make install \
  DESTDIR=<replaceable>/path/to</replaceable>/<replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>/debian/<replaceable>package</replaceable>
</screen>
</listitem>
</itemizedlist>
<para>
Targets which require the <command>fakeroot</command> command contain
<command>dh_testroot</command>.  If you are not pretending to be root using
this command, it exits with an error.
</para>
<para>
The important part to know about the <filename>rules</filename> file created by
<command>dh_make</command>, is that it is just a suggestion.  It will work for
most packages but for more complicated ones, don't be afraid to customize it to
fit your needs.  Only things that you must not change are the names of the
rules, because all the tools use these names, as mandated by the Debian Policy.
</para>
<para>
Although <literal>install</literal> is not required target, it is supported.
<literal>fakeroot dh install</literal> behaves like <literal>fakeroot dh
binary</literal> but stops after <command>dh_fixperms</command>.
</para>
</section>
<section id="customrules"><title>Customization of <filename>rules</filename> file</title>
<para>
There are many ways to customize the <filename>rules</filename> file created
with the new <command>dh</command> command.
</para>
<para>
The <literal>dh $@</literal> command can be customized as follows.
<footnote><para> If a package installs the
<filename>/usr/share/perl5/Debian/Debhelper/Sequence/<replaceable>custom_name</replaceable>.pm</filename>
file, you should activate its customization function by <literal>dh --with
<replaceable>custom-name</replaceable> $@</literal>.  </para> </footnote>
</para>
<itemizedlist>
<listitem>
<para>
Add support of the <command>dh_pysupport</command> command.  (The best choice
for Python.) <footnote><para> Use of the <command>dh_pysupport</command>
command is preferred over use of the <command>dh_pycentral</command> command.
Do not use the <command>dh_python</command> command.  </para> </footnote>
</para>
<itemizedlist>
<listitem>
<para>
Install the <systemitem role="package">python-support</systemitem> package in
<literal>Build-Depends</literal>.
</para>
</listitem>
<listitem>
<para>
Use <literal>dh $@</literal> as usual.  (This is enabled by default)
</para>
</listitem>
<listitem>
<para>
This handles Python modules using the <systemitem role="package">python-support</systemitem> framework.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Add support of the <command>dh_pycentral</command> command.
</para>
<itemizedlist>
<listitem>
<para>
Install the <systemitem role="package">python-central</systemitem> package in
<literal>Build-Depends</literal>.
</para>
</listitem>
<listitem>
<para>
Use <literal>dh --with python-central $@</literal> instead.
</para>
</listitem>
<listitem>
<para>
This also deactivates the <command>dh_pysupport</command> command.
</para>
</listitem>
<listitem>
<para>
This handles Python modules using the <systemitem role="package">python-central</systemitem> framework.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Add support of the <command>dh_installtex</command> command.
</para>
<itemizedlist>
<listitem>
<para>
Install the <systemitem role="package">tex-common</systemitem> package in
<literal>Build-Depends</literal>.
</para>
</listitem>
<listitem>
<para>
Use <literal>dh --with tex $@</literal> instead.
</para>
</listitem>
<listitem>
<para>
This registers Type 1 fonts, hyphenation patterns, or formats with TeX.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Add support of the <command>dh_quilt_patch</command> and
<command>dh_quilt_unpatch</command> commands.
</para>
<itemizedlist>
<listitem>
<para>
Install the <systemitem role="package">quilt</systemitem> package in
<literal>Build-Depends</literal>.
</para>
</listitem>
<listitem>
<para>
Use <literal>dh --with quilt $@</literal> instead.
</para>
</listitem>
<listitem>
<para>
This applies and un-applies patches to the upstream source from files in the
<filename>debian/patches</filename> directory for the <literal>1.0</literal>
source package.
</para>
</listitem>
<listitem>
<para>
This is not needed if you use the new <literal>3.0 (quilt)</literal> source
package.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Add support of the <command>dh_dkms</command> command.
</para>
<itemizedlist>
<listitem>
<para>
Install the <systemitem role="package">dkms</systemitem> package in
<literal>Build-Depends</literal>.
</para>
</listitem>
<listitem>
<para>
Use <literal>dh --with dkms $@</literal> instead.
</para>
</listitem>
<listitem>
<para>
This correctly handles DKMS usage by the kernel module package.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Add support of the <command>dh_autotools-dev_updateconfig</command> and
<command>dh_autotools-dev_restoreconfig</command> commands.
</para>
<itemizedlist>
<listitem>
<para>
Install the <systemitem role="package">autotools-dev</systemitem> package in
<literal>Build-Depends</literal>.
</para>
</listitem>
<listitem>
<para>
Use <literal>dh --with autotools-dev $@</literal> instead.
</para>
</listitem>
<listitem>
<para>
This updates and restores <filename>config.sub</filename> and
<filename>config.guess</filename>.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Add support of the <command>dh_autoreconf</command> and
<command>dh_autoreconf_clean</command> commands.
</para>
<itemizedlist>
<listitem>
<para>
Install the <systemitem role="package">dh-autoreconf</systemitem> package in
<literal>Build-Depends</literal>.
</para>
</listitem>
<listitem>
<para>
Use <literal>dh --with autoreconf $@</literal> instead.
</para>
</listitem>
<listitem>
<para>
This updates the GNU Build System files and restores them after the build.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Add support to the <command>bash</command> completion feature.
</para>
<itemizedlist>
<listitem>
<para>
Install the <systemitem role="package">bash-completion</systemitem> package in
<literal>Build-Depends</literal>.
</para>
</listitem>
<listitem>
<para>
Use <literal>dh --with bash-completion $@</literal> instead.
</para>
</listitem>
<listitem>
<para>
This installs <command>bash</command> completions using configuration file at
<filename>debian/<replaceable>package</replaceable>.bash-completion</filename>.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
Many <command>dh_*</command> commands invoked by the new <command>dh</command>
command can be customized by the corresponding configuration files in the
<filename>debian</filename> directory.  See <xref linkend="dother"/> and the
manpage of each command for the customization of such features.
</para>
<para>
Some <command>dh_*</command> commands invoked by the new <command>dh</command>
command may require you to run it with some arguments or to run additional
commands with them or to skip them.  For such cases, you create an
<literal>override_dh_<replaceable>foo</replaceable></literal> target with its
rule in the <filename>rules</filename> file only for the
<command>dh_<replaceable>foo</replaceable></command> command you want to
change.  It basically say <emphasis>run me instead</emphasis>.
<footnote><para> Under <literal>lenny</literal>, if you wanted to change the
behavior of a <command>dh_*</command> script you found the relevant line in the
<filename>rules</filename> file and adjusted it.  </para> </footnote>
</para>
<para>
Please note that the <command>dh_auto_*</command> commands tend to do more than
what has been discussed as (over)simplified explanation to take care all the
corner cases.  Use of simplified equivalent command instead of these in
<literal>override_dh_*</literal> targets except the
<literal>override_dh_auto_clean</literal> target is a bad idea since it may
kill such <systemitem role="package">debhelper</systemitem>'s smart features.
</para>
<para>
If you want to store the system configuration data in the
<filename>/etc/gentoo</filename> directory instead of the usual
<filename>/etc</filename> directory for the recent 
<systemitem role="package">gentoo</systemitem> package using Autotools, you can override the default
<literal>--sysconfig=/etc</literal> argument given by the
<command>dh_auto_configure</command> command to the
<command>./configure</command> command by the following.
</para>
<screen>
override_dh_auto_configure:
        dh_auto_configure -- --sysconfig=/etc/gentoo
</screen>
<para>
The arguments given after <literal>--</literal> are appended to the default
arguments of the auto-executed program to override them.  Using the
<command>dh_auto_configure</command> command is better than the
<command>./configure</command> command here since it will only override the
<literal>--sysconfig</literal> argument and keeps well intended other arguments
to the <command>./configure</command> command.
</para>
<para>
If <filename>Makefile</filename> of a source for <systemitem role="package">gentoo</systemitem> requires you to specify
<literal>build</literal> as its target to build it <footnote><para>
<command>dh_auto_build</command> without any arguments will execute the first
target in the <filename>Makefile</filename> file.  </para> </footnote>, you
create an <literal>override_dh_auto_build</literal> target to enable it.
</para>
<screen>
override_dh_auto_build:
        dh_auto_build -- build
</screen>
<para>
This ensures to run $(MAKE) with all the default arguments given by the
<command>dh_auto_build</command> command and <literal>build</literal> argument.
</para>
<para>
If <filename>Makefile</filename> of a source for <systemitem role="package">gentoo</systemitem> requires you to specify the
<literal>packageclean</literal> target to clean it for Debian package instead
of the <literal>distclean</literal> or <literal>clean</literal> targets in the
<filename>Makefile</filename> file, you create an
<literal>override_dh_auto_clean</literal> target to enable it.
</para>
<screen>
override_dh_auto_clean:
        $(MAKE) packageclean
</screen>
<para>
If <filename>Makefile</filename> of a source for <systemitem role="package">gentoo</systemitem> contains <literal>test</literal> target
which you do not want to run for the Debian package building process, you can
use empty <literal>override_dh_auto_test</literal> target to skip it.
</para>
<screen>
override_dh_auto_test:
</screen>
<para>
If <systemitem role="package">gentoo</systemitem> has an unusual upstream
changelog file called <filename>FIXES</filename>,
<command>dh_installchangelogs</command> will not install that file by default.
The <command>dh_installchangelogs</command> command requires
<filename>FIXES</filename> as its argument to install it.  <footnote><para> The
<filename>debian/changelog</filename> and <filename>debian/NEWS</filename>
files are always automatically installed.  The upstream changelog is searched
by converting filenames to the lower case and matching them with the
<filename>changelog</filename>, <filename>changes</filename>,
<filename>changelog.txt</filename>, and <filename>changes.txt</filename>.
</para> </footnote>
</para>
<screen>
override_dh_installchangelogs:
        dh_installchangelogs FIXES
</screen>
<para>
When you use the new <command>dh</command> command, use of explicit targets
such as the ones listed in <xref linkend="targets"/> except
<literal>get-orig-source</literal> target may make it difficult to understand
their exact effects.  Please limit explicit targets to
<literal>override_dh_*</literal> targets and completely independent ones, if
possible.
</para>
</section>
</section>
</chapter>
<chapter id="dother"><title>Other files under the <filename>debian</filename> directory</title>
<para>
To control most of what <systemitem role="package">debhelper</systemitem> does
while building the package, you put optional configuration files under the
<filename>debian</filename> directory.  This chapter will make an overview of
what each of these does and its format.  Please read <ulink url="&debian-policy;">Debian Policy
Manual</ulink> and <ulink url="&developers-reference;">Debian Developer's
Reference</ulink> for guidelines for the packaging.
</para>
<para>
The <command>dh_make</command> command will create some template configuration
files under the <filename>debian</filename> directory.  Most of them come with
filenames suffixed by <literal>.ex</literal>.  Some of them come with filenames
prefixed by the binary package name such as
<literal><replaceable>package</replaceable></literal>.  Take a look at all of
them.
<footnote><para>
In this chapter, files in the <filename>debian</filename> directory are
referred without preceding <filename>debian/</filename> for simplicity whenever
they are obvious.
</para></footnote>
</para>
<para>
The <command>dh_make</command> command may not create some template
configuration files for <systemitem role="package">debhelper</systemitem>.  In
such cases, you need to create them with the editor.
</para>
<para>
If you wish or need to activate any of those, please do the following.
</para>
<itemizedlist>
<listitem>
<para>
rename template files by removing the <literal>.ex</literal> or
<literal>.EX</literal> suffix if the template files have one.
</para>
</listitem>
<listitem>
<para>
rename the name of these configuration files using the actual binary package
name in place of <literal><replaceable>package</replaceable></literal>.
</para>
</listitem>
<listitem>
<para>
modify template file contents to suit your needs.
</para>
</listitem>
<listitem>
<para>
remove template files which you do not need.
</para>
</listitem>
<listitem>
<para>
modify the <filename>control</filename> file (see <xref linkend="control"/>),
if necessary.
</para>
</listitem>
<listitem>
<para>
modify the <filename>rules</filename> file (see <xref linkend="rules"/>), if
necessary.
</para>
</listitem>
</itemizedlist>
<para>
Those <systemitem role="package">debhelper</systemitem> configuration files
without <filename><replaceable>package</replaceable></filename> prefix such as
<filename>install</filename> apply to the first binary package.  When there are
many binary packages, their configurations can be specified by prefixing their
name to their configuration filenames such as
<filename><replaceable>package-1</replaceable>.install</filename>,
<filename><replaceable>package-2</replaceable>.install</filename>, etc.
</para>
<section id="readme"><title><filename>README.Debian</filename> file</title>
<para>
Any extra details or discrepancies between the original package and your Debian
version should be documented here.
</para>
<para>
<command>dh_make</command> created a default one, this is what it looks like:
</para>
<screen>
gentoo for Debian
-----------------
&lt;possible notes regarding this package - if none, delete this file&gt;
 -- Josip Rodin &lt;joy-mg@debian.org&gt;, Wed, 11 Nov 1998 21:02:14 +0100
</screen>
<para>
If you have nothing to be documented, remove this file.  See <citerefentry>
<refentrytitle>dh_installdocs</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>.
</para>
</section>
<section id="compat"><title><filename>compat</filename> file</title>
<para>
The <filename>compat</filename> file defines the <systemitem role="package">debhelper</systemitem> compatibility level.  Currently, you
should set it to the <systemitem role="package">debhelper</systemitem> V7 by
the following.
</para>
<screen>
$ echo 7 &gt; debian/compat
</screen>
</section>
<section id="conffiles"><title><filename>conffiles</filename> file</title>
<para>
One of the most annoying things about software is when you spend a great deal
of time and effort customizing a program, only to have an upgrade stomp all
over your changes.  Debian solves this problem by marking such configuration files as conffiles.
<footnote><para>See <citerefentry> <refentrytitle>dpkg</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> and
<ulink url="&policy-conffiles;">Debian Policy Manual 'D.2.5 Conffiles'</ulink>.
</para></footnote>
When you upgrade a package, you'll be prompted whether you want to keep
your old configuration files or not.
</para>
<para>
Since <systemitem role="package">debhelper</systemitem> V3, <citerefentry>
<refentrytitle>dh_installdeb</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> will <emphasis>automatically</emphasis> flag any files under
the <filename>/etc</filename> directory as conffiles, so if your program only
has conffiles there you do not need to specify them in this file.  For most
package types, the only place there is (and should be conffiles) is under
<filename>/etc</filename> and so this file doesn't need to exist.
</para>
<para>
If your program uses configuration files but also rewrites them on its own,
it's best not to make them as conffiles because <command>dpkg</command> will
then prompt users to verify the changes all the time.
</para>
<para>
If the program you're packaging requires every user to modify the configuration
files in the <filename>/etc</filename> directory, there are 2 popular ways to
make them not as conffiles to keep <command>dpkg</command> quiet.
</para>
<itemizedlist>
<listitem>
<para>
You make a symlink under the <filename>/etc</filename> directory pointing to a
file under the <filename>/var</filename> directory generated by the
<emphasis>maintainer scripts</emphasis>.
</para>
</listitem>
<listitem>
<para>
You make a file generated by the <emphasis>maintainer scripts</emphasis> under
the <filename>/etc</filename> directory.
</para>
</listitem>
</itemizedlist>
<para>
For more information on the <emphasis>maintainer scripts</emphasis>, see <xref linkend="maintscripts"/>.
</para>
</section>
<section id="crond"><title><filename><replaceable>package</replaceable>.cron.*</filename> files</title>
<para>
If your package requires regularly scheduled tasks to operate properly, you can
use this file to set it up.  You can either setup regular tasks that happen
hourly, daily, weekly or monthly or alternatively happen any other time that
you wish.  The filenames are:
</para>
<itemizedlist>
<listitem>
<para>
<filename>cron.hourly</filename> - Installed as
<filename>/etc/cron.hourly/<replaceable>package</replaceable></filename>: run
once an hour every hour.
</para>
</listitem>
<listitem>
<para>
<filename>cron.daily</filename> - Installed as
<filename>/etc/cron.daily/<replaceable>package</replaceable></filename>: run
once a day, usually early morning.
</para>
</listitem>
<listitem>
<para>
<filename>cron.weekly</filename> - Installed as
<filename>/etc/cron.weekly/<replaceable>package</replaceable></filename>: run
once a week, usually early Sunday morning.
</para>
</listitem>
<listitem>
<para>
<filename>cron.monthly</filename> - Installed as
<filename>/etc/cron.monthly/<replaceable>package</replaceable></filename>: run
once a month, usually early morning on the first of the month.
</para>
</listitem>
<listitem>
<para>
<filename>cron.d</filename> - Installed as
<filename>/etc/cron.d/<replaceable>package</replaceable></filename>: for any
other time
</para>
</listitem>
</itemizedlist>
<para>
For the named files, the format of them is the shell script.  The different one
is <filename><replaceable>package</replaceable>.cron.d</filename> which follows
the format of <citerefentry> <refentrytitle>crontab</refentrytitle>
<manvolnum>5</manvolnum> </citerefentry>.
</para>
<para>
Note that this doesn't include log rotation; for that, see <citerefentry>
<refentrytitle>dh_installlogrotate</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> and <citerefentry> <refentrytitle>logrotate</refentrytitle>
<manvolnum>8</manvolnum> </citerefentry>.
</para>
</section>
<section id="dirs"><title><filename>dirs</filename> file</title>
<para>
This file specifies the directories which we need but the normal installation
procedure (<literal>make install DESTDIR=...</literal> invoked by
<literal>dh_auto_install</literal>) somehow doesn't create.  This generally
means there is a problem with the <filename>Makefile</filename>.
</para>
<para>
Files listed in the <filename>install</filename> file doesn't need the
directories created first.  See <xref linkend="install"/>.
</para>
<para>
It is best to try to run the installation first and only use this if you
run into trouble.  There is no preceding slash on the directory names listed in 
the <filename>dirs</filename> file.
</para>
</section>
<section id="doc-base"><title><filename><replaceable>package</replaceable>.doc-base</filename> file</title>
<para>
If your package has documentation other than manual pages and info docs, you
should use the <systemitem role="package">doc-base</systemitem> file to
register it, so the user can find it with e.g.  <citerefentry>
<refentrytitle>dhelp</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,
<citerefentry> <refentrytitle>dwww</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> or <citerefentry> <refentrytitle>doccentral</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.
</para>
<para>
This usually includes HTML, PS and PDF files, shipped in
<filename>/usr/share/doc/<replaceable>packagename</replaceable>/</filename>.
</para>
<para>
This is how <systemitem role="package">gentoo</systemitem>'s doc-base file
<filename>gentoo.doc-base</filename> looks like:
</para>
<screen>
Document: gentoo
Title: Gentoo Manual
Author: Emil Brink
Abstract: This manual describes what Gentoo is, and how it can be used.
Section: File Management
Format: HTML
Index: /usr/share/doc/gentoo/html/index.html
Files: /usr/share/doc/gentoo/html/*.html
</screen>
<para>
For information on the file format, see <citerefentry>
<refentrytitle>install-docs</refentrytitle> <manvolnum>8</manvolnum>
</citerefentry> and the <systemitem role="package">doc-base</systemitem>
manual, in <ulink url="&doc-base;">Debian doc-base Manual</ulink>.
</para>
<para>
For more details on installing additional documentation, look in <xref linkend="destdir"/>.
</para>
</section>
<section id="docs"><title><filename>docs</filename> file</title>
<para>
This file specifies the file names of documentation files we can have
<citerefentry> <refentrytitle>dh_installdocs</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> install into the temporary directory
for us.
</para>
<para>
By default, it will include all existing files in the top-level source
directory that are called <filename>BUGS</filename>,
<filename>README*</filename>, <filename>TODO</filename> etc.
</para>
<para>
For <systemitem role="package">gentoo</systemitem>, I also included some other
files:
</para>
<screen>
BUGS
CONFIG-CHANGES
CREDITS
NEWS
README
README.gtkrc
TODO
</screen>
</section>
<section id="emacsen"><title><filename>emacsen-*</filename> file</title>
<para>
If your package supplies Emacs files that can be bytecompiled at package
installation time, you can use these files to set it up.
</para>
<para>
They are installed into the temporary directory by <citerefentry>
<refentrytitle>dh_installemacsen</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>.
</para>
<para>
If you don't need these, remove them.
</para>
</section>
<section id="examples"><title><filename><replaceable>package</replaceable>.examples</filename> file</title>
<para>
The <citerefentry> <refentrytitle>dh_installexamples</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> command installs files and directories
listed in this file as example files.
</para>
</section>
<section id="initd"><title><filename><replaceable>package</replaceable>.init</filename> and <filename><replaceable>package</replaceable>.default</filename> files</title>
<para>
If your package is a daemon that needs to be run at the system start-up, you've
obviously disregarded my initial recommendation, haven't you?  :-)
</para>
<para>
The <filename><replaceable>package</replaceable>.init</filename> file is
installed as the
<filename>/etc/init.d/<replaceable>package</replaceable></filename> script 
for the <emphasis>init script</emphasis> which starts and stops a daemon.
Its fairly generic skeleton template is provided by the
<command>dh_make</command> command as <filename>init.d.ex</filename>.  You'll
likely have to rename and edit it, a lot, while making sure to provide
<ulink url="&lsb;">Linux Standard Base</ulink> (LSB) compliant headers.  It
gets installed into the temporary directory by <citerefentry>
<refentrytitle>dh_installinit</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>.
</para>
<para>
The <filename><replaceable>package</replaceable>.default</filename> file will
be installed into
<filename>/etc/default/<replaceable>package</replaceable></filename>.  This
file sets defaults that are sourced by the <emphasis>init script</emphasis>.  Most times this
<filename><replaceable>package</replaceable>.default</filename> file is used to disable running a daemon, set some default flags or
timeouts.  If your <emphasis>init script</emphasis> has certain <emphasis>settable</emphasis>
features you want to install these into the <filename><replaceable>package</replaceable>.default</filename> file, not the <emphasis>init script</emphasis>.
</para>
<para>
If your upstream program provides a file for the <emphasis>init script</emphasis>, you can either use it or not.  If you
don't use their <emphasis>init script</emphasis> then create a new one in
<filename><replaceable>package</replaceable>.init</filename>.  However
if the upstream <emphasis>init script</emphasis> looks fine and installs in the right place you
still need to setup the <filename>rc*</filename> symlinks.  To do this you will
need to override <command>dh_installinit</command> in the
<filename>rules</filename> file with the following lines:
</para>
<screen>
override_dh_installinit:
        dh_installinit --onlyscripts
</screen>
<para>
If you don't need this, remove the files.
</para>
</section>
<section id="install"><title><filename>install</filename> file</title>
<para>
If there are files that need to be installed into your package but your
standard <literal>make install</literal> won't do it, you put the filenames and
destinations into this <filename>install</filename> file.  They are installed
by <citerefentry> <refentrytitle>dh_install</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.<footnote><para> This replaces the
deprecated <citerefentry> <refentrytitle>dh_movefiles</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> command which is configured by the
<filename>files</filename> file.  </para> </footnote> You should first check
there is not a more specific tool to use.  For example, documents should be in
the <filename>docs</filename> file and not in this one.
</para>
<para>
This <filename>install</filename> file has one line per file installed, with
the name of the file (relative to the top build directory) then a space then
the installation directory (relative to the install directory).  One example of
where this is used is where a binary is forgotten to be installed, the
<filename>install</filename> file would look like:
</para>
<screen>
src/foo/mybin usr/bin
</screen>
<para>
This will mean when this package is installed, there will be a binary file
<filename>/usr/bin/mybin</filename>.
</para>
<para>
Alternatively, this <filename>install</filename> can have the name of the file
only without the installation directory when the relative directory path does
not change.  This format is usually used for a large package that splits build
result into multiple binary packages using
<filename><replaceable>package-1</replaceable>.install</filename>,
<filename><replaceable>package-2</replaceable>.install</filename>, etc.
</para>
<para>
The <command>dh_install</command> command will fall back to look in
<filename>debian/tmp</filename> for files, if it doesn't find them in the
current directory (or wherever you've told it to look using
<literal>--sourcedir</literal>).
</para>
</section>
<section id="info"><title><filename><replaceable>package</replaceable>.info</filename> file</title>
<para>
If your package has info pages, you should install them using <citerefentry>
<refentrytitle>dh_installinfo</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> by listing them in the
<filename><replaceable>package</replaceable>.info</filename> files.
</para>
</section>
<section id="lintian"><title><filename>{<replaceable>package</replaceable>.|source/}lintian-overrides</filename> files</title>
<para>
If <systemitem role="package">lintian</systemitem> reports an erroneous
diagnostics for a case when the policy allows exceptions to some rule, you can
use <filename><replaceable>package</replaceable>.lintian-overrides</filename>
or <filename>source/lintian-overrides</filename> to quiet it.  Please read
<ulink url="&lintian-doc;">Lintian User's Manual</ulink> and refrain
from abusing this.
</para>
<para>
<filename><replaceable>package</replaceable>.lintian-overrides</filename> is
for the binary package named as <systemitem role="package"><replaceable>package</replaceable></systemitem> and is installed
into
<filename>usr/share/lintian/overrides/<replaceable>package</replaceable></filename>
by the <command>dh_lintian</command> command.
</para>
<para>
<filename>source/lintian-overrides</filename> is for the source package.  This
is not installed.
</para>
</section>
<section id="manpage"><title><filename>manpage.*</filename> files</title>
<para>
Your program(s) should have a manual page.  If they don't, you should create
them.  The <command>dh_make</command> command creates few template files for a
manual page.  These need to be copied and edited for each command without its
manual page.  Please make sure to remove unused templates.
</para>
<section id="manpage1"><title><filename>manpage.1.ex</filename> file</title>
<para>
Manual pages are normally written in <citerefentry>
<refentrytitle>nroff</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.
The <filename>manpage.1.ex</filename> template is written in
<command>nroff</command>, too.  See the <citerefentry>
<refentrytitle>man</refentrytitle> <manvolnum>7</manvolnum> </citerefentry>
manual page for a brief description of how to edit such a file.
</para>
<para>
The final manual page file name should include the name of the program it is
documenting, so we will rename it from <literal>manpage</literal> to
<literal>gentoo</literal>.  The file name also includes <literal>.1</literal>
as the first suffix, which means it's a manual page for a user command.  Be
sure to verify that this section is indeed the correct one.  Here's a short
list of manual page sections:
</para>
<table id="manpage-sections" pgwide="0" frame="topbot" rowsep="1" colsep="1">
<title>manual page sections</title>
<tgroup cols="3">
  <colspec colwidth="8*" align="left"/> <colspec colwidth="24*" align="left"/> <colspec colwidth="40*" align="left"/>
  <thead>
    <row> <entry>Section</entry> <entry>Description</entry> <entry>Notes</entry> </row>
  </thead>
  <tbody>
    <row> <entry>1</entry> <entry>User command</entry> <entry>Executable commands or scripts</entry> </row>
    <row> <entry>2</entry> <entry>System calls</entry> <entry>Functions provided by the kernel</entry> </row>
    <row> <entry>3</entry> <entry>Library calls</entry> <entry>Functions within system libraries</entry> </row>
    <row> <entry>4</entry> <entry>Special files</entry> <entry>Usually found in <filename>/dev</filename></entry> </row>
    <row> <entry>5</entry> <entry>File formats</entry> <entry>E.g. <filename>/etc/passwd</filename>'s format</entry> </row>
    <row> <entry>6</entry> <entry>Games</entry> <entry>Games or other frivolous programs</entry> </row>
    <row> <entry>7</entry> <entry>Macro packages</entry> <entry>Such as <command>man</command> macros</entry> </row>
    <row> <entry>8</entry> <entry>System administration</entry> <entry>Programs typically only run by root</entry> </row>
    <row> <entry>9</entry> <entry>Kernel routines</entry> <entry>Non-standard calls and internals</entry> </row>
  </tbody>
</tgroup>
</table>
<para>
So <systemitem role="package">gentoo</systemitem>'s man page should be called
<filename>gentoo.1</filename>.  If there was no <filename>gentoo.1</filename>
man page in the original source, you should create it by renaming the
<filename>manpage.1.ex</filename> template to <filename>gentoo.1</filename> and
edit it by using information from the example and from upstream docs.
</para>
<para>
You can use the <command>help2man</command> command to generate a man page out
of <literal>--help</literal> and <literal>--version</literal> output of each
program, too.  <footnote><para> If the command is missing
<command>info</command> page but have documentation files in the
<filename>/usr/share/<replaceable>package</replaceable></filename> directory,
you should manually edit generated the man page created by the
<command>help2man</command> command.  </para> </footnote>
</para>
</section>
<section id="manpagesgml"><title><filename>manpage.sgml.ex</filename> file</title>
<para>
If on the other hand you prefer writing SGML instead of
<command>nroff</command>, you can use the <filename>manpage.sgml.ex</filename>
template.  If you do this, you have to:
</para>
<itemizedlist>
<listitem>
<para>
rename the file to something like <filename>gentoo.sgml</filename>.
</para>
</listitem>
<listitem>
<para>
install the <systemitem role="package">docbook-to-man</systemitem> package
</para>
</listitem>
<listitem>
<para>
add <literal>docbook-to-man</literal> to the <literal>Build-Depends</literal>
line in the <filename>control</filename> file
</para>
</listitem>
<listitem>
<para>
add a <literal>override_dh_auto_build</literal> target to your
<filename>rules</filename> file:
</para>
<screen>
override_dh_auto_build:
        docbook-to-man debian/gentoo.sgml &gt; debian/gentoo.1
        dh_auto_build
</screen>
</listitem>
</itemizedlist>
</section>
<section id="manpagexml"><title><filename>manpage.xml.ex</filename> file</title>
<para>
If you prefer XML over SGML, you can use the <literal>manpage.xml.ex</literal>
template.  If you do this, you have to:
</para>
<itemizedlist>
<listitem>
<para>
rename the source file to something like <literal>gentoo.1.xml</literal>
</para>
</listitem>
<listitem>
<para>
install the <systemitem role="package">docbook-xsl</systemitem> package and an
XSLT processor like <systemitem role="package">xsltproc</systemitem>
(recommended)
</para>
</listitem>
<listitem>
<para>
add the <literal>docbook-xsl</literal>, <literal>docbook-xml</literal> and
<literal>xsltproc</literal> packages to the <literal>Build-Depends</literal>
line in the <literal>control</literal> file
</para>
</listitem>
<listitem>
<para>
add a <literal>override_dh_auto_build</literal> target to your
<filename>rules</filename> file:
</para>
<screen>
override_dh_auto_build:
        xsltproc --nonet \
         --param make.year.ranges 1 \
         --param make.single.year.ranges 1 \
         --param man.charmap.use.subset 0 \
         -o debian/ \
 http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl\
        debian/gentoo.1.xml
        dh_auto_build
</screen>
</listitem>
</itemizedlist>
</section>
</section>
<section id="manpages"><title><filename><replaceable>package</replaceable>.manpages</filename> file</title>
<para>
If your package has manual pages, you should install them using <citerefentry>
<refentrytitle>dh_installman</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> by listing them in the
<filename><replaceable>package</replaceable>.manpages</filename> files.
</para>
<para>
To install <filename>docs/gentoo.1</filename> for the <systemitem role="package">gentoo</systemitem> package as its manpage, you create a
<filename>gentoo.manpages</filename> file as the following.
</para>
<screen>
docs/gentoo.1
</screen>
</section>
<section id="menu"><title><filename>menu</filename> file</title>
<para>
X Window System users usually have a window manager with a menu that can be
customized to launch programs.  If they have installed the Debian <systemitem role="package">menu</systemitem> package, a set of menus for every program on
the system will be created for them.
</para>
<para>
Here's the default <filename>menu.ex</filename> file that
<command>dh_make</command> created.
</para>
<screen>
?package(gentoo):needs=X11|text|vc|wm \
        section=Applications/see-menu-manual\
        title=gentoo command=/usr/bin/gentoo
</screen>
<para>
The first field after the colon character is <literal>needs</literal>, and it
specifies what kind of interface the program needs.  Change this to one of the
listed alternatives, e.g.  <literal>text</literal> or <literal>X11</literal>.
</para>
<para>
The next is <literal>section</literal>, where the menu and submenu entry
should appear in.  
<footnote><para> The current list of sections is at 
<ulink url="&menu-structure;">The Debian Menu sub-policy 2.1 'Preferred menu structure'</ulink>.
There were a major reorganization of menu structure for <literal>squeeze</literal>.
</para> </footnote>
</para>
<para>
The <literal>title</literal> field is the name of the program.  You can start
this one in uppercase if you like.  Just keep it short.
</para>
<para>
Finally, the <literal>command</literal> field is the command that runs the
program.
</para>
<para>
Let's change the file name to <filename>menu</filename> and change the menu
entry to this:
</para>
<screen>
?package(gentoo): needs=X11 \
        section=Applications/Tools \
        title=Gentoo command=gentoo
</screen>
<para>
You can also add other fields like <literal>longtitle</literal>,
<literal>icon</literal>, <literal>hints</literal> etc.  See <citerefentry>
<refentrytitle>dh_installmenu</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>, <citerefentry> <refentrytitle>menufile</refentrytitle>
<manvolnum>5</manvolnum> </citerefentry>, <citerefentry>
<refentrytitle>update-menus</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> and 
<ulink url="&menu-policy;">The Debian Menu sub-policy</ulink> for more
information.
</para>
</section>
<section id="news"><title><filename>NEWS</filename> file</title>
<para>
The <citerefentry> <refentrytitle>dh_installchangelogs</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> command installs this.
</para>
</section>
<section id="maintscripts"><title><filename>{post|pre}{inst|rm}</filename> files</title>
<para>
These <filename>postinst</filename>, <filename>preinst</filename>,
<filename>postrm</filename>, and <filename>prerm</filename> files
<footnote><para> Although I used Bash short hand expression to indicate these
files as <filename>{post|pre}{inst|rm}</filename> here, I recommend you to use
pure POSIX (non-Bash) shell for these <emphasis>maintainer scripts</emphasis>
as much as possible for the better compatibility.  </para> </footnote> are
called <emphasis>maintainer scripts</emphasis>.  They are scripts which are put
in the control area of the package and run by <command>dpkg</command> when your
package is installed, upgraded or removed.
</para>
<para>
As a novice maintainer, you should avoid any manual editing of
<emphasis>maintainer scripts</emphasis> because they are problematic.  For more
information look in the <ulink url="&policy-mantainerscripts;">Debian
Policy Manual, 6 'Package maintainer scripts and installation
procedure'</ulink>, and take a look at these example files provided by
<command>dh_make</command>.
</para>
<para>
If you did not listen to me and made your custom <emphasis>maintainer
scripts</emphasis> for a package, you should make sure to test them not only
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>.
</para>
<para>
Upgrades to the new version should be silent and non-intrusive (existing users
should not notice the upgrade except by discovering that old bugs have been
fixed and there perhaps are new features).
</para>
<para>
When the upgrade is necessarily intrusive (eg., config files scattered through
various home directories with totally different structure), you may consider to
set package to the safe default (e.g., disabled service) and provide proper
documentations required by the policy (<filename>README.Debian</filename> and
<filename>NEWS.Debian</filename>) as the last resort.  Don't bother user with
the <command>debconf</command> note invoked from these <emphasis>maintainer
scripts</emphasis> for upgrades.
</para>
<para>
The <systemitem role="package">ucf</systemitem> package provides
<emphasis>conffile-like</emphasis> handling infrastructure to preserve user
changes for files that may not be labeled <emphasis>conffiles</emphasis> such
as ones managed by the <emphasis>maintainer scripts</emphasis>.  This should
minimize issues associated with them.
</para>
<para>
These <emphasis>maintainer scripts</emphasis> are the Debian enhancements that
explain <emphasis role="strong">why people choose Debian</emphasis>.  You must
be very careful not to annoy them with these.
</para>
</section>
<section id="todo"><title><filename>TODO</filename> file</title>
<para>
The <citerefentry> <refentrytitle>dh_installdocs</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> command installs this.
</para>
</section>
<section id="watch"><title><filename>watch</filename> file</title>
<para>
The <filename>watch</filename> file format is documented in the <citerefentry>
<refentrytitle>uscan</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
manpage.  The <filename>watch</filename> file configures the
<command>uscan</command> program (in the <systemitem role="package">devscripts</systemitem> package) to watch the site where you
originally got the source from.  This is also used by <ulink url="&dehs;">Debian External Health Status (DEHS)</ulink>.
</para>
<para>
Here's what I put in it:
</para>
<screen>
# watch control file for uscan
version=3
&sf-net;/gentoo/gentoo-(.+)\.tar\.gz debian uupdate
</screen>
<para>
Normally with this <filename>watch</filename> file, the URL at
<literal>&sf-net;/gentoo</literal> is downloaded and searched for links of
the form <literal>&lt;a href=...&gt;</literal>.  The base name (just the part
after the final <literal>/</literal>) of these linked URLs are matched against
Perl regular expression (see <citerefentry> <refentrytitle>perlre</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>) pattern
<literal>gentoo-(.+)\.tar\.gz</literal>.  Out of matched files, the file with
the greatest version number is downloaded and the <command>uupdate</command>
program is run to create the updated source tree from them.
</para>
<para>
Although this is true for other sites, the SourceForge download service at
<ulink url="&sf-net;"/> is an exception.  When the
<filename>watch</filename> file has an URL matching with the Perl regexp
<literal>^http://sf\.net/</literal>, the <command>uscan</command> program
substitutes it with <literal>&qa-do;watch/sf.php/</literal> and
then applies this rule.  The URL redirector service at this <ulink url="&qa-do;"/> is designed to offer
a stable redirect service to the desired file for the
<filename>watch</filename> file having
<literal>&sf-net;/<replaceable>project</replaceable>/<replaceable>tar-name</replaceable>-(.+)\.tar\.gz</literal>.
This solves issues related to the periodically changing URL there.
</para>
</section>
<section id="sourcef"><title><filename>source/format</filename> file</title>
<para>
In the <filename>debian/source/format</filename> file, there should be a single
line indicating the desired format for the source package (check <citerefentry>
<refentrytitle>dpkg-source</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> for an exhaustive list).  After <literal>squeeze</literal>, it
should say either:
</para>
<itemizedlist>
<listitem>
<para>
<literal>3.0 (native)</literal> for Debian native packages or
</para>
</listitem>
<listitem>
<para>
<literal>3.0 (quilt)</literal> for everything else.
</para>
</listitem>
</itemizedlist>
<para>
The newer <literal>3.0 (quilt)</literal> source format records modifications in
a <command>quilt</command> patch series within
<filename>debian/patches</filename>.  Those changes are then automatically
applied during extraction of the source package.  <footnote><para> See <ulink url="&debsrc3;">DebSrc3.0</ulink> for the
summary information concerning the switch to the new <literal>3.0
(quilt)</literal> and <literal>3.0 (native)</literal> source formats.  </para>
</footnote> The Debian modifications are simply stored in a
<filename>debian.tar.gz</filename> archive containing all files under the
<filename>debian</filename> directory.  This new format supports inclusion of
binary files such as PNG icons by the package maintainer without requiring
tricks.  <footnote><para> Actually, this new format also supports multiple
upstream tarballs and more compression methods.  These are beyond the scope of
this document.  </para> </footnote>
</para>
<para>
When <command>dpkg-source</command> extracts a source package in <literal>3.0
(quilt)</literal> source format, it automatically applies all patches listed in
<filename>debian/patches/series</filename>.  You can avoid applying patches at
the end of the extraction with the <literal>--skip-patches</literal> option.
</para>
</section>
<section id="sourcel"><title><filename>source/local-options</filename> file</title>
<para>
When you want to manage Debian packaging activities under a VCS, you typically
create one branch (e.g.  <literal>upstream</literal>) tracking the upstream
source and another branch (e.g.  typically <literal>master</literal> for Git)
tracking the Debian package.  For the latter, you usually want to have
unpatched upstream source with your <filename>debian/*</filename> files for the
Debian packaging to ease merging of the new upstream source.
</para>
<para>
After you build a package, the source is normally left patched.  You need to
unpatch it manually by running <literal>dquilt pop -a</literal> before
committing to the <literal>master</literal> branch.  You can automate this by
adding the optional <filename>debian/source/local-options</filename> file
containing <literal>unapply-patches</literal>.  This file is not included in
the generated source package and changes the local build behavior only.  This
file may contain <literal>abort-on-upstream-changes</literal>, too (see
<citerefentry> <refentrytitle>dpkg-source</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>).
</para>
<screen>
unapply-patches
abort-on-upstream-changes
</screen>
</section>
<section id="sourceopt"><title><filename>source/options</filename> file</title>
<para>
The autogenerated files in the source tree can be quite annoying for packaging
since they generate meaningless large patch files.  There are custom modules
such as <command>dh_autoreconf</command> to ease this problem as described in 
<xref linkend="customrules"/>.
</para>
<para>
You can provide a Perl regular expression to the
<literal>--extend-diff-ignore</literal> option argument of <citerefentry>
<refentrytitle>dpkg-source</refentrytitle><manvolnum>1</manvolnum>
</citerefentry> to ignore changes made to the autogenerated files while
creating the source package.
</para>
<para>
You can store such <command>dpkg-source</command> option argument in the
<filename>source/options</filename> file of the source package as the generic
solution to address this problem of the autogenerated files.  The following
will skip creating patch files for <filename>config.sub</filename>,
<filename>config.guess</filename> and <filename>Makefile</filename>.
</para>
<screen>
extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"
</screen>
</section>
<section id="patches"><title><filename>patches/*</filename> files</title>
<para>
The old <literal>1.0</literal> source format created a single large
<filename>diff.gz</filename> file which contains package maintenance files in
<filename>debian</filename> and patch files to the source.  Such a package is a
bit cumbersome to inspect and understand for each source tree modification
later.  This is not so nice.
</para>
<para>
The newer <literal>3.0 (quilt)</literal> source format stores patches in
<filename>debian/patches/*</filename> files using the <command>quilt</command>
command.  These patches and other package data which are all constrained under
the <filename>debian</filename> directory are packaged as the
<filename>debian.tar.gz</filename> file.  Since the
<command>dpkg-source</command> command can handle <command>quilt</command>
formatted patch data in the <literal>3.0 (quilt)</literal> source without the
<systemitem role="package">quilt</systemitem> package, it does not need to
<literal>Build-Depends</literal> on the <systemitem role="package">quilt</systemitem> package.  <footnote><para> Several methods
for the patch set maintenance have been proposed and are in use with Debian
packages.  The <command>quilt</command> system is the preferred maintenance
system in use.  Other ones are <command>dpatch</command>,
<command>dbs</command>, <command>cdbs</command>, etc.  Many of these keep such
patches as <filename>debian/patches/*</filename> files.  </para> </footnote>
</para>
<para>
The <command>quilt</command> command is explained in <citerefentry>
<refentrytitle>quilt</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.
It records modifications to the source as a stack of <literal>-p1</literal>
patch files in the <filename>debian/patches</filename> directory and the source
tree is untouched outside of the <filename>debian</filename> directory.  The
order of these patches are recorded in the
<filename>debian/patches/series</filename> file.  You can apply (=push),
un-apply (=pop), and refresh patches easily.  <footnote><para> If you are
asking a sponsor to upload your package, this kind of clear separation and
documentation of your changes are very important to expedite the package review
by your sponsor.  </para> </footnote>
</para>
<para>
For <xref linkend="modify"/>, we created 3 patches in
<filename>debian/patches</filename>.
</para>
<para>
Since Debian patches are located in <filename>debian/patches</filename>, please
make sure to setup the <command>dquilt</command> command properly as described
in <xref linkend="quiltrc"/>.
</para>
<para>
When someone (including yourself) provides you with a patch
<filename><replaceable>foo</replaceable>.patch</filename> to the source later,
then the modification of a <literal>3.0 (quilt)</literal> source package is
quite simple:
</para>
<screen>
$ dpkg-source -x gentoo_0.9.12.dsc
$ cd gentoo-0.9.12
$ dquilt import ../<replaceable>foo</replaceable>.patch
$ dquilt push
$ dquilt refresh
$ dquilt header -e
... describe patch
</screen>
<para>
The patches stored in the newer <literal>3.0 (quilt)</literal> source format
must be <emphasis>fuzz</emphasis> free.  You should ensure it as <literal>dquilt
pop -a; while dquilt push; do dquilt refresh; done</literal>.
</para>
</section>
</chapter>
<chapter id="build"><title>Building the package</title>
<para>
We should now be ready to build the package.
</para>
<section id="completebuild"><title>Complete (re)build</title>
<para>
In order to properly make complete (re)build of a package, you have to ensure
to install
</para>
<itemizedlist>
<listitem>
<para>
the <systemitem role="package">build-essential</systemitem> package,
</para>
</listitem>
<listitem>
<para>
packages listed in the <literal>Build-Depends</literal> field (see <xref linkend="control"/>), and
</para>
</listitem>
<listitem>
<para>
packages listed in the <literal>Build-Depends-indep</literal> field (see <xref linkend="control"/>).
</para>
</listitem>
</itemizedlist>
<para>
Then you issue the following command in the source directory:
</para>
<screen>
$ dpkg-buildpackage
</screen>
<para>
This will do everything to make full binary and source packages for you.  It
will:
</para>
<itemizedlist>
<listitem>
<para>
clean the source tree (<literal>debian/rules clean</literal>)
</para>
</listitem>
<listitem>
<para>
build the source package (<literal>dpkg-source -b</literal>)
</para>
</listitem>
<listitem>
<para>
build the program (<literal>debian/rules build</literal>)
</para>
</listitem>
<listitem>
<para>
build binary packages (<literal>fakeroot debian/rules binary</literal>)
</para>
</listitem>
<listitem>
<para>
sign the source <filename>.dsc</filename> file, using <command>gpg</command>
</para>
</listitem>
<listitem>
<para>
create and sign the upload <filename>.changes</filename> file, using
<command>dpkg-genchanges</command> and <command>gpg</command>
</para>
</listitem>
</itemizedlist>
<para>
The only input that will be required of you is your GPG secret pass phrase,
twice.
<footnote><para>
This GPG key must be signed by a Debian developer to get connected to the web
of trust and must be registered to <ulink url="&keyring;">the Debian
keyring</ulink>.  This enables your uploaded packages to be accepted to the
Debian archives.  See 
<ulink url="&keycreate;">Creating a new GPG key</ulink> and
<ulink url="&keysigning; ">Debian Wiki on Keysigning</ulink>.
</para></footnote>
</para>
<para>
After all this is done, you will see the following files in the directory above
(<filename>~/gentoo</filename>):
</para>
<itemizedlist>
<listitem>
<para>
<filename>gentoo_0.9.12.orig.tar.gz</filename>
</para>
<para>
This is the original source code tarball, merely renamed to the above so that
it adheres to the Debian standard.  Note that this was created initially by the
<literal>dh_make -f ../gentoo-0.9.12.tar.gz</literal>.
</para>
</listitem>
<listitem>
<para>
<filename>gentoo_0.9.12-1.dsc</filename>
</para>
<para>
This is a summary of the contents of the source code.  The file is generated
from your <filename>control</filename> file, and is used when unpacking the
source with <citerefentry> <refentrytitle>dpkg-source</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.  This file is GPG signed, so that
people can be sure that it's really yours.
</para>
</listitem>
<listitem>
<para>
<filename>gentoo_0.9.12-1.debian.tar.gz</filename>
</para>
<para>
This compressed tarball contains your <filename>debian</filename> directory
contents.  Each and every addition you made to the original source code are
stored as <command>quilt</command> patches in
<filename>debian/patches</filename>.
</para>
<para>
If someone else wants to re-create your package from scratch, they can easily
do so using the above three files.  The extraction procedure is trivial: just
copy the three files somewhere else and run <literal>dpkg-source -x
gentoo_0.9.12-1.dsc</literal>.  <footnote><para> You can avoid applying
<command>quilt</command> patches in the <literal>3.0 (quilt)</literal> source
format at the end of the extraction with the <literal>--skip-patches</literal>
option.  Alternatively, you can run <literal>dquilt pop -a</literal> after
normal operation.  </para> </footnote>
</para>
</listitem>
<listitem>
<para>
<filename>gentoo_0.9.12-1_i386.deb</filename>
</para>
<para>
This is your completed binary package.  You can use <command>dpkg</command> to
install and remove this just like any other package.
</para>
</listitem>
<listitem>
<para>
<filename>gentoo_0.9.12-1_i386.changes</filename>
</para>
<para>
This file describes all the changes made in the current package revision, and
it is used by the Debian FTP archive maintenance programs to install the binary
and source packages in it.  It is partly generated from the
<filename>changelog</filename> file and the <filename>.dsc</filename> file.
This file is GPG signed, so that people can be sure that it's really yours.
</para>
<para>
As you keep working on the package, behavior will change and new features will
be added.  People downloading your package can look at this file and quickly
see what has changed.  Debian archive maintenance programs will also post the
contents of this file to the <ulink url="&debian-devel-announce-ldo;">debian-devel-announce@lists.debian.org</ulink>
mailing list.
</para>
</listitem>
</itemizedlist>
<para>
The long strings of numbers in the <filename>.dsc</filename> and
<filename>.changes</filename> files are MD5/SHA1/SHA256 checksums for the files
mentioned.  A person downloading your files can test them with <citerefentry>
<refentrytitle>md5sum</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,
<citerefentry> <refentrytitle>sha1sum</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>, or <citerefentry> <refentrytitle>sha256sum</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> and if the numbers don't match,
they'll know the file is corrupt or has been tampered with.
</para>
</section>
<section id="autobuilder"><title>Autobuilder</title>
<para>
Debian supports many <ulink url="&ports;">ports</ulink>
with the <ulink url="&buildd;">autobuilder
network</ulink> running <command>buildd</command> daemons on many different
architecture computers.  Although you do not need to do this by yourself, you
should be aware of what will happen on your packages.  Let's look into roughly
how your packages are rebuild for many different architectures by them.
<footnote><para> The actual autobuilder system involves much more complicated
schemes than the one documented here.  Such details are beyond the scope of
this document.  </para> </footnote>
</para>
<para>
For <literal>Architecture: any</literal> packages, the autobuilder system
rebuild them.  It ensures to install
</para>
<itemizedlist>
<listitem>
<para>
the <systemitem role="package">build-essential</systemitem> package, and
</para>
</listitem>
<listitem>
<para>
packages listed in the <literal>Build-Depends</literal> field (see <xref linkend="control"/>).
</para>
</listitem>
</itemizedlist>
<para>
Then it issues the following command in the source directory:
</para>
<screen>
$ dpkg-buildpackage -B
</screen>
<para>
This will do everything to make architecture dependent binary packages on
another architecture.  It will:
</para>
<itemizedlist>
<listitem>
<para>
clean the source tree (<literal>debian/rules clean</literal>)
</para>
</listitem>
<listitem>
<para>
build the program (<literal>debian/rules build</literal>)
</para>
</listitem>
<listitem>
<para>
build architecture dependent binary packages (<literal>fakeroot debian/rules
binary-arch</literal>)
</para>
</listitem>
<listitem>
<para>
sign the source <filename>.dsc</filename> file, using <command>gpg</command>
</para>
</listitem>
<listitem>
<para>
create and sign the upload <filename>.changes</filename> file, using
<command>dpkg-genchanges</command> and <command>gpg</command>
</para>
</listitem>
</itemizedlist>
<para>
This is why you see your package for other architectures.
</para>
<para>
Although packages listed in the <literal>Build-Depends-indep</literal> field
are required to be installed for the normal packaging by us (see <xref linkend="completebuild"/>), they are not required to be installed for the
autobuilder system since it build only architecture dependent binary packages.
<footnote><para> Unlike under the <systemitem role="package">pbuilder</systemitem> package, the <command>chroot</command>
environment under the <systemitem role="package">sbuild</systemitem> package
used by the autobuilder system does not force the minimal system and may leave
many packages installed.  </para> </footnote> This difference between normal
packaging and autobuilder situation dictates whether you record such required
packages in the <literal>Build-Depends</literal> or
<literal>Build-Depends-indep</literal> fields of the
<filename>debian/control</filename> file (see <xref linkend="control"/>).
</para>
</section>
<section id="option-sa"><title>Including <filename>orig.tar.gz</filename> for upload</title>
<para>
When you first upload the package to the archive, you need to include the
original <filename>orig.tar.gz</filename> source, too.  If the Debian revision
number of such package is neither <literal>1</literal> nor
<literal>0</literal>, you must provide <command>dpkg-buildpackage</command>
command with the <literal>-sa</literal> option.  On the other hand, the
<literal>-sd</literal> option will force to exclude the original
<filename>orig.tar.gz</filename> source.
</para>
</section>
<section id="debuild"><title><command>debuild</command> command</title>
<para>
You can automate package build process of the
<command>dpkg-buildpackage</command> command further with the
<command>debuild</command> command.  See <citerefentry>
<refentrytitle>debuild</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>.
</para>
<para>
Customization of the <command>debuild</command> command can be done through
<filename>/etc/devscripts.conf</filename> or
<filename>~/.devscripts</filename>.  I would suggest at least following items:
</para>
<screen>
DEBSIGN_KEYID=Your_GPG_keyID
DEBUILD_LINTIAN=yes
DEBUILD_LINTIAN_OPTS=-i -I --show-overrides
</screen>
<para>
With these, packages are signed by your specified GPG key ID (good for
sponsoring packages) and checked by the <command>lintian</command> command in
details.
</para>
<para>
Cleaning source and rebuilding package from a user account is as simple as:
</para>
<screen>
$ debuild
</screen>
<para>
Please note that the <command>dpkg-buildpackage</command> option
<literal>-sa</literal> to include the original <filename>orig.tar.gz</filename>
source can be specified as:
</para>
<screen>
$ debuild -sa
</screen>
<para>
You can clean source tree as simple as:
</para>
<screen>
$ debuild clean
</screen>
</section>
<section id="pbuilder"><title><systemitem role="package">pbuilder</systemitem> package</title>
<para>
For a clean room (<command>chroot</command>) build environment to verify the
build dependencies, the <systemitem role="package">pbuilder</systemitem>
package is very useful.  <footnote><para> Since the <systemitem role="package">pbuilder</systemitem> package is still evolving, you have to
check the actual configuration situation by consulting the latest official
documentation.</para> </footnote> This ensures a clean build from the source
under the <literal>sid</literal> auto-builder for different architectures and
avoids the severity serious FTBFS (Fails To Build From Source) bug which is
always in the RC (release critical) category. 
<footnote><para>See <ulink url="&buildd-do;"/> for more on the
auto-builder of the Debian package.</para></footnote>
</para>
<para>
Let's customize the <systemitem role="package">pbuilder</systemitem> package by
the following.
</para>
<itemizedlist>
<listitem>
<para>
setting <filename>/var/cache/pbuilder/result</filename> directory writable by
the user.
</para>
</listitem>
<listitem>
<para>
creating a directory, e.g.
<filename><replaceable>/var/cache/pbuilder/hooks</replaceable></filename>,
writable by the user to place hook scripts.
</para>
</listitem>
<listitem>
<para>
setting <filename>~/.pbuilderrc</filename> or
<filename>/etc/pbuilderrc</filename> to include as follows.
</para>
<screen>
AUTO_DEBSIGN=yes
HOOKDIR=<replaceable>/var/cache/pbuilder/hooks</replaceable>
</screen>
</listitem>
</itemizedlist>
<para>
This will allow you to sign generated packages with your secret GPG key in the
<filename>~/.gnupg/</filename> directory.
</para>
<para>
Let's then initialize the local <systemitem role="package">pbuilder</systemitem> <command>chroot</command> system first as
follows.
</para>
<screen>
$ sudo pbuilder create
</screen>
<para>
If you already have the completed source packages, issue the following commands
in the directory where the
<filename><replaceable>foo</replaceable>.orig.tar.gz</filename>,
<filename><replaceable>foo</replaceable>.debian.tar.gz</filename>, and
<filename><replaceable>foo</replaceable>.dsc</filename> files exist to update
the local <systemitem role="package">pbuilder</systemitem>
<command>chroot</command> system and to build binary packages in it.
</para>
<screen>
$ sudo pbuilder --update
$ sudo pbuilder --build <replaceable>foo</replaceable>.dsc
</screen>
<para>
Please note that the <command>dpkg-buildpackage</command> option
<literal>-sa</literal> to include the original <filename>orig.tar.gz</filename>
source can be specified as:
</para>
<screen>
$ sudo pbuilder --build --debbuildopts -sa <replaceable>foo</replaceable>.dsc
</screen>
<para>
The newly built packages will be located in
<filename>/var/cache/pbuilder/result/</filename> with non-root ownership.
</para>
<para>
If you already have the updated source tree without generating the matching
source packages, issue the following commands in the source directory where the
<filename>debian</filename> directory exists, instead.
</para>
<screen>
$ sudo pbuilder --update
$ pdebuild
</screen>
<para>
Please note that the <command>dpkg-buildpackage</command> option
<literal>-sa</literal> to include the original <filename>orig.tar.gz</filename>
source can be specified as:
</para>
<screen>
$ pdebuild --debbuildopts -sa
</screen>
<para>
You can log into its <command>chroot</command> environment with the
<literal>pbuilder --login --save-after-login</literal> command and configure it
as you wish.  This environment can be saved by leaving its shell prompt with
<literal>^D</literal> (Control-D).
</para>
<para>
The latest version of the <command>lintian</command> command can be executed in
the <literal>chroot</literal> environment using the hook script
<filename><replaceable>/var/cache/pbuilder/hooks</replaceable>/B90lintian</filename>
configured as follows.  <footnote><para> This assumes
<literal>HOOKDIR=/var/cache/pbuilder/hooks</literal>.  You can find many
examples of the hook script in the
<filename>/usr/share/doc/pbuilder/examples</filename> directory.  </para>
</footnote>
</para>
<screen>
#!/bin/sh
set -e
install_packages() {
    apt-get -y --force-yes install $@
    }
install_packages lintian
echo +++ lintian output +++
su -c lintian -i -I --show-overrides /tmp/buildd/*.changes - pbuilder
# use this version if you don't want lintian to fail the build
#su -c lintian -i -I --show-overrides /tmp/buildd/*.changes; : - pbuilder
echo +++ end of lintian output +++
</screen>
<para>
You need to have access to the latest <literal>sid</literal> environment to
build packages properly for <literal>sid</literal>.  In reality,
<literal>sid</literal> may be experiencing issues which makes it not desirable
for you to migrate your whole system.  The <systemitem role="package">pbuilder</systemitem> package can help you to cope with this
kind of situation.
</para>
<para>
You may need to update your <literal>stable</literal> packages after their
release for <literal>stable-proposed-updates</literal>,
<literal>stable/updates</literal>, etc.  <footnote><para> There are some
restrictions for such updates of your <literal>stable</literal> package.
</para> </footnote> For such occasions, I am running <literal>sid</literal>
system is not good enough excuse not to update them promptly.  The <systemitem role="package">pbuilder</systemitem> package can help you to access
environments of almost any Debian derivative distributions of the same CPU
architecture.
</para>
<para>
See <ulink url="&pbuilder;"/>,
<citerefentry> <refentrytitle>pdebuild</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>, <citerefentry> <refentrytitle>pbuilderrc</refentrytitle>
<manvolnum>5</manvolnum> </citerefentry>, and <citerefentry>
<refentrytitle>pbuilder</refentrytitle> <manvolnum>8</manvolnum>
</citerefentry>.
</para>
</section>
<section id="git-buildpackage"><title><command>git-buildpackage</command> command and similars</title>
<para>
If your upstream uses the source code management system (VCS)
<footnote><para>See <ulink url="&debref-vcs;">Version control systems</ulink> for more.</para></footnote>
to maintain their code, you should consider to use them.  That makes merging
and cherry-picking upstream patches much easier.  There are several specialized
wrapper script packages for the Debian package building for each VCS.
</para>
<itemizedlist>
<listitem>
<para>
<systemitem role="package">git-buildpackage</systemitem>: Suite to help with
Debian packages in Git repositories.
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">svn-buildpackage</systemitem>: helper programs to
maintain Debian packages with Subversion.
</para>
</listitem>
<listitem>
<para>
<systemitem role="package">cvs-buildpackage</systemitem>: A set of Debian
package scripts for CVS source trees.
</para>
</listitem>
</itemizedlist>
<para>
There are packages which <emphasis>automate</emphasis> building of packages
under VCS managed source tree for advanced audiences.  I will not explain them
in this tutorial.  
<footnote><para> Here are few web resources available for advanced audiences.  </para> 
<itemizedlist>
<listitem> <para> <ulink url="&git-buildpackage-doc;">Building Debian Packages with git-buildpackage</ulink> </para> </listitem> 
<listitem> <para> <ulink url="&debian-packages-git;">debian packages in git</ulink> </para> </listitem> 
<listitem> <para> <ulink url="&git-debian-packaging;">Using Git for Debian Packaging</ulink> </para> </listitem> 
<listitem> <para> <ulink url="&git-dpm;">git-dpm: Debian packages in Git manager</ulink> </para> </listitem>
<listitem> <para> <ulink url="&topgit;">Using TopGit to generate quilt series for Debian packaging</ulink> </para> </listitem>
</itemizedlist> 
</footnote>
</para>
</section>
<section id="quickrebuild"><title>Quick rebuild</title>
<para>
With a large package, you may not want to rebuild from scratch every time while
you tune details in <filename>debian/rules</filename>.  For testing purposes,
you can make a <filename>.deb</filename> file without rebuilding the upstream
sources like this <footnote><para> Environment variables which are normally
configured to proper values are not set by this method.  Never create real
packages to be uploaded using this <emphasis role="strong">quick</emphasis>
method.  </para> </footnote>:
</para>
<screen>
$ fakeroot debian/rules binary
</screen>
<para>
Or, simply as following to see if it build or not.
</para>
<screen>
$ fakeroot debian/rules build
</screen>
<para>
Once you are finished with your tuning, remember to rebuild following the
proper procedure.  You may not be able to upload correctly if you try to upload
<filename>.deb</filename> files built this way.
</para>
</section>
</chapter>
<chapter id="checkit"><title>Checking the package for errors</title>
<para>
There are few chores you should know to check the package for errors by
yourself before uploading packages to public archives.
</para>
<para>
Testing on machine other than your own is also good idea.  You must watch
closely for any warnings or errors for all the test described here.
</para>
<section id="pinstall"><title>Verifying package for install</title>
<para>
You must test your package if it installs without problem.  The <citerefentry>
<refentrytitle>debi</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
command helps you to test to install all the generated binary packages.
</para>
<screen>
$ sudo debi gentoo_0.9.12-1_i386.changes
</screen>
<para>
You have to make sure that there are no overlapped files with other existing
packages using the
<filename>Contents-<replaceable>i386</replaceable></filename> file downloaded
from the Debian archive to prevent installation problem on different systems.
The <command>apt-file</command> command may be handy for this task.  If there
are overlapped files, please take actions to avoid the real problem using the
alternatives mechanism (see <citerefentry>
<refentrytitle>update-alternatives</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>) by coordinating with other affected packages or by setting the
<literal>Conflicts</literal> entry in the <filename>debian/control</filename>
file.
</para>
</section>
<section id="pmaintscripts"><title>Verifying package for <emphasis>maintainer scripts</emphasis></title>
<para>
All <emphasis>maintainer scripts</emphasis>, i.e.,
<filename>preinst</filename>, <filename>prerm</filename>,
<filename>postinst</filename>, and <filename>postrm</filename> files, are
non-trivial unless they are auto-generated by the <systemitem role="package">debhelper</systemitem> programs.  So do not use them if you are
a novice maintainer (see <xref linkend="maintscripts"/>).
</para>
<para>
If the package makes use of these non-trivial <emphasis>maintainer
scripts</emphasis>, be sure to test not only for install but also for remove,
purge, and upgrade.  Many <emphasis>maintainer script</emphasis> bugs show up
when packages are removed or purged.  Use the <command>dpkg</command> command
as follows to test them.
</para>
<screen>
$ sudo dpkg -r gentoo
$ sudo dpkg -P gentoo
$ sudo dpkg -i gentoo_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>i386</replaceable>.deb
</screen>
<para>
This should be done with sequences such as the following.
</para>
<itemizedlist>
<listitem>
<para>
install the previous version (if needed).
</para>
</listitem>
<listitem>
<para>
upgrade it from the previous version.
</para>
</listitem>
<listitem>
<para>
downgrade it back to the previous version (optional).
</para>
</listitem>
<listitem>
<para>
purge it.
</para>
</listitem>
<listitem>
<para>
install the new package.
</para>
</listitem>
<listitem>
<para>
remove it.
</para>
</listitem>
<listitem>
<para>
install it again.
</para>
</listitem>
<listitem>
<para>
purge it.
</para>
</listitem>
</itemizedlist>
<para>
If this is your first package, you should create dummy packages with different
versions to test your package in advance to prevent future problems.
</para>
<para>
Bear in mind that if your package has previously been released in Debian,
people will often be upgrading to your package from the version that was in the
last Debian release.  Remember to test upgrades from that version too.
</para>
<para>
Although downgrade is not officially supported, it should be nice to support
it.
</para>
</section>
<section id="lintians"><title><systemitem role="package">lintian</systemitem> package</title>
<para>
Run <citerefentry> <refentrytitle>lintian</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> on your <filename>.changes</filename>
file.  The <command>lintian</command> command runs many test scripts to check
for many common packaging errors.  <footnote><para> You do not need to provide
the <command>lintian</command> option <literal>-i -I --show-overrides</literal>
if you customized <filename>/etc/devscripts.conf</filename> or
<filename>~/.devscripts</filename> as described in <xref linkend="debuild"/>.
</para> </footnote>
</para>
<screen>
$ lintian -i -I --show-overrides gentoo_0.9.12-1_i386.changes
</screen>
<para>
Of course, replace the filename with the name of the
<filename>.changes</filename> file generated for your package.  The output of
the <command>lintian</command> command are marked as follows.
</para>
<itemizedlist>
<listitem>
<para>
<literal>E:</literal> for error; a sure policy violation or a packaging error.
</para>
</listitem>
<listitem>
<para>
<literal>W:</literal> for warning; a possible policy violation or a packaging
error.
</para>
</listitem>
<listitem>
<para>
<literal>I:</literal> for info; a information on certain packaging aspects.
</para>
</listitem>
<listitem>
<para>
<literal>N:</literal> for note; a detailed message to help your debugging.
</para>
</listitem>
<listitem>
<para>
<literal>O:</literal> for overridden; a message overridden by the
<filename>lintian-overrides</filename> files but displayed by the
<literal>--show-overrides</literal> option.
</para>
</listitem>
</itemizedlist>
<para>
For warnings, tune the package to avoid them or verify that the warnings are
spurious.  If spurious, set the <filename>lintian-overrides</filename> files as
described in <xref linkend="lintian"/>.
</para>
<para>
Note that you can build the package with <command>dpkg-buildpackage</command>
and run <command>lintian</command> on it in one command with <citerefentry>
<refentrytitle>debuild</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
or with <citerefentry> <refentrytitle>pdebuild</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.
</para>
</section>
<section id="debc"><title><command>debc</command> command</title>
<para>
You can list files in the binary Debian package by <citerefentry>
<refentrytitle>debc</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
command.
</para>
<screen>
$ debc <replaceable>package</replaceable>.changes
</screen>
</section>
<section id="debdiff"><title><command>debdiff</command> command</title>
<para>
You can compare file contents in two source Debian packages with the
<citerefentry> <refentrytitle>debdiff</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> command.
</para>
<screen>
$ debdiff <replaceable>old-package</replaceable>.dsc <replaceable>new-package</replaceable>.dsc
</screen>
<para>
You can also compare file lists in two sets of binary Debian packages with the
<citerefentry> <refentrytitle>debdiff</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> command.
</para>
<screen>
$ debdiff <replaceable>old-package</replaceable>.changes <replaceable>new-package</replaceable>.changes
</screen>
<para>
These are useful to identify what has been changed in the source packages, if
no files have been unintentionally misplaced or removed in the binary packages,
and if no other inadvertent changes were made when updating binary packages.
</para>
</section>
<section id="interdiff"><title><command>interdiff</command> command</title>
<para>
You can compare two <filename>diff.gz</filename> files with the <citerefentry>
<refentrytitle>interdiff</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> command.  This is useful for verifying that no inadvertent
changes were made to the source by the maintainer when updating packages in the
old <literal>1.0</literal> source format.
</para>
<screen>
$ interdiff -z <replaceable>old-package</replaceable>.diff.gz <replaceable>new-package</replaceable>.diff.gz
</screen>
<para>
The new <literal>3.0</literal> source format stores changes in multiple patch
files as described in <xref linkend="patches"/>.  You can trace changes of each
<filename>debian/patches/*</filename> file using <command>interdiff</command>, too.
</para>
</section>
<section id="mc"><title><command>mc</command> command</title>
<para>
Many of these file inspection operations can be made into an intuitive process
by using a file manager like <citerefentry> <refentrytitle>mc</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> which will let you browse not only the
contents of <filename>*.deb</filename> package files but also
<filename>*.udeb</filename>, <filename>*.debian.tar.gz</filename>,
<filename>*.diff.gz</filename>, and <filename>*.orig.tar.gz</filename> files.
</para>
<para>
Be on the lookout for extra unneeded files or zero length files, both in the
binary and source package.  Often cruft doesn't get cleaned up properly; adjust
your <filename>rules</filename> file to compensate for that.
</para>
</section>
</chapter>
<chapter id="upload"><title>Uploading the package</title>
<para>
Now that you have tested your new package thoroughly, you want to release it to
a public archive to share it.
</para>
<section id="upload-debian"><title>Uploading to the Debian archive</title>
<para>
Once you become an official developer,
<footnote><para>
See <xref linkend="socialdynamism"/>.
</para></footnote>
you can upload the package to the Debian archive.
<footnote><para>
There are publicly accessible archives such as <ulink url="&mentors-dn;"/>
which work almost the same way as Debian archive and provide upload area for
the non-DD.  You can set up an equivalent archive by yourself using tools
listed at <ulink url="&deb-archive;"/>.  So this section is useful for the
non-DD, too.
</para></footnote>
You can do this manually, but it's easier to use the existing
automated tools, like <citerefentry> <refentrytitle>dupload</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> or <citerefentry>
<refentrytitle>dput</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.
We'll describe how it's done with <command>dupload</command>.  <footnote><para>
The <systemitem role="package">dput</systemitem> package seems to come with
more features and becoming more popular than the <systemitem role="package">dupload</systemitem> package.  It uses the
<filename>/etc/dput</filename> file for the global configuration and the
<filename>~/.dput.cf</filename> file for the per-user one.  It supports Ubuntu
related services out-of-box, too.  </para> </footnote>
</para>
<para>
First you have to set up <command>dupload</command>'s config file.  You can
either edit the system-wide <filename>/etc/dupload.conf</filename> file, or
have your own <filename>~/.dupload.conf</filename> file override the few things
you want to change.
</para>
<para>
You can read the <citerefentry> <refentrytitle>dupload.conf</refentrytitle>
<manvolnum>5</manvolnum> </citerefentry> manual page to understand what each of
these options means.
</para>
<para>
The <literal>$default_host</literal> option determines which of the upload
queues will be used by default.  <literal>anonymous-ftp-master</literal> is the
primary one, but it's possible that you will want to use another one.
<footnote><para>See <ulink url="&devref-upload;">Debian Developer's Reference 5.6. 'Uploading a package'</ulink>.</para></footnote>
</para>
<para>
While connected to the Internet, you can upload your package by the following:
</para>
<screen>
$ dupload gentoo_0.9.12-1_i386.changes
</screen>
<para>
<command>dupload</command> checks that the MD5/SHA1/SHA256 checksums of the
files match those from the <filename>.changes</filename> file.  If they do not
match, it will warn you to rebuild it as described in <xref linkend="completebuild"/> so it can be properly uploaded.
</para>
<!--
 No more use of ftp-master nor faster queue.  It is not so
useful these days.  If you upload to ftp-master, <command>dupload</command>
will ask for your password on Debian machines, and then upload the packages.
-->
<para>
If you encounter an upload problem at <ulink url="&uploadqueue;"/>, you can fix this
by manually uploading GPG signed <filename>*.commands</filename> file to there
with <command>ftp</command>.  <footnote><para> See <ulink url="&uploadqueue-readme;"/>.  Alternatively, you may
use <command>dcut</command> command from the <systemitem role="package">dput</systemitem> package.  </para> </footnote> For example, use
<filename>hello.commands</filename>:
</para>
<screen>
-----BEGIN PGP SIGNED MESSAGE-----
Uploader: Foo Bar &lt;Foo.Bar@example.org&gt;
Commands: 
 rm hello_1.0-1_i386.deb
 mv hello_1.0-1.dsx hello_1.0-1.dsc
-----BEGIN PGP SIGNATURE-----
Version: 2.6.3ia
iQCVAwUBNFiQSXVhJ0HiWnvJAQG58AP+IDJVeSWmDvzMUphScg1EK0mvChgnuD7h
BRiVQubXkB2DphLJW5UUSRnjw1iuFcYwH/lFpNpl7XP95LkLX3iFza9qItw4k2/q
tvylZkmIA9jxCyv/YB6zZCbHmbvUnL473eLRoxlnYZd3JFaCZMJ86B0Ph4GFNPAf
Z4jxNrgh7Bc=
=pH94
-----END PGP SIGNATURE-----
</screen>
</section>
<section id="skipped-uploads"><title>Skipped uploads</title>
<para>
If you created multiple entries in <filename>debian/changelog</filename> by
skipping uploads, you must create a proper <filename>*_.changes</filename> file
which includes all changes from the last upload.
</para>
<para>
This can be done by specifying <literal>-v</literal> option to the package
building programs such as <command>dpkg-buildpackage</command>,
<command>debuild</command>, <command>pdebuild</command>, etc.
</para>
</section>
</chapter>
<chapter id="update"><title>Updating the package</title>
<para>
Once you release a package, you need to update it soon.
</para>
<section id="newrevision"><title>New Debian revision</title>
<para>
Let's say that a bug report was filed against your package as
<literal>#54321</literal>, and it describes a problem that you can solve.  To
create a new Debian revision of the package, you need to:
</para>
<itemizedlist>
<listitem>
<para>
If this is to be recorded as a new patch, do the following.
</para>
<itemizedlist>
<listitem>
<para>
<literal>dquilt new <replaceable>bugname.patch</replaceable></literal> to set
patch name;
</para>
</listitem>
<listitem>
<para>
<literal>dquilt add <replaceable>buggy-file</replaceable></literal> to declare
file to be modified;
</para>
</listitem>
<listitem>
<para>
Correct the problem in the package source for the upstream bug;
</para>
</listitem>
<listitem>
<para>
<literal>dquilt refresh</literal> to record to
<filename><replaceable>bugname.patch</replaceable></filename>;
</para>
</listitem>
<listitem>
<para>
<literal>dquilt header -e</literal> to add its description;
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
If this is to update an existing patch, do the following.
</para>
<itemizedlist>
<listitem>
<para>
<literal>dquilt pop <replaceable>foo.patch</replaceable></literal> to recall
existing <filename><replaceable>foo.patch</replaceable></filename>;
</para>
</listitem>
<listitem>
<para>
Correct the problem in the old
<filename><replaceable>foo.patch</replaceable></filename>;
</para>
</listitem>
<listitem>
<para>
<literal>dquilt refresh</literal> to update
<filename><replaceable>foo.patch</replaceable></filename>;
</para>
</listitem>
<listitem>
<para>
<literal>dquilt header -e</literal> to update its description;
</para>
</listitem>
<listitem>
<para>
<literal>while dquilt push; do dquilt refresh; done</literal> to apply all
patches while removing <emphasis>fuzz</emphasis>;
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Add a new revision at the top of the Debian <filename>changelog</filename>
file, for example with <literal>dch -i</literal>, or explicitly with
<literal>dch -v
<replaceable>version</replaceable>-<replaceable>revision</replaceable></literal>
and then insert the comments using your preferred editor.  <footnote><para> To
get the date in the required format, use <literal>LANG=C date -R</literal>.
</para> </footnote>
</para>
</listitem>
<listitem>
<para>
Include a short description of the bug and the solution in the changelog entry,
followed by <literal>Closes: #54321</literal>.  That way, the bug report will
be <emphasis>automagically</emphasis> closed by the archive maintenance
software the moment your package gets accepted in the Debian archive.
</para>
</listitem>
<listitem>
<para>
Repeat what you did in the above to fix more bugs while updating the Debian
<filename>changelog</filename> file with <literal>dch</literal> as needed.
</para>
</listitem>
<listitem>
<para>
Repeat what you did in <xref linkend="completebuild"/>, <xref linkend="checkit"/>, and <xref linkend="upload"/>.  The difference is that
this time, the original source archive won't be included, as it hasn't been
changed and it already exists in the Debian archive.
</para>
</listitem>
</itemizedlist>
</section>
<section id="inspectnewupstream"><title>Inspection of the new upstream release</title>
<para>
When preparing packages of the new upstream release for the Debian archive, you
must check the new upstream release, first.
</para>
<para>
You start this by reading the upstream <filename>changelog</filename>,
<filename>NEWS</filename>, and whatever other documentations they may have
released with the new version.
</para>
<para>
You then inspect changes between the old and new upstream sources as follow to
watch out for anything suspicious.
</para>
<screen>
$ diff -urN <replaceable>foo</replaceable>-<replaceable>oldversion</replaceable> <replaceable>foo</replaceable>-<replaceable>newversion</replaceable>
</screen>
<para>
Changes to some auto-generated files by Autotools such as
<filename>missing</filename>, <filename>aclocal.m4</filename>,
<filename>config.guess</filename>, <filename>config.h.in</filename>,
<filename>config.sub</filename>, <filename>configure</filename>,
<filename>depcomp</filename>, <filename>install-sh</filename>,
<filename>ltmain.sh</filename>, and <filename>Makefile.in</filename> may be
ignored.  You may erase them before running <command>diff</command> to the
source for inspection.
</para>
</section>
<section id="newupstream"><title>New upstream release</title>
<para>
If a package <systemitem role="package"><replaceable>foo</replaceable></systemitem> is properly packaged
in the newer <literal>3.0 (native)</literal> or <literal>3.0 (quilt)</literal>
formats, packaging a new upstream version is essentially moving the old
<filename>debian</filename> directory to the new source.  This can be done by
running <literal>tar xvzf
/<replaceable>path</replaceable>/<replaceable>to</replaceable>/<replaceable>foo</replaceable>_<replaceable>oldversion</replaceable>.debian.tar.gz</literal>
in the new extracted source.  <footnote><para> If a package <systemitem role="package"><replaceable>foo</replaceable></systemitem> is packaged in the
old <literal>1.0</literal> format, this can be done by running <literal>zcat
/<replaceable>path</replaceable>/<replaceable>to</replaceable>/<replaceable>foo</replaceable>_<replaceable>oldversion</replaceable>.diff.gz|patch
-p1</literal> in the new extracted source, instead.  </para> </footnote> Of
course, you need to do few obvious chores.
</para>
<itemizedlist>
<listitem>
<para>
Create a copy of upstream source as the
<filename>foo_<replaceable>newversion</replaceable>.tar.gz</filename> file.
</para>
</listitem>
<listitem>
<para>
Update the Debian <filename>changelog</filename> file with <literal>dch -v
<replaceable>newversion</replaceable>-<replaceable>1</replaceable></literal>.
</para>
<itemizedlist>
<listitem>
<para>
Add an entry with <literal>New upstream release</literal>.
</para>
</listitem>
<listitem>
<para>
Describe concisely the changes <emphasis>in the new upstream release</emphasis>
that fix reported bugs and close those bugs by adding <literal>Closes: #<replaceable>bug_number</replaceable></literal>.
</para>
</listitem>
<listitem>
<para>
Describe concisely the changes <emphasis>to the new upstream release</emphasis>
by the maintainer that fix reported bugs and close those bugs by adding <literal>Closes: #<replaceable>bug_number</replaceable></literal>.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
<literal>while dquilt push; do dquilt refresh; done</literal> to apply all
patches while removing <emphasis>fuzz</emphasis>.
</para>
</listitem>
</itemizedlist>
<para>
If the patch/merge did not apply cleanly, inspect the situation (clues are left
in <filename>.rej</filename> files).
</para>
<itemizedlist>
<listitem>
<para>
If a patch you applied to the source was integrated to the upstream source,
</para>
<itemizedlist>
<listitem>
<para>
<literal>dquilt delete</literal> to remove it.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
If a patch you applied to the source conflicted with new changes in the
upstream source,
</para>
<itemizedlist>
<listitem>
<para>
<literal>dquilt push -f</literal> to apply old patches while forcing rejects as
<filename><replaceable>baz</replaceable>.rej</filename>.
</para>
</listitem>
<listitem>
<para>
Edit the <filename><replaceable>baz</replaceable></filename> file manually to
realize intended effect of
<filename><replaceable>baz</replaceable>.rej</filename>.
</para>
</listitem>
<listitem>
<para>
<literal>dquilt refresh</literal> to update the patch.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Continue back to <literal>while dquilt push; do dquilt refresh; done</literal>.
</para>
</listitem>
</itemizedlist>
<para>
This process can be automated using the <citerefentry>
<refentrytitle>uupdate</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
command as follows:
</para>
<screen>
$ apt-get source <replaceable>foo</replaceable>
...
dpkg-source: info: extracting <replaceable>foo</replaceable> in <replaceable>foo</replaceable>-<replaceable>oldversion</replaceable>
dpkg-source: info: unpacking <replaceable>foo</replaceable>_<replaceable>oldversion</replaceable>.orig.tar.gz
dpkg-source: info: applying <replaceable>foo</replaceable>_<replaceable>oldversion</replaceable>-1.debian.tar.gz
$ ls -F
<replaceable>foo</replaceable>-<replaceable>oldversion</replaceable>/
<replaceable>foo</replaceable>_<replaceable>oldversion</replaceable>-1.debian.tar.gz
<replaceable>foo</replaceable>_<replaceable>oldversion</replaceable>-1.dsc
<replaceable>foo</replaceable>_<replaceable>oldversion</replaceable>.orig.tar.gz
$ wget http://example.org/<replaceable>foo</replaceable>/<replaceable>foo</replaceable>-<replaceable>newversion</replaceable>.tar.gz
$ cd <replaceable>foo</replaceable>-<replaceable>oldversion</replaceable>
$ uupdate -v <replaceable>newversion</replaceable> ../<replaceable>foo</replaceable>-<replaceable>newversion</replaceable>.tar.gz
$ cd ../<replaceable>foo</replaceable>-<replaceable>newversion</replaceable>
$ while dquilt push; do dquilt refresh; done
$ dch
... document changes made
</screen>
<para>
If you set up a <filename>debian/watch</filename> file as described in <xref linkend="watch"/>, you can skip the <command>wget</command> command.  You
simply run <citerefentry> <refentrytitle>uscan</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> in the
<filename><replaceable>foo</replaceable>-<replaceable>oldversion</replaceable></filename>
directory instead of the <command>uupdate</command> command.  This will
<emphasis>automagically</emphasis> look for the updated source, download it,
and run the <command>uupdate</command> command.  <footnote><para> If the
<command>uscan</command> command downloads the updated source but it does not
run the <command>uupdate</command> command, you should correct the
<filename>debian/watch</filename> file to have <literal>debian
uupdate</literal> at the end of the URL.  </para> </footnote>
</para>
<para>
You can release this updated source by repeating what you did in <xref linkend="completebuild"/>, <xref linkend="checkit"/>, and <xref linkend="upload"/>.
</para>
</section>
<section id="packagestyle"><title>Updating the packaging style</title>
<para>
Updating the package style is not a required activity for the update of a
package.  But, you can use the full capability of the modern <systemitem role="package">debhelper</systemitem> system and the <literal>3.0</literal>
source format by doing this.  <footnote><para> If your sponsor or other
maintainers object to updating the existing packaging style, it is not worth
bothering nor arguing.  There are more important things to do.  </para>
</footnote>
</para>
<itemizedlist>
<listitem>
<para>
If you need to add erased template files for any reason, you may run
<command>dh_make</command> again in the same Debian package source tree with
<literal>--addmissing</literal> option.  Then edit them properly.
</para>
</listitem>
<listitem>
<para>
If the package has not updated to use the <systemitem role="package">debhelper</systemitem> V7 <command>dh</command> syntax for the
<filename>debian/rules</filename> file, update it to use <command>dh</command>.
Update the <filename>debian/control</filename> file accordingly.
</para>
</listitem>
<listitem>
<para>
If you want to update the <filename>rules</filename> file created with the
<filename>Makefile</filename> inclusion mechanism of the Common Debian Build
System (<systemitem role="package">cdbs</systemitem>) to the
<command>dh</command> syntax, see
<ulink url="&cdbs-doc;">cdbs-doc.pdf.gz</ulink> and understand its
<literal>DEB_*</literal> configuration variables.  <footnote><para> In the
<systemitem role="package">cdbs</systemitem> (0.4.74) package, there are some
negative descriptions of the <filename>rules</filename> file created by the
<command>dh_make</command> command for the non-<systemitem role="package">cdbs</systemitem> choices.  Do not worry about it.  It applies
only for <literal>lenny</literal> which created explicit targets with long list
of <command>dh_*</command> commands.  </para> </footnote>
</para>
</listitem>
<listitem>
<para>
If you have a <literal>1.0</literal> source package without the
<filename><replaceable>foo</replaceable>.diff.gz</filename> file, you can
update it to the newer <literal>3.0 (native)</literal> source format by
creating <filename>debian/source/format</filename> with <literal>3.0
(native)</literal>.  The rest of <filename>debian/*</filename> files can be
just copied.
</para>
</listitem>
<listitem>
<para>
If you have a <literal>1.0</literal> source package with the
<filename><replaceable>foo</replaceable>.diff.gz</filename> file, you can
update it to the newer <literal>3.0 (quilt)</literal> source format by creating
<filename>debian/source/format</filename> with <literal>3.0 (quilt)</literal>.
The rest of <filename>debian/*</filename> files can be just copied.  Import the
<filename>big.diff</filename> file generated by the <literal>filterdiff -z -x
'*/debian/*' <replaceable>foo</replaceable>.diff.gz &gt; big.diff</literal>
command to your <command>quilt</command> system, if needed.  <footnote><para>
You may split <filename>big.diff</filename> into many small incremental patches
using the <command>splitdiff</command> command.  </para> </footnote>
</para>
</listitem>
<listitem>
<para>
If it was packaged with another patch system such as <systemitem role="package">dpatch</systemitem>, <systemitem role="package">dbs</systemitem>, or <systemitem role="package">cdbs</systemitem> with <literal>-p0</literal>,
<literal>-p1</literal>, or <literal>-p2</literal>, convert it to the
<systemitem role="package">quilt</systemitem> command using
<filename>deb3</filename> at <ulink url="&deb3;"/>.
</para>
</listitem>
<listitem>
<para>
If it was packaged with the <command>dh</command> command with the
<literal>--with quilt</literal> option or with the
<command>dh_quilt_patch</command> and <command>dh_quilt_unpatch</command>
commands, remove such things and make it use the newer <literal>3.0
(native)</literal> source format.
</para>
</listitem>
</itemizedlist>
<para>
You need to do other tasks described in <xref linkend="newupstream"/>, too.
</para>
</section>
<section id="reminders"><title>Reminders for updating packages</title>
<para>
Here are few reminders for updating packages.
</para>
<itemizedlist>
<listitem>
<para>
Preserve old <filename>changelog</filename> entries (sounds obvious, but there
have been incidents to type <literal>dch</literal> when you should have typed
<literal>dch -i</literal>.)
</para>
</listitem>
<listitem>
<para>
Existing Debian changes need to be reevaluated; throw away stuff that upstream
has incorporated (in one form or another) and remember to keep stuff that
hasn't been incorporated by upstream, unless there is a compelling reason not
to.
</para>
</listitem>
<listitem>
<para>
If any changes were made to the build system (hopefully you'd know from
inspecting upstream changes) then update the <filename>debian/rules</filename>
and <filename>debian/control</filename> build dependencies if necessary.
</para>
</listitem>
<listitem>
<para>
Check to see <ulink url="&bts;">Debian Bug Tracking
System (BTS)</ulink> if someone have provided patches to bugs that are
currently open in it.
</para>
</listitem>
<listitem>
<para>
Check the contents of the <filename>.changes</filename> file to make sure you
are uploading to the correct distribution, the proper bugs closures are listed
in the <literal>Closes</literal> field, the <literal>Maintainer</literal> and
<literal>Changed-By</literal> fields match, the file is GPG-signed, etc.
</para>
</listitem>
</itemizedlist>
</section>
</chapter>
</book>