Nächste Seite: Sonstiges Aufwärts: eisfair Entwickler-Dokumentation Vorherige Seite: Eisfair Konfigurationsschicht Inhalt Index
Für viele Pakete ist eine Administration unerlässlich. Sofern eine Administration vorgesehen ist, muss diese über das eisfair Setup-Menü erfolgen.
Dieses Kapitel der Entwicklerdokumentation beschreibt die Erstellung und Einbindung eigener Untermenüs in das eisfair Menüsystem.
Die einzelnen Menüs liegen unter /var/install/menu/ und sind in einer XML-ähnlichen Syntax geschrieben. Wichtig dabei ist, dass jedes Tag vollständig in einer separaten Zeile steht. Der Dateiname muss nach folgendem Schema aufgebaut sein:
setup.services.$package[.$submenu].menu
Beispiele:
/var/install/menu/setup.services.foo.menu /var/install/menu/setup.services.foo.bar.menu
Beispiel:
setup.services.foo.menu <!-- /var/install/menu/setup.services.foo.menu --> <!-- Creation: 2005-04-09 max --> <!-- Last Update: 2005-04-09 max --> <title>Administration of Package Foo</title> <package>foo</package> <version/> <doc>Read Foo Documentation</doc> <edit>Edit Foo Configuration</edit> <menu file="setup.services.foo.bar.menu">All bar functions of foo</menu> <init task="start">Start Foo</init> <init task="stop">Stop Foo</init> <script file="foo-dosomething">Do Something</script>
ACHTUNG
Da derzeit keine mehrsprachigen Menüs unterstützt werden,
müssen die Menütexte in Englisch verfasst sein.
Im folgenden werden die einzelnen Tags mit den jeweiligen Optionen erklärt.
Mit dem <!-- -Tag wird eine Kommentarzeile eingeleitet und mit dem -->-Tag beendet.
Beispiel:
<!-- Creation: 2005-04-09 jed -->
ACHTUNG
Es duerfen nicht mehrere Kommentarzeilen zusammengefasst werden,
dies fuehrt im classic Menu zu einem Fehler in der Darstellung
Beispiel: So nicht
<!-- /var/install/menu/setup.services.foo.menu Creation: 2005-04-09 max Last Update: 2005-04-09 max -->
Mit dem <title>-Tag wird der Titel des Menüs angegeben.
In jedem Menü und Untermenü muss das <title>-Tag gesetzt werden.
Beispiel:
<title>Administration of Package Foo</title>
Mit dem <package>-Tag wird die Umgebungsvariable PACKAGE gesetzt. Diese kann dann von abhängigen Skripten ausgewertet werden.
In jedem Menü und Untermenü eines Pakets muss ein <package>-Tag gesetzt werden.
Beispiel:
<package>foo</package>
Mit diesem Tag wird gesteuert, dass die aktuelle eisfair -Version und eiskernel-Version auf dieser Menüebene angezeigt werden sollen.
Beispiel:
<version/>
Dient zur Anzeige der aktuellen Paket-Installationsquelle.
Beispiel:
<url/>
Zum Einhängen eines Untermenüs dient der <menu>-Tag. Hier wird mit der Option file="untermenue" die Menüdatei des Untermenüs angegeben. Diese muss ebenfalls den Spezifikationen des vorliegenden Kapitels genügen.
Der anzuzeigende Name des Untermenüs wird innerhalb des Tags angegeben.
Beispiel:
<menu file="setup.services.foo.bar.menu">All bar functions of foo</menu>
Die Menüdateien müssen alle unter /var/install/menu/ liegen und
den Namen setup.services.$package.menu bzw.
setup.services.$package.$submenu.menu tragen.
Tipp für fortgeschrittene Entwickler
Beim Tag <menu> kann optional die Option package="" verwendet
werden um die Variable $PACKAGE explizit für ein Untermenü zu setzen.
Dies entspricht der Verwendung des Tags <package> in diesem Untermenü.
Dieses Vorgehen ist nur für generische Untermenüs (z.B. ACFH) gedacht, bei
denen eine explizite Verwendung des Tags <package> nicht möglich ist.
Die Dokumentation des Pakets oder eine beliebige andere Datei im Unix-Textformat kann mit Hilfe des <doc>-Tags angezeigt werden.
Die anzuzeigende Datei wird mit der Option file="" angegeben. Sofern die Datei im Verzeichnis /usr/share/doc/$package liegt, ist die Angabe des Dateinamens ausreichend.
Wird kein Dateiname angegeben, so wird die Datei /usr/share/doc/$package/$package.txt angezeigt.
Bei abweichenden Verzeichnissen muss der absolute Pfad mit angegeben werden.
Der Aufbau der Paketdokumentation ist im entprechenden Kapitel der verliegenden Entwicklerdokumentation beschrieben.
Zur Anzeige auf der Konsole wird automatisch der in der Basiskonfiguration eingestellte PAGER verwendet.
Beispiele:
<doc file="foo.txt">Read Foo Documentation</doc> <doc file="/usr/share/doc/foo/bar.txt">Display bar-txt</doc>
Mit dem <edit>-Tag wird eine Funktion zum Editieren der eisfair Konfiguration eingehängt. Es wird dabei immer die mit dem <package>-Tag gesetzte Konfiguration bearbeitet.
Bei der Option package="" kann optional der Name der Konfigurationsdatei unter /var/config.d/ angegeben werden. Dieser entspricht dem Namen des Paketes.
Der im Menü anzuzeigende Text ist innerhalb des Tags anzugeben.
Auf der Konsole wird automatisch der in der Basiskonfiguration eingestellte Konfigurationseditor verwendet. Alternative Administrationsoberflächen wie Webconf bieten teilweise eigene Editoren.
Voraussetzung für die Verwendung des <edit>-Tags sind:
Beispiele:
<package>foo</package> <edit>Edit Foo Configuration</edit> <edit package="myfoo">Edit MyFoo Configuration</edit> <edit stopstart>Stop process, Edit Foo configuration, start process</edit>
Die Verarbeitung des Parameters ,,restart`` in /etc/init.d/$package sieht im einfachsten Fall so aus:
Beispiel:
restart)
$0 stop
$0 start
;;
Sollte ein Neuschreiben der Konfiguration nur möglich sein, wenn das Paket vorher gestoppt wurde, dann kann dazu die Option stopstart genutzt werden. In diesem Fall wird nicht /etc/init.d/$package restart zum Neustarten des Pakets verwendet, sondern es wird als erstes das Paket mittels /etc/init.d/$package stop angehalten, bevor die Konfiguration neu geschrieben und danach das Paket wieder gestartet wird. Diese Vorgehensweise darf nur verwendet werden, wenn der normale Ablauf nicht möglich ist!
Funktionen in /etc/init.d/$package können über die standardisierte Schnittstelle <init> aufgerufen werden. Als Option wird die durchzuführende Aktion task="" übergeben.
Es wird dazu immer das Script unter /etc/init.d/ aufgerufen, das dem
in <package> gesetztem Paketnamen entspricht. Optional kann aber auch
mittels der Option package="" das anzusteuernde Skript angegeben
werden. Bei dieser Funktion können auch mehrere Pakete mit einem einzelnen
Aufruf angesteuert werden, dazu sind diese durch ein Leerzeichen (Space)
getrennt anzugeben.
Im Parameter task="" wird die Funktion sowie optional Aufrufparameter
angegeben. Gängige Funktionen sind start, stop oder status. Ein
Parameter wird durch ein Leerzeichen getrennt in task="" mit
angegeben.
Beispiele:
<init task="start">Start Foo</init> <init task="stop">Stop Foo</init> <init package="foo" task="stop -force">Kill Foo/init> <init task="status">Show Foo Status</init>
Tipp für fortgeschrittene Entwickler
Beim <init>-Tag können mit der Option package="" auch
mehrere Pakete durch Leerzeichen getrennt angegeben werden. Die jeweiligen
Aktionen werden dann für alle Pakete ausgeführt:
Beispiel:
<init package="foo bar"task="start">Foo und Bar starten</init>
Der Aufruf paketeigener Skripte erfolgt über den Tag <script>.
Dort wird mit der Option file="" das auszuführende
Skript angegeben.
Wenn dieses Skript unter /var/install/bin/ liegt, dann reicht die
Angabe des Namens (ohne absoluten Pfad). (empfohlen)
Alternativ kann auch ein Skript in einem anderen Verzeichnis aufgerufen werden. Dazu muss der absolute Pfad mit angegeben werden. Diese Methode funktioniert nicht mehr mit zukünftigen Webconf-Versionen (siehe Webconf).
Beispiele:
<script file="foo-dosomething">Do Something</script> <script file="/usr/local/foo/doanything">Do Anything</script>
Zu diesem Zweck kennen die Menü-Tags <menu>, <doc>,
<edit>, <init> und <script> die optionalen
Attribute ''pre'' und ''post''.
Als Wert für die beiden Attribute wird dabei der Verweis auf ein
Programm oder ein Shell-Skript erwartet, das entweder mit einem
absoluten Pfad oder nur mit seinem Dateinamen angegeben wird. Im
zweiten Fall wird angenommen, dass die Datei vom Paketentwickler
im Verzeichnis /var/install/bin abgelegt wurde.
Beispiele:
<menu file="setup.foo.dyn.menu" pre="foo_menu.sh">Dynamic Menu</menu> <doc pre="foo_compose_mod_doc.sh">View Foo Modules Doc</doc>
Im Beispiel wird das Skript /var/install/bin/foo_menu.sh aufgerufen, bevor das Untermenü geöffnet wird. Ein entsprechendes post-Skript würde entsprechend beim Verlassen des Untermenüs ausgeführt.
Hinweis
In fast allen Anwendungsfällen reicht das statische Verhalten
des Menüs mit dessen Möglichkeiten vollkommen aus. Das dynamische
Verhalten richtet sich in erster Linie an erfahrene Paketentwickler,
die eine Funktionalität benötigen, die in eisfair noch nicht vorgesehen
ist.
An die pre/post-Skripte bzw. -Programme werden eine Reihe von Parametern übergeben, mit denen sich deren Verhalten steuern lässt. Die zu den jeweiligen Tags passenden Parameter sind in der folgenden Tabelle dargestellt:
| Tag | $1 | $2 | $3 | $4 | $5 |
|---|---|---|---|---|---|
| <menu> | ''pre'' ''post'' | $package | ''menu'' | $menu_file | |
| <doc> | ''pre'' ''post'' | $package | ''doc'' | $doc_file | |
| <edit> | ''pre'' ''post'' | $package | ''edit'' | $config_file | $stopstart |
| <init> | ''pre'' ''post'' | $package | ''init'' | $init_file | $init_task |
| <script> | ''pre'' ''post'' | $package | ''script'' | $shell_script | |
Der Parameter $stopstart des <edit> Tags nimmt die Werte ''apply'' oder ''apply-stopstart'' an, je nachdem, ob der zu konfigurierende Dienst neu gestartet werden muss oder nicht.
Dateiverweise wie $shell_script werden immer mit einem absoluten Pfad an die pre/post-Skripte übergeben. Steht im Menü die Datei ohne Pfadangabe, dann wird der Pfad nach dem in der folgenden Tabelle dargestellten Schema erweitert.
| Datei | Name und absoluter Pfad |
|---|---|
| menu file | /var/install/menu/$menu_file |
| doc file | /usr/share/doc/$package/$doc_file |
| config file | /etc/config.d/$config_file |
| init file | /etc/init.d/$init_file |
| shell script | /etc/init.d/$shell_script |
Sollte ein pre/post-Skript eine Fehlerbedingung feststellen, so kann es durch einen Rückgabewert ungleich ''0'' (z.B. exit 1 ) diesen Fehler an das Menü signalisieren. Im Falle des pre-Skripts wird dadurch zudem die Ausführung der mit dem Menü-Tag verbundenen Aktion unterbunden. Im Falle von Fehlern sollte in jedem Fall über die Standardausgabe oder die Fehlerausgabe eine erklärende Fehlermeldung erfolgen.
Beispiel:
echo "unable to write menu file "\$3"!"
exit 1
Hinweis
Die mit einem Tag verbundene Menüaktion wird auch dann nicht
ausgeführt, wenn das in der ''pre'' Option angegebene Programm oder
Skript nicht gefunden oder nicht ausgeführt werden konnte. Eine
entsprechende Fehlermeldung wird in diesem Fall vom System erzeugt.
/var/install/bin/add-menu MENÜ UNTERMENÜ MENÜTEXT /var/install/bin/del-menu MENÜ UNTERMENÜ
| MENÜ | gibt das Menü an, unter das das neue Menü gehängt werden soll. |
| UNTERMENÜ | gibt das Untermenü an, dass in MENÜ eingehängt werden soll. |
| MENÜTEXT | gibt den in MENÜ anzuzeigenden Text an. |
Beispiele:
/var/install/bin/add-menu \
setup.services.menu \
setup.services.foo.menu \
"Foo Configuration"
/var/install/bin/del-menu \
setup.services.menu \
setup.services.foo.menu
ACHTUNG
Hier hat sich die Aufrufsyntax gegenüber der alten Version
geändert.
Der alte Aufruf mit dem auszuführenden Skript als Parameter funktioniert
aus Kompatibilitätsgründen weiter, darf aber bei neuen Releases nicht mehr
verwendet werden.
Hinweis
Bis inklusive Base Version 1.0.7 wurde eine andere Syntax für die
Menüstruktur verwendet. Dabei konnten aus dem Menü nur Shellscripts
aufgerufen werden, die ggf. wieder ein Menü anzeigten.
Diese Menüsyntax ist veraltet und wird nur übergangsweise parallel unterstützt. Alternative Administrationsoberflächen wie Webconf werden mit der alten Menüstruktur nicht funktionieren.
Deshalb ist die Verwendung der alten Struktur in neuen Releases nicht mehr zulässig.
Bei Verwendung der neuen Menüsyntax sind die alten Scripte wie
foo-edit, foo-doc oder foo-bar nicht mehr nötig, da viele Funktionen
jetzt standardisiert aufgerufen werden.
Sollte es aus einem Grund einmal nötig sein eine komplett neue Menüdatei anzulegen, so kann dies durch Aufruf des Skriptes /var/install/bin/create-menu erledigt werden.
/var/install/bin/create-menu MENÜ MENÜTITEL
| MENÜ | gibt das Menü an, welches erzeugt werden soll. |
| MENÜTITEL | gibt den Menütitel an, welcher über dem Menü angezeigt werden soll. |
Die eigentliche Dokumentation eines Pakets muss im Verzeichnis /usr/share/doc/$package abgelegt werden und eine im Unix-Textformat erstellte Datei Namens $package.txt sein.
In der Dokumentation müssen zumindest folgende Punkte genauer erklärt werden:
Zusätzliche Dokumentation, die den Originalquellen normalerweise beiliegt (man-Pages, info-Dateien, README, etc.), dürfen nicht mitgeliefert werden.
Im Verzeichnis /usr/share/doc/$package ist eine Datei changes.txt anzulegen, in dem die Veränderungen, die von Version zu Version am Paket durchgeführt werden, kurz beschrieben werden.
Bewährt hat sich eine Form wie in folgendem Beispiel:
Beispiel für ein Changelog:
1.0.6 --> 1.0.7 --------------- - added file /bin/bigone - deleted obsolete variable ONE in /etc/config.d/master - renamed /etc/old to /etc/new - - 1.0.5 --> 1.0.6 --------------- - modified some comments in /etc/this - -
Dabei sollten die letzten Änderungen jeweils oben in der Datei changes.txt stehen. Uralte Änderungen können mit der Zeit auch entfallen.