<!--
  * Titel: Debian-Pakete mittels CDBS (Common Debian Build System)
  * [c] Nico Golde
  * Autor: Nico Golde <nico (at) ngolde.de>
  * Homepage: http://www.ngolde.de
  * Lizenz: GNU General Public License (GPL)
  -->

Debian-Pakete mittels CDBS (Common Debian Build System)

Inhalt
1 Warum überhaupt CDBS?
1.1 Vorteile in CDBS
2 Das Basisgerüst von CDBS (buildcore.mk)
2.1 Einführung in Klassen
2.2 Eine einfache rules-Datei
2.3 Anpassen der Regeln
3 Compat Level & Build-Dependencies
4 Debhelper
4.1 Debhelper angepasste build-Regeln
5 Möglichkeiten Quellen zu patchen
5.1 Das CDBS-Patchsystem
5.2 Patchen mit dpatch
6 Pakete ohne autoconf, nur mit Makefile
7 Quellpakete ohne bestimmte Elemente (Manual)
8 Bauen des Paketes
9 Schlusswort
10 Credits


1 Warum überhaupt CDBS?

CDBS wurde entwickelt um die Arbeit eines Maintainers zu vereinfachen.
Es soll nicht die Aufgabe eines Maintainers sein immer komplizierter
werdende debian/rules-Dateien zu maintainen, sondern sich auf das eigentliche
Paketieren zu konzentrieren.
Der ursprünglich von dh_make (debhelper) entwickelte Code wird mit der Zeit
je nach Programm immer schwerer zu maintainen. CDBS schafft Abhilfe.

CDBS benutzt ebenfalls die Datei debian/rules, allerdings besteht diese
selbst bei komplexen Programmen meist nur aus ein paar Zeilen.
CDBS benutzt lediglich normale Makefile Regeln und es ist bei Bedarf
sehr einfach zu erweitern.
CDBS arbeitet mit sogenannten Klassen (classes) und Regeln (rules), eine Regel,
z.B. für das Benutzen des Upstream-Makefiles braucht fast jede rules-Datei.
Bei Bedarf von autotools, dpatch, Python-Installationsroutinen, braucht man
lediglich die entsprechenden Klassen in die rules-Datei einzubinden.

1.1 Vorteile in CDBS

    - leicht zu maintainende debian/rules-Datei (klein, lesbar, ...)
    - automatisiert debhelper, autotools, etc. , sodass man sich mit diesen
      unschönen Tätigkeiten nicht weiter auseinander setzen muss
    - CDBS ist modular aufgebaut, sodass man bei Bedarf verschiedene
      Klassen inkludieren kann oder auch nicht
    - Umstieg/Einstieg zu CDBS ist sehr einfach
    - CDBS kann mit debhelper Routinen arbeiten
	- es ist sehr einfach System weite Veränderungen in ein Paket
      einzubeziehen. Variablen innerhalb der Klassen ermöglichen
      umfangreiche Änderungen an der Programm-Konfiguration
    - weniger komplexe Pakete
    - es ist cool ;-)

CDBS ist eine Rahmen, der auf einer Ansammlung von Makefile-Fragmenten,
die bei Bedarf in die Quellen eingebunden werden können und somit eine
enge Code-Schreiberei in einer 100 Zeilen langen rules-Datei verhindern.



2 Das Basisgerüst von CDBS (buildcore.mk)

Buildcore.mk ist neben buildvars.mk, debhelper.mk, dpatch.mk,
simple-patchsys.mk, tarball.mk und utils.mk eine der Regeln, die
CDBS zur Verfügung stellt und die sich in /usr/share/cdbs/1/rules/
befinden.

Regeln und Klassen werden mit dem Befehl include in der rules-Datei
eingeschlossen. Die Regel buildcore.mk sollte in jedes Paket eingebunden
werden, da sie wichtige Routinen wie testdir, testroot, etc. beinhaltet.
Eventuell wird diese Regel allerdings über die verschiedenen Klassen
bereits inkludiert, sodass es meistens nicht notwendig ist
include /usr/share/cdbs/1/rules/buildcore.mk in die rules-Datei
mit aufzunehmen.



2.1 Einführung in Klassen

Unter /usr/share/cdbs/1/classes befinden sich die verschiedenen Klassen,
die CDBS bereitstellt. Die Klassen beinhalten verschiedene Routinen, die
bei der Benutzung von bestimmten Programmen benötigt werden.
Verwendet ein Programm z.B. ein Makefile, so fügt man einfach in die
rules-Datei include /usr/share/cdbs/1/class/makefile.mk und verfügt somit
automatisch über den Code, der Benötigt wird um die Makefile-Regeln
abzuarbeiten.



2.2 Eine einfache rules-Datei

Die einfachste denkbare rules-Datei mittels CDBS sieht so aus:

 #!/usr/bin/make -f

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

Nicht mehr und nicht weniger. Durch die debhelper-Regel können nun die
debhelper-Programme automatisch mitbenutzt werden.
Wichtig: Verwendet man die debhelper-Regel, was eigentlich immer der Fall
sein sollte, ist es wichtig, dass in den
Build-Dependencies der control-Datei debhelper mit Version (>= 4.1.0)
eingetragen ist. Empfohlen wird sogar Version (>= 4.1.16), um einige
zusätzliche debhelper-Eigenschaften verwenden zu können.

Die Klasse autotools.mk wird benötigt, um configure-Skripte zu verwenden,
config.guess-Dateien zu aktualisieren uns sonstige Arbeiten der autotools
zu automatisieren.

Wichtig: Wie oben genannt ist es meistens nicht nötig die buildcore.mk
Regel zu inkludieren, da sie bereits von anderen Klassen oder Regeln
inkludiert wird. Debhelper.mk und autotools inkludieren z.B. diese Regel
schon, sodass es nicht mehr nötig ist dies selbst zu tun.

Die debhelper-Regel sollte immer vor allen anderen Regeln inkludiert
werden.



2.3 Anpassen der Regeln

Für das Anpassen der Regeln von z.B. configure-Skripten stellen die
inkludierten Klassen und Regeln verschiedene Variablen zur Verfügung, die
verändert werden können.

So kann man mit  DEB_CONFIGURE_EXTRA_FLAGS := --flags einem
configure-Skript benötigte Einstellungen übergeben.

An dieser Stelle ist es wichtig, dass man dies erst tut, nachdem man die
Regel oder Klasse eingebunden hat.
Die zur Verfügung stehenden Variablen kann man in den Klassen- und
Regel-Dateien nachgucken. Sie sind sehr gut dokumentiert und auch für
Anfänger gut lesbar.

Verwendet man ein nicht von autoconf erstelltes configure-Skript kann
man durch hinzufügen von:

common-configure::
    Configure --foobar

auch andere Skripte verwenden. Tut man dies, sollte man allerdings auf das
einbinden der autotools-Klasse verzichten, da sonst zwei Implementierungen
von common-configure existieren.

Natürlich ist es auch möglich eigene Clean-Regeln zu schreiben:

clean::
    rm -f po/*.gmo

Eigene Build-Routinen

build/foobar-data::
    $(MAKE) helpfiles

Man kann außerdem Abhängigkeiten zu den Regeln hinzufügen. Möchten man bei
einem "multi-binary"-Paket zum Beispiel, welches eine shared library und
das Programm enthält, dass die shared library zuerst kompiliert wird kann
man folgendes benutzen:

binary/programmname:: binary/libfoobar

Wichtig: Dies muss getan werden, bevor die Regel buildcore.mk eingebunden
wird!

Es gibt ebenfalls pre-configure-Aktionen (makebuilddir/foobar::),
post-configure-Aktionen (configure/foobar::),
post-build-Aktionen(build/foobar::), post-install-Aktionen
(install:/foobar::) etc.



3 Compat Level & Build-Dependencies

Es ist wichtig, dass das Paket bei der Benutzung von CDBS das compat Level
(siehe Maintainers-Guide) auf 4 gestellt hat. Dazu ist einfach eine Datei
compat mit dem Inhalt 4 anzulegen. Tut man dies nicht, legt CDBS
automatisch eine "compat Level 4"-Datei an.

Natürlich muss CDBS auch in den Build-Dependencies des Paketes stehen.



4 Debhelper

Mit dem einbinden von debhelper (include /usr/share/cdbs/1/rules/debhelper.mk)
erledigt CDBS so gut wie alle Aufgabe von debhelper automatisch.

Diese Regel behandelt die folgenden debhelper-Skripte (dh_*) automatisch:
dh_builddeb             dh_installcron      dh_installinfo      dh_link
dh_clean                dh_installdeb       dh_installinit      dh_makeshlibs
dh_compress             dh_installdebconf   dh_installlogcheck  dh_md5sums
dh_fixperms             dh_installdirs      dh_installlogrotate dh_perl
dh_gencontrol           dh_installdocs      dh_installman       dh_shlipdeps
dh_install              dh_installemacsen   dh_installmenu      dh_strip
dh_installchangelogs    dh_installexamples  dh_installpam

Fehlende debhelper-Skripte können sich entweder in einer der Klassen
befinden oder man hat die Möglichkeit sie über eigene Regeln in der
rules-Datei zu implementieren.



4.1 Debhelper angepasste build-Regeln

Wie oben angesprochen kann man die debhelper Regeln auch selbst schreiben.
Es gibt post-preparation-Aktionen (binary-install/foobar::), clean-Aktionen
(clean::) und einige andere, die man in in /usr/share/cdbs/1/rules/debhelper.mk
nachschlagen kann.



5 Möglichkeiten Quellen zu patchen

Natürlich biete auch CDBS Methoden an, um Quellen zu patchen.
Es stellt dabei eine eigene Patchmethode zur Verfügung und bietet ebenfalls
an, dpatch zu verwenden.
Das CDBS-eigene Patchyystem verwendet normale diff-Dateien als Patches,
die normale Textdateien darstellen. Dpatch hingegen erstellt den Patch in
Form eines Shellskripts, das bei Bedarf die Quellen patchen oder unpatchen
kann.
Beide Methoden werden hier vorgestellt.



5.1 Das CDBS-Patchsystem

Originalsourcen direkt zu editieren ist eine sehr schlechte Methode, um
Dateien zu patchen. Stattdessen benötigen wir eine Methode, die es erlaub
den Patch extra abzulegen und die Quellen beim build-Prozess zu damit zu
patchen und anschliessend wieder zu unpatchen.
CDBS hat für diese Schritte eine eigene Patchsystem-Implementierung. Sie
nennt sich simple-patchsys.mk. Um sie zu benutzen muss man lediglich die
Zeile include /usr/share/cdbs/1/rules/simple-patchsys.mk in die rules-Datei
schreiben.

Anschliessend erstellt man im debian-Verzeichnis ein weiteres Verzeichnis
namens patches.
Nun werden die mittels diff erstellten Patches in das Verzeichnis
debian/patches/ getan.
Die patchsys-Regel kümmert sich nun um den Vorgang des Patchens und des
Unpatchens nach dem build-Prozess. Das CDBS-Patchsystem ermöglicht die
Patchlevel 0,1,2 und 3 zu benutzen. Welches man benutzen will muss man
allerdings nicht angeben, CDBS probiert alle Patchlevel aus und benutzt das
richtige automatisch. Benutzt man diese Methode müssen die Patches Dateien
mit der Endung .patch sein.
Man hat jedoch die Möglichkeit die Endungen und das Patchverzeichnis über
die Variablen von simple-patchsys.mk zu modifizieren:

DEB_PATCHDIRS := debian/mypatches
DEB_PATCH_SUFFIX := .foobar

Treten während des Patchprozesses Fehler auf, so findet man im Verzeichnis
der Patches immer eine gleichnamige Log-Datei des Patches.



5.2 Patchen mit dpatch

Möchte man statt mit dem CDBS-Patchsystem mit dem Debian-Patchsystem dpatch
arbeiten, so braucht man lediglich die Zeile
include /usr/share/cdbs/1/rules/dpatch.mk in die debian/rules-Datei
mitaufzunehmen.
Den Rest übernimmt CDBS automatisch, sodass man sich um nichts weiteres
mehr zu kümmern braucht.
Wichtig: Bei der Benutzung von dpatch ist es nötig dpatch in die
Build-Dependencies mitaufzunehmen. Bei der Verwendung von autotools.mk ist
es ebenfalls wichtig die Regel dpatch.mk erst nach autotools.mk
einzubinden.
Für weitere Informationen empfehle ich die dpatch-Dokumentation unter
/usr/share/doc/dpatch/README.gz zu lesen.



6 Pakete ohne autoconf, nur mit Makefile

Eine rules-Datei für ein solches Programm besteht im Prinzip nur aus
folgenden Einträgen:

#!/usr/bin/make -f

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

DEB_MAKE_CLEAN_TARGET    := distclean
DEB_MAKE_BUILD_TARGET    := all
DEB_MAKE_INSTALL_TARGET  := install DESTDIR=$(CURDIR)/debian/paketname

Die Klasse makefile.mk wird benötigt, damit der Umgang mit Makefiles
automatisiert werden kann.
Die drei Variablen geben an, welche Makefile-Regel für die clean-Aktion,
zum kompilieren und zum installieren des Paketes zuständig ist.
Diese Variablen sollten in jedem Fall gesetzt werden.
Des weiteren kann DEB_MAKE_CHECK_TARGET verwendet werden, wenn das Makefile
ein check-target beinhaltet.
Wenn die Make-Datei nicht mit der DESTDIR-Variablen arbeitet, muss das
Makefile gepatcht werden (siehe Maintainers-Guide).



7 Quellpakete ohne bestimmte Elemente (Manual)

Verfügt ein Quellpaket nicht über bestimmte Dateien (in diesem Beispiel
über das Manual), so wird dies in anderen Paketierungsverfahren z.B. durch
den Eintrag dh_installman debian/manual.1 in debian/rules gelöst.

Diese Möglichkeiten hat man natürlich auch mit CDBS.
So würde die Variable
DEB_INSTALL_MANPAGES_paketname := debian/manual.1, die in debhelper.mk
definiert ist, die gleiche Aufgabe übernehmen. Es gibt noch mehr solcher
Variablen, die an dieser Stelle nichta aufgeführt werden. Die
Klassen-Dateien sind allerdings gut lesbar und man findet sie schnell.



8 Bauen des Paketes

Das Paket wird wie in allen anderen Paketierungsverfahren mit dem Programm
dpkg-buildpackage gebaut.



9 Schlusswort

CDBS scheint auch für die Zukunft eine gute Alternative zu dem normalen
Verfahren für Pakete zu sein. Die Dokumentation ist noch sehr unzureichend
vorhanden und muss auf jeden Fall noch erweitert werden. CDBS selbst
verfügt noch nichteinmal über ein Manual. Wen das nicht abschreckt, sollte
CDBS auf jeden Fall ausprobieren.
Verbesserungen, Lob, Kritik etc. an Nico Golde <nico (at) ngolde.de>

Credits

Danke an https://wiki.duckcorp.org/DebianPackagingTutorial_2fCDBS.
Dieses Wiki war der Anreiz für diesen Text.

Zusätzliche Informationen:
Ursprüngliche CDBS-Entwickler: Jeff Bailey & Colin Walters
Homepage: http://alioth.debian.org/projects/build-common/
Mailingliste: build-common-hackers (at) lists.alioth.debian.org
vim:tw=75