
PACKAGE:	inka-buildpackage
VERSION:	0.3.5


INHALT:

1.	Das Paket
1.1.	Kurzbeschreibung
1.2.	Die Dateien
1.3.	Lizenz

2.	Umgang mit dem Paket
2.1.	Voraussetzungen
2.2.	Installation/Deinstallation
2.3.	Konfiguration
2.4.	Betrieb

------------------------------------------------------------------------------

1.	Das Paket

1.1.	Kurzbeschreibung

Das Paket enthaelt Vorlagen fuer Programmpakete, die mit inka-pkgmanager
installiert werden koennen und ein Programm, das aus den bearbeiteten Dateien
ein Tarball-Paket erstellt.


1.2.	Die Dateien

GPL-2.0.txt			Gnu General Public License 2.0
LGPL-2.1.txt			Die Gnu Lesser General Public License 2.1
ChangeLog			Enthaelt die Entwicklungsgeschichte des Pakets
README				Diese Datei
install.sh			Installationsprogramm
pkg.inf				Paketinformationen
buildpackage			Programm zum Erstellen von Paketen
buildpackage.conf		Konfigurationsdatei fuer build-inka-pkg
txttoman                        Programm zum Erstellen von Manpages
vorlage-X.X.X.tar.gz		Vorlagen der Dateien
<ROGRAMM>			Die Textvorlagen der Manpages
<PROGRAMM>.<SEKTION>.gz		Die Manpages der Befehle


1.3.	Lizenz

Diese Software wird unter der Gnu General Public License 2.0 bzw.
unter der Gnu Lesser General Public License 2.1 vertrieben.
Welche Lizenz fuer ein Produkt jeweils zutrifft ist aus einem Vermerk am
Anfang des Quelltextes des jeweiligen Programms ersichtlich.

------------------------------------------------------------------------------

2.	Umgang mit dem Paket

2.1.	Voraussetzungen

Es sind folgende Programme erforderlich:
basename, bash, cat, chmod, chown, cp, cut, echo, grep, mkdir, mv, sed, rm,
rmdir, tar, test, tree, txt2man, wc

Zusaetzlich wird das Paket inka-basis ab Version 1.3.6 benoetigt.
Es ist auf dem Server von mir herunterladbar:
http://www.ingokaesmann.de/download/linux


2.2.	Installation/Deinstallation

Zuerst muss inka-basis installiert und konfiguriert werden.
Dann mit inka-pkgmanager dieses Paket installieren.
Eine Deinstallation erfolgt ebenfalls mit inka-pkgmanager.


2.3.	Konfiguration

In der Datei '/usr/local/etc/build-inka-pkg.conf' befinden sich folgende
Variablen, mit Default-Werten, die als Beispiel dienen und den eigenen
Erfordernissen angepasst werden sollten:

Archdir		# Archiv-Verzeichnis fuer Pakete
Archown		# Eigentuemer der Dateien im Archiv-Verzeichnis fuer Pakete
Fdpdir		# Ftp-Verzeichnis
Ftpown		# Eigentuemer der Dateien im Ftp-Verzeichnis


2.4.	Betrieb

Uebersicht:
Der Benutzer, der Pakete erstellen moechte, kopiert
/usr/local/share/inkabuildpackages/vorlage-X.X.X.tar.gz in ein Verzeichnis und
entpackt den Inhalt dort.
(X.X.X steht fuer die Version.)
Wenn ein Paket erstellt werden soll, kopiert der Benutzer die benoetigten
Verzeichnisse/Dateien in ein leeres Verzeichnis und bearbeitet diese.
Nach dem Bearbeiten der Dateien durch den Benutzer, wechselt der root in ein
eigenes leeres Verzeichnis, kopiert alle Verzeichnisse und Dateien des Pakets
in sein eigenes Verzeichnis und ruft 'buildpackage -t' auf, um an die
pkg.inf eine Dateiliste anzuhaengen, die die Dateien mit den Pfaden anzeigen,
in die sie kopiert werden.
Danach ruft er 'buildpackage' auf, um das Paket zu erstellen und im
Archiv-Verzeichnis zu speichern.
Ggf. benutzt er auch die Optionen -f und/oder -p, um eine Kopie des Pakets im
Ftp-Verzeichnis, bzw. im Paket-Verzeichnis zu speichern.
Fuer weitere Informationen bezueglich der Anforderungen an den Dateinamen
siehe Manpage von 'inkapkgupdate'.

Dateien, die in jedem Fall zu bearbeiten sind:
	------------
	|doc/README|
	------------
Anzupassen sind Paketname, Version, Kurzbeschreibung, Dateien, Voraussetzung,
Installation, Konfiguration, Betrieb, Autor und Datum.
Die Datei kann auch vollstaendig anders aufgebaut sein.

	---------------
	|doc/ChangeLog|
	---------------
Anzupassen sind Version, Datum, Beschreibung.
Die Datei kann auch vollstaendig anders aufgebaut sein.

	---------
	|pkg.inf|
	---------
Anzupassen sind PKGNAME, VERSION, FILENAME, DESCRIPT, AUTHOR, ggf. PKGDEPS.
PKGNAME, VERSION, FILENAME und (ggf.) PKGDEPS werden fuer die einwandfreie
Funktion benoetigt. Die anderen Angaben sind informell.
DESCRIPT darf in mehreren Zeilen enthalten sein.
Zwischen dem ersten Teil der Zeile und dem zu bearbeitenden zweiten Teil muss
genau ein Tabulator stehen.

	------------
	|install.sh|
	------------
Es gibt vier zu bearbeitende Bereiche:
Variablenkonfigurationsabschnitt, Installationsabschnitt,
Deinstallationsabschnitt und Hauptprogrammabschnitt.

Variablenkonfigurationsabschnitt:
Es sind fuer jedes benutzte Installationsverzeichnis drei Zeilen zu aktivieren.
Die erste gibt das Quell-Verzeichnis entsprechend der Vorlage an.
Die zweite gibt die zu installierenden Dateien an. Die dritte gibt das
Zielverzeichnis an.
Die Angaben von Quell- und Zielverzeichnis sollten nicht geaendert werden.
Wenn weitere Verzeichnisse benutzt werden sollen, sind zusaetliche Absaetze
zu schreiben. Die Angabe der zusaetlichen Verzeichnisse werden beim Anhaengen
der Dateiliste an die pkg.inf nicht in ihre Zielverzeichnisse umgesetzt und
sollten deshalb in der pkg.inf manuell bearbeitet werden.
Ebenfalls nicht in der pkg.inf eingetragen werden die Dateien von
'data files 1' bis 'data files 3' und die unsichtbar markierten
Konfigurationsdateien und unsichtbar markierten Verzeichnisse in den
Home-Verzeichnissen.
Zu beachten ist, dass es fuer Konfigurationsdateien vier verschiedene
Moeglichkeiten gibt:
1. Konfdatei unter /usr/local/etc
2. Konfdatei fuer user (u. root) in deren Home-Verzeichnissen
3. Konfdatei nur fuer root in dessen Home-Verzeichnis
4. Konfdatei fuer user (u. root) in einem Unterverzeichnis des Home-Verzeichnis
Konfigurationsdateien, die in Home-Verzeichnissen installiert werden, mussen
die Endung 'rc' haben. Beispiel: feinesprogrammrc
Konfigurationsdateien werden unter '/usr/local/share/PAKETNAME' installiert.
Nach der Installation werden die Konfigurationsdateien (globale und
persoenliche) durch verschiedene Update-Funktionen in den entsprechenden
Verzeichnissen installiert/aktualisiert.
Bei 'all variables in all conf files' werden alle in mitgelieferten
Konfigurationsdateien vorhandenen Variablen angegeben (ausser der
Versions-Variablen).
Bei 'data files 1' koennen in allen Home-Verzeichnissen anzulegende
Verzeichnisse angegeben werden.
Bei 'data files 2' koennen dateien (nicht Konfigdateien) in den
Home-Verzeichnissen von user und root installiert werden.
Bei 'data files 3' koennen Dateien installiert werden, die nicht in
Home-Verzeichnissen zu installieren sind.

Installationsabschnitt:
Bei der Funktion 'install_package' sind fuer jeden vorher aktivierten
Variablenabsatz im entsprechenden Installationsabsatz die Zeilen zu
aktivieren, die fuer die Installation notwendig sind.
Eigentuemer und Berechtigungen brauchen in den meisten Faellen nicht
geaendert werden.
Sollten in der Variablendefinition weitere Absaetze geschrieben worden sein,
muessen fuer diese auch Installationsabsaetze geschrieben werden.
Anschliessend koennen nach der Zeile 'correction' Befehle angegeben werden,
die Fehler frueherer Versionen behebt (z.B. uebriggebliebene Dateien
loescht). Auch fuer den root auszugebende notwendige Hinweise koennen hier
per 'echo' eingefuegt werden.

Deinstallationsabschnitt:
Bei der Funktion 'uninstall_package' sind ebenfalls fuer jeden vorher
aktivierten Variablenabsatz im entsprechenden Deinstallationsabsatz die
Zeilen zu aktivieren, die fuer die Deinstallation notwendig sind.
Sollten in der Variablendefinition weitere Absaetze geschrieben worden sein,
muessen fuer diese auch Deinstallationsabsaetze geschrieben werden.
Dabei ist zu beachten, dass beim Aufruf 'install.sh -u' Dateien, die der
fortgefuehrten Benutzung nach einer Wiederinstallation dienen, nicht entfernt
werden sollen. (z.B. Konfigurationsdateien, Listen, die eng mit der
Benutzung des Pakets zu tun haben, und aenliche.) Beim Aufruf von
'install.sh -U' sollen alle installierten Dateien, Verzeichnisse und von den
Programmen des Pakets angelegten programmspezifischen Dateien entfernt werden,
so, als ob das Paket nie installiert wurde.
(Benutzerdatendateien, die mit Programmen des Pakets bearbeitet wurden,
sollen natuerlich nicht entfernt werden.)

Hauptprogrammabschnitt:
Im Abschnitt 'MAIN' sind die Zeilen zu deaktivieren, die nicht in Aktion zu
tretende Funktionen beinhalten.
Dies sind die Zeilen bezueglich der nicht benoetigten Installation der
Konfigurationsdateien.
Die Reihenfolge der Zeilen darf nicht geaendert werden.

Weitere Vorlagen koennen je nach Anforderung bearbeitet werden:
	-------------------
	|lbin/programmname|
	-------------------
Anzupassen sind Dateiname, Beschreibung, Autor.
Im Source-Abschnitt sind die 'main-inka-sh.conf' und 'lib-inka-std.sh' fast
immer zu sourcen.
In der 'main-inka-sh.conf ist das temporaere Verzeichnis angegeben, die
'lib-inka-std.sh wird u. a. benoetigt, um z. B. Versionsnummern von
Konfigurationsdateien zu verifizieren.

Im Variablendefinitionsabschnitt sind der Paketname, die niedrigste benoetigte
Version der Standard-Bibliothek und der Konfigurationsdatei (wenn vorhanden)
anzugeben und ggf. die niedrigste Version einer eigenen Bibliothek.
Nach der Definition der Standard-Variablen koennen eigene Variablen definiert
werden.

Die Hilfe-Funktion ist dem Programm anzupassen. Die Optionen -h, --help,
--version, --show-config, --debug, -q, -v, werden im Programm ausgewertet und
sollten deshalb nicht anderweitig vergeben werden, ohne deren Auswertung zu
aendern.

In der Funktion 'show_config' koennen Variableninhalte angezeigt werden, um
die Konfiguration des Programms dem Benutzer anzuzeigen.

Die Funktion 'main_proc' dient als Beispiel einer Grundlage einer Funktion
fuer weitere zu erstellende Funktionen.

Im Abschnitt 'PARSE COMMANDLINE' wird der Befehlsaufruf mit allen Parametern
untersucht. Optionen, von denen nur eine benutzt werden kann und die eine
wesentliche Auswirkung auf die Programmabarbeitung hat, werden der Option
'opt' zugewiesen. Der Inhalt der Option 'opt' wird weiter unten ausgewertet.
Zusaetzlich anzugebende Optionen sollten der Variablen 'opt_z' bzw. anderen
zu definierenden Variablen zugeordnet werden. Zu den Zusatzoptionen
gehoerende Argumente sind der Variablen 'opt_z1', bzw. anderen zu
definierenden Variablen zuzuordnen. Ggf. sind Variablen fuer weitere
Argumente zu definieren. Die Auswertung dieser Zusatz-Optionen und ggf.
ihrer Argumente sollten in der Funktion, in der sie benutzt werden
ausgewertet werden.
Bei der Versionskontrolle der Konfigurationsdatei ist die Zeile zu waehlen,
in der die benutzte Art von Konf-Datei enthalten ist (globale Konf-Datei,
persoenliche Konf-Datei des Benutzers). Anstelle des Worts 'Program' sollte
der Programmname benutzt werden. Daran denken, diesen Variablennamen auch in
der Konfigurationsdatei zu verwenden.
Bei der Argumentenkontrolle wird die Anzahl der Argumente geprueft und in
Variablen eingelesen. Dieser Absatz muss den Anforderungen angepasst werden.

Im Mainprogramm-Abschnitt werden der Inhalt der Variablen 'opt' ausgewertet
und die erforderlichen Funktionen aufgerufen. Dieser Abschnitt muss den
Anforderungen angepasst werden.

	---------------------------------
	|lbin/installbyuser-programmname|
	---------------------------------
Dieses Programm wird von Benutzern benutzt, um eine persoenliche
Konfigurationsdatei zu erstellen. Das ist ueblicherweise nur erforderlich,
wenn ein neues Benutzerkonto nach der Programminstallation / der
Programmaktualisierung erstellt wird oder wenn mehrere Konfigurationsdateien
erstellt werden koennen.
Anzupassen sind Dateiname, Beschreibung und Autor.
Paketname, Mindestversion der Standard-Bibliothek sind anzugeben.
Nach den Standard-Variablen sind nur die Zeilen in der Variablenkonfiguration
zu aktivieren und entsprechend anzupassen, in denen die zu installierenden
Dateien stehen.
Es gehoeren immer zwei, bzw. drei zeilen zusammen.

	----------------------------------------------
	|help1/programmnamen, bzw. help8/programmname|
	----------------------------------------------
Dies ist die Vorlage der manpage.
Mit Formatierbefehlen kann Text formatiert werden:
\fB	nachfolgender Text wird fett
\fI	nachfolgender Text wird kursiv, unterstrichen oder farbig
\fP	nachfolgender Text wird normal
Grossgeschriebener Text am Zeilenanfang wird fett.
Woerter, die mit einem Minus beginnen, werden ebenfalls fett.
Zwischen den Absaetzen muss eine Leerzeile stehen.
Regeln zum Schreiben einer manpage siehe 'man man'.
Nach dem Fertigstellen der Vorlage der manpage des Befehls kann aus der
Vorlage mit dem Befehl 'txt2man' die manpage erstellt werden.
'txt2man -T -t PROGRAMM -s SEKTION -r PAKET-VERSION PROGRAMM' zeigt die fertige
manpage im Pager zum Anschauen. Evtl. werden die Formatierungen nicht
korrekt dargestellt. Dies hat jedoch keine Auswirkung auf die korrekte
Erstellung der manpage.
Wenn manpage korrekt ist, gleichen Befehl wiederholen (ohne '-T') und nach
PROGRAMM.SEKTION.gz speichern.
Weitere Infos siehe 'man txt2man'.
Die fertigen manpages nach man1, bzw. man8 verschieben.
Bei manpages fuer andere Sektionen entsprechende Verzeichnisse erstellen und
in der install.sh eintragen.

	---------------
	|letc/xyz.conf|
	---------------
Bearbeitung siehe Vorlage, keine Variablen benutzen, die mit einer Ziffer
beginnen.
	--------------
	|lshare/xyzrc|
	--------------
Bearbeitung siehe Vorlage, keine Variablen benutzen, die mit einer Ziffer
beginnen.

Weitere zu installierenden Dateien koennen erstellt und in die passenden
Verzeichnisse gespeichert werden, bzw. weitere zusaetzliche Verzeichnisse
erstellt werden und in die 'install.sh' zum (De)Installieren eingebunden
werden.

Vor dem Ausliefern des fertigen Pakets alles pruefen, da Fehler moeglich sind.

'man <ROGRAMM>' gibt ausfuehrliche Informationen.
'<ROGRAMM> -h' gibt kurze Hilfe.

------------------------------------------------------------------------------

Ingo Kaesmann
HTTP: http://www.ingokaesmann.de/

Berlin, den 21.08.2013
