Difference between revisions of "Paketierung von Software für UCS"

From Univention Wiki

Jump to: navigation, search
(Replaced content with "See {{DevRef|section=chap:packaging}}.")
 
Line 1: Line 1:
= Einführung  =
+
See {{DevRef|section=chap:packaging}}.
 
 
Univention Corporate Server basiert auf der Debian-Distribution. Diese verfügt mit dem Paketmanager '''dpkg''' und dessen Frontend '''apt-get''' über ausgereifte Werkzeuge zur Paketverwaltung, die es erlauben, Pakete unter Berücksichtigung von Abhängigkeiten zu installieren und zu entfernen.
 
 
 
Diese Dokumentation soll helfen, eigene Softwarepakete für UCS - das selbst aus über 1000 Paketen besteht - zu erstellen, um beispielsweise hausinterne Software oder Konfigurationen effizienter einzubinden.
 
 
 
= Voraussetzungen und Vorbereitung  =
 
 
 
Um Debian-Pakete zu bauen, müssen folgende Programme installiert sein:
 
*dh-make
 
*devscripts
 
*build-essential
 
 
 
Ist dies nicht der Fall, müssen die Pakete nachinstalliert werden (siehe {{Handbuch UCS|UCS-Handbuch}} im Kapitel Softwarepflege).
 
 
 
= Paketierung eines-Beispiel-Skripts  =
 
 
 
Es soll nun ein Paket erstellt werden, das nur aus einem Python-Skript ''testdeb.py'' besteht. Dieses Skript legt im Verzeichnis ''/tmp/'' eine Datei namens ''testdeb-DATUM+UHRZEIT'' an.
 
 
 
Zunächst muss ein Arbeitsverzeichnis mit dem Namen des zukünftigen Pakets und der Versionsnummer erstellt werden (<Paketname>-<Version>, alles in Kleinbuchstaben):
 
<pre>mkdir testdeb-0.1
 
cd testdeb-0.1
 
</pre>
 
In diesem Verzeichnis wird die Datei ''testdeb.py'' angelegt, die das nachfolgende Python-Skript - das eigentlich zu installierende Programm - enthält:
 
<pre>#!/usr/bin/env python
 
# Beispielskript Univention-Paketerstellung
 
 
 
import time, os
 
 
 
file='/tmp/testdeb-%s'&nbsp;% time.strftime('%y%m%d%H%M', time.localtime())
 
f=open(file,'a')
 
f.close()
 
</pre>
 
Für die Erstellung des Pakets wird ein Unterverzeichnis ''debian/'' benötigt. Dieses Verzeichnis enthält einige wichtige Kontrolldateien, die im Folgenden genauer erklärt werden. Durch den Befehl '''dh_make''' wird dieses Verzeichnis erstellt und mit Vorlagen der Kontrolldateien befüllt:
 
<pre>dh_make -e max@muster.de --createorig
 
</pre>
 
 
 
'''dh_make''' erfragt nach dem Start, um was für eine Art von Paket es sich handelt. Hier stehen vier Varianten zur Auswahl, die für spezielle Anpassungen in den Vorlagen für die Kontrolldateien sorgen: Mit Binärpaket ist hier das erstellte Debian-Paket gemeint, mit Quellpaket das Verzeichnis oder Archiv mit den Quellen zum Programm und den Debian-Paketkonfigurationen (z.B. gibt es ein Quellpaket für Samba und Binärpakete für Server- und Client-Programme)
 
 
 
*'''single binary''': ein Quellpaket, ein Binärpaket
 
*'''multiple binary:''' ein Quellpaket, mehrere Binärpakete
 
*'''library''': Pakete für Programmbibliotheken
 
*'''kernel module''': Paket für Kernelmodule
 
 
 
In dem hier aufgeführten Beispiel wird ein '''single binary'''-Paket erstellt (in dieser Dokumentation soll auch nur auf diesen Pakettyp eingegangen werden). Nach der Eingabe von "s" erscheint folgende Ausgabe:
 
<pre>Type of package: single binary, multiple binary, library, or kernel module?
 
[s/m/l/k] s
 
 
 
Maintainer name&nbsp;: Max Muster
 
Email-Address  &nbsp;: max@muster.de
 
Date          &nbsp;: Mon, 21 Mar 2005 13:46:39 +0100
 
Package Name  &nbsp;: testdeb
 
Version        &nbsp;: 0.1
 
Type of Package&nbsp;: Single
 
Hit &lt;enter&gt; to confirm:
 
Currently there is no top level Makefile. This may require additional tuning.
 
Done. Please edit the files in the debian/ subdirectory now. You should also
 
check that the testdeb Makefiles install into \$DESTDIR and not in / .
 
</pre>
 
Die von '''dh_make''' ermittelten Informationen (hier '''testdeb''' als Paketname, '''0.1''' als Paketversion, der Name des Maintainers u.s.w.) werden bei der Erstellung der Kontrolldateien berücksichtigt. Durch die Option '''--createorig''' wird eine nicht "debianisierte" Kopie des Quellverzeichnisses angelegt.
 
 
 
= Übersicht Kontrolldateien =
 
 
 
Durch die Kontrolldateien im Verzeichnis ''debian/'' werden die Eigenschaften des Pakets beschrieben. Im Folgenden ein kurzer Überblick über die möglichen Kontrolldateien bevor im Detail auf einige wichtige Dateien eingegangen wird.
 
 
 
Dateien mit der Endung '''.ex''' dienen nur als Beispiel und werden bei der Paketerstellung nicht berücksichtigt. Durch Umbenennen und das Entfernen der Endung '''.ex''' wird dafür gesorgt, dass die entsprechende Datei bei der Erstellung des Pakets verwendet wird. In Klammern wird auf das jeweilige Programm verwiesen, das die entsprechende Kontrolldatei während der Paketerstellung weiterverarbeitet.
 
{| class="wikitable"
 
|-
 
! Dateiname
 
! Funktion
 
|-
 
|README.Debian
 
|Hinweis auf Unterschiede zur unpaketierten Software, z.B. spezielle Einstellungen, Compileroptionen u.s.w., wird nach ''/usr/share/doc/<Paketname>'' kopiert. ('''dh_installdocs''')
 
|-
 
|changelog
 
|Änderungshistorie des Pakets (siehe Abschnitt '''changelog''')
 
|-
 
|conffiles
 
|Eine Liste der im Paket verwendeten Konfigurationsdateien. Konfigurationsdateien werden von ''dpkg'' während der Installation gesondert behandelt und nicht automatisch überschrieben. In Problemfällen wird der Benutzer um eine Auflösung des Konfliktes gefragt.
 
|-
 
|control
 
| Enthält Informationen über ein Paket, wie z.B. den Paketnamen oder Paketabhängigkeiten. Diese Informationen können mittels ''dpkg -info'' abgefragt werden (siehe Abschnitt '''control''').
 
|-
 
|copyright
 
|Enthält das Copyright des Paketerstellers und des Autors der Upstream-Version sowie weitere Lizenzinformationen (siehe Abschnitt '''copyright''').
 
|-
 
|cron.d
 
|Automatisch zu erstellende crontab-Einträge.('''dh_installcron''')
 
|-
 
|dirs
 
|Eine Liste von Verzeichnissen, die ggf. von dpkg erstellt werden müssen. ('''dh_files''')
 
|-
 
|docs
 
|Eine Liste von Dateien, die nach /usr/share/doc/<Paketname> kopiert werden. ('''dh_installdocs''')
 
|-
 
|emacsen-install
 
|Emacs-spezifische Kontrolldatei, die die Installation, automatische Übersetzung in Binärformate, automatisches Laden sowie das Entfernen von Emacs-Lisp-Dateien steuert. ('''dh_installemacsen''')
 
|-
 
|doc-base.<Paketname>
 
|Wird benötigt, um HTML-Dokumentationen bei ''doc-base'' zu registrieren.
 
|-
 
|init.d
 
|Kann ein Startup-Skript enthalten, mit dem ein Dienst gestartet/gestoppt werden kann
 
|-
 
|manpage.1.ex
 
|Beispielrumpf einer Manpage. ('''dh_installman''')
 
|-
 
|manpage.sgml.ex
 
|Beispielrumpf einer Manpage (SGML-Format) ('''dh_installman''')
 
|-
 
|menu
 
|Ermöglicht Einträge in das Debian-Menü.
 
|-
 
|postinst
 
|Nach der Installation des Pakets auszuführendes Skript
 
|-
 
|postrm
 
|Nach dem Entfernen des Pakets auszuführendes Skript
 
|-
 
|preinst
 
|Vor der Installation des Pakets auszuführendes Skript
 
|-
 
|prerm
 
|Vor dem Entfernen des Pakets auszuführendes Skript
 
|-
 
|rules
 
|Enthält das zentrale Regelwerk für ''dpkg-buildpackage'' zum Bauen des Pakets (siehe Abschnitt '''rules''')
 
|-
 
|watch
 
|Prüft ob eine aktuellere Version eines Pakets verfügbar ist
 
|-
 
|}
 
 
 
== debian/control  ==
 
 
 
Die ''control''-Datei enthält verschiedene Informationen, die '''dpkg''' benötigt, um das Paket bearbeiten zu können. Die von '''dh_make''' erstellte initiale ''control''-Datei sieht wie folgt aus:
 
<pre>Source: testdeb
 
Section: unknown
 
Priority: optional
 
Maintainer: Max Muster &lt;max@muster.de&gt;
 
Build-Depends: debhelper (&gt;= 5.0.0)
 
Standards-Version: 3.7.2
 
 
 
Package: testdeb
 
Architecture: any
 
Depends: ${shlibs:Depends}, ${misc:Depends}
 
Description: &lt;insert up to 60 chars description&gt;
 
&lt;insert long description, indented with spaces&gt;
 
</pre>
 
 
 
Der obere Block enthält Informationen für die Erstellung des Quell-Pakets:
 
*'''Source''' Name des Quellpakets
 
*'''Section''' Dient der Kategorisierung des Pakets (z.B. durch grafische Paketmanager)
 
*'''Priority''' Dient der Priorisierung des Pakets (z.B. durch grafische Paketmanager). Diese Einstellung hat keine Auswirkung unter UCS.
 
*'''Maintainer''' Name und die Email-Adresse des Paketerstellers
 
*'''Build-Depends''' Namen von Paketen, die zur Übersetzung dieses Pakets zwingend benötigt werden
 
*'''Standards-Version''' Enthält die Version des Debian-Policy-Standards anhand der das Paket das letzte mal aktualisiert wurde.
 
 
 
Der untere Teil beschreibt das Binärpaket (ein Quellpaket kann auch mehrere Binärpakete erzeugen):
 
*'''Package''' Der Name eines Binärpakets
 
*'''Architecture''' Gibt die CPU-Architektur (z.B. amd64 oder i386) an, für die dieses Paket gebaut werden soll. Wird es bei ''any'' belassen, muss es für alle Plattformen übersetzt werden, wobei die jeweilige Architektur beim Paketbau eingefügt wird.<br>Handelt es sich bei dem Paket ausschließlich um architekturunabhängige Skripte oder Dokumentationen, kann ''any'' durch ''all'' ersetzt werden, so dass das Paket dann auf jeder Architektur installiert werden kann.
 
*'''Description''' Enthält eine max. 60 Zeichen lange Kurzbeschreibung des Pakets. Darunter folgt, durch Leerzeichen am Zeilenanfang eingerückt, eine beliebig lange, ausführliche Beschreibung. Leerzeilen in der Beschreibung können mit einem Leerzeichen und einem Punkt erzeugt werden.
 
 
 
Für Pakete können verschiedene Arten von Abhängigkeiten zu anderen Paketen definiert werden:
 
*'''Depends''' Abhängigkeit zur Laufzeit des Pakets. Hier können auch Variablen wie ''${shlibs:Depends}'' oder ''${python:Depends}'' stehen, die durch Paketnamen von Programmbibliotheken ersetzt werden, die beim Erstellen des Pakets als zwingend benötigt ermittelt werden (siehe '''dh_shlibdeps''')
 
*'''Recommends''' Für Pakete, die häufig zusammen mit dem Ursprungspaket eingesetzt werden und mitinstalliert werden sollten (aber nicht müssen), z.B. Pakete mit Plugins.
 
*'''Suggests''' Für Pakete die gut mit dem Ursprungspaket zusammenarbeiten, aber nicht benötigt werden, z.B. Pakete mit Dokumentationen.
 
*'''Pre-Depends''' Die angegebenen Pakete müssen installiert und konfiguriert sein, bevor das Ursprungspaket installiert werden kann (in aller Regel nicht notwendig, nur wenn auf das abhängige Paket schon im Preinst zugegriffen werden muss)
 
*'''Conflicts''' Das Paket kann nicht zusammen mit den hier aufgeführten Paketen installiert werden.
 
*'''Provides''' Das Paket tritt unter einem weiteren Namen auf.
 
*'''Replaces''' Das Paket überschreibt Dateien aus dem angegebenen Paket oder ersetzt dieses (z.B. wichtig bei der Umbenennung eines Pakets).<br>
 
 
 
In diesen Feldern können auch mehrere Paketnamen angegeben werden, die durch Kommata voneinander getrennt angegeben werden. Ein Paketname kann aber auch aus einer Liste alternativer Pakete bestehen, die dann durch das Pipe-Zeichen "|" getrennt werden müssen. Die Angabe eines Pakets kann auch mit einer exakten Versionsnummer erfolgen. Dafür stehen folgende Vergleichsoperatoren zur Verfügung:
 
 
 
{| class="wikitable"
 
|-
 
! Operator
 
! Bedeutung
 
|-
 
| <<
 
| niedriger
 
|-
 
| <=
 
| niedriger oder gleich
 
|-
 
| =
 
| gleich
 
|-
 
| >=
 
| größer oder gleich
 
|-
 
| >>
 
| größer
 
|-
 
|}
 
 
 
Diese werden, zusammen mit der gewünschten Versionsnummer, direkt hinter den Paketnamen in Klammern gefasst angegeben. Ein Beispiel:
 
 
 
<pre>
 
Depends: libc6 (>= 2.3.2.ds1-4), exim4 | mail-transport-agent
 
Conflicts: libgg0, libggi1
 
Recommends: libncurses5 (>> 5.3)
 
Suggests: libgii0-target-x (= 1:0.8.5-2)
 
Replaces: vim-python (<< 6.0), vim-tcl (<= 6.0)
 
Provides: www-browser, news-reader
 
</pre>
 
 
 
Die ''control''-Datei des Beispielpakets sieht folgendermaßen aus:
 
 
 
<pre>
 
Source: testdeb
 
Section: univention
 
Priority: optional
 
Maintainer: Max Muster <max@muster.de>
 
Build-Depends: debhelper (>= 5.0.0)
 
Standards-Version: 3.7.2
 
 
 
Package: testdeb
 
Architecture: all
 
Depends: ${shlibs:Depends}, ${misc:Depends}, ${python:Depends}
 
Description: Ein Beispielpaket im Rahmen einer UCS-Dokumentation.
 
Dieses Paket soll die Struktur von Debian Paketen beschreiben.
 
Außerdem erläutert die Dokumentation:
 
.
 
  + Grundsätzliches zu Debian/Univention Paketen.
 
  + Installationsverlauf.
 
  + Aufbau eines Pakets.
 
  + Inhalt und Funktion der Kontroll Dateien.
 
.
 
For more information about UCS, refer to:
 
http://www.univention.de/
 
</pre>
 
 
 
Es wurde eine zusätzliche Abhängigkeit zu ''${python:Depends}'' hinzugefügt. Diese Variable wird während der Paketerstellung von dem Debhelper-Programm '''dh_python''' durch die Namen der benutzten Python-Pakete ersetzt. '''dh_python''' untersucht dabei den Inhalt des Pakets nach Python-Skripten
 
und -Modulen und generiert aus diesen Informationen Abhängigkeiten für das Paket.
 
 
 
== debian/copyright ==
 
 
 
Die ''copyright''-Datei enthält die Lizenzinformationen des Quellcodes des Pakets. Dazu zählen auch die Kontaktadressen der Entwickler. Die von '''dh_make''' erstellte Version:
 
 
 
<pre>
 
This package was debianized by Max Muster <max@muster.de> on
 
Mon, 21 Mar 2009 13:46:39 +0100.
 
 
 
It was downloaded from <fill in ftp site>
 
 
 
Copyright:
 
Upstream Author(s): <put author(s) name and email here>
 
 
 
License:
 
<Must follow here>
 
</pre>
 
 
 
Die Datei kann nach Belieben angepasst werden, es gelten keine Syntax-Regeln.
 
 
 
== debian/changelog ==
 
 
 
Die ''changelog''-Datei enthält eine Historie der Änderungen, die an diesem Paket vorgenommen wurden. Die von '''dh_make''' erzeugte Datei sollte ungefähr den folgenden Inhalt aufweisen:
 
 
 
<pre>
 
testdeb (0.1-1) unstable; urgency=low
 
 
 
  * Initial Release.
 
 
 
-- Max Muster <max@muster.de>  Mon, 21 Mar 2005 13:46:39 +0100
 
</pre>
 
 
 
Wird eine neue Paketversion gebaut, muss die Versionsnummer erhöht und ein Kommentar zu den erfolgten Änderungen in dieser Datei eingetragen werden. Am einfachsten ist dies mit dem Programm '''debchange''' bzw. dem Alias '''dch''' aus dem Paket ''devscripts''
 
 
 
Folgender Befehl, ausgeführt im Arbeitsverzeichnis, löst diese Aktion aus:
 
 
 
<pre>
 
dch -i
 
</pre>
 
 
 
Danach sollte die ''changelog''-Datei so aussehen:
 
 
 
<pre>
 
testdeb (0.1-2) unstable; urgency=low
 
 
 
  * Nur eine Versionsnummer höher!
 
 
 
-- Max Muster <max@muster.de>  Mon, 21 Mar 2005 17:55:47 +0100
 
 
 
testdeb (0.1-1) unstable; urgency=low
 
 
 
  * Initial Release.
 
 
 
-- Max Muster <max@muster.de>  Mon, 21 Mar 2005 13:46:39 +0100
 
</pre>
 
 
 
Das Datums- und Zeitformat muss RFC822-konform sein.  Die aktuelle Uhrzeit/Datum kann mit dem Befehl '''date -R''' im RFC822-Format ausgegeben werden.
 
 
 
== debian/rules ==
 
 
 
Die ''rules''-Datei enthält die eigentlichen Befehlssequenzen, mit denen '''dpkg-buildpackage''' das Paket schließlich erstellt. Die Datei ist ein Makefile und enthält mehrere Regeln (Rules), die bestimmen, wie mit dem Quellcode verfahren werden soll. Generell ist eine Regel folgendermaßen aufgebaut:
 
 
 
<pre>
 
ZIEL: VORAUSSETZUNG
 
BEFEHL
 
...
 
</pre>
 
 
 
Jede Regel besteht aus mindestens einem '''ZIEL''' (Target), das der Name einer Aktion (z.B. '''build:''' oder '''install:''') oder ein Dateiname sein kann. Wildcards (z.B. *) in den Dateinamen sind ebenfalls erlaubt. Die '''BEFEHL'''-Zeile muß mit einem Tab beginnen und wird durch die Shell ausgeführt.
 
 
 
Diese Regel steuert das Verhalten von '''make'''. Sie gibt an, wann das Ziel veraltet ist und wie '''make''' es erneuern kann. Das Kriterium, nach dem '''make''' entscheidet, ob das Ziel veraltet ist, ist in der '''VORAUSSETZUNG''' beschrieben. Sie kann eine oder mehrere Dateien, ein anderes Ziel oder auch eine Datei innerhalb eines Archivs enthalten. Wie bei '''ZIEL''' sind auch hier Wildcards erlaubt.
 
 
 
Ein '''ZIEL''' ist veraltet, sobald es nicht existiert oder mindestens eine der Dateien der '''VORAUSSETZUNG''' neuer als das '''ZIEL''' ist. In einem solchen Fall wird mittels des unter '''BEFEHL''' angegebenen Kommandos das '''ZIEL''' neu erzeugt.
 
 
 
Zu beachten ist, dass '''dh_make''' lediglich ein Beispiel der ''rules''-Datei erzeugt. Der Inhalt dieser Datei sollte immer angepasst werden.  Die von '''dh_make''' generierte Datei sollte in etwa den folgenden Inhalt aufweisen:
 
 
 
<pre>
 
#!/usr/bin/make -f
 
# -*- makefile -*-
 
# Sample debian/rules that uses debhelper.
 
# This file was originally written by Joey Hess and Craig Small.
 
# As a special exception, when this file is copied by dh-make into a
 
# dh-make output file, you may use that output file without restriction.
 
# This special exception was added by Craig Small in version 0.37
 
# of dh-make.
 
 
 
# Uncomment this to turn on verbose mode.
 
#export DH_VERBOSE=1
 
 
 
CFLAGS = -Wall -g
 
ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
 
        CFLAGS += -O0
 
else
 
        CFLAGS += -O2
 
endif
 
 
 
configure: configure-stamp
 
configure-stamp:
 
        dh_testdir
 
        # Add here commands to configure the package.
 
 
 
        touch configure-stamp
 
 
 
build: build-stamp
 
 
 
build-stamp: configure-stamp
 
        dh_testdir
 
        # Add here commands to compile the package.
 
        $(MAKE)
 
        #docbook-to-man debian/testdeb.sgml > testdeb.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) clean
 
        dh_clean
 
 
 
install: build
 
        dh_testdir
 
        dh_testroot
 
        dh_clean -k
 
        dh_installdirs
 
        # Add here commands to install the package into debian/testdeb.
 
        $(MAKE) install DESTDIR=$(CURDIR)/debian/testdeb
 
 
 
# 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_installchangelogs
 
        dh_installdocs
 
        dh_installexamples
 
#      dh_install
 
#      dh_installmenu
 
#      dh_installdebconf
 
#      dh_installlogrotate
 
#      dh_installemacsen
 
#      dh_installpam
 
#      dh_installmime
 
#      dh_installinit
 
#      dh_installcron
 
#      dh_installinfo
 
        dh_installman
 
        dh_link
 
        dh_strip
 
        dh_compress
 
        dh_fixperms
 
#      dh_perl
 
#      dh_python
 
#      dh_makeshlibs
 
        dh_installdeb
 
        dh_shlibdeps
 
        dh_gencontrol
 
        dh_md5sums
 
        dh_builddeb
 
 
 
binary: binary-indep binary-arch
 
.PHONY: build clean binary-indep binary-arch binary install configure
 
</pre>
 
 
 
Der erste Block konfiguriert die zu benutzenden Compiler-Flags ('''CFLAGS'''), das Setzen von '''DH_VERBOSE''' konfiguriert den Debug-Level der Debian-Paketskripte. Da es sich bei der ''rules''-Datei lediglich um ein Grundgerüst handelt, ist dies nur ein Hinweis, wie im Allgemeinen vorzugehen ist.
 
 
 
Die Regeln '''configure''' und '''configure-stamp''' sind für die Konfiguration des Pakets zuständig. Wenn das Quellpaket Autoconf oder Automake verwendet, sind dort evtl. schon Schritte angegeben, die '''dh_make''' aus den ''config''-Dateien des Quellpakets generiert hat. '''build''' und '''build-stamp''' steuern den eigentlichen Erstellungsprozess des Pakets. Die Regel '''clean''' verwaltet die notwendigen Schritte zum Entfernen temporärer Dateien aus dem Paketbaum.
 
 
 
'''binary-indep''' erstellt architekturunabhängige Pakete. Ist das nicht
 
der Fall, ist hier keine Änderung notwendig. '''binary-arch''' erzeugt dementsprechend architekturabhängige Paket-Bestandteile.
 
 
 
Da in diesem Paket in der ''control''-Datei '''Architecture:''' auf '''all''' gesetzt wurde, sollten alle Anweisungen zum Erzeugen des Pakets in der Regel '''binary-indep''' platziert werden. '''binary-arch''' bleibt in diesem Fall leer.
 
 
 
Unterhalb der '''binary-arch'''-Regel finden sich zahlreiche mit ''dh_'' beginnende Debhelper-Programme. In den meisten Fällen gibt der Name Aufschluss über ihre Funktion. Nähere Informationen finden sich in den Manpages des jeweiligen Programms.
 
 
 
Da eine Beschreibung aller Debhelper-Programme einen enormen Umfang annehmen würde, werden im Folgenden nur die wichtigsten Programme kurz aufgeführt:
 
 
 
{| class="wikitable"
 
|-
 
! Programmname
 
! Beschreibung
 
|-
 
| dh_testdir
 
| Überprüft, ob das aktuelle Arbeitsverzeichnis sich im obersten Verzeichnis des Quellcode-Verzeichnissbaums befindet
 
|-
 
| dh_testroot
 
| Überprüft, ob mit root-Rechten gearbeitet wird (dies kann mit ''fakeroot'' simuliert werden)
 
|-
 
| dh_installmanpages
 
| Installiert die Manpages. Es muss der Pfad zu den Manpages relativ zum obersten Verzeichnis angegeben werden
 
|-
 
| dh_installdocs
 
| Installiert ''copyright'', ''README.Debian'', ''TODO.Debian'' und Dateien aus ''debian/paketname.docs'' nach ''/usr/share/doc/paketname''
 
|-
 
| dh_installdeb
 
| Installiert die Maintainer-Skripte, z.B postinst
 
|-
 
| dh_strip
 
| Entfernt nicht benötigte Debug-Symbole aus Bibliotheken und Programmen (wird nur bei Binärprogrammen benötigt
 
|-
 
| dh_gencontrol
 
| Verarbeitet die ''control''-Datei
 
|-
 
| dh_md5sums
 
| Generiert MD5-Prüfsummen für jede Datei des Pakets
 
|-
 
| dh_fixperms
 
| Korrigiert Dateiberechtigungen auf Standardwerte
 
|-
 
| dh_builddeb
 
| Erzeugt das eigentliche Debian-Paket
 
|-
 
| dh_installinfo
 
| Installiert Info-Seiten
 
|-
 
| dh_examples
 
| Kopiert Beispieldateien in das Paket
 
|-
 
| dh_shlibdeps
 
| Generiert Abhängigkeiten auf Bibliotheken und Binär-Dateien
 
|-
 
| dh_python
 
| Durchsucht Python-Skripte bzw. -Module und generiert aus gefundenen Informationen Abhängigkeiten für das Paket. Ersetzt die Variable '''${python:Depends}''' aus der ''control''-Datei mit diesen Informationen.
 
|}
 
 
 
Die Änderungen an der ''rules''-Datei beschränken sich oft im wesentlichen auf das Auskommentieren der '''$(MAKE)''' Aufrufe. Da in diesem Beispiel aber keine Programme und Dateien übersetzt oder generiert werden, wird hier lediglich die Anweisung zum Installieren des Python-Skripts hinzugefügt:
 
 
 
<pre>
 
#!/usr/bin/make -f
 
# -*- makefile -*-
 
# Sample debian/rules that uses debhelper.
 
# This file was originally written by Joey Hess and Craig Small.
 
# As a special exception, when this file is copied by dh-make into a
 
# dh-make output file, you may use that output file without restriction.
 
# This special exception was added by Craig Small in version 0.37
 
# of dh-make.
 
 
 
# Uncomment this to turn on verbose mode.
 
#export DH_VERBOSE=1
 
 
 
CFLAGS = -Wall -g
 
ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
 
        CFLAGS += -O0
 
else
 
        CFLAGS += -O2
 
endif
 
 
 
configure: configure-stamp
 
configure-stamp:
 
        dh_testdir
 
        # Add here commands to configure the package.
 
 
 
        touch configure-stamp
 
 
 
build: build-stamp
 
 
 
build-stamp: configure-stamp
 
        dh_testdir
 
        # Add here commands to compile the package.
 
#        $(MAKE)
 
        #docbook-to-man debian/testdeb.sgml > testdeb.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) clean
 
        dh_clean
 
 
 
install: build
 
        dh_testdir
 
        dh_testroot
 
        dh_clean -k
 
        dh_installdirs
 
        # Add here commands to install the package into debian/testdeb.
 
#        $(MAKE) install DESTDIR=$(CURDIR)/debian/testdeb
 
 
 
        install -m 0755 testdeb.py debian/testdeb/usr/bin/
 
 
 
# Build architecture-independent files here.
 
binary-indep: build install
 
        dh_shlibdeps
 
        dh_python
 
        dh_md5sums
 
        dh_gencontrol
 
        dh_installdeb
 
        dh_builddeb
 
 
 
# Build architecture-dependent files here.
 
binary-arch: build install
 
 
 
binary: binary-indep binary-arch
 
.PHONY: build clean binary-indep binary-arch binary install configure
 
</pre>
 
 
 
Mit dem Befehl
 
<pre>install -m 0755 testdeb.py debian/testdeb/usr/bin/</pre>
 
wird die im Arbeitsverzeichnis befindliche Datei ''testdeb.py'' mit Standardzugriffsrechten nach ''debian/testdeb/usr/bin/'' kopiert.
 
 
 
== debian/preinst, debian/prerm, debian/postinst, debian/postrm  ==
 
 
 
Es existieren vier so genannte Maintainer-Skripte, die zu unterschiedlichen Zeitpunkten während der Paketinstallation bzw. -deinstallation aufgerufen werden:
 
 
 
*'''preinst''' Wird vor der Paketinstallation aufgerufen
 
*'''postinst''' Wird nach der Paketinstallation aufgerufen
 
*'''prerm''' Wird vor dem Entfernen des Pakets aufgerufen
 
*'''postrm''' Wird nach dem Entfernen des Pakets aufgerufen
 
 
 
Es handelt sich dabei um Shell-Skripte, die von '''dh_make''' schon mit einem Grundgerüst gefüllt wurden. Um das im Paket befindliche Python-Skript nach erfolgreicher Installation zu starten, müssen Anpassungen in der ''postinst''-Datei vorgenommen werden. Die von '''dh_make''' generierte
 
Version sollte folgenden Inhalt haben:
 
 
 
<pre>
 
#! /bin/sh
 
# postinst script for testdeb
 
#
 
# see: dh_installdeb(1)
 
 
 
set -e
 
 
 
# summary of how this script can be called:
 
#        * <postinst> `configure' <most-recently-configured-version>
 
#        * <old-postinst> `abort-upgrade' <new version>
 
#        * <conflictor's-postinst> `abort-remove' `in-favour' <package>
 
#          <new-version>
 
#        * <deconfigured's-postinst> `abort-deconfigure' `in-favour'
 
#          <failed-install-package> <version> `removing'
 
#          <conflicting-package> <version>
 
# for details, see http://www.debian.org/doc/debian-policy/ or
 
# the debian-policy package
 
#
 
 
 
case "$1" in
 
    configure)
 
 
 
    ;;
 
 
 
    abort-upgrade|abort-remove|abort-deconfigure)
 
 
 
    ;;
 
 
 
    *)
 
        echo "postinst called with unknown argument \`$1'" >&2
 
        exit 1
 
    ;;
 
esac
 
 
 
# dh_installdeb will replace this with shell code automatically
 
# generated by other debhelper scripts.
 
 
 
#DEBHELPER#
 
 
 
exit 0
 
</pre>
 
 
 
Grundsätzlich kann ein Aufruf, der nach einer erfolgreichen Installation ausgeführt werden soll, innerhalb des '''configure'''-Blocks erfolgen, da das Paket auf jeden Fall während der Installation konfiguriert wird. Weitere Blöcke mit Übergabeparametern wurden bereits von '''dh_make''' erzeugt und brauchen in
 
diesem Fall nicht beachtet werden.
 
 
 
Der Eintrag '''#DEBHELPER#''' wird, wie in den darüber stehenden Kommentaren beschrieben, automatisch von den Debhelper-Programmen ersetzt. Er sollte nicht entfernt werden.
 
 
 
Im nachfolgenden Beispiel ist lediglich ein Aufruf zum Starten des Skripts '''testdeb.py''' einzufügen. Zusätzlich wird die UCR-Variable ''update/server'' auf ''http://download.univention.de/'' gesetzt. Das Fragezeichen nach der Variable weist '''univention-config-registry''' an, die Variable nur bei Bedarf zu setzen, d.h. nur wenn sie zum Installationszeitpunkt noch keinen Wert enthält.
 
Dem Skript werden bei der Installation über Parameter weitere Informationen übergeben, anhand derer entschieden werden kann, ob bereits eine frühere Versionen des Pakets installiert war oder ist.
 
Das Beispiel zweigt, wie die UCR-Variable ''timeserver1'' auf '''time.fu-berlin.de''' gesetzt wird, falls bereits eine Version kleiner '''0.1-2''' installiert ist.
 
 
 
<pre>
 
#! /bin/sh
 
# postinst script for testdeb
 
#
 
# see: dh_installdeb(1)
 
 
 
set -e
 
 
 
# summary of how this script can be called:
 
#        * <postinst> `configure' <most-recently-configured-version>
 
#        * <old-postinst> `abort-upgrade' <new version>
 
#        * <conflictor's-postinst> `abort-remove' `in-favour' <package>
 
#          <new-version>
 
#        * <deconfigured's-postinst> `abort-deconfigure' `in-favour'
 
#          <failed-install-package> <version> `removing'
 
#          <conflicting-package> <version>
 
# for details, see http://www.debian.org/doc/debian-policy/ or
 
# the debian-policy package
 
#
 
 
 
case "$1" in
 
    configure)
 
  /usr/bin/testdeb.py
 
  univention-config-registry set \
 
                      update/server?http://download.univention.de/
 
  if dpkg --compare-versions "$2" lt-nl 0.1-2; then
 
  univention-config-registry set timeserver1?time.fu-berlin.de
 
  fi
 
    ;;
 
 
 
    abort-upgrade|abort-remove|abort-deconfigure)
 
 
 
    ;;
 
 
 
    *)
 
        echo "postinst called with unknown argument \`$1'" >&2
 
        exit 1
 
    ;;
 
esac
 
 
 
# dh_installdeb will replace this with shell code automatically
 
# generated by other debhelper scripts.
 
 
 
#DEBHELPER#
 
exit 0
 
</pre>
 
 
 
Nicht benötigte Skripte können gefahrlos entfernt bzw. auskommentiert werden.
 
 
 
== debian/conffiles, debian/dirs ==
 
 
 
Die ''conffiles''-Datei enthält den absoluten Namen von Konfigurationsdateien, falls es solche gibt. Diese Dateien werden dann bei der Installation gesondert behandelt (nicht überschrieben).
 
 
 
<pre>
 
#
 
# If you want to use this conffile, remove all comments and put files that
 
# you want dpkg to process here using their absolute pathnames.
 
# See the policy manual
 
#
 
# for example:
 
# /etc/testdeb/testdeb.conf
 
</pre>
 
 
 
Die ''dirs''-Datei ermöglicht das einfache Anlegen von Verzeichnissen im Paket-Build-Tree unterhalb von ''debian/PAKETNAME''. Sie werden einfach ohne den führenden Schrägstrich untereinander aufgelistet. Üblicherweise ist diese Datei von ''dh_make'' mit folgendem Inhalt erzeugt worden:
 
 
 
<pre>
 
usr/bin
 
usr/sbin
 
</pre>
 
 
 
= Bau des Pakets =
 
 
 
Bevor der eigentliche Erstellungsprozess des Pakets beginnen kann, sollte das Paketverzeichnis von nicht verwendeten Dateien "gesäubert" werden. Grundsätzlich können Beispiel-Dateien unterhalb von ''debian/'', die auf ".ex" enden und nicht benötigt werden, gelöscht werden.
 
 
 
Sind alle nicht verwendeten Dateien entfernt, kann der Erstellungsprozess gestartet werden. Dazu muss folgender Befehl im Paket-Quellverzeichnis (''testdeb-0.1/'') ausgeführt werden:
 
 
 
<pre>
 
dpkg-buildpackage -rfakeroot
 
</pre>
 
 
 
Die Option '''-rfakeroot''' teilt '''dpkg-buildpackage''' mit, bei der Erstellung des Pakets eine simulierte root-Umgebung zu benutzen, in der normale Benutzer Dateirechte manipulieren können (siehe '''install'''-Anweisung in der ''rules''- Datei in ''rules''). Ab UCS 2.3 kann "-rfakeroot" auch weggelassen werden, es wird ggf. automatisch aufgerufen.
 
 
 
Es sollte eine Ausgabe ähnlich der folgenden erscheinen:
 
 
 
<pre>
 
dpkg-buildpackage: source package is testdeb
 
dpkg-buildpackage: source version is 0.1-1
 
dpkg-buildpackage: source maintainer is Max Muster <max@muster.de>
 
dpkg-buildpackage: host architecture is i386
 
fakeroot debian/rules clean
 
dh_testdir
 
dh_testroot
 
rm -f build-stamp configure-stamp
 
# Add here commands to clean up after the build process.
 
dh_clean
 
dpkg-source -b testdeb-0.1
 
dpkg-source: building testdeb in testdeb_0.1.orig.tar.gz
 
dpkg-source: building testdeb in testdeb_0.1-1.diff.gz
 
dpkg-source: building testdeb in testdeb_0.1-1.dsc
 
debian/rules build
 
dh_testdir
 
# Add here commands to configure the package.
 
touch configure-stamp
 
dh_testdir
 
# Add here commands to compile the package.
 
#docbook-to-man debian/testdeb.sgml > testdeb.1
 
touch build-stamp
 
fakeroot debian/rules binary
 
dh_testdir
 
dh_testroot
 
dh_clean -k
 
dh_installdirs
 
# Add here commands to install the package into debian/testdeb.
 
install -m 0755 testdeb.py debian/testdeb/usr/bin/
 
dh_shlibdeps
 
dh_python
 
dh_md5sums
 
dh_gencontrol
 
dpkg-gencontrol: warning: unknown substitution variable ${shlibs:Depends}
 
dpkg-gencontrol: warning: unknown substitution variable ${misc:Depends}
 
dh_installdeb
 
dh_builddeb
 
dpkg-deb: building package `testdeb' in `../testdeb_0.1-1_all.deb'.
 
dpkg-genchanges
 
dpkg-genchanges: not including original source code in upload
 
dpkg-buildpackage: binary and diff upload (original source NOT included)
 
</pre>
 
 
 
Das erstellte Paket liegt nun eine Verzeichnisebene höher und kann mit '''dpkg''' installiert werden. Nach der Installation befindet sich in ''/usr/bin/'' das Python-Skript ''testdeb.py'' und eine vom postinst-Skript erstellte Datei ''/tmp/testdeb-DATUM+UHRZEIT''.
 
 
 
= Integration von Univention Configuration Registry in eigene Pakete  =
 
 
 
Pakete, die für UCS erstellt werden, nutzen teilweise zusätzliche Mechanismen, die auf einem normalen Debian-System nicht existieren. Eine Erweiterung ist die Möglichkeit Univention Configuration Registry-Variablen zu registrieren und eigene Templates mitzubringen.
 
 
 
Um diese Erweiterung zu nutzen, muss das Paket ''univention-config-dev'' zu den '''Build-Depends:''' hinzugefügt werden. Dadurch steht während des Bauvorgangs das Skript '''univention-install-config-registry''' zur Verfügung, das die Registrierung von Variablen und das Hinzufügen von Templates automatisch durchführt. Anhand einer Konfigurationsdatei wird für das Skript vorgegeben, welche Operationen es durchführen soll. Diese Datei muss unterhalb des ''debian/''-Verzeichnisses liegen und den Namen des Pakets mit der Endung ''.univention-config-registry'' tragen.
 
 
 
== Template-Konfigurationsdateien ==
 
 
 
Der Inhalt der Datei ''debian/&lt;Paketname&gt;.univention-config-registry'' kann aus mehreren Abschnitten bestehen, die wie folgt aufgebaut sind:
 
<pre>Type: &lt;type&gt;
 
[Multifile|File]: &lt;filename&gt;
 
[Subfile: &lt;sub-filename&gt;]
 
Variables: &lt;variable1&gt;
 
Variables: &lt;variable2&gt;
 
...
 
</pre>
 
Im Feld '''&lt;type&gt;''' wird der Typ des Templates eingetragen:
 
 
 
*'''file''' Die Konfigurationsdatei besteht nur aus einer einzigen Datei.
 
*'''multifile''' Setzt sich eine Konfigurationsdatei aus mehreren Templates zusammen, dann muss für diese Datei ein solcher Eintrag erstellt werden.
 
*'''subfile''' Für jedes einzelne Template, das Teil eines Multifile-Templates ist, muss ein solcher Eintrag erstellt werden.
 
 
 
<pre>
 
Type: file
 
File: etc/logrotate.conf
 
Variables: log/rotate/weeks
 
 
 
Type: multifile
 
Multifile: etc/hosts
 
Variables: interfaces/eth0/type
 
Variables: interfaces/eth.*/address
 
Variables: hostname
 
Variables: domainname
 
 
 
Type: subfile
 
Multifile: etc/hosts
 
Subfile: etc/hosts.d/00-base
 
Variables: interfaces/eth.*/address
 
Variables: hostname
 
Variables: domainname
 
</pre>
 
 
 
Anschließend wird für jeden Block eine Liste von UCR-Variablen eingetragen,  bei deren Setzen die Konfigurationsdatei neu erzeugt werden soll.  Es gibt auch die Möglichkeit reguläre Ausdrücke anzugeben. Im Beispiel wird das Muster '''interfaces/eth.*/address''' angegeben,  mit dem die Variablen für alle Netzwerk-Interface Adressen abgedeckt werden.
 
 
 
Anhand dieser Informationen kann das Skript '''univention-install-config-registry''' eine Registrierung durchführen. Damit es die genannten Templates installieren und als Konfigurationsdateien markieren kann, müssen diese in einem
 
bestimmten Verzeichnis liegen. Im Hauptverzeichnis des Quellpakets muss es dafür ein Verzeichnis ''conffiles/'' geben. Unterhalb dieses Verzeichnisses wird die benötigte Verzeichnisstruktur für die einzelnen Konfigurationsdateien, wie sie später auch auf dem System installiert werden, erstellt (z.B. conffiles/etc/hosts, d.h. ohne /etc/univention/templates/files/). Für das obige Beispiele würde folgende Struktur genutzt werden:
 
 
 
<pre>
 
conffiles/etc/logrotate.conf
 
conffiles/etc/hosts.d/00-base
 
</pre>
 
 
 
Damit das Skript während des Bauvorgangs aufgerufen wird, muss es in der Datei ''debian/rules'' eingetragen werden:
 
 
 
<pre>
 
...
 
install:
 
        ...
 
        univention-install-config-registry
 
...
 
</pre>
 
 
 
Sind all diese Anpassungen durchgeführt, wird das Paket bei der Installation die Templates installieren und registrieren.
 
 
 
== Skripte ==
 
 
 
Univention Configuration Registry kann auch auf Änderungen an Variablen mit dem
 
Aufruf von Skripten oder Modulen reagieren. Module erlauben es zusätzlich
 
auf kontextspezifische Parameter zu reagieren.
 
 
 
Um ein Template für ein Skript in einem Paket einzubinden, muss es in der
 
''.univention-config-registry'' Datei aufgeführt werden.
 
 
 
<pre>
 
Type: script
 
Script: script.sh
 
Variables: script/variablen/*
 
</pre>
 
 
 
Der Eintrag ''Type: script'' gibt an das es sich bei der Template Datei um ein Skript handelt. Die Zeile '''Script: script.sh''' verweist auf das Skript mit dem Namen '''script.sh''', welches direkt im Unterordner ''conffiles/'' des Pakets abgelegt werden muss. Durch das Setzen der Eigenschaft '''Variables:''' auf ''script/variablen/*'' wird angegeben, dass das Skript bei jeder Änderung einer UCR-Variable ausgeführt wird, welche auf das angegebene Muster passt.
 
 
 
Auf dem Zielsystem werden die Skripte in dem Ordner ''/etc/univention/template/script/'' abgelegt.
 
 
 
== Module ==
 
 
 
Einem Univention Configuration Registry-Modul werden beim Aufruf kontextspezifische Informationen mitgegeben. Dazu ist es nötig, dass das Modul in Python geschrieben und die Methode ''def handler(ucr,changes)'' implementiert ist. Dabei enthält die Variable '''ucr''' ein ConfigRegistry()-Objekt mit dem neuen/geänderten Zustand der UCR-Variablen. '''changes''' enthält ein Python-Dictionary. Jede geänderte UCR-Variable ist in dem Dictionary als Key hinterlegt. Für jeden Key ist ein Tupel bestehend aus altem um neuen Wert enthalten:
 
<pre>ucr: { 'cron/autostart': 'yes', 'update/secure_apt': 'yes', … }
 
changes: { 'changedUCRVariable1': ( 'oldValue', 'newValue' ),
 
          'changedUCRVariable2': ( 'oldValue', 'newValue' ) }</pre>
 
 
 
Die Einbindung in das Paket erfolgt ähnlich wie bei einem Skript. Dazu wird ein Eintrag in der ''.univention-config-registry'' Datei angelegt, der folgendem Aufbau entspricht.
 
 
 
<pre>
 
Type: module
 
Module: module.py
 
Variables: module/variable
 
</pre>
 
 
 
Die Eigenschaft '''Type: module''' gibt vor das es sich um ein Modul handelt welches im Ordner ''conffiles/'' abgelegt ist. Durch den Eintrag '''Module: module.py''' wird der Name des Moduls angegeben. Über den Wert ''module/variable'' der Eigenschaft  '''Variables''' wird vorgegeben für welche UCR-Variablen das Modul aufgerufen werden soll.
 
 
 
Auf dem Zielsystem werden die Module in dem Ordner ''/etc/univention/template/modules/'' abgelegt.
 
 
 
= Weiterführende Informationen =
 
 
 
*Grundlagen des Debian-Paketverwaltungssystems: http://www.debian.org/doc/FAQ/ch-pkg_basics
 
*Debian New Maintainers' Guide: http://www.debian.de/doc/manuals/maint-guide/index.de.html
 
*Debian Policy Manual: http://www.debian.org/doc/debian-policy/
 
*Debian Developer's Reference: http://www.debian.org/doc/developers-reference/
 
 
 
[[Category:Entwicklung]]
 

Latest revision as of 06:34, 3 June 2013

Personal tools