[Build-common-hackers] Bug#243356: [Fwd: CDBS: suggestions]

Colin Walters Colin Walters <walters@debian.org>, 243356@bugs.debian.org
Mon, 12 Apr 2004 12:25:20 -0400


--=-kpB2adoZS098NwyOkPIY
Content-Type: multipart/mixed; boundary="=-dCjfk7IK+YEQjujvHsG0"


--=-dCjfk7IK+YEQjujvHsG0
Content-Type: text/plain
Content-Transfer-Encoding: quoted-printable

Package: cdbs
Tags: patch


--=-dCjfk7IK+YEQjujvHsG0
Content-Disposition: inline
Content-Description: Forwarded message - CDBS: suggestions
Content-Type: message/rfc822

Return-Path: <mw@miwie.in-berlin.de>
X-Original-To: walters@nexus.verbum.private
Delivered-To: walters@nexus.verbum.private
Received: from localhost (nexus.verbum.private [127.0.0.1]) by
	nexus.verbum.private (Postfix) with ESMTP id 0F80E174DA2 for
	<walters@nexus.verbum.private>; Sun, 11 Apr 2004 14:46:44 -0400 (EDT)
Delivered-To: walters@verbum.org
Received: from monk.debian.net [216.226.142.128] by localhost with IMAP
	(fetchmail-6.2.0) for walters@nexus.verbum.private (single-drop); Sun, 11
	Apr 2004 14:46:44 -0400 (EDT)
Received: from master.debian.org (master.debian.org [146.82.138.7]) by
	monk.verbum.org (Postfix (Debian/GNU)) with ESMTP id 15CBE32A6DD for
	<walters@verbum.org>; Sun, 11 Apr 2004 12:33:42 -0400 (EDT)
Received: from einhorn.in-berlin.de [192.109.42.8]  by master.debian.org
	with esmtp (Exim 3.35 1 (Debian)) id 1BChrp-000326-00; Sun, 11 Apr 2004
	11:31:33 -0500
X-Envelope-From: mw@miwie.in-berlin.de
X-Envelope-To: <walters@debian.org>
Received: from miwie.in-berlin.de (pD9E7CCB4.dip0.t-ipconnect.de
	[217.231.204.180]) (authenticated bits=0) by einhorn.in-berlin.de
	(8.12.10/8.12.10/Debian-4) with ESMTP id i3BGVXJm002538 for
	<walters@debian.org>; Sun, 11 Apr 2004 18:31:33 +0200
Received: from mw by miwie.in-berlin.de with local (Exim 3.36 #1 (Debian))
	id 1BChtn-0000Ky-00 for <walters@debian.org>; Sun, 11 Apr 2004 18:33:35
	+0200
Date: Sun, 11 Apr 2004 18:33:35 +0200
To: Colin Walters <walters@debian.org>
Subject: CDBS: suggestions
Message-ID: <20040411163335.GA1276@miwie.in-berlin.de>
Mime-Version: 1.0
Content-Type: multipart/mixed; boundary="vkogqOf2sHV7VnPd"
Content-Disposition: inline
X-Mailer: Mutt http://www.mutt.org/
X-PGP-Key: http://www.miwie.org/pubkey.asc
User-Agent: Mutt/1.5.5.1+cvs20040105i
From: Michael Wiedmann <mw@miwie.in-berlin.de>
X-Scanned-By: MIMEDefang 2.40
X-Spam-Checker-Version: SpamAssassin 2.63 (2004-01-11) on
	nexus.verbum.private
X-Spam-Level: 
X-Spam-Status: No, hits=-4.8 required=5.0 tests=BAYES_00,HTML_MESSAGE
	autolearn=no version=2.63


--vkogqOf2sHV7VnPd
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

Hi Colin,

Wolfgang Borgert <debacle@debian.org> pointed me to CDBS and I try to
understand it.

After fetching a copy of the CDBS CVS I had a look at the
documentation (which is not included in the deb!) and made some
changes (mainly consistent use of some markup tags regarding
filenames).

Attached you'll find a unified diff of my changes against the CVS
version. Feel free to use this in the way you like.

I'd really like to see the documentation included in the deb (at
least a HTML version) and it would be great if there were more
documentation which tries to describe the different makefile fragments
in detail.

Regards
Michael
--=20
mw@miwie.in-berlin.de                              http://www.miwie.org
mw@miwie.org

--vkogqOf2sHV7VnPd
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="cdbs.dbk.diff"
Content-Transfer-Encoding: quoted-printable

Index: cdbs.dbk
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
RCS file: /cvsroot/build-common/cdbs/docs/cdbs.dbk,v
retrieving revision 1.2
diff -u -r1.2 cdbs.dbk
--- cdbs.dbk	6 Oct 2003 01:00:28 -0000	1.2
+++ cdbs.dbk	11 Apr 2004 16:23:48 -0000
@@ -1,7 +1,7 @@
 <?xml version=3D'1.0' encoding=3D'ISO-8859-1'?>
 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-<article>
+<article lang=3D"en">
   <title>Introduction to the Common Debian Build System</title>
=20
   <articleinfo>
@@ -47,7 +47,7 @@
     </revhistory>
   </articleinfo>
=20
-  <para>In a single sentence: CDBS is a framework based on Makefile
+  <para>In a single sentence: CDBS is a framework based on <filename>Makef=
ile</filename>
   inheritance for building Debian packages.</para>
=20
   <para>It is essentially a set of Makefile fragments which you may
@@ -59,7 +59,8 @@
   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
+  <filename>debian/rules</filename> could be factored out. =20
+  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 systems.</para>
=20
@@ -82,13 +83,15 @@
     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
+    later).  This <filename>Makefile</filename> fragment sets up all=20
+    of the core default <filename>Makefile</filename> structure and=20
+    variables, but doesn't actually
     <emphasis>do</emphasis> anything on its own.</para>
=20
     <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>
+    compiling, installing, and building <filename>.deb</filename>s=20
+    if you wish.</para>
   </section>
=20
   <section>
@@ -118,7 +121,8 @@
     <title><filename>debhelper.mk</filename>: A rule fragment</title>
=20
     <para>The next important piece of the puzzle is to actually build
-    .debs from the now compiled software.  You could implement this
+    <filename>.deb</filename>s from the now compiled software. =20
+    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>
@@ -135,7 +139,7 @@
=20
     <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>
+    <filename>debian/rules</filename> should now look like:</para>
=20
     <programlisting>#!/usr/bin/make -f
 include /usr/share/cdbs/1/rules/debhelper.mk
@@ -174,7 +178,7 @@
     <title>Customization</title>
=20
     <para>However, suppose you need to pass --disable-frobnication to
-    ./configure.  How do you do this?  Well, it couldn't be easier.
+    <command>./configure</command>.  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>
=20
@@ -189,11 +193,12 @@
     variables should be set after rule fragments are included.</para>
=20
     <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
+    (e.g. Perl); perhaps it has a <command>./Configure</command>=20
+    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>
+      something like the following to your <filename>debian/rules</filenam=
e>:</para>
=20
     <programlisting>common-configure::
 	./Configure --blah --blargh &lt; debian/answers</programlisting>
@@ -244,7 +249,8 @@
     <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
+    <filename>Makefile</filename> to install everything into=20
+    <filename>debian/packagename</filename>, 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;
@@ -257,7 +263,8 @@
=20
     <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
+    Makefile to install everything in <filename>debian/tmp</filename>. =20
+    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
@@ -269,7 +276,8 @@
     <title>A simple patch system</title>
=20
     <para>Suppose you'd like to keep separated patches, instead of
-    having them all in your .diff.gz.  cdbs lets you hook in arbitrary
+    having them all in your <filename>.diff.gz</filename>. =20
+    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
@@ -300,15 +308,15 @@
     <title>Common build problems</title>
=20
     <section>
-      <title>Build fails to to missing include files or something</title>
+      <title>Build fails to missing include files or something</title>
=20
       <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>
+      <command>-I</command>.  However if fixing the upstream source is=20
+      too difficult, you may do this:</para>
=20
       <programlisting>DEB_MAKE_INVOKE :=3D $(DEB_MAKE_ENVVARS) \
 	make -C $(DEB_BUILDDIR)</programlisting>

--vkogqOf2sHV7VnPd--


--=-dCjfk7IK+YEQjujvHsG0--

--=-kpB2adoZS098NwyOkPIY
Content-Type: application/pgp-signature; name=signature.asc
Content-Description: This is a digitally signed message part

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)

iD8DBQBAesLwOIkJWWp2WGURApy2AJoDbxsao3R49xMsu3T/6DDxY9ypOwCfQDVb
10Wq5/bi63jVCCAp7BHuGYs=
=Jo+k
-----END PGP SIGNATURE-----

--=-kpB2adoZS098NwyOkPIY--