Nächste Seite: Sonstiges Aufwärts: eisfair Entwickler-Dokumentation Vorherige Seite: Eisfair Konfigurationsschicht Inhalt Index
Fuer viele Pakete ist eine Administration unerlaesslich. Sofern eine Administration vorgesehen ist, muss diese ueber das eisfair Setup-Menue erfolgen.
Dieses Kapitel der Entwicklerdokumentation beschreibt die Erstellung und Einbindung eigener Untermenues in das eisfair Menuesystem.
Die einzelnen Menues liegen unter /var/install/menu/ und sind in einer XML-aehnlichen Syntax geschrieben. Wichtig dabei ist, dass jedes Tag vollstaendig 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 Menues unterstuetzt werden,
muessen die Menuetexte in Englisch verfasst sein.
Im folgenden werden die einzelnen Tags mit den jeweiligen Optionen erklaert.
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 Menues angegeben.
In jedem Menue und Untermenue 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 abhaengigen Skripten ausgewertet werden.
In jedem Menue und Untermenue 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 Menueebene angezeigt werden sollen.
Beispiel:
<version/>
Dient zur Anzeige der aktuellen Paket-Installationsquelle.
Beispiel:
<url/>
Zum Einhaengen eines Untermenues dient der <menu>-Tag. Hier wird mit der Option file="untermenue" die Menuedatei des Untermenues angegeben. Diese muss ebenfalls den Spezifikationen des vorliegenden Kapitels genuegen.
Der anzuzeigende Name des Untermenues wird innerhalb des Tags angegeben.
Beispiel:
<menu file="setup.services.foo.bar.menu">All bar functions of foo</menu>
Die Menuedateien muessen 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 fuer
ein Untermenue zu setzen. Dies entspricht der Verwendung des Tags
<package> in diesem Untermenue.
Dieses Vorgehen ist nur fuer generische Untermenues (z.B. ACFH)
gedacht, bei denen eine explizite Verwendung des Tags <package>
nicht moeglich ist.
Die Dokumentation des Paketes 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 eingehaengt. 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 Menue anzuzeigende Text ist innerhalb des Tags anzugeben.
Auf der Konsole wird automatisch der in der Basiskonfiguration eingestellte Konfigurationseditor verwendet. Alternative Administrationsoberflaechen bieten teilweise eigene Editoren.
Voraussetzung fuer 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 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 moeglich 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 moeglich ist!
Funktionen in /etc/init.d/$package koennen ueber die standardisierte Schnittstelle <init> aufgerufen werden. Als Option wird die durchzufuehrende Aktion task="" uebergeben.
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 koennen 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. Gaengige 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 koennen mit der Option package=""
auch mehrere Pakete durch Leerzeichen getrennt angegeben werden.
Die jeweiligen Aktionen werden dann fuer alle Pakete ausgefuehrt:
Beispiel:
<init package="foo bar"task="start">Foo und
Bar starten</init>
Der Aufruf paketeigener Skripte erfolgt ueber das Tag <script>.
Dort wird mit der Option file="" das auszufuehrende
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 zukuenftigen Webconf-Versionen (siehe Webconf).
Beispiele:
<script file="foo-dosomething">Do Something</script> <script file="/usr/local/foo/doanything">Do Anything</script>
Gültige Werte für das Attribut sind bislang ''classic'' und ''cui''. Wird das Attribut nicht angegeben ist der entsprechende Menüeintrag immer sichtbar. Wird ''ui'' mit dem Wert ''classic'' angegeben ist der Eintrag lediglich im klassischen Menü sichtbar, während ''cui'' das selbe für das Curses-Menü leistet. Es ist auch möglich mehrere Werte durch Komma getrennt anzugeben.
Beispiele:
<doc file="foo.txt">This item is always visible</doc> <script file="foo.cui.sh" ui="cui">Curses mode only</script> <menu file="setup.foo.menu" ui="classic">Classic mode only</menu>
Zu diesem Zweck kennen die Menue-Tags <menu>, <doc>,
<edit>, <init> und <script> die optionalen
Attribute ''pre'' und ''post''.
Als Wert fuer 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 Untermenue geoeffnet wird. Ein entsprechendes post-Skript wuerde entsprechend beim Verlassen des Untermenues ausgefuehrt.
Hinweis
In fast allen Anwendungsfaellen reicht das statische
Verhalten des Menues mit dessen Moeglichkeiten vollkommen aus. Das
dynamische Verhalten richtet sich in erster Linie an erfahrene
Paketentwickler, welche eine Funktionalitaet benoetigen, die in
eisfair noch nicht vorgesehen ist.
An die pre/post-Skripte bzw. -Programme werden eine Reihe von Parametern uebergeben, mit denen sich deren Verhalten steuern laesst. 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 uebergeben. Steht im Menue 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 Rueckgabewert ungleich ''0'' (z.B. exit 1 ) diesen Fehler an das Menue signalisieren. Im Falle des pre-Skripts wird dadurch zudem die Ausfuehrung der mit dem Menue-Tag verbundenen Aktion unterbunden. Im Falle von Fehlern sollte in jedem Fall ueber die Standardausgabe oder die Fehlerausgabe eine erklaerende Fehlermeldung erfolgen.
Beispiel:
echo "Unable to write menu file "\$3"!"
exit 1
Hinweis
Die mit einem Tag verbundene Menueaktion wird auch dann
nicht ausgefuehrt, wenn das in der ''pre'' Option angegebene
Programm oder Skript nicht gefunden oder nicht ausgefuehrt werden
konnte. Eine entsprechende Fehlermeldung wird in diesem Fall vom
System erzeugt.
/var/install/bin/add-menu MENUE UNTERMENUE MENUETEXT /var/install/bin/del-menu MENUE UNTERMENUE
| MENUE | gibt das Menue an, unter welches das neue Menue gehaengt werden soll. |
| UNTERMENUE | gibt das Untermenue an, dass in MENUE eingehaengt werden soll. |
| MENUETEXT | gibt den in MENUE 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 gegenueber der alten Version
geaendert. Der alte Aufruf mit dem auszufuehrenden Skript als
Parameter funktioniert aus Kompatibilitaetsgruenden weiter, darf
aber bei neuen Releases nicht mehr verwendet werden!
Hinweis
Bis inklusive Base Version 1.0.7 wurde eine andere Syntax
fuer die Menuestruktur verwendet. Dabei konnten aus dem Menue nur
Shellscripts aufgerufen werden, die ggf. wieder ein Menue anzeigten.
Diese Menuesyntax ist veraltet und wird nur uebergangsweise parallel unterstuetzt. Alternative Administrationsoberflaechen werden mit der alten Menuestruktur nicht funktionieren, weshalb die Verwendung der alten Struktur in neuen Releases nicht mehr zulaessig ist.
Bei Verwendung der neuen Menuesyntax sind die alten Scripte wie
foo-edit, foo-doc oder foo-bar nicht mehr noetig, da viele Funktionen
jetzt standardisiert aufgerufen werden.
Sollte es aus einem Grund einmal noetig sein eine komplett neue Menuedatei anzulegen, so kann dies durch Aufruf des Skriptes /var/install/bin/create-menu erledigt werden.
/var/install/bin/create-menu MENUE MENUETITEL
| MENUE | gibt das Menue an, welches erzeugt werden soll. |
| MENUETITEL | gibt den Menuetitel an, welcher ueber dem Menue 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 muessen zumindest folgende Punkte genauer erklaert werden:
Zusaetzliche Dokumentation, die den Originalquellen normalerweise beiliegt (man-Pages, info-Dateien, README, etc.), duerfen nicht mitgeliefert werden.
Im Verzeichnis /usr/share/doc/$package ist eine Datei changes.txt anzulegen, in dem die Veraenderungen, die von Version zu Version am Paket durchgefuehrt werden, kurz beschrieben werden.
Bewaehrt hat sich eine Form wie in folgendem Beispiel:
Beispiel fuer ein Changelog:
1.0.6 ----- - added file /bin/bigone - deleted obsolete variable ONE in /etc/config.d/master - renamed /etc/old to /etc/new - - 1.0.5 ----- - modified some comments in /etc/this - -
Dabei sollten die letzten aenderungen jeweils oben in der Datei changes.txt stehen. Uralte aenderungen koennen mit der Zeit auch entfallen.