7. User-Interface¶
7.1. Menü¶
7.1.1. Einleitung¶
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
Beispiel:
/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>
Warnung
Da derzeit keine mehrsprachigen Menüs unterstützt werden, müssen die Menütexte in Englisch verfasst sein.
7.1.2. Verfügbare Tags¶
Im folgenden werden die einzelnen Tags mit den jeweiligen Optionen erklärt.
7.1.2.1. <!-- -->-Tag¶
Mit dem <!-- -Tag wird eine Kommentarzeile eingeleitet und mit dem --> -Tag beendet.
Beispiel:
<!-- Creation: 2005-04-09 jed -->
Warnung
Es dürfen nicht mehrere Kommentarzeilen zusammengefasst werden, dies führt 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
-->
7.1.2.2. <title>-Tag¶
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>
7.1.2.3. <package>-Tag¶
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>
7.1.2.4. <version>-Tag¶
Mit diesem Tag wird gesteuert, dass die aktuelle eisfair-Version und eiskernel-Version auf dieser Menüebene angezeigt werden sollen.
Beispiel:
<version/>
7.1.2.5. <menu>-Tag¶
Zum Einhängen eines Untermenüs dient der <menu>
-Tag. Hier wird mit
der Option file="untermenü"
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 Optionpackage=""
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.
7.1.2.6. <doc>-Tag¶
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 vorliegenden 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>
7.1.2.7. <edit>-Tag¶
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 bieten teilweise eigene Editoren.
Voraussetzung für die Verwendung des <edit>
-Tags sind:
Die Konfiguration steht in
/etc/config.d/$package
und entspricht den Richtlinien für eine eisfair Konfiguration.Es existiert eine Standardkonfiguration
/etc/default.d/$package
.Es wird die Gültigkeitsprüfung mittels
/etc/check.d/$package
durchgeführt.Es existiert ein spezifikationskonformes Apply-Skript
/var/install/config.d/$package.sh
zum Schreiben der „nativen“ Konfigurationsdateien des Pakets./etc/init.d/$package
kennt den Parameter „restart“ zum Neustarten des Pakets.
Beispiel:
<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 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!
7.1.2.8. <init>-Tag¶
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
angegeben. Gängige Funktionen sind start
, stop
oder
status
.
Beispiel:
<init task="start">Start Foo</init>
<init task="stop">Stop Foo</init>
<init package="foo" task="stop">Kill Foo/init>
<init task="status">Show Foo Status</init>
- Tipp für fortgeschrittene Entwickler
Beim
<init>
-Tag können mit der Optionpackage=""
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>
7.1.2.9. <script>-Tag¶
Der Aufruf paketeigener Skripte erfolgt über das 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).
Beispiel:
<script file="foo-dosomething">Do Something</script>
<script file="/usr/local/foo/doanything">Do Anything</script>
7.1.3. Menüs auf alternativen Benutzeroberflächen¶
Aktuell existieren mehrere alternative Benutzeroberflächen, die
Menüinhalte darstellen können. Dies sind das klassische Menüsystem,
die Curses-Oberfläche und das Web-Frontend „webconf“. Teilweise
unterscheiden sich die Menüsysteme in ihrer Funktion und in ihrem
Verhalten, weshalb eine Möglichkeit existiert, die Sichtbarkeit von
Menüeinträgen einzuschränken. Zu diesem Zweck kann bei den Tags <menu>
,
<doc>
, <script>
und <init>
das optionale Attribut „ui“ angegeben
werden.
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.
Beispiel:
<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>
7.1.4. Dynamisches Verhalten in Menüs¶
Falls das bis hierher beschriebene statische Verhalten von Menüs nicht ausreicht, um den Anforderungen eines Paketes zu genügen, können Skripte zur Vor- und Nachbearbeitung von Menüaktionen eingebunden werden. Damit kann z.B. dynamisch ein Untermenü oder eine Dokumentationsdatei erstellt werden.
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.
Beispiel:
<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, welche 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 |
$6 |
<menu> |
„pre“ „post“ |
$package |
„menu“ |
$menu_file |
$menuitem |
|
<doc> |
„pre“ „post“ |
$package |
„doc“ |
$doc_file |
$menuitem |
|
<edit> |
„pre“ „post“ |
$package |
„edit“ |
$config_file |
$stopstart |
$menuitem |
<init> |
„pre“ „post“ |
$package |
„init“ |
$init_file |
$init_task |
$menuitem |
<script> |
„pre“ „post“ |
$package |
„script“ |
$shell_script |
$menuitem |
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 |
Das Argument $menuitem
teilt dem aufgerufenen Skript mit, über welchen
Menüpunkt der Aufruf erfolgt ist. D.h. hier ist immer der Text des Menüeintrags
enthalten, der auch dem Anwender des Menüs angezeigt wird.
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.
7.1.5. Untermenüs einhängen und entfernen¶
Um eigene Untermenüs ins eisfair Menü einhängen zu können, gibt es die
Skripte /var/install/bin/add-menu
und /var/install/bin/del-menu
.
Beide Skripte werden mit den selben Parametern aufgerufen, deshalb
werden diese nur einmal gemeinsam erklärt.
/var/install/bin/add-menu MENUE UNTERMENUE MENUETEXT
/var/install/bin/del-menu MENUE UNTERMENUE
siehe auch:
MENUE gibt das Menü an, unter welches das neue Menü gehängt werden soll. UNTERMENUE gibt das Untermenü an, dass in MENUE eingehängt 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
Warnung
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 werden mit der alten Menüstruktur nicht funktionieren, weshalb die Verwendung der alten Struktur in neuen Releases nicht mehr zulässig ist.
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 MENUE MENUETITEL
siehe auch:
MENUE gibt das Menü an, welches erzeugt werden soll. MENUETITEL gibt den Menütitel an, welcher über dem Menü angezeigt werden soll.
7.2. Dokumentation¶
7.2.1. Dokumentation¶
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:
Welche weiteren Pakete werden benötigt?
Eventuelle Konfigurationsdateien und die in ihr definierten Variablen.
Die Punkte im Setup-Menü, soweit sie dieses Paket betreffen.
Die Funktionen des Pakets.
Wie arbeitet dieses Paket mit anderen Paketen zusammen?
Zusätzliche Dokumentation, die den Originalquellen normalerweise beiliegt (man-Pages, info-Dateien, README, etc.), dürfen nicht mitgeliefert werden.
7.2.2. Changelog¶
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 Beipiel.
Beispiel für 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 änderungen jeweils oben in der Datei
changes.txt
stehen. Uralte änderungen können mit der Zeit auch
entfallen.