Debian - Paketerstellung (Eine Einführung)


Copyright Notice:

Copyright © 2001, Marcus Geiger


Abstrakt

Dieses Dokument soll eine kleine Einführung in die Erstellung von Debian-Paketen geben. Es ist nicht als vollstaendige Anleitung gedacht. Details sollten in den Manualpages oder den offiziellen Debian-Referenzen nachgeschlagen werden.

Im folgenden soll aus einem kleinen Programm namens hallo ein binäres Debian-Paket erstellt werden. hallo verwendet GNU-Autoconf und GNU-Automake, wie es heute für fast alle größeren Pakete üblich ist.

Fundorte im Web

Notwendige Pakete


Vorbereitungen

Zunächst sollte ein Arbeitsverzeichnis erstellt werden (am besten mit dem Namen des Paketes, ohne Versionsnummer).
Hier entpacken wir den Orginal-Source unseres Paketes:

      mkdir hallo; cd hallo
	  tar xvfz ~/hallo-0.1.tar.gz
      cd hallo-0.1
	

Hinweis: Es ist wichtig, daß das Verzeichnis in dem der Source des Entpackten Paktes liegt, namentlich die Paket-Version (upstream-version) enthält (z.B. hallo-0.1).

Aus dem "Debian New Maintainer Guide"

Also check for the exact version of the program (to be included in the package version). If that piece of software is not numbered with versions like X.Y.Z, but with some kind of date, feel free to use that date as the version number, prepended with a "0.0." (just in case upstream people one day decide to release a nice version like 1.0). So, if the release or snapshot date was 19th of December, 1998, you can use the version string of 0.0.19981219. Some programs won't be numbered at all, in which case you should contact the upstream maintainer to see if they've got some other revision-tracking method.

"Debianisieren"

Nun können wir mit Hilfe des Pakets dh_make den Quellbaum für die Erstellung eines Debian-Pakets vorbereiten.

     dh_make -e marcus@antbear.org -f ~/hallo-0.1.tar.gz
    

Die Option -e gibt dabei die E-Mail-Adresse des Maintainers an. Die Option -f die Lage des Orginal-Source (upstream) im Filesystem an.
dh_make wird anschließend erfragen, um welchen Typ es sich bei dem zu erstellenden Paket handelt. Die Möglichen Antworten lauten:

Wir wählen hier natuerlich single binary, da es sich bei hallo um ein einfaches Programm handelt.
Abschließend wird uns eine Übersicht, des erstellten Paket-Grundgerüsts angezeigt.

Im übergeordneten Verzeichnis befindet sich nun neben dem Orginal Source-Archiv des Pakets, ein neues Archiv, das dazu gedacht ist, in Kombination mit dem erzeugten Debian-Paket, auf die Debian-Server hochgeladen zu werden. Der Name des Archives lautet: hallo_0.1.orig.tar.gz


Das debian-Unterverzeichnis

Alle zur Erstellung des Debian-Pakets notwendigen Dateien befinden sich im debian-Unterverzeichnis unseres Quellbaums.

Hier ein Überblick der generierten Dateien:

README.Debian README-Datei die später im /usr/share/doc/hallo Verzeichnis abgelegt wird. Hier sollten Debian-spezifische Anpassungen oder Kompilierungsoptionen oder Abweichungen von der upstream-Version dokumentiert werden.
changelog Enthält die Änderungshistory des Debian-Pakets. Achtung die Datei muß in einem speziellen Format vorliegen.
conffiles.ex Enthält eine Liste von Konfigurationsdateien, die dpkg beachten sollten.
control Enthält die Informationen, die mit dpkg --info ausgegeben werden können. Hier muß auch die Beschreibung des Pakets angepasst werden.
copyright Hier sollte die Website oder ftp-URL angegeben werden, von wo das Orginal-Paket bezogen werden kann. Autoren und weitere upstream Copyright-Hinweise müssen hier eingetragen werden.
cron.d.ex Beispiel-crontab (optional)
dirs Enthält die Verzeichnisse, die bei Bedarf von dpkg während der Installation erzeugt werden sollen. Im einfachsten Fall muß hier nichts geändert werden, oder einfach nur das Installationsverzeichnis eingetragen werden (z.B. /usr/bin).
docs List von Dateien, die aus den Orginalquellen nach /usr/share/doc/paket übernommen werden sollen.
emacsen-install.ex Emacs-spezifisch (optional)
emacsen-remove.ex Emacs-spezifisch (optional)
emacsen-startup.ex Emacs-spezifisch (optional)
ex.doc-base.package Für Pakete mit eigener HTML-Dokumentation. Wird benötigt, um die Paket-Dokumentation bei doc-base zu registrieren (damit sie mittels dhelp(1) oder dwww(1) gefunden werden kann). (optional)
init.d.ex Für Pakete die einen Daemon enthalten und von init gestartet werden sollten (Initskript). (optional)
manpage.1.ex Skellet einer Manpage (troff(1)). (optional)
manpage.sgml.ex Skellet einer Manpage im SGML-Format (Docboc). (optional)
menu.ex Einstellungen für das Debian-Menu system. Ermoeglich es auf einfach Art einen Menüeintrag für das Paket zu erstellen, der dann in allen X11-Umgebungen sichtbar ist.
postinst.ex Skript, das nach der Installation ausgeführt werden soll
postrm.ex Skript, das nach dem Entfernen des Pakets ausgeführt werden soll.
preinst.ex Skript, das vor der Installation ausgeführt werden soll.
prerm.ex Sript, das vor dem Entfernen ausgeführt werden soll.
rules Enthält die Regeln die dpkg-buildpackage auswertet, um das Paket zu erstellen.
watch.ex Siehe uscan(1) und uupdate(1). (optional)

Da die Semantik, wann welche Paket-Skripte ausgeführt werden, recht komplex ist, verweise ich an dieser Stelle auf die "Debian Developers Reference"

Die Endung .ex steht für Example. Soll eine der Aufgeführten Dateien verwendet werden, so ist sie umzubennen (ohne .ex).


Anpassungen

Im Folgenden werden wir einige der oben aufgeführten Dateien anpassen, um aus dem hallo-Paket ein Debian-Paket zu erstellen.

Ein Wort zu Makefiles

Da die Debian-Policy genauch vorschreibt, wo die Vielzahl von Dateien aus denen sich ein Paket zusammensetzt, im Filesystem zu installieren sind, müssen bei manchen Paketen Anpassungen am Makefile vorgenommen werden. In der Regel sind das Pakete, die mit normalen Makefiles ausgeliefert werden.

Pakete die Automake/Autoconf einsetzen, müssen meist nicht angepasst werden, da hier über die Option --prefix=pfad des configure-Skripts, der Basispfad für die Installation vorgegeben werden kann. Entgegen dem GNU-"Standard", Programmpakete nach /usr/local zu installieren, müssen Debian-Pakete, die ausführbare Programme enthalten, nach /usr/bin installiert werden.
Auf jeden Fall muß sichergestellt werden, daß das resultierende Paket, den Debian-Standards entspricht.

Das control-File

Das control-File enthält verschiedene Informationen, die dpkg und apt benötigen, um das Paket zu verwalten:

     Source: hallo
     Section: unknown
     Priority: optional
     Maintainer: Marcus Geiger 
     Build-Depends: debhelper (>> 3.0.0)
     Standards-Version: 3.5.2

     Package: hallo
     Architecture: any
     Depends: ${shlibs:Depends}
     Description: 
      
	

Der obere Abschnitt enthält die Informationen für das Source-Paket, der Untere für das Binärpaket. Die Semantik der einzelnen Felder ist wahrscheinlich jedem Debianer bekannt.
Die erste Zeile der Description enthält eine Kurzbeschreibung des Pakets. Eine Ausführliche Beschreibung folgt unmittelbar in der nächsten Zeile. Jede Zeile muß dabei mit Leerzeichen eingerückt werden. Paragraphen können mit einem Punkt erzeugt werden.

Die Zeile Section: ... dient der Kategorisierung des Pakets (z.B. für apt-Frontends).

Die Zeile Depends: ${shlibs:Depends} wird vom während der Erstellung des Pakets automatisch substituiert (duch die Liste der Bibliotheken, die zum Paket (dynamisch) gelinkt wurden).

Weiter wichtige Felder die oft eingefügt werden müssen, sind:

Einzelheiten sind der "Debian Developers Reference" zu entnehmen.

Wir ändern nun unser control-File folgendermassen ab:

     Source: hallo
     Section: misc
     Priority: optional
     Maintainer: Marcus Geiger 
     Build-Depends: debhelper (>> 3.0.0)
     Standards-Version: 3.5.2

     Package: hallo
     Architecture: any
     Depends: ${shlibs:Depends}
     Suggests: hello
     Description: A package to learn howto create debian packages.
      A long description.
      .
      A new paragraph. Also take a look at the hello package, because
      it's more full-featured.
	

Das copyright-File

Hier sollen alle upstream Copyright-Hinweise eingefügt werden. Auch sollte hier die Quelle angegeben werden, von wo das Orginalpaket bezogen werden kann.

Hier die Anpassungen im Rahmen des hallo-Pakets:

     This package was debianized by Marcus Geiger  on
     Sun, 29 Jul 2001 18:48:42 +0200.

     It was downloaded from http://www.antbear.org

     Upstream Author(s): Marcus Geiger 

     Copyright:

     blah
	

Das changelog-File

Das changelog-File enthält die Änderungshistorie des Debian-Pakets. Das genaue Format kann dem "Packaging Manual" (section 3.2.3) entnommen werden.

Wir ändern es folgendermaßen ab:

     hallo (0.1-1) unstable; urgency=low

      * Initial Release.
      * This is my first Debian package.
      * No upstream changes.

     -- Marcus Geiger   Sun, 29 Jul 2001 18:48:42 +0200

     Local variables:
     mode: debian-changelog
     End:
	

Damit Emacs in den Debian-Changelog-Mode wechselt, wurden die unteren drei Zeilen eingefügt (Erleichtert das Einhalten des Formats).
urgency=low besagt, daß die Änderungen nicht wesentlich sind.

Jedesmal, wenn ein neues Paket-Release erstellt werden soll, muß die Version des Pakets erhöt werden. Am besten verwendet man dazu den Befehl dch -i, der die Versionsnummer des Pakets inkrementiert (siehe dch(1)). Anschließ muß nur die changelog ergänzt werden.

Hinweis: Das Datums- und Zeitformat muß muß RFC822-konform sein. Händisch kann die aktuelle Zeit/Datum mit date -R abgefragt werden.

Das rules-File

Das rules-File enthält das Regelwerk für dpkg-buildpackage(1). Es handelt sich also um ein ausfürbares Makefile für die Paketerstellung.

Wie ein "normales" Makefile, enthält das rules-File Ziele und die davon abhängigen Regeln (siehe auch info make). Das von dh_make erstellt rules-File ist nur ein Vorschalg und sollte auf jeden Fall angepasst werden.

configure und configure-stamp

Die make-Ziele configure und configure-stamp sind für die Konfiguration des Software Pakets zuständig. Diese make-Ziele werden von dh_make nur dann erzeugt, wenn das Quellpaket autoconf/automake verwendet. Hier wird configure mit den notwendigen Optionen gestartet, so daß das resultierende Paket Debiankonform ist.

build und build-stamp

Die make-Ziele build und build-stamp steuern den normalen Erstellungsprozess des Software-Pakets. Es wird also im wesentlichen ein make ausgeführt.

binary-arch

Dieses make-Ziel ist das interessanteste, da es die Erstellung des Debianpakets steuert. Hier werden viele kleine Hilfprogramme aus der debhelper-Sammlung verwendet. Hier sollten auf jeden Fall Anpassungen vorgenommen werden, die die Gegebenheiten des Pakets reflektieren.

Obige Auflistung ist nicht vollständig und sollte nur als Anhaltspunkt dienen. Jedes der dh_*-Programme kommt mit einer eigenen Manualpage in der Sektion (1). Jedes der dh_*-Programme fügt ein besonderes Featuer zum zu erstellenden Debian-Paket hinzu.

Hier die rules-Date nach unseren Anpassungen:

     #!/usr/bin/make -f
     # Sample debian/rules that uses debhelper.
     # GNU copyright 1997 to 1999 by Joey Hess.
     
     # Uncomment this to turn on verbose mode.
     #export DH_VERBOSE=1
     
     # This is the debhelper compatability version to use.
     export DH_COMPAT=3
     
     configure: configure-stamp
     configure-stamp:
     	dh_testdir
     	# Add here commands to configure the package.
     	./configure --prefix=/usr --mandir=\$${prefix}/share/man \
                    --infodir=\$${prefix}/share/info
     
     	touch configure-stamp
     
     build: configure-stamp build-stamp
     build-stamp:
     	dh_testdir
     
     	# Add here commands to compile the package.
     	$(MAKE)
     	#/usr/bin/docbook-to-man debian/hallo.sgml > hallo.1
     
     	touch build-stamp
     
     clean:
     	dh_testdir
     	dh_testroot
     	rm -f build-stamp configure-stamp
     
     	# Add here commands to clean up after the build process.
     	-$(MAKE) distclean
     
     	dh_clean
     
     install: build
     	dh_testdir
     	dh_testroot
     	dh_clean -k
     	dh_installdirs
     
     	# Add here commands to install the package into debian/hallo.
     	$(MAKE) install prefix=$(CURDIR)/debian/hallo
     
     
     # Build architecture-independent files here.
     binary-indep: build install
     # We have nothing to do by default.
     
     # Build architecture-dependent files here.
     binary-arch: build install
     	dh_testdir
     	dh_testroot
     #	dh_installdebconf	
     	dh_installdocs
     #	dh_installexamples
     	dh_installmenu
     #	dh_installlogrotate
     #	dh_installemacsen
     #	dh_installpam
     #	dh_installmime
     #	dh_installinit
     #	dh_installcron
     #	dh_installman
     #	dh_installinfo
     	dh_undocumented
     	dh_installchangelogs ChangeLog
     	dh_link
     	dh_strip
     	dh_compress
     	dh_fixperms
     #	dh_makeshlibs
     	dh_installdeb
     #	dh_perl
     	dh_shlibdeps
     	dh_gencontrol
     	dh_md5sums
     	dh_builddeb
     
     binary: binary-indep binary-arch
     .PHONY: build clean binary-indep binary-arch binary install configure
	

Das README.debian-File

Hier sollten alle Änderungen gegenüber der upstream-Version des Pakets ausführlich dokumentiert werden.

conffiles

Jedem Debianer dürfte die Debian-Handhabe mit den Konfigurationsdateien bekannt sein. Damit das Paketsystem weiß, welche Konfigurationsdateien das Paket mitbringt, sind diese in dieser Datei mit absolutem Pfad anzugen.

dirs

Hier werden alle zu Installation benötigten Verzeichnisse aufgeführt (z.B. /usr/bin).

menu

Hier kann angegeben werden, wie das Paket in das Debian-Menüsystem integriert werden soll (siehe auch dh_installmenu(1) im rules-File).

Da hallo ein Konsolenprogramm ist, ändern wir es wie folgt ab:

     ?package(hallo):needs=text section=Apps/Tools \
     title="hallo" command="/usr/bin/hallo"
	

Paketerstellung

Wenn wir uns sicher sind, alle Anpassungen vorgenommen zu haben, wechseln wir in das Paket-Hauptverzeichnis (hier hallo-0.1) und erstellen unser Debian-Paket:

     dpkg-buildpackage -rfakeroot
    

Ging alles gut erhalten wir die folgenden Dateien (ein Verzeichnis höher):

Abschlußbemerkung

Hier endet der kleine Ausflug in die Welt der Debian-Pakete. Jeder kann nun die oben beschriebenen Schritte mit dem orginal-Paket nachvollziehen. Die Debian-Manualpages und die Developers-Reference können die meisten offenen Fragen beantworten.

Nicht behandelt wurde die Erstellung von shared-libraries und die verwendung von Skripten (postrm, prerm, ....)


Marcus Geiger
Last modified: Tue Aug 28 21:00:39 CEST 2001