<chapter id="first"><title>First steps</title>
<para>
The rewrite of this tutorial document with updated contents and more practical examples is available as <ulink url="&guidedeb;">Guide for Debian Maintainers</ulink>.  Please use this new tutorial as the primary tutorial document.
</para>
<para>
Let's start by creating a package of your own (or, even better,
adopting an existing one).
</para>
<section id="workflow"><title>Debian package building workflow</title>
<para>
If you are making a Debian package with an upstream program, the
typical workflow of Debian package building involves generating several
specifically named files for each step as follows:
</para>
<itemizedlist>
<listitem>
<para>Get a copy of the upstream software, usually in a compressed tar format.</para>
<itemizedlist>
<listitem><literal><replaceable>package</replaceable>-<replaceable>version</replaceable>.tar.gz</literal></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Add Debian-specific packaging modifications to the upstream program under the
<filename>debian</filename> directory, and create a non-native source package
(that is, the set of input files used for Debian package building) in
<literal>3.0 (quilt)</literal> format.
</para>
<itemizedlist>
<listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.orig.tar.gz</literal></listitem>
<listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.debian.tar.gz</literal>
<footnote><para>For the older style of non-native Debian source packages in <literal>1.0</literal> format,
<literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.diff.gz</literal>
is used instead. </para></footnote></listitem>
<listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.dsc</literal></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
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>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
Please note that the character separating
<literal><replaceable>package</replaceable></literal> and
<literal><replaceable>version</replaceable></literal> was changed from
<literal>-</literal> (hyphen) in the tarball name to
<literal>_</literal> (underscore) in the Debian package filenames.
</para>
<para>
In the file names above, replace
the <literal><replaceable>package</replaceable></literal> part with the <emphasis role="strong">package name</emphasis>,
the <literal><replaceable>version</replaceable></literal> part with the <emphasis role="strong">upstream version</emphasis>,
the <literal><replaceable>revision</replaceable></literal> part with the <emphasis role="strong">Debian revision</emphasis>,
and the <literal><replaceable>arch</replaceable></literal> part with the <emphasis role="strong">package architecture</emphasis>,
as defined in the Debian Policy Manual.
<footnote> <para> See
<ulink url="&policy-source;">5.6.1 "Source"</ulink>, 
<ulink url="&policy-package;">5.6.7 "Package"</ulink>, and
<ulink url="&policy-version;">5.6.12 "Version"</ulink>.  
The <emphasis role="strong">package architecture</emphasis> follows the
<ulink url="&policy-architecture;">Debian Policy Manual, 5.6.8 "Architecture"</ulink> 
and is automatically assigned by the package build process.</para></footnote>
</para>
<para>
Each step of this outline is explained with detailed examples in later sections.
</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="&debtrack;">Debian Package Tracker</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>The <command>wnpp-alert</command> command from the <systemitem role="package">devscripts</systemitem> package</para>
</listitem>
<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 to 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 &#x2014; 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>
<listitem>
<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>
</itemizedlist>
</listitem>
<listitem>
<para>
The program should <emphasis role="strong">not</emphasis> introduce security
and maintenance concerns into the Debian system.
</para>
<itemizedlist>
<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>
<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>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
Of course, the last one is just a safety measure, and is intended to save you from
enraging users if you do something wrong in some setuid daemon&#x2026;  When you gain
more experience in packaging, you'll be able to package such software.
</para>
<para>
As a new maintainer, you are encouraged to get some experience in packaging
with easier packages and discouraged from creating complicated packages.  
</para>
<itemizedlist>
<listitem><para>Simple packages</para>
<itemizedlist>
<listitem><para>single binary package, arch = all (collection of data such as wallpaper graphics)</para></listitem>
<listitem><para>single binary package, arch = all (executables written in an interpreted language such as POSIX shell)</para></listitem>
</itemizedlist>
</listitem>
<listitem><para>Intermediate complexity packages</para>
<itemizedlist>
<listitem><para>single binary package, arch = any (ELF binary executables compiled from languages such as C and C++)</para></listitem>
<listitem><para>multiple binary packages, arch = any + all (packages for ELF binary executables + documentation)</para></listitem>
<listitem><para>upstream source in a format other than <filename>tar.gz</filename> or <filename>tar.bz2</filename></para></listitem>
<listitem><para>upstream source containing undistributable contents</para></listitem>
</itemizedlist>
</listitem>
<listitem><para>High complexity packages</para>
<itemizedlist>
<listitem><para>interpreter module package used by other packages</para></listitem>
<listitem><para>generic ELF library package used by other packages</para></listitem>
<listitem><para>multiple binary packages including an ELF library package</para></listitem>
<listitem><para>source package with multiple upstream sources</para></listitem>
<listitem><para>kernel module packages</para></listitem>
<listitem><para>kernel patch packages</para></listitem>
<listitem><para>any package with non-trivial maintainer scripts</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
Packaging high complexity packages is not too hard, but it requires a bit more
knowledge. You should seek specific guidance for every complex feature. For
example, some languages have their own sub-policy documents:
</para>
<itemizedlist>
<listitem><para><ulink url="&policy-perl;">Perl policy</ulink></para></listitem>
<listitem><para><ulink url="&policy-python;">Python policy</ulink></para></listitem>
<listitem><para><ulink url="&policy-java;">Java policy</ulink></para></listitem>
</itemizedlist>
<para>
There is another old Latin saying: <emphasis>fabricando fit faber</emphasis>
(practice makes perfect).  It is <emphasis>highly</emphasis> recommended to
practice and experiment with all the steps of Debian packaging with simple packages
while reading this tutorial.  A trivial upstream tarball,
<filename>hello-sh-1.0.tar.gz</filename>, created as follows may offer
a good starting point:<footnote><para>Do not worry about the missing
<filename>Makefile</filename>.  You can install the <command>hello</command>
command by simply using <command>debhelper</command> as in
<xref linkend="install"/>, or by modifying the upstream source to add a new
<filename>Makefile</filename> with the <literal>install</literal> target as in
<xref linkend="modify"/>.</para></footnote>
</para>
<screen>
$ mkdir -p hello-sh/hello-sh-1.0; cd hello-sh/hello-sh-1.0
$ cat &gt; hello &lt;&lt;EOF
#!/bin/sh
# (C) 2011 Foo Bar, GPL2+
echo "Hello!"
EOF
$ chmod 755 hello
$ cd ..
$ tar -cvzf hello-sh-1.0.tar.gz hello-sh-1.0
</screen>
</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>,
<command>tar</command>+<command>bzip2</command> format with the extension
<filename>.tar.bz2</filename>, or
<command>tar</command>+<command>xz</command> format with the extension
<filename>.tar.xz</filename>.  These usually contain a directory called
<filename><replaceable>package</replaceable>-<replaceable>version</replaceable></filename>
with all the sources inside.
</para>
<para>
If the latest version of the source is available through a Version Control System
(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>
If your program's source comes with some contents which do not comply with
DFSG, you should also unpack it to remove such contents and repack it with a
modified upstream version containing <literal>dfsg</literal>.
</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 command line 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>
You should start packaging with a completely clean (pristine) source directory,
or simply with freshly unpacked sources.
</para>
</section>
<section id="simplemake"><title>Simple build systems</title>
<para>
Simple programs usually 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 named <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>Popular portable build systems</title>
<para>
A lot of free software programs are 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 build tools need 
to be used to generate the <filename>Makefile</filename> and other
required source files first.  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>Autotools is too big to deal with in this small tutorial. This
section is meant to provide keywords and references only.  Please make sure to read the 
<ulink url="&autotools-tutorial;">Autotools Tutorial</ulink> and 
the local copy of <filename>&autotools-readme;</filename>, 
if you need to use it.</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 an executable command
<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 <literal>./configure --prefix=/usr</literal>.
</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>
If the upstream source comes as <filename>gentoo-0.9.12.tar.gz</filename>, you can
take <literal>gentoo</literal> as the (source) <emphasis role="strong">package name</emphasis>
and <literal>0.9.12</literal> as the <emphasis role="strong">upstream version</emphasis>.
These are used in the <filename>debian/changelog</filename> file described later in
<xref linkend="changelog"/>, too.
</para>
<para>
Although this simple approach works most of the time, you may need to adjust
<emphasis role="strong">package name</emphasis> and 
<emphasis role="strong">upstream version</emphasis> by renaming the upstream
source to follow Debian Policy and existing convention.
</para>
<para>
You must choose the <emphasis role="strong">package name</emphasis> 
to consist 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>). It must be
at least two characters long, must start with an alphanumeric character, and
must not be the same as existing packages.
It is a good idea to keep its length within 30 characters.
<footnote><para>The default package name field length of <command>aptitude</command> is 30.  For more than 90% of packages, the package name is less than 24 characters.</para></footnote>
</para>
<!--
Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):
=== stat for package name string length ===
11 1947 36.9%   mode
14 1717 54.7%  50% median
23 611 91.0%   90%
32 89 99.0%    99%
41 12 99.9%    99.9%
52 1 100.0%
Previous 20 chars is becoming too short for 17% of packages
Default aptitude setting display up to 30 chars (98.3%).
-->
<para>
If upstream uses some generic term such as <literal>test-suite</literal> for
its name, it is a good idea to rename it to identify its contents explicitly and avoid namespace pollution.
<footnote><para>If you follow the 
<ulink url="&devref-newpackage;">Debian Developer's Reference 5.1. "New packages"</ulink>, 
the ITP process will usually catch this kind of issue.</para></footnote>
</para>
<para>
You should choose the <emphasis role="strong">upstream version</emphasis> 
to consist only of
alphanumerics (<literal>0-9A-Za-z</literal>), plus signs (<literal>+</literal>),
tildes (<literal>~</literal>), and periods (<literal>.</literal>). It must
start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter
rule should help you avoid confusing file names.</para></footnote>
It is good idea to keep its length within 8 characters if possible.
<footnote><para>The default version field length of <command>aptitude</command> is 10.  The Debian revision with preceding hyphen usually consumes 2.  For more than 80% of packages, the upstream version is less than 8 characters and the Debian revision is less than 2 characters.  For more than 90% of packages, the upstream version is less than 10 characters and the Debian revision is less than 3 characters.</para></footnote>
</para>
<!--
Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):
=== stat for upstream version string length ===
5 9765 60.2%  50% median and mode
6 3765 73.3%
7 2789 82.9%
8 1158 86.9%
9 501 88.6%
10 773 91.3%  90%
18 55 99.1%   99%
27 11 99.9%    99.9
35 6 100.0%
=== stat for debian revision string length ===
1 22556 83.3%  50% median and mode
2 1106 87.2%
3 1312 91.7%   90%
4 2127 99.1%   99%
7 14 99.9%     99.9%

aptitude display 10 = 8char for up + 1char (for -) + 1char for deb
90chars as max for file name of binary debs (package+up+deb+arch+.deb)
-->
<para>
If upstream does not use a normal versioning scheme such as
<literal>2.30.32</literal> but uses some kind of date such as
<literal>11Apr29</literal>, a random codename string, or a VCS hash value as part
of the version, make sure to remove them from the
<emphasis role="strong">upstream version</emphasis>.  Such information can be
recorded in the <filename>debian/changelog</filename> file.  If you need to
invent a version string, use the <literal>YYYYMMDD</literal> format such as
<literal>20110429</literal> as upstream version.  This ensures that
<command>dpkg</command> interprets later versions correctly as upgrades.
If you need to ensure smooth transition to the normal version scheme such as
<literal>0.1</literal> in the future, use the <literal>0~YYMMDD</literal> format
such as <literal>0~110429</literal> as the upstream version.
</para>
<para>
Version strings <footnote><para>Version strings may be
<emphasis role="strong">upstream version</emphasis> 
(<literal><replaceable>version</replaceable></literal>),
<emphasis role="strong">Debian revision</emphasis> 
(<literal><replaceable>revision</replaceable></literal>), or
<emphasis role="strong">version</emphasis> 
(<literal><replaceable>version</replaceable>-<replaceable>revision</replaceable></literal>).
See <xref linkend="newrevision"/> for how the 
<emphasis role="strong">Debian revision</emphasis> is incremented.
</para></footnote>
can be compared using <citerefentry>
<refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry> as follows:
</para>
<screen>
$ dpkg --compare-versions <replaceable>ver1</replaceable> <replaceable>op</replaceable> <replaceable>ver2</replaceable>
</screen>
<para>
The version comparison rule can be summarized as:
</para>
<itemizedlist>
<listitem><para>Strings are compared from the head to the tail.</para></listitem>
<listitem><para>Letters are larger than digits.</para></listitem>
<listitem><para>Numbers are compared as integers.</para></listitem>
<listitem><para>Letters are compared in ASCII code order.</para></listitem>
<listitem><para>There are special rules for period
(<literal>.</literal>), plus (<literal>+</literal>), and tilde
(<literal>~</literal>) characters, as follows:</para>
<para>
<literal>0.0</literal> &lt; 
<literal>0.5</literal> &lt; 
<literal>0.10</literal> &lt; 
<literal>0.99</literal> &lt; 
<literal>1</literal> &lt;
<literal>1.0~rc1</literal> &lt;
<literal>1.0</literal> &lt; 
<literal>1.0+b1</literal> &lt; 
<literal>1.0+nmu1</literal> &lt;
<literal>1.1</literal> &lt; 
<literal>2.0</literal>
</para>
</listitem>
</itemizedlist>
<para>
One tricky case occurs when upstream releases
<filename>gentoo-0.9.12-ReleaseCandidate-99.tar.gz</filename> as the
pre-release of <filename>gentoo-0.9.12.tar.gz</filename>.  You need to make
sure that the upgrade works properly by renaming the upstream source to
<filename>gentoo-0.9.12~rc99.tar.gz</filename>.
</para>
</section>
<section id="dh-make"><title>Setting up <command>dh_make</command></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
$ . ~/.bashrc
</screen>
</section>
<section id="non-native-dh-make"><title>Initial non-native Debian package</title>
<para>
Normal Debian packages are non-native Debian packages made from upstream
programs.  If you wish to create a non-native Debian package of an upstream
source <filename>gentoo-0.9.12.tar.gz</filename>, you can create an initial
non-native Debian package for it by issuing the <command>dh_make</command>
command as follows:
</para>
<screen>
$ cd ~/gentoo
$ wget http://example.org/gentoo-0.9.12.tar.gz
$ tar -xvzf gentoo-0.9.12.tar.gz
$ cd 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 version for your Debian package.  </para> </footnote> See
<citerefentry> <refentrytitle>dh_make</refentrytitle> <manvolnum>8</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 &#x2014; it creates only one binary package, i.e.,
one <filename>.deb</filename> file &#x2014; 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 package, <literal>i</literal> for arch-Independent package, <literal>m</literal> for
Multiple binary packages, <literal>l</literal> for Library package, <literal>k</literal> for
Kernel module package, <literal>n</literal> for kernel patch package, and <literal>b</literal>
for <systemitem role="package">cdbs</systemitem> package.  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>
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>
<para>
Please note that the source file does not need to contain any build system
discussed in <xref linkend="simplemake"/> and <xref linkend="portable"/>.  It
could be just a collection of graphical data, etc.  Installation of files may be
carried out using only <systemitem role="package">debhelper</systemitem> configuration
files such as <filename>debian/install</filename> (see
<xref linkend="install"/>).
</para>
</section>
</chapter>