Revision as of 10:42, 16 January 2013

Einführung

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 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):

mkdir testdeb-0.1
cd testdeb-0.1

In diesem Verzeichnis wird die Datei testdeb.py angelegt, die das nachfolgende Python-Skript - das eigentlich zu installierende Programm - enthält:

#!/usr/bin/env python
# Beispielskript Univention-Paketerstellung

import time, os

file='/tmp/testdeb-%s' % time.strftime('%y%m%d%H%M', time.localtime())
f=open(file,'a')
f.close()

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:

dh_make -e max@muster.de --createorig

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:

Type of package: single binary, multiple binary, library, or kernel module?
 [s/m/l/k] s

Maintainer name : Max Muster
Email-Address   : max@muster.de
Date            : Mon, 21 Mar 2005 13:46:39 +0100
Package Name    : testdeb
Version         : 0.1
Type of Package : Single
Hit <enter> 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 / .

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.

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:

Source: testdeb
Section: unknown
Priority: optional
Maintainer: Max Muster <max@muster.de>
Build-Depends: debhelper (>= 5.0.0)
Standards-Version: 3.7.2

Package: testdeb
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: <insert up to 60 chars description>
 <insert long description, indented with spaces>

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.
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).

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:

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:

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

Die control-Datei des Beispielpakets sieht folgendermaßen aus:

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/

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:

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>

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:

testdeb (0.1-1) unstable; urgency=low

  * Initial Release.

 -- Max Muster <max@muster.de>  Mon, 21 Mar 2005 13:46:39 +0100

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:

dch -i

Danach sollte die changelog-Datei so aussehen:

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

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:

ZIEL: VORAUSSETZUNG
	BEFEHL
	...

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:

#!/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

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:

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:

#!/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

Mit dem Befehl

install -m 0755 testdeb.py debian/testdeb/usr/bin/

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:

#! /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

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.

#! /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

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).

#
# 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

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:

usr/bin
usr/sbin

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:

dpkg-buildpackage -rfakeroot

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:

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)

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/<Paketname>.univention-config-registry kann aus mehreren Abschnitten bestehen, die wie folgt aufgebaut sind:

Type: <type>
[Multifile|File]: <filename>
[Subfile: <sub-filename>]
Variables: <variable1>
Variables: <variable2>
...

Im Feld <type> 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.

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

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:

conffiles/etc/logrotate.conf
conffiles/etc/hosts.d/00-base

Damit das Skript während des Bauvorgangs aufgerufen wird, muss es in der Datei debian/rules eingetragen werden:

...
install:
        ...
        univention-install-config-registry
...

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.

Type: script
Script: script.sh
Variables: script/variablen/*

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:

ucr: { 'cron/autostart': 'yes', 'update/secure_apt': 'yes', … }
changes: { 'changedUCRVariable1': ( 'oldValue', 'newValue' ),
           'changedUCRVariable2': ( 'oldValue', 'newValue' ) }

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.

Type: module
Module: module.py
Variables: module/variable

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/

@@ Line 817: / Line 817: @@
 == Module ==
-Einem Univention Configuration Registry-Modul werden beim Aufruf kontextspezifische Informationen mitgegeben. Dazu ist es nötig, dass das Modul in Python geschrieben ist und die Methode ''def handler(bc,changes)'' implementiert. Dabei enthält die Variable '''bc''' den Namen der UCR-Variable und '''changes''' den neuen Wert auf den die Variable gesetzt wurde.
+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.

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

From Univention Wiki