[Build-common-hackers] Bug#213374: marked as done (cdbs: README in DocBook/XML)

Debian Bug Tracking System owner@bugs.debian.org
Wed, 15 Oct 2003 22:33:10 -0500

Your message dated Wed, 15 Oct 2003 23:22:02 -0400
with message-id <1066274521.23652.4.camel@columbia>
and subject line applied
has caused the attached Bug report to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what I am
talking about this indicates a serious mail system misconfiguration
somewhere.  Please contact me immediately.)

Debian bug tracking system administrator
(administrator, Debian Bugs database)

Received: (at submit) by bugs.debian.org; 30 Sep 2003 02:44:23 +0000
>From knorke.in-berlin.de!debacle@knorke.in-berlin.de Mon Sep 29 21:44:22 2003
Return-path: <knorke.in-berlin.de!debacle@knorke.in-berlin.de>
Received: from hirsch.in-berlin.de [] 
	by master.debian.org with esmtp (Exim 3.35 1 (Debian))
	id 1A3sYp-0007Mk-00; Mon, 29 Sep 2003 02:35:11 -0500
Received: from hirsch.in-berlin.de (localhost [])
	by hirsch.in-berlin.de (8.12.9/8.12.9/Debian-1) with ESMTP id h8T7ZAjS031249
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT);
	Mon, 29 Sep 2003 09:35:10 +0200
Received: from knorke.UUCP (uucp@localhost)
	by hirsch.in-berlin.de (8.12.9/8.12.9/Debian-1) with UUCP id h8T7ZAuN031240;
	Mon, 29 Sep 2003 09:35:10 +0200
X-Envelope-From: knorke.in-berlin.de!debacle@knorke.in-berlin.de
X-Envelope-To: submit@bugs.debian.org
Received: from k6.in-berlin.de (really []) by knorke.in-berlin.de
	via in.smtpd with esmtp
	id <m1A3sWx-000RBWC@knorke.in-berlin.de> (Debian Smail3.2.0.102)
	for <debacle@debian.org>; Mon, 29 Sep 2003 07:33:15 +0000 (GMT) 
Received: from debacle by k6.in-berlin.de with local (Exim 3.36 #1 (Debian))
	id 1A3sWv-0001nh-00; Mon, 29 Sep 2003 09:33:13 +0200
Content-Type: multipart/mixed; boundary="===============1686981912=="
MIME-Version: 1.0
From: "W. Borgert" <debacle@debian.org>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: cdbs: README in DocBook/XML
Reply-To: debacle@debian.org
X-Mailer: reportbug 2.30
Date: Mon, 29 Sep 2003 07:33:13 +0000
Message-Id: <E1A3sWv-0001nh-00@k6.in-berlin.de>
Sender: debacle <debacle@k6.in-berlin.de>
X-Scanned-By: MIMEDefang 2.35
Delivered-To: submit@bugs.debian.org
X-Spam-Status: No, hits=1.5 required=4.0
X-Spam-Level: *
X-Spam-Checker-Version: SpamAssassin 2.53-bugs.debian.org_2003_9_21 (

This is a multi-part MIME message sent by reportbug.

Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

Package: cdbs
Version: 0.4.8
Severity: normal
Tags: patch

In the TODO a README in DocBook/XML format is requested.
See attachment cdbs.dbk.

Content-Type: text/xml; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cdbs.dbk"

<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    <title>Introduction to the Common Debian Build System</title>

    <para>In a single sentence: CDBS is a framework based on
    Makefile inheritance for building Debian packages.</para>

    <para>It is essentially a set of Makefile fragments which you may
    include into your <filename>debian/rules</filename>.  Each
    makefile fragment can have effects in different parts of your
    build process.</para>

    <para>The original motivating factor for CDBS was originally that
    more and more programs today are created using GNU configure
    scripts and GNU automake, and as such they are all very similar to
    configure and build.  I realized that a lot of duplicated code in
    everyone's debian/rules could be factored out.  But CDBS isn't
    only useful for packages which use the GNU autotools.  It is a
    flexible core upon which you can create your own custom build

    <title>Versioning note</title>

    <para>CDBS might change incompatibly in the future, and to allow
    for this, all the rules and classes are in a verison-specific
    subdirectory.  That's the reason for the <literal>1</literal> in
    <filename>/usr/share/cbds/1</filename>.  For right now though,
    during the initial development of cdbs, when few packages are
    using it, I might break compatibility in small ways.  You will be
    warned if this happens.</para>

    <title><filename>buildcore.mk</filename>: A framework</title>

    <para>Every CDBS-using <filename>debian/rules</filename> should
    eventually include
    <filename>/usr/share/cdbs/1/rules/buildcore.mk</filename> (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
    <emphasis>do</emphasis> anything on its own.</para>

    <para>You can use the <filename>buildcore.mk</filename> rules to
    hook in your own build system to actually implement each stage of
    compiling, installing, and building .debs if you wish.</para>

    <title>Introduction to classes</title>

    <para>However, cdbs also provides <emphasis>classes</emphasis>
    which contain makefile rules and variables implementing some or
    all of these steps.  Classes tend to be declarative; they say your
    program has particular properties.  Suppose for instance that your
    package uses a regular Makefile to compile, and has the normal
    <command>make</command> and <command>make install</command>
    targets.  In that case, you can say:</para>

    <programlisting>include /usr/share/cdbs/1/class/makefile.mk</programlisting>

    <para>And you get all the code to run <command>make</command>
    automagically.  This basically works by adding code to the
    <literal>common-install-arch</literal>, and
    <literal>common-install-indep</literal> targets inside
    <filename>buildcore.mk</filename>.  It might be instructive to
    look at <filename>makefile.mk</filename> now.</para>

    <title><filename>debhelper.mk</filename>: A rule fragment</title>

    <para>The next important piece of the puzzle is to actually build
    .debs from the now compiled software.  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 another line like:</para>

    <programlisting>include /usr/share/cdbs/1/rules/debhelper.mk</programlisting>

    <para>Note that if you use <filename>debhelper.mk</filename>, you
    must add a Build-Depends on debhelper (>= 4.1.0).</para>

    <title>A full example</title>

    <para>With just the two lines above, you should have a reasonable
    first cut at a fully functional build system!  To recap, your
    debian/rules should now look like:</para>

    <programlisting>#!/usr/bin/make -f
include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/makefile.mk</programlisting>

    <para>And that's all!  Note that <filename>makefile.mk</filename>
    and <filename>debhelper.mk</filename> both include
    <filename>buildcore.mk</filename>, so you don't need to include it

    <para>Incidentally, you should usually include
    <filename>debhelper.mk</filename> first, before other rules.  This
    will turn on optional Debhelper-using parts of other rules, if
    any, which is usually what you want.</para>

    <title>Class inheritance</title>

    <para>Now, let's look at some common situations.  Say that your
    package uses GNU autoconf and automake.  In that case, you can use
    the provided <classname>autotools</classname> class.  One thing to
    note is that the autotools class actually builds upon the
    <classname>makefile</classname> class.  This
    <classname>autotools</classname> class will take care of details
    such as updating the <filename>config.{sub,guess}</filename>
    files, running <command>./configure</command> with the standard
    arguments, etc.  So now our debian/rules looks like:</para>

    <programlisting>#!/usr/bin/make -f
include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/autotools.mk</programlisting>


    <para>However, suppose you need to pass --disable-frobnication to
    ./configure.  How do you do this?  Well, it couldn't be easier.
    The <filename>autotools.mk</filename> file includes a number of
    variables which you can override, like this:</para>

    <programlisting>#!/usr/bin/make -f
include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/autotools.mk
DEB_CONFIGURE_EXTRA_FLAGS := --disable-frobnication</programlisting>

    <para>Note that the variable is set <emphasis>after</emphasis> the
    rule fragment is included.  This is necessary for it to have any
    effect.  There are a few exceptions to this; but generally
    variables should be set after rule fragments are included.</para>

    <para>Now, let's suppose your package is a little bit strange
    (e.g. Perl); perhaps it has a ./Configure script which 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 <literal>common-configure</literal> rule, by adding
    something like the following to your debian/rules:</para>

	./Configure --blah --blargh &lt; debian/answers</programlisting>

    <para>Note that if you do this, you can't include
    <filename>autotools.mk</filename>, since then you'll get
    <emphasis>two</emphasis> implementations of common-configure,
    which is sure to fail.  It would be nice to be able to partially
    override rule fragments; this is a tricky problem, but I hope to
    address it.</para>

    <title>Adding extra code</title>

    <para>Suppose that your package generates extra cruft as a side
    effect of the build process that's not taken care of by the
    upstream <literal>clean</literal> rule, and ends up bloating your
    diff.  To handle this (until upstream fixes it), you can simply
    add stuff to the <literal>clean</literal> rule as follows:</para>

	rm -f foo/blah.o po/.intltool-merge-cache</programlisting>

    <para>Almost all of the current rules are <emphasis>double
    colon</emphasis> rules (See the GNU Make manual).  This means you
    can simply add to them without overriding the default.</para>

    <para>You can also add dependencies to the rules.  For example,
    suppose you have a multi-binary package which 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:</para>

    <programlisting>binary/program:: binary/libfoo</programlisting>

    <para>However, this must come <emphasis>before</emphasis> you
    include <filename>buildcore.mk</filename>.  This is due to the way
    make works.</para>

    <para>And speaking of multi-binary packages:</para>

    <title><filename>makefile.mk</filename> and Single vs. Multi
    Binary packages</title>

    <para>If you have a single binary package, the default
    <literal>common-install</literal> implementation in
    <filename>makefile.mk</filename> tries to use the upstream
    Makefile to install everything into debian/packagename, so it will
    all appear in the binary package.  If you're using
    <filename>debhelper.mk</filename>, to remove files, move them
    around, just override the binary-post-install/&lt;packagename&gt;

	mv debian/mypackage/usr/sbin/myprogram debian/mypackage/usr/bin/myprogram
	rm debian/mypackage/usr/share/doc/mypackage/INSTALL</programlisting>

    <para>If you have a multi-binary package,
    <filename>makefile.mk</filename> (by default) uses the upstream
    Makefile to install everything in debian/tmp.  After this, the
    recommended method is to use <filename>debhelper.mk</filename>
    (which uses <command>dh_install</command>) to copy these files
    into the appropriate package.  To do this, just create
    <filename>packagename.install</filename> files; see the
    <command>dh_install</command> man page.</para>

    <title>A simple patch system</title>

    <para>Suppose you'd like to keep separated patches, instead of
    having them all in your .diff.gz.  cdbs lets you hook in arbitrary
    patch systems, but (as with the rest of cdbs), it has its own
    default implementation, called
    <filename>simple-patchsys.mk</filename>.  To use it, just

    <programlisting>include /usr/share/cdbs/1/rules/simple-patchsys.mk</programlisting>

    <para>to your <filename>debian/rules</filename>.  Now, you can
    drop patch files into the <filename>debian/patches</filename>
    directory, and they will be automatically applied and unapplied.
    Note that currently patches must end in

    <title>DBS (tarball-inside-a-tarball) build system</title>

    <para>Some Debian developers may be familiar with DBS, where you
    include a tarball of the source inside the Debian source package
    itself.  This has some advantages, and some disadvantages.  If
    you'd like to use this, just include
    <filename>tarball.mk</filename>, and specify
    <varname>DEB_TAR_SRCDIR</varname>.  Note that it must be
    <emphasis>first</emphasis> in the list of included rules.</para>

    <title>Common build problems</title>

      <title>Build fails to to missing include files or something</title>

      <para>Often this is caused by the fact that cdbs passes
      <varname>CFLAGS</varname> along with the make invocation.  A
      sane build system allows this - <varname>CFLAGS</varname> are
      for the user to customize.  Setting <varname>CFLAGS</varname>
      shouldn't override other internal flags used in the package like
      -I.  However if fixing the upstream source is too difficult, you
      may do this:</para>

      <programlisting>DEB_MAKE_INVOKE := $(DEB_MAKE_ENVVARS) make -C $(DEB_BUILDDIR)</programlisting>

      <para>That will avoid passing <varname>CFLAGS</varname>.  But
      note this breaks the automatic implementation of


Received: (at 213374-done) by bugs.debian.org; 16 Oct 2003 03:25:04 +0000
>From walters@verbum.org Wed Oct 15 22:25:03 2003
Return-path: <walters@verbum.org>
Received: from monk.debian.net (monk.verbum.org) [] 
	by master.debian.org with esmtp (Exim 3.35 1 (Debian))
	id 1A9yl5-00009B-00; Wed, 15 Oct 2003 22:25:03 -0500
Received: from columbia (dhcp024-208-189-249.columbus.rr.com [])
	(using TLSv1 with cipher EDH-RSA-DES-CBC3-SHA (168/168 bits))
	(Client CN "columbia.verbum.org", Issuer "monk.verbum.org" (verified OK))
	by monk.verbum.org (Postfix (Debian/GNU)) with ESMTP id 17F1832A6CF
	for <213374-done@bugs.debian.org>; Wed, 15 Oct 2003 23:26:08 -0400 (EDT)
Received: by columbia (Postfix, from userid 1000)
	id 0E13726F776; Wed, 15 Oct 2003 23:22:02 -0400 (EDT)
Subject: applied
From: Colin Walters <walters@verbum.org>
To: 213374-done@bugs.debian.org
Content-Type: text/plain
Content-Transfer-Encoding: 7bit
Message-Id: <1066274521.23652.4.camel@columbia>
Mime-Version: 1.0
X-Mailer: Ximian Evolution 1.4.5 
Date: Wed, 15 Oct 2003 23:22:02 -0400
Delivered-To: 213374-done@bugs.debian.org
X-Spam-Status: No, hits=1.0 required=4.0
X-Spam-Level: *
X-Spam-Checker-Version: SpamAssassin 2.53-bugs.debian.org_2003_10_13 (

This patch has been applied, thank you!