La documentation de CDBS [La documentation d'AbulÉdu]

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
====== La documentation de CDBS ======

Le site hébergeant la doc ayant disparu ... vous trouverez ci-dessous l'export de la doc au format HTML depuis les sources.

<note>
Voir aussi la doc en ligne archivée sur https://web.archive.org/web/20170331113853/https://cdbs-doc.duckcorp.org/en/cdbs-doc.xhtml qui n'est pas la même que celle qui se trouve ci-dessous !!!!
</note>

<html>

<div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="idm45814503232144"></a>The Common Debian Build System</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Marc</span> <span class="othername">(Duck)</span> <span class="surname">Dequènes</span></h3><div class="affiliation"><span class="orgname">DuckCorp<br /></span></div><code class="email">&lt;<a class="email" href="mailto:duck@duckcorp.org">duck@duckcorp.org</a>&gt;</code></div><div class="author"><h3 class="author"><span class="firstname">Arnaud</span> <span class="othername">(Rtp)</span> <span class="surname">Patard</span></h3><code class="email">&lt;<a class="email" href="mailto:arnaud.patard@rtp-net.org">arnaud.patard@rtp-net.org</a>&gt;</code></div><div class="author"><h3 class="author"><span class="firstname">Peter</span> <span class="surname">Eisentraut</span></h3><code class="email">&lt;<a class="email" href="mailto:petere@debian.org">petere@debian.org</a>&gt;</code></div><div class="author"><h3 class="author"><span class="firstname">Colin</span> <span class="surname">Walters</span></h3><code class="email">&lt;<a class="email" href="mailto:walters@debian.org">walters@debian.org</a>&gt;</code></div></div></div><div><p class="copyright">Copyright © 2007, 2008, 2009 Peter Eisentraut</p></div><div><p class="copyright">Copyright © 2005, 2004 DuckCorp</p></div><div><p class="copyright">Copyright © 2003 Colin Walters</p></div><div><div class="legalnotice"><a id="idm45814503199552"></a><p>Permission is granted to copy, distribute and/or modify
      this document under the terms of the <a class="ulink" href="http://www.gnu.org/licenses/gpl.html" target="_top">GNU General Public
      License</a>, Version 2 or any later version published by the
      Free Software Foundation.</p></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="#idm45814503249040">1. Introduction</a></span></dt><dd><dl><dt><span class="sect1"><a href="#idm45814503245568">Why Does CDBS Exist?</a></span></dt><dt><span class="sect1"><a href="#idm45814503098976">What Makes CDBS Better?</a></span></dt><dt><span class="sect1"><a href="#idm45814498943152">Why Not Just Debhelper?</a></span></dt><dt><span class="sect1"><a href="#idm45814503224880">Summary</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idm45814503214448">2. First Steps</a></span></dt><dd><dl><dt><span class="sect1"><a href="#idm45814503212368">Switching the Package to CDBS</a></span></dt><dt><span class="sect1"><a href="#basic-settings">Basic Settings and Available Variables</a></span></dt><dt><span class="sect1"><a href="#idm45814497777408">Custom Rules</a></span></dt><dt><span class="sect1"><a href="#idm45814497728976">Common Build Options</a></span></dt><dt><span class="sect1"><a href="#idm45814497724992">Debhelper Support</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idm45814497700688">Debhelper Parameters</a></span></dt><dt><span class="sect2"><a href="#idm45814497690224">Debhelper Custom Build Rules</a></span></dt><dt><span class="sect2"><a href="#idm45814497682832">Debug Package Support</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#idm45814497665200">3. Classes</a></span></dt><dd><dl><dt><span class="sect1"><a href="#idm45814497651216">The Makefile Class</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idm45814497635168">Build Problems</a></span></dt><dt><span class="sect2"><a href="#idm45814497630016">The Makefile Class and Single vs. Multiple Binary
        Packages</a></span></dt></dl></dd><dt><span class="sect1"><a href="#idm45814497618384">The Autotools Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497576640">The CMake Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497567504">The Perl Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497557104">The Python Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497546272">The GNOME Class</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idm45814497532784">The Debian GNOME Team Class</a></span></dt></dl></dd><dt><span class="sect1"><a href="#idm45814497522944">The KDE Class</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idm45814497511648">Obsolescent: KDE 3 Support</a></span></dt></dl></dd><dt><span class="sect1"><a href="#idm45814497494736">The Qmake Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497482656">The Ant Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497449552">The HBuild Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497443536">The Waf Class</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idm45814497428832">4. Common Tasks</a></span></dt><dd><dl><dt><span class="sect1"><a href="#idm45814497427696">Patching Sources Using the Simple Patch System</a></span></dt><dt><span class="sect1"><a href="#idm45814497407328">Patching Sources Using Dpatch</a></span></dt><dt><span class="sect1"><a href="#idm45814497397376">Patching Sources Using Quilt</a></span></dt><dt><span class="sect1"><a href="#idm45814497393936">Standard Patch System Targets</a></span></dt><dt><span class="sect1"><a href="#idm45814503314576">Tarball-Inside-a-Tarball Build System</a></span></dt><dt><span class="sect1"><a href="#idm45814497367216"><code class="filename">debian/control</code> Management</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idm45814497341040">5. Hall of Examples</a></span></dt><dd><dl><dt><span class="sect1"><a href="#idm45814497339680">GNOME + Autotools + Simple Patch System Example</a></span></dt><dt><span class="sect1"><a href="#idm45814497333568">Python Example</a></span></dt><dt><span class="sect1"><a href="#idm45814497324416">Makefile + Dpatch example</a></span></dt><dt><span class="sect1"><a href="#idm45814497316624">Perl Examples</a></span></dt><dt><span class="sect1"><a href="#example-ant">Ant Example</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idm45814497381760">6. Conclusion</a></span></dt></dl></div><div class="list-of-figures"><p><strong>List of Figures</strong></p><dl><dt>2.1. <a href="#fig:buildcore">Buildcore targets</a></dt><dt>3.1. <a href="#fig:depgraph">Dependencies between the CDBS class and rule files</a></dt></dl></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="idm45814503249040"></a>Chapter 1. Introduction</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#idm45814503245568">Why Does CDBS Exist?</a></span></dt><dt><span class="sect1"><a href="#idm45814503098976">What Makes CDBS Better?</a></span></dt><dt><span class="sect1"><a href="#idm45814498943152">Why Not Just Debhelper?</a></span></dt><dt><span class="sect1"><a href="#idm45814503224880">Summary</a></span></dt></dl></div><p>CDBS is essentially a set of makefile fragments that you may
    include into your <code class="filename">debian/rules</code> for building
    Debian packages.  Each makefile fragment can have effects in
    different parts of the package build process.</p><p>The motivating factor for CDBS was originally that more and
    more programs today are created using GNU Autoconf configure
    scripts and GNU Automake, and as such they are all very similar to
    configure and build.  It was realized that a lot of duplicated
    code in everyone's <code class="filename">debian/rules</code> could be
    factored out.  But CDBS isn't only useful for packages that use
    the GNU autotools.  It is a flexible core upon which you can
    create your own custom build systems.</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814503245568"></a>Why Does CDBS Exist?</h2></div></div></div><p>The current generally accepted practice for creating new
      Debian packages is to run <span class="command"><strong>dh_make</strong></span>, which
      generates a bunch of files, the most important of which are
      <code class="filename">debian/control</code>,
      <code class="filename">debian/copyright</code>, and
      <code class="filename">debian/rules</code>.  The first two are relatively
      straightforward.  But <code class="filename">debian/rules</code> is not.
      Debhelper was an enormous step forward in this area, greatly
      reducing redundant and incomprehensible code from the Debian
      package creation process.  But it doesn't go far enough; the
      typical <span class="command"><strong>dh_make</strong></span> generated
      <code class="filename">debian/rules</code> is hundreds of lines, only
      some of which apply.  From experience with helping several
      people to learn Debian packaging,
      <code class="filename">debian/rules</code> was by far the hardest part
      for them to understand.</p><p>Moreover, this generated code will become stale with time,
      as the Debian policy changes.  At some time in the past, the
      <code class="varname">DEB_BUILD_OPTIONS</code> variable dropped the
      <code class="literal">debug</code> flag in favor of
      <code class="literal">noopt</code>.  But gradually it was realized that
      since the code to check this variable was duplicated over
      hundreds (if not thousands) of
      <span class="command"><strong>dh_make</strong></span>-generated source packages (and had
      possibly been modified), it would likely be years before most
      packages were updated.  And there are many packages that
      predate <code class="varname">DEB_BUILD_OPTIONS</code> and don't even use
      it at all, when they easily could.</p><p>The Unix and hacker cultures in general have long looked
      down upon generated code, and for good reason.  It is often hard
      to edit, and there is almost always no way to regenerate the
      code but keep your local changes.  Instead of generating code
      (like all the Microsoft tools tend to do), the Unix tradition is
      to create a metalanguage, a compiler, or some other form of
      abstraction.</p><p>CDBS is that abstraction.  It's not the first attempt at
      abstracting the Debian build process; before Debhelper, many
      attempts came along and had only marginal success, if any.  So
      now the question you're asking yourself is probably:</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814503098976"></a>What Makes CDBS Better?</h2></div></div></div><p>First of all, it is not monolithic (as opposed to debstd,
      for instance).  CDBS is quite simply a set of makefile fragments
      that can be included; if you don't want a particular part, you
      just don't include the makefile fragment for it.</p><p>Second, CDBS does not attempt to supplant Debhelper (which
      has generally done an excellent job at the
      <code class="literal">binary</code> stage of Debian package building).
      CDBS can optionally use Debhelper to implement various parts of
      building a Debian package.  This is the recommended mode of
      operation, actually.  But some people may find Debhelper doesn't
      work for them; if that's the case, you just don't include
      <code class="filename">debhelper.mk</code>, and you can do the work
      yourself.</p><p>Third, CDBS tries to make the common case easy.  If you
      have a package that uses the GNU autotools and such, you can
      have a working build system simply by including about two or
      three makefile fragments.  No custom code required at all.
      Additionally, CDBS has even higher-level makefile fragments; for
      example, there are <code class="filename">gnome.mk</code> and
      <code class="filename">kde.mk</code> rule files which handle a number of
      common things required by GNOME and KDE packages.</p><p>Finally, CDBS (along with Debhelper) should make it much
      easier to effect systemwide changes.  For example, if we later
      decide to switch our default <code class="literal">i386</code>
      architecture to <code class="literal">i486</code> (as we probably will),
      all we have to do is change <code class="filename">autotools.mk</code>,
      and the correct <code class="option">--host</code> and
      <code class="option">--build</code> will be passed to all
      <code class="literal">./configure</code> invocations.  Currently
      <span class="emphasis"><em>some</em></span> packages have the
      <code class="varname">DEB_HOST_ARCH</code> boilerplate code in their
      <code class="filename">debian/rules</code>, but many don't.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814498943152"></a>Why Not Just Debhelper?</h2></div></div></div><p>Some things done in CDBS could just as well go into a
      <span class="command"><strong>dh_foo</strong></span> program (for example, some of
      <code class="filename">autotools.mk</code>).  Likewise, some
      <span class="command"><strong>dh_foo</strong></span> programs would probably do better as
      CDBS makefile fragments (<span class="command"><strong>dh_pysupport</strong></span> and
      <span class="command"><strong>dh_pycentral</strong></span> comes to mind).</p><p>But CDBS' makefile fragment orientation allows it to do
      things that Debhelper can't, or can't easily do.  For example,
      CDBS automatically generates a ton of makefile rules
      corresponding to package building.  This saves a great deal of
      redundant code in <code class="filename">debian/rules</code>.</p><p>CDBS automatically creates <code class="literal">build-arch</code>
      and <code class="literal">build-indep</code> targets, and builds
      architecture-dependent and -independent packages under them.  It
      also can cleanly affect a number of different parts of the build
      system (e.g., <code class="literal">clean</code>,
      <code class="literal">configure</code>, <code class="literal">build</code>) by
      simply including one makefile fragment; doing this as a
      <span class="command"><strong>dh_foo</strong></span> would require inserting a call like
      <code class="literal">dh_foo --clean</code>, <code class="literal">dh_foo
      --configure</code> at each step.  And doing things this way
      wouldn't allow future expansion; you'd have to change your code
      to say <code class="literal">dh_foo --build</code> if the foo helper
      wanted to modify the build process, too.</p><p>So CDBS complements Debhelper (or it can; again, CDBS does
      not require Debhelper).</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814503224880"></a>Summary</h2></div></div></div><p>In summary, we believe CDBS (typically combined with
      Debhelper) is the future of Debian packaging.  By reducing the
      complexity in each package, we make sweeping changes much
      easier.  Debian has made several major transitions in the past,
      and will in the future.  It shouldn't be as painful as it has
      been.  Moreover, CDBS makes creating simple packages very easy,
      as it should be.</p><p>CDBS advantages:

        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>short and readable <code class="filename">debian/rules</code></p></li><li class="listitem"><p>automates Debhelper and autotools for you so you
            don't have to bother with these repetitive tasks</p></li><li class="listitem"><p>maintainer can focus on real packaging problems
            because CDBS helps you but does not limit
            customization</p></li><li class="listitem"><p>rules used in CDBS have been well tested</p></li><li class="listitem"><p>switching to CDBS is easy</p></li><li class="listitem"><p>can be used to generate debian files (like
            <code class="filename">debian/control</code> for GNOME Team Uploaders
            inclusion)</p></li><li class="listitem"><p>CDBS is easily extensible</p></li><li class="listitem"><p>It |70&gt;&lt; !!!</p></li></ul></div><p>
      </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="idm45814503214448"></a>Chapter 2. First Steps</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#idm45814503212368">Switching the Package to CDBS</a></span></dt><dt><span class="sect1"><a href="#basic-settings">Basic Settings and Available Variables</a></span></dt><dt><span class="sect1"><a href="#idm45814497777408">Custom Rules</a></span></dt><dt><span class="sect1"><a href="#idm45814497728976">Common Build Options</a></span></dt><dt><span class="sect1"><a href="#idm45814497724992">Debhelper Support</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idm45814497700688">Debhelper Parameters</a></span></dt><dt><span class="sect2"><a href="#idm45814497690224">Debhelper Custom Build Rules</a></span></dt><dt><span class="sect2"><a href="#idm45814497682832">Debug Package Support</a></span></dt></dl></dd></dl></div><p>The best documentation for CDBS are the makefile fragments
    under <code class="filename">/usr/share/cdbs/1/</code>.  The following will
    tell you how to get started with CDBS and explain what is
    possible, but since you can pretty much override or customize
    anything in CDBS, you will sooner or later want to look at the
    code itself.</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814503212368"></a>Switching the Package to CDBS</h2></div></div></div><p>Switching to CDBS is easy.  A simple
      <code class="filename">debian/rules</code> for an autotools-using C or
      C++ software with no extra rules would be written as this:

</p><pre class="programlisting">
#!/usr/bin/make -f

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/autotools.mk
</pre><p>
      </p><p>Yes, really.  This is sufficient, and it handles autotools
      management, like updating <code class="filename">config.guess</code> and
      <code class="filename">config.sub</code>, cleaning up temporary files
      after the build, and running all common debhelper
      commands.</p><p>Create your
      <code class="filename"><em class="replaceable"><code>package</code></em>.install</code>,
      <code class="filename"><em class="replaceable"><code>package</code></em>.info</code>,
      etc. as you usually do with <span class="command"><strong>dh_*</strong></span> commands,
      and CDBS will call them if necessary, autodetecting a lot of
      things.  In case of missing Debhelper compatibility information, CDBS
      will create a <code class="filename">debian/compat</code> file with
      compatibility level 5.</p><p>Incidentally, you should usually include
      <code class="filename">debhelper.mk</code> first, before other files.
      This will turn on optional Debhelper-using parts of other rules
      files, if any, which is usually what you want.</p><p>Naturally, if you switch a package to use CDBS, you must
      add a build dependency on <code class="literal">cdbs</code> to your
      package.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Versioning note</h3><p>CDBS might change incompatibly in the future, and to
        allow for this, all the rules and classes are in a
        version-specific subdirectory.  That's the reason for the
        <code class="literal">1</code> in
        <code class="filename">/usr/share/cdbs/1</code>.</p></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>CDBS does not work if the name of the current directory
        contains spaces or some other special characters such as
        quotation marks.  This situation is very hard to handle in
        <span class="command"><strong>make</strong></span>, so it is best to stick to
        <span class="quote">“<span class="quote">sane</span>”</span> directory names.</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="basic-settings"></a>Basic Settings and Available Variables</h2></div></div></div><p>Every CDBS-using <code class="filename">debian/rules</code> should
      eventually include
      <code class="filename">/usr/share/cdbs/1/rules/buildcore.mk</code>.  (It
      might be included automatically via dependencies, as we will see
      later.)  This makefile fragment sets up all of the core default
      makefile structure and variables, but doesn't actually
      <span class="emphasis"><em>do</em></span> anything on its own.</p><p>You can use the <code class="filename">buildcore.mk</code> rules to
      hook in your own build system to actually implement each stage
      of compiling, installing, and building
      <code class="filename">.deb</code>s if you wish, but typically you will
      use the rules and classes that CDBS has prepared for you.</p><p>You can change common build parameters this way:
</p><pre class="programlisting">
# where sources are
DEB_SRCDIR = src

# in which directory to build
DEB_BUILDDIR = $(DEB_SRCDIR)/build
</pre><p>
      Remember that you can get the package directory using the
      <code class="varname">CURDIR</code> variable.</p><p>Note that the variables should be set
      <span class="emphasis"><em>after</em></span> the rule fragments are included.
      This is necessary for them to have any effect.  There are a few
      exceptions to this; but generally variables should be set after
      rule fragments are included.</p><p>
        Some of the variables you can use in
        <code class="filename">debian/rules</code>:

        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">DEB_SOURCE_PACKAGE</code></span></dt><dd><p>name of the source package</p></dd><dt><span class="term"><code class="varname">DEB_VERSION</code></span></dt><dd><p>full Debian version</p></dd><dt><span class="term"><code class="varname">DEB_NOEPOCH_VERSION</code></span></dt><dd><p>Debian version without epoch</p></dd><dt><span class="term"><code class="varname">DEB_ISNATIVE</code></span></dt><dd><p>nonemtpy if the package is native</p></dd><dt><span class="term"><code class="varname">DEB_ALL_PACKAGES</code></span></dt><dd><p>list of all binary packages</p></dd><dt><span class="term"><code class="varname">DEB_INDEP_PACKAGES</code></span></dt><dd><p>list of architecture-independent binary packages</p></dd><dt><span class="term"><code class="varname">DEB_ARCH_PACKAGES</code></span></dt><dd><p>list of architecture-dependent binary packages</p></dd><dt><span class="term"><code class="varname">DEB_PACKAGES</code></span></dt><dd><p>list of normal (non-udeb) binary packages</p></dd><dt><span class="term"><code class="varname">DEB_UDEB_PACKAGES</code></span></dt><dd><p>list of udeb binary packages, if any</p></dd><dt><span class="term"><code class="varname">DEB_ARCH</code></span></dt><dd><p>the old Debian architecture name
            (deprecated, only use to provide backward compatibility;
            see <span class="command"><strong>dpkg-architecture</strong></span> man page for more
            information)</p></dd><dt><span class="term"><code class="varname">DEB_HOST_ARCH_CPU</code></span></dt><dd><p>the CPU part of the Debian architecture (e.g., <code class="literal">powerpc</code>)</p></dd><dt><span class="term"><code class="varname">DEB_HOST_ARCH_OS</code></span></dt><dd><p>the operating system part of the Debian architecture (e.g., <code class="literal">linux</code>)</p></dd><dt><span class="term"><code class="varname">DEB_DESTDIR</code></span></dt><dd><p>The directory in which to install the
            package.  This is automatically set to
            <code class="filename">$(CURDIR)/debian/<em class="replaceable"><code>packagename</code></em></code>
            if there is one package and
            <code class="filename">$(CURDIR)/debian/tmp</code> if there are
            multiple packages.  In the latter case you would usually
            use <code class="filename">.install</code> files to install the
            package files into the final directories.  In some
            exceptional cases, you may need to set
            <code class="varname">DEB_DESTDIR</code> yourself.  One case is when
            some packages are only built on some architectures, which
            could make CDBS set the variable inconsistently across
            architectures, which in turn would create problems with
            the <code class="filename">.install</code> files.</p></dd></dl></div><p>
      </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497777408"></a>Custom Rules</h2></div></div></div><p>Suppose that your package generates extra cruft as a side
      effect of the build process that's not taken care of by the
      upstream <code class="literal">clean</code> rule and ends up bloating
      your diff.  To handle this (until upstream fixes it), you can
      simply add stuff to the <code class="literal">clean</code> rule as
      follows:

</p><pre class="programlisting">
clean::
	rm -f foo/blah.o po/.intltool-merge-cache
</pre><p>

      Almost all of the current rules are
      <em class="firstterm">double-colon</em> rules (see the
      <em class="citetitle">GNU Make Manual</em>).  This means you can
      simply add to them without overriding the default.</p><p>You can also add dependencies to the rules.  For example,
      suppose you have a multiple-binary package that builds both a
      program and a shared library, and the program depends on the
      shared library.  To tell CDBS to build the shared library before
      the program, just do something like:

</p><pre class="programlisting">
binary/program:: binary/libfoo
</pre><p>

      However, this must come <span class="emphasis"><em>before</em></span> you include
      <code class="filename">buildcore.mk</code>.  This is due to the way make
      works.</p><p>Targets of the form
      <code class="literal"><em class="replaceable"><code>something</code></em>/<em class="replaceable"><code>package</code></em></code>
      exist for many stages of the package build process and allow you
      to hook in additional commands.  Suppose you want custom rules
      for the source package <code class="literal">foo</code>, creating binary
      packages <code class="literal">foo</code> (architecture-depependent) and
      <code class="literal">foo-data</code> (architecture-independent).  You
      simply need to add some lines like the following to
      <code class="filename">debian/rules</code>.</p><p>To add pre-configure actions:
</p><pre class="programlisting">
makebuilddir/foo::
	ln -s plop plop2
</pre><p>
      </p><p>To add post-configure actions:
</p><pre class="programlisting">
configure/foo::
	sed -ri 's/PLOP/PLIP/' Makefile

configure/foo-data::
	touch src/z.xml
</pre><p>
      In this case we are talking about package configuration and not
      about a <code class="filename">configure</code> script made with
      autotools (although such a <code class="filename">configure</code> script
      would normally also be called in that very package configuration
      phase).</p><p>To add post-build actions:
</p><pre class="programlisting">
build/foo::
	$(SHELL) debian/scripts/toto.sh

build/foo-data::
	$(MAKE) helpfiles
</pre><p>
      </p><p>To add post-install actions:
</p><pre class="programlisting">
install/foo::
	cp debian/tmp/myfoocmd debian/foo/foocmd
	find debian/foo/ -name "CVS" -depth -exec rm -rf {} \;
	strip --remove-section=.comment --remove-section=.note --strip-unneeded \
	    debian/foo/usr/lib/foo/totoz.so

install/foo-data::
	cp data/*.png debian/foo-data/usr/share/foo-data/images/
	dh_stuff -m ipot -f plop.bz3 debian/foo-data/libexec/
</pre><p>
      </p><p>To add post deb preparation actions (usually not very
      useful):
</p><pre class="programlisting">
binary/foo::
	@echo 'Package foo successfully built.'
</pre><p>
      </p><p>To add pre-clean actions:
</p><pre class="programlisting">
cleanbuilddir/foo::
	rm -f debian/fooman.1
</pre><p>
      </p><p>Now, let's suppose your package is a little bit strange
      (e.g. Perl); perhaps it has a <span class="command"><strong>Configure</strong></span>
      script that isn't made by Autoconf; this script might instead
      expect the user to interactively configure the program.  In that
      case, you can just implement the
      <code class="literal">common-configure</code> rule, by adding something
      like the following to your
      <code class="filename">debian/rules</code>:

</p><pre class="programlisting">
common-configure::
	./Configure --blah --blargh &lt; debian/answers
</pre><p>
      </p><p>Note that if you do this, you can't include
      <code class="filename">autotools.mk</code>, since then you'll get
      <span class="emphasis"><em>two</em></span> implementations of common-configure,
      which is sure to fail.  It would be nice to be able to partially
      override rule fragments, but that is a tricky problem.</p><p><a class="xref" href="#fig:buildcore" title="Figure 2.1. Buildcore targets">Figure 2.1, “Buildcore targets”</a> gives an overview of the
      targets provided by <code class="filename">buildcore.mk</code> where you
      can hook in custom rules.  The bold ellipses are the targets
      required by the Debian policy.  For illustration, the
      diamond-shaped nodes show how a typical autotools-using build
      process would be hooked into these rules.  These are not
      actually provided by <code class="filename">buildcore.mk</code> of
      course.</p><div class="figure"><a id="fig:buildcore"></a><p class="title"><strong>Figure 2.1. Buildcore targets</strong></p><div class="figure-contents"><div class="mediaobject"><img src="buildcore.png" alt="Rules graph" /></div></div></div><br class="figure-break" /><p>Rules that add commands should normally be written
      <span class="emphasis"><em>after</em></span> including any CDBS rule fragments,
      unless you know exactly what you're doing.  The reason for this
      is as follows.  The commands for double-colon rules are
      accumulated in the order in which they appear in the makefile.
      That is, writing
</p><pre class="programlisting">
target::
	foo

target::
	bar
</pre><p>
      will have approximately the same effect as
</p><pre class="programlisting">
target:
	foo
	bar
</pre><p>
      Now if you have, for example, an autotools-using package and
      wrote something like
</p><pre class="programlisting">
build/myprog::
	$(MAKE) extrastuff

include /usr/share/cdbs/1/class/autotools.mk
</pre><p>
      (more on the autotools class below), this would end up running
      <code class="literal">$(MAKE) extrastuff</code> before
      <code class="literal">autotools.mk</code> has a chance to run
      <span class="command"><strong>configure</strong></span>, so there will probably not be any
      instantiated makefile yet and the build will fail.</p><p>Again, the recommended practice is to include all the CDBS
      rule fragments first on your <code class="filename">debian/rules</code>
      and put variable assignments and extra rules afterwards, unless
      an exception is explicitly pointed out in this manual.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497728976"></a>Common Build Options</h2></div></div></div><p>
        <code class="varname">CFLAGS</code> and <code class="varname">CXXFLAGS</code> are
        set to <code class="literal">-g -Wall -O2</code> by default.
      </p><p>
        <code class="varname">DEB_BUILD_OPTIONS</code> is a well known Debian
        environment variable, not a CDBS one, containing special build
        options (a comma-separated list of key words).  CDBS does
        check <code class="varname">DEB_BUILD_OPTIONS</code> to take these
        options into account; see details in each class.
      </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497724992"></a>Debhelper Support</h2></div></div></div><p>An important piece of the puzzle after configuring and
      building the software is to actually build
      <code class="filename">.deb</code>s from there.  You could implement this
      step yourself if you wished, but most people will want to take
      advantage of Debhelper to do it mostly automatically.  To do
      this, simply add a line like

</p><pre class="programlisting">
include /usr/share/cdbs/1/rules/debhelper.mk
</pre><p>
      in <code class="filename">debian/rules</code>.
      </p><p>CDBS debhelper rules handle the following
      <span class="command"><strong>dh_*</strong></span> commands for each binary package
      automatically:

        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>dh_builddeb</p></li><li class="listitem"><p>dh_clean</p></li><li class="listitem"><p>dh_compress</p></li><li class="listitem"><p>dh_fixperms</p></li><li class="listitem"><p>dh_gencontrol</p></li><li class="listitem"><p>dh_install</p></li><li class="listitem"><p>dh_installcatalogs</p></li><li class="listitem"><p>dh_installchangelogs</p></li><li class="listitem"><p>dh_installcron</p></li><li class="listitem"><p>dh_installdeb</p></li><li class="listitem"><p>dh_installdebconf</p></li><li class="listitem"><p>dh_installdirs</p></li><li class="listitem"><p>dh_installdocs</p></li><li class="listitem"><p>dh_installemacsen</p></li><li class="listitem"><p>dh_installexamples</p></li><li class="listitem"><p>dh_installinfo</p></li><li class="listitem"><p>dh_installinit</p></li><li class="listitem"><p>dh_installlogcheck</p></li><li class="listitem"><p>dh_installlogrotate</p></li><li class="listitem"><p>dh_installman</p></li><li class="listitem"><p>dh_installmenu</p></li><li class="listitem"><p>dh_installmime</p></li><li class="listitem"><p>dh_installpam</p></li><li class="listitem"><p>dh_installudev</p></li><li class="listitem"><p>dh_link</p></li><li class="listitem"><p>dh_lintian</p></li><li class="listitem"><p>dh_makeshlibs</p></li><li class="listitem"><p>dh_md5sums</p></li><li class="listitem"><p>dh_perl</p></li><li class="listitem"><p>dh_prep</p></li><li class="listitem"><p>dh_shlibdeps</p></li><li class="listitem"><p>dh_strip</p></li></ul></div><p>

      Of course, these are called in the correct order, not in the one
      shown above.  Other debhelper commands can be handled in
      specific classes or may be called in custom rules.</p><p>If you use <code class="filename">debhelper.mk</code>, you must add
      a build dependency on <code class="literal">debhelper</code>.  If you use
      Debhelper compatibility level 5, then the dependency should be
      (at least) <code class="literal">debhelper (&gt;= 5)</code>, if you use
      version 4 then (at least) <code class="literal">debhelper (&gt;=
      4.2.0)</code>.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idm45814497700688"></a>Debhelper Parameters</h3></div></div></div><p>The following variables allow Debhelper call
        customization while leaving the other calls to be handled
        without writing any rule.  Some of them apply on all binary
        packages, for instance
        <code class="varname">DEB_INSTALL_DOCS_ALL</code>, and some apply only
        to a specific package, for instance
        <code class="varname">DEB_SHLIBDEPS_LIBRARY_<em class="replaceable"><code>package</code></em></code>
        (where <em class="replaceable"><code>package</code></em> is the name of a
        binary package).  Read the comments in
        <code class="filename">/usr/share/cdbs/1/rules/debhelper.mk</code> for
        a complete listing.  Some non-exhaustive examples follow.</p><p>
          To specify a tight dependency on a package containing shared libraries:
</p><pre class="programlisting">
DEB_DH_MAKESHLIBS_ARGS_libfoo = -V"libfoo (&gt;= 0.1.2-3)"
DEB_SHLIBDEPS_LIBRARY_arkrpg = libfoo
DEB_SHLIBDEPS_INCLUDE_arkrpg = debian/libfoo/usr/lib/
</pre><p>
        </p><p>
          To install a changelog file with an uncommon name like
          <code class="filename">ProjectChanges.txt.gz</code>:
</p><pre class="programlisting">
DEB_INSTALL_CHANGELOGS_ALL = ProjectChanges.txt
</pre><p>
          (CDBS automatically recognizes a fair number of possible
          changelog names, but not that one.)
        </p><p>
          To avoid compressing files with a <code class="filename">.py</code>
          extension:
</p><pre class="programlisting">
DEB_COMPRESS_EXCLUDE = .py
</pre><p>
        </p><p>
          Perl-specific debhelper options (The
          <span class="command"><strong>dh_perl</strong></span> call is always performed.):
</p><pre class="programlisting">
# Add a space-separated list of paths to search for perl modules
DEB_PERL_INCLUDE = /usr/lib/perl-z

# Like the above, but for the 'libperl-stuff' package
DEB_PERL_INCLUDE_libperl-stuff = /usr/lib/perl-plop

# Overrides options passed to dh_perl
DEB_DH_PERL_ARGS = -d
</pre><p>
        </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idm45814497690224"></a>Debhelper Custom Build Rules</h3></div></div></div><p>
          CDBS debhelper rules also add more adequate build rules.
          For example, to add post deb preparation (including
          debhelper stuff) actions:
</p><pre class="programlisting">
binary-install/foo::
	chmod a+x debian/foo/usr/bin/pouet
</pre><p>
        </p><p>
          Several other rules exists, for rarer cases:

          </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">binary-strip/foo</code> (called
              after stripping)</p></li><li class="listitem"><p><code class="literal">binary-fixup/foo</code> (called
              after gzipping and fixing
              permissions)</p></li><li class="listitem"><p><code class="literal">binary-predeb</code> (called just
              before creating the <code class="filename">.deb</code>)</p></li></ul></div><p>
        </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idm45814497682832"></a>Debug Package Support</h3></div></div></div><p>A debug package is a binary package named
        <code class="literal"><em class="replaceable"><code>package</code></em>-dbg</code> that
        contains the debugging symbols for the binaries (programs,
        libraries, etc.) in other packages, typically all other binary
        packages built from the same source package.  Debhelper
        facilitates the creation of these debug packages by the
        <code class="option">--dbg-package</code> option in the command
        <span class="command"><strong>dh_strip</strong></span>.  CDBS has support for creating
        debug packages, if Debhelper level 5 compatibility is
        used.</p><p>CDBS will automatically call <span class="command"><strong>dh_strip</strong></span>
        with the right options if exactly one debug package is
        mentioned in <code class="filename">debian/control</code> and so that
        the debugging symbols of all other binary packages are
        included in that debug package.  This takes care of the most
        common situation.</p><p>To control more finely which debug symbols go where, in
        particular if you want to build more than one debug package,
        there are variables
        <code class="varname">DEB_DBG_PACKAGE_<em class="replaceable"><code>package</code></em></code>
        that specify the debug package target for each individual
        binary package.  An example usage would be:
</p><pre class="programlisting">
DEB_DBG_PACKAGE_libfoo4 = libfoo-dbg
DEB_DBG_PACKAGE_foo-bin = foo-bin-dbg
</pre><p>
        </p><p>If exactly one debug package is defined, setting any
        variable
        <code class="varname">DEB_DBG_PACKAGE_<em class="replaceable"><code>package</code></em></code>
        disables the behavior of putting all debug symbols in that
        package.</p><p>If there is more than one debug package defined and each
        debug package is named <code class="literal">foo-dbg</code> such that
        there is a package called <code class="literal">foo</code>, then the
        assignments <code class="literal">DEB_DBG_PACKAGE_foo = foo-dbg</code>
        are done automatically.  Again, this only happens if all debug
        packages can be assigned this way.  Of course, all these
        assignments can be overridden if you find that this behavior
        doesn't quite work for you.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If a source package builds a single binary package,
	  and then a debug package is added, this changes the
	  automatic assignment of <code class="varname">DEB_DESTDIR</code>
	  to <code class="literal">$(CURDIR)/debian/tmp</code>, as described in
	  <a class="xref" href="#basic-settings" title="Basic Settings and Available Variables">the section called “Basic Settings and Available Variables”</a>, which will likely invalidate
	  the installation rules and leave you with a nearly-empty
	  package.  To work around this behavior,
	  set <code class="varname">DEB_DESTDIR</code> manually
	  in <code class="filename">debian/rules</code> as
</p><pre class="programlisting">
DEB_DESTDIR = $(CURDIR)/debian/<em class="replaceable"><code>packagename</code></em>
</pre><p>
          Alternatively, write
          a <code class="filename"><em class="replaceable"><code>packagename</code></em>.install</code>
          file listing
</p><pre class="programlisting">
debian/tmp/*
</pre><p>
          or whatever subset you need.
	  </p></div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="idm45814497665200"></a>Chapter 3. Classes</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#idm45814497651216">The Makefile Class</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idm45814497635168">Build Problems</a></span></dt><dt><span class="sect2"><a href="#idm45814497630016">The Makefile Class and Single vs. Multiple Binary
        Packages</a></span></dt></dl></dd><dt><span class="sect1"><a href="#idm45814497618384">The Autotools Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497576640">The CMake Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497567504">The Perl Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497557104">The Python Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497546272">The GNOME Class</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idm45814497532784">The Debian GNOME Team Class</a></span></dt></dl></dd><dt><span class="sect1"><a href="#idm45814497522944">The KDE Class</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idm45814497511648">Obsolescent: KDE 3 Support</a></span></dt></dl></dd><dt><span class="sect1"><a href="#idm45814497494736">The Qmake Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497482656">The Ant Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497449552">The HBuild Class</a></span></dt><dt><span class="sect1"><a href="#idm45814497443536">The Waf Class</a></span></dt></dl></div><p>CDBS provides <em class="firstterm">classes</em> which contain
    makefile rules and variables implementing compilation,
    installation, and building of Debian packages.  There are a number
    of classes covering different types of ways a software is built.
    Classes tend to be declarative; they say your package has
    particular properties.  Suppose for instance that your package
    uses a regular makefile to compile, and has the normal
    <span class="command"><strong>make</strong></span> and <span class="command"><strong>make install</strong></span>
    targets.  In that case you would use the <span class="quote">“<span class="quote">makefile</span>”</span>
    class, and you can say:

    </p><pre class="programlisting">include /usr/share/cdbs/1/class/makefile.mk</pre><p>

    This gives you all the code to run <span class="command"><strong>make</strong></span>
    automatically.  It basically works by adding code to the
    <code class="literal">common-build-arch</code>,
    <code class="literal">common-build-indep</code>,
    <code class="literal">common-install-arch</code>, and
    <code class="literal">common-install-indep</code> targets inside
    <code class="filename">buildcore.mk</code>.  It might be instructive to
    look at <code class="filename">makefile.mk</code> now.</p><p>Some classes actually include another class, or
    <span class="quote">“<span class="quote">inherit</span>”</span> if you like.  For example, the autotools
    class inherits the makefile class because much of the build
    process is the same between them, only the configuration stage is
    different.  The effect is that all the variables provided by the
    inherited class are available in the inheriting class as well.
    <a class="xref" href="#fig:depgraph" title="Figure 3.1. Dependencies between the CDBS class and rule files">Figure 3.1, “Dependencies between the CDBS class and rule files”</a> shows the relationship between the
    classes and other rule sets provided by CDBS.</p><div class="figure"><a id="fig:depgraph"></a><p class="title"><strong>Figure 3.1. Dependencies between the CDBS class and rule files</strong></p><div class="figure-contents"><div class="mediaobject"><img src="depgraph.png" alt="Dependency graph" /></div></div></div><br class="figure-break" /><p>The rest of this chapter explains all the classes supported
    by CDBS.</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497651216"></a>The Makefile Class</h2></div></div></div><p>The makefile class is for the packages who only have a
      makefile to build the program.  (If the package uses Autoconf,
      use the autotools class instead.)  You only need to have four
      rules in the makefile:

      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>one for cleaning the build directory (e.g.,
          <code class="literal">clean</code>)</p></li><li class="listitem"><p>one for building the software
          (e.g. <code class="literal">all</code>)</p></li><li class="listitem"><p>one for checking if the software is working properly
          (e.g. <code class="literal">check</code>)</p></li><li class="listitem"><p>one for installing the software
          (e.g. <code class="literal">install</code>)</p></li></ul></div><p>

      The installation and check rules are optional, but it always
      helps a lot when you've got them.</p><p>The first step is to write the
      <code class="filename">debian/rules</code>.  First, we add the include
      lines:
</p><pre class="programlisting">
include /usr/share/cdbs/1/class/makefile.mk
</pre><p>
      Now, it remains to tell CDBS the name of our four makefile
      rules.  For the previous examples it gives:
</p><pre class="programlisting">
DEB_MAKE_CLEAN_TARGET   = clean
DEB_MAKE_BUILD_TARGET   = all
DEB_MAKE_INSTALL_TARGET = install DESTDIR=$(CURDIR)/debian/tmp/
# no check for this software
DEB_MAKE_CHECK_TARGET   =

# example when changing environment variables is necessary
DEB_MAKE_ENVVARS        = CFLAGS="-pwet"
</pre><p>
      </p><p><code class="varname">DEB_BUILD_OPTIONS</code> is checked for the
      following options:
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">noopt</code></span></dt><dd><p>use <code class="option">-O0</code> instead of <code class="option">-O2</code></p></dd><dt><span class="term"><code class="literal">nocheck</code></span></dt><dd><p>skip the check rule</p></dd></dl></div><p>
      </p><p>If your makefile doesn't support the
      <code class="varname">DESTDIR</code> variable, take a look in it and find
      the variable responsible for setting installation directory.  If
      you don't find some variable to do this, you'll have to patch
      the makefile.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idm45814497635168"></a>Build Problems</h3></div></div></div><p>Sometimes, when using the makefile class (or a derived
        one), a build fails because of missing include files or
        something like that.  Often this is caused by the fact that
        CDBS passes <code class="varname">CFLAGS</code> (and
        <code class="varname">CPPFLAGS</code>) along with the make invocation.
        A sane build system allows this: <code class="varname">CFLAGS</code> are
        for the user to customize.  Setting <code class="varname">CFLAGS</code>
        shouldn't override other internal flags used in the package,
        such as <code class="option">-I</code>.  If fixing the upstream source is
        too difficult, however, you may do this:

</p><pre class="programlisting">
DEB_MAKE_INVOKE = $(DEB_MAKE_ENVVARS) make -C $(DEB_BUILDDIR)
</pre><p>

        That will avoid passing <code class="varname">CFLAGS</code>.  But note
        that this breaks the automatic implementation of
        <code class="varname">DEB_BUILD_OPTIONS</code>.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idm45814497630016"></a>The Makefile Class and Single vs. Multiple Binary
        Packages</h3></div></div></div><p>If you have a single binary package, the default
        <code class="literal">common-install</code> implementation in
        <code class="filename">makefile.mk</code> tries to use the upstream
        <code class="filename">Makefile</code> to install everything into
        <code class="filename">debian/packagename</code>, so it will all appear
        in the binary package.  If you're using
        <code class="filename">debhelper.mk</code> to remove files or move them
        around, just override the
        <code class="literal">binary-post-install/<em class="replaceable"><code>package</code></em></code>
        target:

</p><pre class="programlisting">
binary-post-install/mypackage::
	mv debian/mypackage/usr/sbin/myprogram debian/mypackage/usr/bin/myprogram
	rm debian/mypackage/usr/share/doc/mypackage/INSTALL
</pre><p>
        </p><p>If you have a multiple-binary package,
        <code class="filename">makefile.mk</code> (by default) uses the
        upstream <code class="filename">Makefile</code> to install everything
        in <code class="filename">debian/tmp</code>.  After this, the
        recommended method is to use <code class="filename">debhelper.mk</code>
        (which uses <span class="command"><strong>dh_install</strong></span>) to copy these files
        into the appropriate package.  To do this, just create
        <code class="filename"><em class="replaceable"><code>package</code></em>.install</code>
        files; see the <span class="command"><strong>dh_install</strong></span> man page.</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497618384"></a>The Autotools Class</h2></div></div></div><p>The autotools class is for software that uses GNU Autoconf
      and possibly Automake and Libtool.  The class will take care of
      details such as updating the
      <code class="filename">config.{sub,guess}</code> files, running
      <span class="command"><strong>configure</strong></span> with the standard arguments, etc.
      The autotools class actually builds upon the makefile
      class.</p><p>To use the autotools class, just add this line to your
      <code class="filename">debian/rules</code>:
</p><pre class="programlisting">
include /usr/share/cdbs/1/class/autotools.mk
</pre><p>
      </p><p>Suppose you need to pass some additional options to
      <span class="command"><strong>configure</strong></span>.  The
      <code class="filename">autotools.mk</code> file includes a number of
      variables that you can override for that purpose, like this:

</p><pre class="programlisting">
DEB_CONFIGURE_EXTRA_FLAGS = --enable-ipv6 --with-foo
</pre><p>
      </p><p>If the build system uses non-standard configure options
      you can override the CDBS default behavior:
</p><pre class="programlisting">
DEB_CONFIGURE_NORMAL_ARGS = --program-dir=/usr
</pre><p>
      Note that <code class="varname">DEB_CONFIGURE_EXTRA_FLAGS</code> will
      still be appended.</p><p>If some specific environnement variables need to be setup,
      use:
</p><pre class="programlisting">
DEB_CONFIGURE_SCRIPT_ENV += LDFLAGS=" -Wl,-z,defs -Wl,-O1"
</pre><p>
      </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Prefer the use of <code class="literal">+=</code> over
        <code class="literal">=</code> lest you override other environment
        variables like <code class="varname">CC</code> or <code class="varname">CXX</code>
        defined in the CDBS default.
        </p></div><p>CDBS will automatically update
      <code class="filename">config.sub</code>,
      <code class="filename">config.guess</code>, and
      <code class="filename">config.rpath</code> before the build and restore
      the old ones at the clean stage (even if using the tarball
      system).  If needed, and if <code class="filename">debian/control</code>
      management is activated, <code class="literal">autotools-dev</code> and
      <code class="literal">gnulib</code>, respectively, will then be
      automatically added to the build dependencies (needed to obtain
      updated versions of the files).  Otherwise, you should add these
      packages, as appropriate, to the build dependencies yourself.
      If you fail to do so, these updates will not execute unless the
      required packages are already installed by coincidence.
      (Lintian is likely to complain if you forget.)  If the program
      does not use the top source directory to store autoconf files,
      you can teach CDBS where they are to be found:
</p><pre class="programlisting">
DEB_AC_AUX_DIR = $(DEB_SRCDIR)/autoconf
</pre><p>
      </p><p>CDBS automatically cleans autotools files generated during
      the build (<code class="filename">config.cache</code>,
      <code class="filename">config.log</code>, and
      <code class="filename">config.status</code>).</p><p>CDBS can be asked to update Autoconf, Automake, and
      Libtool generated files, but this behavior is likely to break
      the build system and is <span class="emphasis"><em>strongly</em></span>
      discouraged.  Nevertheless, if you still want this feature, set
      the following variables:

      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="varname">DEB_AUTO_UPDATE_AUTOCONF</code> to
        the version of Autoconf to use; e.g.,
        <code class="literal">2.61</code></p></li><li class="listitem"><p><code class="varname">DEB_AUTO_UPDATE_AUTOHEADER</code> to
        the version of <span class="command"><strong>autoheader</strong></span> to use; e.g.,
        <code class="literal">2.61</code></p></li><li class="listitem"><p><code class="varname">DEB_AUTO_UPDATE_AUTOMAKE</code> to
        the version of Automake to use; e.g.,
        <code class="literal">1.10</code>.  To pass extra arguments
        to <span class="command"><strong>automake</strong></span>, such
        as <code class="literal">--add-missing --copy</code>, put them into the
        variable <code class="varname">DEB_AUTOMAKE_ARGS</code>.</p></li><li class="listitem"><p><code class="varname">DEB_AUTO_UPDATE_ACLOCAL</code> to
        the version of <span class="command"><strong>aclocal</strong></span> to use; e.g.,
        <code class="literal">1.10</code>.  In the current version of CDBS,
        <code class="varname">DEB_AUTO_UPDATE_AUTOMAKE</code> implies
        <code class="varname">DEB_AUTO_UPDATE_ACLOCAL</code>.  This behavior will
        eventually be discontinued; so if you meant <code class="filename">aclocal.m4</code> to be
        regenerated, please use <code class="varname">DEB_AUTO_UPDATE_ACLOCAL</code>.
        </p></li><li class="listitem"><p><code class="varname">DEB_AUTO_UPDATE_LIBTOOL</code> to
        <code class="literal">pre</code> to run <span class="command"><strong>libtoolize</strong></span>
        before the build, or to <code class="literal">post</code> to copy the
        system-supplied <span class="command"><strong>libtool</strong></span> program into the
        build tree after the configure run</p></li></ul></div><p>

      (Corresponding build dependencies will automatically be
      added.)</p><p>The following make parameters can also be overridden :
</p><pre class="programlisting">
# these are the defaults CDBS provides
DEB_MAKE_INSTALL_TARGET = install DESTDIR=$(DEB_DESTDIR)
DEB_MAKE_CLEAN_TARGET = distclean
DEB_MAKE_CHECK_TARGET =

# example to work around dirty makefile
DEB_MAKE_INSTALL_TARGET = install prefix=$(CURDIR)/debian/tmp/usr

# example with unexistant install rule for make
DEB_MAKE_INSTALL_TARGET =

# example to activate check rule
DEB_MAKE_CHECK_TARGET = check
</pre><p>
      </p><p><code class="varname">DEB_BUILD_OPTIONS</code> is checked for the
      following options:
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">noopt</code></span></dt><dd><p>use <code class="option">-O0</code> instead of <code class="option">-O2</code></p></dd><dt><span class="term"><code class="literal">nocheck</code></span></dt><dd><p>skip the check rule</p></dd></dl></div><p>
      </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497576640"></a>The CMake Class</h2></div></div></div><p>CMake is a cross-platform build tool.  On Unix-like systems
      it typically generates makefiles, which are then run through make
      normally.  To use the CMake class, add this include to
      your <code class="filename">debian/rules</code>:

</p><pre class="programlisting">
include /usr/share/cdbs/1/class/cmake.mk
</pre><p> 

      The class takes care of the call to <span class="command"><strong>cmake</strong></span> and
      the subsequent calls to <span class="command"><strong>make</strong></span>, with all the
      necessary options to honor <code class="varname">DEB_BUILD_OPTIONS</code>,
      for example.  To that end, the CMake class builds upon the
      makefile class.</p><p>CMake is designed to always use separate source and build
      directories.  Therefore, the CMake class by default builds the project
      in a separate build directory named like <code class="filename">obj-<em class="replaceable"><code>platform</code></em></code>
      under the top-level source directory.</p><p><code class="varname">DEB_BUILD_OPTIONS</code> is checked for the
      following options:
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">noopt</code></span></dt><dd><p>use <code class="option">-O0</code> instead of <code class="option">-O2</code></p></dd></dl></div><p>
      </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497567504"></a>The Perl Class</h2></div></div></div><p>The Perl class can manage Perl module packages using
      MakeMaker.  To use this class, add this line to your
      <code class="filename">debian/rules</code>:

</p><pre class="programlisting">
include /usr/share/cdbs/1/class/perlmodule.mk
</pre><p>
      </p><p>The installation directory defaults to
      <code class="filename"><em class="replaceable"><code>first_pkg</code></em>/usr</code>
      where <em class="replaceable"><code>first_pkg</code></em> is the first package
      in <code class="filename">debian/control</code>.</p><p>You can customize build options like this:
</p><pre class="programlisting">
# change MakeMaker defaults (hardly ever useful)
DEB_MAKE_BUILD_TARGET = build-all
DEB_MAKE_CLEAN_TARGET = realclean
DEB_MAKE_CHECK_TARGET =
DEB_MAKE_INSTALL_TARGET = install PREFIX=debian/stuff

# add custom MakeMaker options
DEB_MAKEMAKER_USER_FLAGS = --with-foo
</pre><p>
      </p><p>Common makefile or general options can still be
      overridden: <code class="varname">DEB_MAKE_ENVVARS</code>,
      <code class="varname">DEB_BUILDDIR</code> (must match
      <code class="varname">DEB_SRCDIR</code> for Perl).
      </p><p>Have a look at the Perl-specific debhelper options
      described above.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>If <code class="filename">debian/control</code> management is
        activated (see below), a build dependency on
        <code class="literal">perl</code> is automatically added.  If not, you
        will have to do it yourself.</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497557104"></a>The Python Class</h2></div></div></div><p>The Python class can manage Python module packages using
      Distutils.  To use this class, add this line to your
      <code class="filename">debian/rules</code>:

</p><pre class="programlisting">
include /usr/share/cdbs/1/class/python-distutils.mk
</pre><p>

      Optionally, this class can take care of using
      <span class="command"><strong>dh_pycentral</strong></span> or <span class="command"><strong>dh_pycentral</strong></span>
      as needed, if the CDBS debhelper rules are also included.</p><p>Most Python packages are architecture-independent and then
      don't need to be built for multiple Python versions; your
      package should then be called
      <code class="literal">python-<em class="replaceable"><code>foo</code></em></code> and
      CDBS will automatically use the current Python version in Debian
      to build it.  If your package contains a compiled part or a
      binding to an external library, then you will have packages
      named
      <code class="literal">python2.3-<em class="replaceable"><code>foo</code></em></code>,
      <code class="literal">python2.4-<em class="replaceable"><code>foo</code></em></code>, and
      so on, depending on <code class="literal">${python:Depends}</code> (and
      perhaps other packages); then CDBS will automatically build each
      package with the corresponding Python version.  In this case,
      don't forget to add a
      <code class="literal">python-<em class="replaceable"><code>foo</code></em></code>
      convenience dummy package depending on the current Python
      version in Debian.</p><p>You can customize build options like this:
</p><pre class="programlisting">
# change the python build script name (default is 'setup.py')
DEB_PYTHON_SETUP_CMD = install.py

# clean options for the python build script
DEB_PYTHON_CLEAN_ARGS = -all

# build options for the python build script
DEB_PYTHON_BUILD_ARGS = --build-base="$(DEB_BUILDDIR)/specific-build-dir"

# common additional install options for all binary packages
# ('--root' option is always set)
DEB_PYTHON_INSTALL_ARGS_ALL = --no-compile --optimize --force

# specific additional install options for binary package 'foo'
# ('--root' option is always set)
DEB_PYTHON_INSTALL_ARGS_foo = --root=debian/foo-install-dir/
</pre><p>
      </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497546272"></a>The GNOME Class</h2></div></div></div><p>The GNOME class is obviously for building GNOME software.
      It inherits the autotools class, so everything that was said
      there also applies to the GNOME class.</p><p>The GNOME class can call the following debhelper scripts
      automatically:

      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>dh_desktop</p></li><li class="listitem"><p>dh_gconf</p></li><li class="listitem"><p>dh_icons</p></li><li class="listitem"><p>dh_scrollkeeper</p></li></ul></div><p>

      Moreover it adds some more clean rules:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>to remove <span class="command"><strong>intltool</strong></span> generated files</p></li><li class="listitem"><p>to remove <span class="command"><strong>scrollkeeper</strong></span> generated files</p></li></ul></div><p>
      </p><p>To use it, just add this line to your
      <code class="filename">debian/rules</code>, after the debhelper class
      include:
</p><pre class="programlisting">
include /usr/share/cdbs/1/class/gnome.mk
</pre><p>
      </p><p>The GNOME class adds a make environement variable
      <code class="literal">GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL = 1</code>.
      This is necessary because the Gconf schemas have to be
      registered at install time.  In the case of packaging, this
      registration cannot be done when building the package, so this
      variable disables schema registration in <code class="literal">make
      install</code>.  This procedure is deferred until
      <span class="command"><strong>gconftool-2</strong></span> is called in
      <code class="filename">debian/postinst</code> to register them, and in
      <code class="filename">debian/prerm</code> to unregister them.  The
      <span class="command"><strong>dh_gconf</strong></span> command is able to add the right
      rules automatically for you.
      </p><p>For more information on GNOME-specific packaging rules,
      look at the Debian GNOME packaging policy.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idm45814497532784"></a>The Debian GNOME Team Class</h3></div></div></div><p>If you are part of the GNOME team or have the team as
        uploaders, and you feel bored maintaining the list of
        developers, the GNOME Team class is made for you.</p><p>To use this class, add this line to your
        <code class="filename">debian/rules</code>:
</p><pre class="programlisting">
include /usr/share/gnome-pkg-tools/1/rules/uploaders.mk
</pre><p>
        </p><p>Rename your <code class="filename">debian/control</code> file to
        <code class="filename">debian/control.in</code> and run the clean rule
        (<code class="literal">fakeroot debian/rules clean</code>) to regenerate
        the <code class="filename">debian/control</code> file, which will
        replace the <code class="literal">@GNOME_TEAM@</code> tag with the list
        of developers automatically.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>If you are using the
          <code class="filename">debian/control</code> file management
          described below, please note this class will override this
          feature.  To cope with this problem, allowing at least
          <code class="literal">Build-Depends</code> handling, use the following
          work-arround (until it is solved in a proper way):
</p><pre class="programlisting">
# deactivate 'debian/control' file management
#DEB_AUTO_UPDATE_DEBIAN_CONTROL = yes

# ...
# includes and other stuff
# ...

clean::
	sed -i "s/@cdbs@/$(CDBS_BUILD_DEPENDS)/g" debian/control
	# other clean stuff
</pre><p>
          </p></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497522944"></a>The KDE Class</h2></div></div></div><p>The support for building KDE-related packages for KDE
      version 4 and higher using CDBS is included in the
      package <code class="literal">pkg-kde-tools</code>.  To use the KDE class,
      add this line to your
      <code class="filename">debian/rules</code> file:
</p><pre class="programlisting">
include /usr/share/pkg-kde-tools/makefiles/1/cdbs/kde.mk
</pre><p>
      and add <code class="literal">pkg-kde-tools</code> to the build
      dependencies.  The KDE class inherits the cmake class, so
      everything that was said there also applies here.</p><p>The KDE class provides a plethora of options to
      the <span class="command"><strong>cmake</strong></span> call that have been chosen so that
      the resulting packages integrate properly with Debian.</p><p>The following files are excluded from compression:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="filename">.dcl</code></p></li><li class="listitem"><p><code class="filename">.docbook</code></p></li><li class="listitem"><p><code class="filename">-license</code></p></li><li class="listitem"><p><code class="filename">.tag</code></p></li><li class="listitem"><p><code class="filename">.sty</code></p></li><li class="listitem"><p><code class="filename">.el</code></p></li></ul></div><p>
      </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idm45814497511648"></a>Obsolescent: KDE 3 Support</h3></div></div></div><p>The class named <code class="filename">kde.mk</code> included in
	CDBS is for building KDE-3-based packages.  It will eventually
	be removed from CDBS.</p><p>To use it, add
	this line to <code class="filename">debian/rules</code>:
</p><pre class="programlisting">
include /usr/share/cdbs/1/class/kde.mk
</pre><p>
        This KDE 3 class inherits the autotools class, so everything
        that was said there also applies here.</p><p>CDBS automatically exports the following variables with the right values:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="varname">kde_cgidir</code> (<code class="literal">/usr/lib/cgi-bin</code>)</p></li><li class="listitem"><p><code class="varname">kde_confdir</code> (<code class="literal">/etc/kde3</code>)</p></li><li class="listitem"><p><code class="varname">kde_htmldir</code> (<code class="literal">/usr/share/doc/kde/HTML</code>)</p></li></ul></div><p>
      </p><p>
        <code class="varname">DEB_BUILDDIR</code>,
        <code class="varname">DEB_AC_AUX_DIR</code>, and
        <code class="varname">DEB_CONFIGURE_INCLUDEDIR</code> are set to KDE
        defaults.
      </p><p>The class handles configure options specific to KDE (not
      forgetting to disable rpath and activating xinerama), set the
      correct autotools directory, and launch make rules adequately.</p><p><code class="varname">DEB_BUILD_OPTIONS</code> is checked for the
      following options:
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">noopt</code></span></dt><dd><p>disable KDE final mode</p></dd><dt><span class="term"><code class="literal">nostrip</code></span></dt><dd><p>enable KDE debug mode and disable KDE final mode</p></dd><dt><span class="term"><code class="literal">debug</code></span></dt><dd><p>enable full KDE debug mode</p></dd></dl></div><p>
      </p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497494736"></a>The Qmake Class</h2></div></div></div><p>Qmake is a build tool for software written for the Qt
      toolkit library.  To use the Qmake class, add this include to
      your <code class="filename">debian/rules</code>:

</p><pre class="programlisting">
include /usr/share/cdbs/1/class/qmake.mk
</pre><p> 

      The class takes care of the call to <span class="command"><strong>qmake</strong></span> and
      the subsequent calls to <span class="command"><strong>make</strong></span>, with all the
      necessary options to honor <code class="varname">DEB_BUILD_OPTIONS</code>,
      for example.  To that end, the Qmake class builds upon the
      makefile class.</p><p>The Qmake class will call <code class="literal">make install</code>,
      but many Qmake projects are not set up to have a functioning
      install target, in which case the installation of the package
      components has to be handled manually.</p><p><code class="varname">DEB_BUILD_OPTIONS</code> is checked for the
      following options:
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">noopt</code></span></dt><dd><p>use <code class="option">-O0</code> instead of <code class="option">-O2</code></p></dd><dt><span class="term"><code class="literal">nostrip</code></span></dt><dd><p>pass the <code class="literal">nostrip</code> option to <span class="command"><strong>qmake</strong></span> though the <code class="varname">CONFIG</code> variable</p></dd></dl></div><p>
      </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497482656"></a>The Ant Class</h2></div></div></div><p>Ant is a build tool for software written in the Java
      programming language.  To use the Ant class, add this include to
      your <code class="filename">debian/rules</code>:

</p><pre class="programlisting">
include /usr/share/cdbs/1/class/ant.mk
</pre><p>

      Additionally, you need to set the variable
      <code class="varname">JAVA_HOME</code> to the home directory of the Java
      Runtime Environment (JRE) or Java Development Kit (JDK).  You
      can either set <code class="varname">JAVA_HOME</code> directly or set
      <code class="varname">JAVA_HOME_DIRS</code> to multiple possible home
      directories.  The first directory from this list that provides a
      <span class="command"><strong>java</strong></span> command is used for
      <code class="varname">JAVA_HOME</code>.  For Ant-using packages in the
      Debian main archive, you would typically use either
</p><pre class="programlisting">
JAVA_HOME = /usr/lib/jvm/default-java
</pre><p>
      which requires a build dependency on <code class="literal">default-jdk</code>, or
</p><pre class="programlisting">
JAVA_HOME = /usr/lib/jvm/java-gcj
</pre><p>
      which requires a build dependency on
      <code class="literal">java-gcj-compat-dev</code>.  Setting the Java home
      is required; there is no default.</p><p>You can also override <code class="varname">JAVACMD</code> in case
      you don't want to use the default
      <code class="literal"><em class="replaceable"><code>JAVA_HOME</code></em>/bin/java</code>.</p><p>You may add additional JARs to the build like in the
      following example:

</p><pre class="programlisting">
DEB_JARS = xerces /usr/lib/java-bonus/ldap-connector.jar
</pre><p>

      The <code class="filename">.jar</code> extension may be omitted.  The
      file name must be absolute or relative to
      <code class="filename">/usr/share/java</code>.
      <code class="filename">ant.jar</code>,
      <code class="filename">ant-launcher.jar</code>, and
      <code class="filename">$(JAVA_HOME)/lib/tools.jar</code> are
      automatically added if they exist.</p><p>To use a specific Java compiler, override the variable
      <code class="varname">DEB_ANT_COMPILER</code>, for example
</p><pre class="programlisting">
DEB_ANT_COMPILER = jikes
</pre><p>
      </p><p>If your package does not put the file
      <code class="filename">build.xml</code> in the package root directory,
      where Ant would find it by default, you can point CDBS to the
      right place like this:
</p><pre class="programlisting">
DEB_ANT_BUILDFILE = build/build.xml
</pre><p>
      </p><p>Finally, you need to set the targets to invoke for
      building, installing, testing and cleaning up.  Unless
      overridden, building uses the default target from
      <code class="filename">build.xml</code>, installing and testing is only
      called if the corresponding variable is set, cleaning uses the
      <code class="literal">clean</code> target.  You can also specify multiple
      targets for each step.  To override these rules, or run the
      install or check rules, set the following variables to your
      needs:
</p><pre class="programlisting">
DEB_ANT_BUILD_TARGET = makeitrule
DEB_ANT_CHECK_TARGET = check
DEB_ANT_INSTALL_TARGET = install-all
DEB_ANT_CLEAN_TARGET = super-clean
</pre><p>
      </p><p>Ant called by CDBS will read a property file, by default
      at <code class="filename">debian/ant.properties</code> if it exists.
      There you may define additional properties that are referenced
      from <code class="filename">build.xml</code> so that you don't have to
      modify upstream's <code class="filename">build.xml</code>.  Please note
      that command-line arguments in <code class="varname">ANT_ARGS</code> (see
      below) override the settings in <code class="filename">build.xml</code>
      and the property file.  The use a different property file, set
      the variable <code class="varname">DEB_ANT_PROPERTYFILE</code>.</p><p>You can provide additionnal JVM arguments using the
      variable <code class="varname">ANT_OPTS</code>.  You can moreover provide
      additional Ant command line arguments using
      <code class="varname">ANT_ARGS</code> (global) or
      <code class="varname">ANT_ARGS_<em class="replaceable"><code>package</code></em></code>,
      thus overriding the settings in <code class="filename">build.xml</code>
      and the property file.</p><p><code class="varname">DEB_BUILD_OPTIONS</code> is checked for the
      following options:
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">nocheck</code></span></dt><dd><p>skip the check target</p></dd><dt><span class="term"><code class="literal">noopt</code></span></dt><dd><p>set Ant option <code class="literal">compile.optimize</code> to false</p></dd></dl></div><p>
      </p><p>See <a class="xref" href="#example-ant" title="Ant Example">the section called “Ant Example”</a> for a complete example
      that uses this Ant class.  You can also get some more
      information on Ant at the <a class="ulink" href="http://ant.apache.org/" target="_top">Ant Apache web site</a>.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497449552"></a>The HBuild Class</h2></div></div></div><p>HBuild is the Haskell mini-distutils.  CDBS can take care
      of <code class="literal">-hugs</code> and <code class="literal">-ghc</code>
      packages: invoke <code class="filename">Setup.lhs</code> properly for the
      clean and install part.</p><p>
        To use this class, add this line to your
        <code class="filename">debian/rules</code>:
</p><pre class="programlisting">
include /usr/share/cdbs/1/class/hbuild.mk
</pre><p>
      </p><p>
        You should be able to fetch some more information on Haskell
        distutils in <a class="ulink" href="http://www.haskell.org/pipermail/libraries/2003-July/001239.html" target="_top">this
        thread</a>.
      </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497443536"></a>The Waf Class</h2></div></div></div><p>Waf is a generic and flexible build system based on python. CDBS takes care of calling
      the configure, build and install steps with correct <code class="literal">PREFIX</code>
      and <code class="literal">DESTDIR</code>.</p><p>
        To use this class, you must include this line to your <code class="filename">debian/rules</code> file:
</p><pre class="programlisting">
include /usr/share/cdbs/1/class/waf.mk
</pre><p>
      </p><p>If you need a more advanced control upon build configuration,
      you can pass options to the configure step using the built-in variable
      <code class="literal">DEB_WAF_CONFIGURE_OPTIONS</code>. You can pass options to each
      WAF invocation using the <code class="literal">DEB_WAF_OPTIONS</code> variable.
      You can as well append variables to the environment WAF will run in with the
      <code class="literal">DEB_WAF_ENV</code> variable. Note : those three vars supports 
      global, default and per-package scope. This means you must add the scope suffix
      to use them.
      Full <code class="filename">debian/rules</code> usage example:
</p><pre class="programlisting">
#!/usr/bin/make -f

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/waf.mk

DEB_WAF_CONFIGURE_OPTIONS_DEFAULT = --enable-this-option --disable-this-one
DEB_WAF_OPTIONS_DEFAULT = --verbose
DEB_WAF_ENV_DEFAULT = ENVVAR=value
</pre><p>
      </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
          Waf design is based on a self-extracting executable within the source tree.
          Since waf is executed blindly during build process, it implies potential security
          risk if malware is inserted inside waf.
          To reduce this risk, CDBS includes a SHA1 checksum of the waf file before the build
          process. This is done with checking the file <code class="filename">debian/waf.sha1sum</code>.
          The packager has charge to create and maintain this file along the package evolution.
          <code class="filename">debian/waf.sha1sum</code> can be created with following command:
</p><pre class="programlisting">
sha1sum ./waf &gt; debian/waf.sha1sum
</pre><p>
          However, if the packager trusts the waf file, this checksum can be skipped by assigning
          a non-zero value to <code class="literal">DEB_WAF_SKIP_CHECKSUM</code>.
</p><pre class="programlisting">
DEB_WAF_SKIP_CHECKSUM = 1
</pre><p>
        </p></div><p>
        More information can be found about WAF in a general way on the <a class="ulink" href="http://code.google.com/p/waf/" target="_top">project page</a>.
      </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="idm45814497428832"></a>Chapter 4. Common Tasks</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#idm45814497427696">Patching Sources Using the Simple Patch System</a></span></dt><dt><span class="sect1"><a href="#idm45814497407328">Patching Sources Using Dpatch</a></span></dt><dt><span class="sect1"><a href="#idm45814497397376">Patching Sources Using Quilt</a></span></dt><dt><span class="sect1"><a href="#idm45814497393936">Standard Patch System Targets</a></span></dt><dt><span class="sect1"><a href="#idm45814503314576">Tarball-Inside-a-Tarball Build System</a></span></dt><dt><span class="sect1"><a href="#idm45814497367216"><code class="filename">debian/control</code> Management</a></span></dt></dl></div><p>CDBS also supports other tasks that regularly occur during
    the course of building Debian packages.</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497427696"></a>Patching Sources Using the Simple Patch System</h2></div></div></div><p>Suppose you'd like to keep separated patches, instead of
      having them all in your <code class="filename">.diff.gz</code>.  CDBS
      lets you hook in arbitrary patch systems, but (as with the rest
      of CDBS), it has its own default implementation, called
      <code class="filename">simple-patchsys.mk</code>.  To use it, just
      add

      </p><pre class="programlisting">include /usr/share/cdbs/1/rules/simple-patchsys.mk</pre><p>

      to your <code class="filename">debian/rules</code>.  Now, you can drop
      patch files into the <code class="filename">debian/patches</code>
      directory, and they will be automatically applied and unapplied.
      Files should be named so as to reflect in which order they have
      to be applied, and must end in a <code class="filename">.patch</code> or
      <code class="filename">.diff</code> suffix.  The simple patchsys rules
      will then take care of patching before configure and unpatching
      after clean.  It is possible to use patch level 0 to 3, and CDBS
      will try them and use the right level automatically.  The system
      can handle compressed patches with an additionnal
      <code class="filename">.gz</code> or <code class="filename">.bz2</code> suffix as
      well as uuencoded patches with a <code class="filename">.uu</code>
      suffix.</p><p>You can customize the directories where patches are
      searched and the suffix like this:
</p><pre class="programlisting">
DEB_PATCHDIRS = debian/mypatches
DEB_PATCH_SUFFIX = .plop
</pre><p>
      The defaults are: <code class="filename">.diff</code>,
      <code class="filename">.diff.gz</code>, <code class="filename">.diff.bz2</code>,
      <code class="filename">.diff.uu</code>, <code class="filename">.patch</code>,
      <code class="filename">.patch.gz</code>, <code class="filename">.patch.bz2</code>,
      <code class="filename">.patch.uu</code>.</p><p>In case of errors when applying, for example
      <code class="filename">debian/pacthes/01_hurd_ftbfs_pathmax.patch</code>,
      you can read the log for this patch in
      <code class="filename">debian/pacthes/01_hurd_ftbfs_pathmax.patch.level-0.log</code>
      (<span class="quote">“<span class="quote">0</span>”</span> because it's a level 0 patch).</p><p>When using the simple patch system, a build dependency on
      <code class="literal">patchutils</code> should be added to the
      package.</p><p>The script <span class="command"><strong>cdbs-edit-patch</strong></span> is intended
      to help lazy people edit or create patches easily.  Invoke this
      script with the name of the patch as argument, and you will
      enter a copy of your working directory in a subshell where you
      can edit the sources.  When your work is done and you are
      satisfied with your changes, just exit the subshell and you will
      get back to normal world with
      <code class="filename">debian/patches/<em class="replaceable"><code>patch_name</code></em>.patch</code>
      created or modified accordingly.  The script takes care to apply
      previous patches (ordered patches needed!), the current patch if
      already existing (in case you want to update it), then generate
      an incremental diff to only get desired modifications.  If you
      want to cancel the patch creation or modification, you only need
      to exit the subshell with a nonzero value and the diff will not
      be generated (only cleanups will be done).</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497407328"></a>Patching Sources Using Dpatch</h2></div></div></div><p>Like the simple patch system detailed previously, the
      Dpatch patch system allows you to seperate your changes to the
      upstream tarball into multiple seperate patches instead of a
      monolithic <code class="filename">diff.gz</code>.  This is a wrapper to
      the tools contained in the <code class="literal">dpatch</code> Debian
      package, and it's named <code class="filename">dpatch.mk</code>.  To use
      it, add

      </p><pre class="programlisting">include /usr/share/cdbs/1/rules/dpatch.mk</pre><p>

      to your <code class="filename">debian/rules</code>.  If you use
      <code class="filename">autotools.mk</code>, be sure to include
      <code class="filename">dpatch.mk</code> <span class="emphasis"><em>after</em></span>
      <code class="filename">autotools.mk</code>.  Additionally, remember to
      add <code class="literal">dpatch</code> to your build dependencies.</p><p>Now you can use Dpatch as usual and CDBS will call it
      automatically.  For a more complete treatment of Dpatch files,
      their format, and their application, please read the
      documentation included in the <code class="literal">dpatch</code> package,
      notably <code class="filename">/usr/share/doc/dpatch/README.gz</code> and
      the <span class="command"><strong>dpatch</strong></span> man page.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497397376"></a>Patching Sources Using Quilt</h2></div></div></div><p>Quilt is yet another patch management system.  CDBS itself
      does not actually contain any Quilt support, but the Quilt
      package contains CDBS integration, so there is really no
      difference from the perspective of the user.  To use Quilt with
      CDBS, add

      </p><pre class="programlisting">/usr/share/cdbs/1/rules/patchsys-quilt.mk</pre><p>

      to your <code class="filename">debian/rules</code> and add
      <code class="literal">quilt</code> to the build dependencies.  Read the
      documentation in the Quilt package for more information.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497393936"></a>Standard Patch System Targets</h2></div></div></div><p>The most popular patch systems in Debian, the CDBS Simple
      Patch System, DPatch, and Quilt, support the following uniform
      make targets that you can use directly to apply and unapply the
      patches.  This could be useful during package development.  Of
      course, the patches are automatically applied or unapplied as
      necessary when a full package build is performed.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">patch</code></span></dt><dd><p>to apply the patches</p></dd><dt><span class="term"><code class="literal">unpatch</code></span></dt><dd><p>to unapply the patches</p></dd></dl></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814503314576"></a>Tarball-Inside-a-Tarball Build System</h2></div></div></div><p>Some Debian packagers may be familiar with DBS, where you
      include a tarball of the upstream source inside the Debian
      source package itself.  This has some advantages and some
      disadvantages, but CDBS supports it anyhow.  To use the CDBS
      tarball system, just add this line to your
      <code class="filename">debian/rules</code>, and specify the name of the
      top directory of the extracted tarball:
</p><pre class="programlisting">
DEB_TAR_SRCDIR = foosoft

include /usr/share/cdbs/1/rules/tarball.mk
</pre><p>
      Note that <code class="filename">tarball.mk</code> must be
      <span class="emphasis"><em>first</em></span> in the list of included rules.</p><p>CDBS will recognize tarballs with the following
      extensions: <code class="filename">.tar</code>,
      <code class="filename">.tgz</code>, <code class="filename">.tar.gz</code>,
      <code class="filename">.tar.bz</code>, <code class="filename">.tar.bz2</code>,
      <code class="filename">.zip</code>.  The tarball location is autodetected
      if it is in the top source directory, or can be specified:
</p><pre class="programlisting">
DEB_TARBALL = $(CURDIR)/tarballdir/mygnustuff_beta-1.2.3.tar.gz
</pre><p>
      </p><p>CDBS will handle automatic extraction and cleanups,
      automatically set <code class="varname">DEB_SRCDIR</code> and
      <code class="varname">DEB_BUILDDIR</code> for you, and take care of proper
      integration with other CDBS parts (such as the autotools
      class).</p><p>Note that a build dependency on <code class="filename">bzip2</code>
      or <code class="filename">unzip</code> may be in order if that is the
      format of the tarball.  The <code class="filename">gzip</code> package is
      essential, so no build dependency is necessary for it.</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497367216"></a><code class="filename">debian/control</code> Management</h2></div></div></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>This feature is considered broken and packages using it
        are not allowed into the Debian archive.</p></div><p>The <code class="filename">debian/control</code> management feature
      allows:

      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>CDBS to manage some build dependencies
          automatically</p></li><li class="listitem"><p>use of shell commands embedded in
          <code class="filename">debian/control</code></p></li><li class="listitem"><p>use of CPU and system criteria to specify
          architecture (experimental)</p></li></ul></div><p>
      </p><p>Build dependencies are introduced by the use of certain
      CDBS features or autodetected.</p><p>Embedded shell commands allows including hacks like:
</p><pre class="programlisting">
Build-Depends: libgpm-dev [`type-handling any linux-gnu`]
</pre><p>
      </p><p>CPU and system criteria implement support for
      <code class="literal">Cpu</code>/<code class="literal">System</code> fields, as a
      replacement for the Architecture field (which is to be
      implemented in dpkg in the long term, but still experimental).
      Here is an example: before:
</p><pre class="programlisting">
Architecture: all
</pre><p>
      and after:
</p><pre class="programlisting">
Cpu: all
System: all
</pre><p>
      If these fields are used, it is also possible to include special
      tags to easily take advantage of the
      <span class="command"><strong>type-handling</strong></span> tool, like in this example:
</p><pre class="programlisting">
Build-Depends: @cdbs@, procps [system: linux], plop [cpu: s390]
</pre><p>
      (Look at the <span class="command"><strong>type-handling</strong></span> package
      documentation for more information.)</p><div class="procedure"><a id="idm45814497354064"></a><p class="title"><strong>Procedure 4.1. <code class="filename">debian/control</code> Management</strong></p><ol class="procedure" type="1"><li class="step"><p>Rename <code class="filename">debian/control</code> to
          <code class="filename">debian/control.in</code>.</p></li><li class="step"><p>Replace <code class="literal">cdbs</code> and
          <code class="literal">debhelper</code> build dependencies with
          <code class="literal">@cdbs@</code> in your
          <code class="filename">debian/control.in</code> like this:

</p><pre class="programlisting">Build-Depends-Indep: @cdbs@, python-dev (&gt;= 2.3), python-soya (&gt;= 0.9), python-soya (&lt;&lt; 0.10), python-openal(&gt;= 0.1.4-4), gettext</pre><p>

          </p></li><li class="step"><p>Add the following line to
          <code class="filename">debian/rules</code>, before
          <span class="emphasis"><em>any</em></span> include:
</p><pre class="programlisting">
DEB_AUTO_UPDATE_DEBIAN_CONTROL = yes
</pre><p>
          </p></li><li class="step"><p>Then do a <span class="command"><strong>debian/rules clean</strong></span> run to
          (re)generate <code class="filename">debian/control</code>.</p></li></ol></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="idm45814497341040"></a>Chapter 5. Hall of Examples</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#idm45814497339680">GNOME + Autotools + Simple Patch System Example</a></span></dt><dt><span class="sect1"><a href="#idm45814497333568">Python Example</a></span></dt><dt><span class="sect1"><a href="#idm45814497324416">Makefile + Dpatch example</a></span></dt><dt><span class="sect1"><a href="#idm45814497316624">Perl Examples</a></span></dt><dt><span class="sect1"><a href="#example-ant">Ant Example</a></span></dt></dl></div><p>There are as of this writing more than a thousand packages
    in the Debian archive that use CDBS, so there is a rich source of
    examples.  Nonetheless, to complete this manual, here are a few
    representative examples of real packages using CDBS so you get an
    idea of how to put these things together.</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497339680"></a>GNOME + Autotools + Simple Patch System Example</h2></div></div></div><p>This example is from the package
      <code class="literal">gnome-panel</code>.</p><p><code class="filename">debian/control.in</code>:
          </p><pre class="programlisting">
Source: gnome-panel
Section: gnome
Priority: optional
Maintainer: Guilherme de S. Pastore &lt;guilherme.pastore@terra.com.br&gt;
Uploaders: Sebastien Bacher &lt;seb128@debian.org&gt;, Arnaud Patard &lt;arnaud.patard@rtp-net.org&gt;, @GNOME_TEAM@
Standards-Version: 3.6.2.1
Build-Depends: @cdbs@, liborbit2-dev (&gt;= 1:2.12.1-1), intltool, gnome-pkg-tools, libgtk2.0-dev (&gt;= 2.7.1), libglade2-dev (&gt;= 1:2.5.1), libwnck-dev (&gt;= 2.11.91-1), scrollkeeper (&gt;= 0.3.14-9.1), libgnome-desktop-dev (&gt;= 2.11.1), libpng3-dev, libbonobo2-dev (&gt;= 2.8.1-2), libxmu-dev, libedata-cal1.2-dev (&gt;= 1.2.1-1) [!hurd-i386], libgnome-menu-dev (&gt;= 2.11.1-1), libgnomevfs2-dev (&gt;= 2.10.0-1), libnspr-dev, libxres-dev, sharutils, gnome-doc-utils, libedataserverui1.2-dev (&gt;= 1.3.0)

Package: gnome-panel
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}, gnome-panel-data (= ${Source-Version}), gnome-desktop-data (&gt;= 2.10.0-1), gnome
-control-center (&gt;= 1:2.8.2-3), gnome-menus (&gt;= 2.11.1-1), gnome-about (&gt;= 2.10.0-1)
Recommends: gnome-applets (&gt;= 2.12.1-1), gnome-session, menu-xdg (&gt;= 0.2)
Suggests: yelp, gnome2-user-guide, gnome-terminal, gnome-system-tools, nautilus
Description: launcher and docking facility for GNOME 2
...</pre><p>
      </p><p><code class="filename">debian/rules</code>:
          </p><pre class="programlisting">
#!/usr/bin/make -f

# Gnome Team
include /usr/share/gnome-pkg-tools/1/rules/uploaders.mk

include /usr/share/cdbs/1/rules/debhelper.mk
# Including this file gets us a simple patch system.  You can just
# drop patches in debian/patches, and they will be automatically
# applied and unapplied.
include /usr/share/cdbs/1/rules/simple-patchsys.mk
# Including this gives us a number of rules typical to a GNOME
# program, including setting GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL=1.
# Note that this class inherits from autotools.mk and docbookxml.mk,
# so you don't need to include those too.
include /usr/share/cdbs/1/class/gnome.mk

DEB_CONFIGURE_SCRIPT_ENV += LDFLAGS="-Wl,-z,defs -Wl,-O1 -Wl,--as-needed"
DEB_CONFIGURE_EXTRA_FLAGS := --disable-scrollkeeper
ifneq ($(DEB_BUILD_GNU_SYSTEM),gnu)
	DEB_CONFIGURE_EXTRA_FLAGS += --enable-eds
endif

# debug lib
DEB_DH_STRIP_ARGS := --dbg-package=libpanel-applet-2

# tight versioning
DEB_NOREVISION_VERSION := $(shell dpkg-parsechangelog | egrep '^Version:' | cut -f 2 -d ' ' | cut -f 1 -d '-')
DEB_DH_MAKESHLIBS_ARGS_libpanel-applet2-0 := -V"libpanel-applet2-0 (&gt;= $(DEB_NOREVISION_VERSION))"
DEB_SHLIBDEPS_LIBRARY_gnome-panel:= libpanel-applet2-0
DEB_SHLIBDEPS_INCLUDE_gnome-panel := debian/libpanel-applet2-0/usr/lib/


binary-install/gnome-panel::
	chmod a+x debian/gnome-panel/usr/lib/gnome-panel/*

binary-install/gnome-panel-data::
	chmod a+x debian/gnome-panel-data/etc/menu-methods/gnome-panel-data
	find debian/gnome-panel-data/usr/share -type f -exec chmod -R a-x {} \;

binary-install/libpanel-applet2-doc::
	find debian/libpanel-applet2-doc/usr/share/doc/libpanel-applet2-doc/ -name ".arch-ids" -depth -exec rm -rf {} \;

clean::
	# GNOME Team 'uploaders.mk' should not override this behavior, here is a workarround :
	sed -i "s/@cdbs@/$(CDBS_BUILD_DEPENDS)/g" debian/control</pre><p>
      </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497333568"></a>Python Example</h2></div></div></div><p>This example is from the package <code class="literal">pmock</code>.
      It builds Python modules for version 2.3 and 2.4 as well as a
      metapackage without writing any custom rules.</p><p><code class="filename">debian/control</code>:
          </p><pre class="programlisting">
Source: pmock
Section: python
Priority: optional
Maintainer: Jan Alonzo &lt;jmalonzo@unpluggable.com&gt;
Build-Depends: debhelper (&gt;= 4.1.67), cdbs, python2.3-dev, python2.4-dev, python-dev (&gt;= 2.3)
Standards-Version: 3.6.1.1

Package: python-pmock
Architecture: all
Depends: ${python:Depends}, python (&gt;= 2.3), python (&lt;&lt; 2.5)
Description: Python module for unit testing using mock objects
 Mock Objects is a test-first development process for building object-oriented
 software and a generic unit testing framework that supports that process.
 .
 This package allows you to use Mock Objects for unit testing Python programs.
 .
 This is a dependency package which selects Debian's default Python version.
 .
  Homepage: http://pmock.sourceforge.net

Package: python2.3-pmock
Architecture: all
Depends: ${python:Depends}, python2.3
Description: Python module for unit testing using mock objects
 Mock Objects is a test-first development process for building object-oriented
 software and a generic unit testing framework that supports that process.
 .
 This package allows you to use Mock Objects for unit testing Python programs.
 .
  Homepage: http://pmock.sourceforge.net

Package: python2.4-pmock
Architecture: all
Depends: ${python:Depends}, python2.4
Description: Python module for unit testing using mock objects
 Mock Objects is a test-first development process for building object-oriented
 software and a generic unit testing framework that supports that process.
 .
 This package allows you to use Mock Objects for unit testing Python programs.
 .
  Homepage: http://pmock.sourceforge.net</pre><p>
      </p><p>
        <code class="filename">debian/rules</code>:
          </p><pre class="programlisting">
#!/usr/bin/make -f
# -*- makefile -*-

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/python-distutils.mk</pre><p>
      </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497324416"></a>Makefile + Dpatch example</h2></div></div></div><p>This example is from the package <code class="literal">apg</code>.</p><p><code class="filename">debian/control.in</code>:
          </p><pre class="programlisting">
Source: apg
Section: admin
Priority: optional
Maintainer: Marc Haber &lt;mh+debian-packages@zugschlus.de&gt;
Build-Depends: @cdbs@
Standards-Version: 3.6.1

Package: apg
Architecture: any
Depends: ${shlibs:Depends}
Description: Automated Password Generator - Standalone version
 APG (Automated Password Generator) is the tool set for random
 password generation. It generates some random words of required type
 and prints them to standard output. This binary package contains only
 the standalone version of apg.
 Advantages:
  * Built-in ANSI X9.17 RNG (Random Number Generator)(CAST/SHA1)
  * Built-in password quality checking system (now it has support for Bloom
    filter for faster access)
  * Two Password Generation Algorithms:
     1. Pronounceable Password Generation Algorithm (according to NIST
        FIPS 181)
     2. Random Character Password Generation Algorithm with 35
        configurable modes of operation
  * Configurable password length parameters
  * Configurable amount of generated passwords
  * Ability to initialize RNG with user string
  * Support for /dev/random
  * Ability to crypt() generated passwords and print them as additional output.
  * Special parameters to use APG in script
  * Ability to log password generation requests for network version
  * Ability to control APG service access using tcpd
  * Ability to use password generation service from any type of box (Mac,
    WinXX, etc.) that connected to network
  * Ability to enforce remote users to use only allowed type of password
    generation
 The client/server version of apg has been deliberately omitted.
 .
 Upstream URL: http://www.adel.nursat.kz/apg/download.shtml</pre><p>
      </p><p>
        <code class="filename">debian/rules</code>:
          </p><pre class="programlisting">
#!/usr/bin/make -f

# to re-generate debian/control, invoke
# fakeroot debian/rules debian/control DEB_AUTO_UPDATE_DEBIAN_CONTROL:=yes

# automatic debian/control generation disabled, cdbs bug #311724.

DEB_MAKE_CLEAN_TARGET    := clean
DEB_MAKE_BUILD_TARGET    := standalone
DEB_MAKE_INSTALL_TARGET  := install INSTALL_PREFIX=$(CURDIR)/debian/apg/usr

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/rules/dpatch.mk
include /usr/share/cdbs/1/class/makefile.mk

cleanbuilddir/apg::
	rm -f build-stamp configure-stamp php.tar.gz

install/apg::
	mv $(CURDIR)/debian/apg/usr/bin/apg $(CURDIR)/debian/apg/usr/lib/apg/apg
	tar --create --gzip --file php.tar.gz --directory $(CURDIR)/php/apgonline/ .
	install -D --mode=0644 php.tar.gz $(CURDIR)/debian/apg/usr/share/doc/apg/php.tar.gz
	rm php.tar.gz
	install -D --mode=0755 $(CURDIR)/debian/apg.wrapper $(CURDIR)/debian/apg/usr/bin/apg
	install -D --mode=0644 $(CURDIR)/debian/apg.conf $(CURDIR)/debian/apg/etc/apg.conf

# bug #284231
unpatch: deapply-dpatches</pre><p>

       (Be advised that bug #284231 has been fixed in the meantime.)</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm45814497316624"></a>Perl Examples</h2></div></div></div><p>This example is from the package
      <code class="literal">libmidi-perl</code>.  It builds a Perl
      module.</p><p><code class="filename">debian/control</code>:
</p><pre class="programlisting">
Source: libmidi-perl
Section: interpreters
Priority: optional
Build-Depends: cdbs (&gt;= 0.4.4), debhelper (&gt;= 4.1.0), perl (&gt;= 5.8.0-7)
Maintainer: Mario Lang &lt;mlang@debian.org&gt;
Standards-Version: 3.5.10

Package: libmidi-perl
Architecture: all
Depends: ${perl:Depends}
Description: read, compose, modify, and write MIDI files in Perl
 This suite of Perl modules provides routines for reading, composing,
 modifying, and writing MIDI files.</pre><p>
      </p><p><code class="filename">debian/rules</code>:
</p><pre class="programlisting">
#!/usr/bin/make -f

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/perlmodule.mk</pre><p>
      </p><p>This example is from the package
      <code class="literal">libgd-graph-perl</code>.  It illustrates the
      occasional need to set variables and add customized
      rules.</p><p><code class="filename">debian/control</code>:
</p><pre class="programlisting">
Source: libgd-graph-perl
Section: perl
Priority: extra
Maintainer: Jonas Smedegaard &lt;dr@jones.dk&gt;
Standards-Version: 3.6.1
Build-Depends-indep: cdbs, debhelper (&gt;= 4.1), perl (&gt;= 5.6.0-16), libgd-text-perl (&gt;= 0.80), imagemagick, dh-buildinfo

Package: libgd-graph-perl
Architecture: all
Depends: libgd-text-perl (&gt;= 0.80)
Description:  Graph Plotting Module for Perl 5
 GD::Graph is a perl5 module to create charts using the GD module.
 The following classes for graphs with axes are defined:
 .
 GD::Graph::lines - Create a line chart.
 GD::Graph::bars - Create a bar chart.
 GD::Graph::points - Create an chart, displaying the data as points.
 GD::Graph::linespoints - Combination of lines and points.
 GD::Graph::area - Create a graph, representing the data as areas under a
     line.
 GD::Graph::mixed - Create a mixed type graph, any combination of the
     above. At the moment this is fairly limited. Some of
     the options that can be used with some of the
     individual graph types won't work very well. Multiple
     bar graphs in a mixed graph won't display very nicely.
 GD::Graph::pie - Create a pie chart.</pre><p>
      </p><p><code class="filename">debian/rules</code>:
</p><pre class="programlisting">
#!/usr/bin/make -f
# -*- mode: makefile; coding: utf-8 -*-
# Copyright ~~ 2003 Jonas Smedegaard &lt;dr@jones.dk&gt;

# Put perlmodule.mk last to dh_clean temporary files not in MANIFEST
include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/perlmodule.mk

DEB_INSTALL_EXAMPLES_libgd-graph-perl := samples Dustismo_Sans.ttf

# Upstream says creating samples is a better test so do both
DEB_MAKE_CHECK_TARGET := test samples

# Clean explicitly, as upstream make target "clean" in samples is broken
clean::
	rm -f $(CURDIR)/samples/sample*.png $(CURDIR)/samples/sample*.gif $(CURDIR)/samples/logo.gif

# Add build info
common-binary-post-install-indep::
	dh_buildinfo</pre><p>
      </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="example-ant"></a>Ant Example</h2></div></div></div><p>This example is from the package <code class="literal">jline</code>.
     Here you can see how to use the Ant class and set up rules that
     install the package in a policy-conforming way.</p><p><code class="filename">debian/control</code>:
</p><pre class="programlisting">
Source: jline
Section: libs
Priority: optional
Maintainer: Debian Java Maintainers &lt;pkg-java-maintainers@lists.alioth.debian.org&gt;
Uploaders: Varun Hiremath &lt;varun@debian.org&gt;, Kumar Appaiah &lt;akumar@ee.iitm.ac.in&gt;,
 Torsten Werner &lt;twerner@debian.org&gt;
Build-Depends: cdbs, debhelper (&gt;= 5), default-jdk, ant
Build-Depends-Indep: maven-repo-helper, junit, openjdk-6-doc
Standards-Version: 3.8.2
Homepage: http://jline.sourceforge.net/
Vcs-Svn: svn://svn.debian.org/svn/pkg-java/trunk/jline
Vcs-Browser: http://svn.debian.org/wsvn/pkg-java/trunk/jline

Package: libjline-java
Section: libs
Architecture: all
Depends: ${misc:Depends}, default-jre-headless | java2-runtime-headless | java1-runtime-headless
Suggests: libjline-java-doc
Description: Java library for handling console input
 JLine is a 100% pure Java library for reading and editing console input.
 It is similar in functionality to BSD editline and GNU readline.  People
 familiar with the readline/editline capabilities for modern shells will
 find most of the command editing features of JLine to be familiar.

Package: libjline-java-doc
Section: doc
Architecture: all
Depends: ${misc:Depends}, openjdk-6-doc | classpath-doc
Suggests: libjline-java
Description: documentation for JLine
 JLine is a 100% pure Java library for reading and editing console input.
 It is similar in functionality to BSD editline and GNU readline.  People
 familiar with the readline/editline capabilities for modern shells will
 find most of the command editing features of JLine to be familiar.
 .
 This package contains the documentation for JLine.
</pre><p>
      </p><p><code class="filename">debian/rules</code>
</p><pre class="programlisting">
#!/usr/bin/make -f

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/ant.mk

PACKAGE              := $(DEB_SOURCE_PACKAGE)
VERSION              := $(DEB_UPSTREAM_VERSION)
JAVA_HOME                    := /usr/lib/jvm/default-java
DEB_JARS                     := junit
DEB_ANT_BUILDFILE        := debian/build.xml
DEB_ANT_BUILD_TARGET := jar javadoc

DEB_INSTALL_EXAMPLES_libjline-java-doc = jline-demo.jar

binary-post-install/lib$(PACKAGE)-java::
        mh_installpoms -plib$(PACKAGE)-java
        mh_installjar -plib$(PACKAGE)-java -l debian/pom.xml jline.jar

clean::
        -rm -rf debian/tmp

get-orig-source:
        -uscan --upstream-version 0

get-orig-pom:
        wget -O debian/pom.xml http://repository.sonatype.org/service/local/repositories/central/content/jline/jline/$(VERSION)/jline-$(VERSION).pom
	</pre><p>
      </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="idm45814497381760"></a>Chapter 6. Conclusion</h1></div></div></div><p>CDBS solves most common problems in building Debian
    packages, and it is very pleasant to use.  More and more Debian
    packagers are using it, not because they are obliged to, but
    because they tasted and found it could improve their packages and
    avoid losing time on constantly reinventing silly and complicated
    rules.</p><p>CDBS is not perfect.  It is not yet capable of handling very
    complicated situations, like packages where multiple C or C++ builds
    with different options and/or patches are required, but this only
    affects a very small number of packages.  These limitations are
    planned to be solved in CDBS2, which is work in progress.</p><p>Using CDBS more widely would improve Debian's overall
    quality.  Don't hesitate trying it, talking to your friends about
    it, and contributing.</p><p>Have a lot of fun with CDBS !!! :-)</p></div><div class="colophon"><h1 class="title"><a id="idm45814497376496"></a>Thanks</h1><p>This document was originally written by Marc Dequènes and
    Arnaud Patard with the following revision history:

    </p><div class="revhistory"><table style="border-style:solid; width:100%;" summary="Revision History"><tr><th align="left" valign="top" colspan="3"><strong>Revision History</strong></th></tr><tr><td align="left">Revision 0.1.0</td><td align="left">2005-04-03</td><td align="left"> </td></tr><tr><td align="left" colspan="3">First Public Release (for CDBS V0.4.27-3)</td></tr><tr><td align="left">Revision 0.1.1</td><td align="left">2005-06-07</td><td align="left"> </td></tr><tr><td align="left" colspan="3">Updated for CDBS V0.4.30 (perl class build dependency management, cdbs-edit-patch script)</td></tr><tr><td align="left">Revision 0.1.2</td><td align="left">2005-07-05</td><td align="left"> </td></tr><tr><td align="left" colspan="3">Added DEB_CONFIGURE_SCRIPT_ENV usage warning, fixed typo.</td></tr></table></div><p>
    </p><p>Thanks to Jeff Bailey for his patience and for replying to
    so many questions.</p><p>Special thanks to GuiHome for helping by reviewing this
    documentation.</p><p>This document is a <a class="ulink" href="http://docbook.org/" target="_top">DocBook</a> application, checked
    using xmllint (from <a class="ulink" href="http://www.xmlsoft.org/" target="_top">libxml2</a>), produced using
    xsltproc (from <a class="ulink" href="http://xmlsoft.org/XSLT/" target="_top">libxslt</a>), using the <a class="ulink" href="http://nwalsh.com/" target="_top">N. Walsh</a> and <a class="ulink" href="http://dblatex.sourceforge.net/" target="_top">dblatex</a> XLST
    stylesheets, and converted with <a class="ulink" href="http://www.latex-project.org/" target="_top">LaTeX</a> tools (latex,
    mkindex, pdflatex &amp; dvips) / <a class="ulink" href="http://research.compaq.com/SRC/virtualpaper/pstotext.html" target="_top">pstotext</a>
    (with <a class="ulink" href="http://www.cs.wisc.edu/~ghost/" target="_top">GS</a>).</p></div></div>
</html>