Diese Datei erklrt einige der Konvetionen, die eingehalten werden sollten,
wenn man das Projekt untersttzen will.


	RPM Spezifikations-Dateien.

Unsere Konventionen fr RPM Spezifikations-Dateien sind denen von Red Hat
hnlich, aber ein paar Unterschiede existieren fr Owl-Pakete.

1. Man beginne die spec Datei mit einem Kommentar, der das CVS Schlssel-
wort Id enthlt, gefolgt von einer Leerzeile.

2. Die bevorzugten Tag-Namen (sofern ein Synonym existiert) und die
Reihenfolge der Tags ist:
Summary, Name, Version, Release, Epoch, License, Group, URL,
Source*, Patch*, PreReq, Requires, Conflicts, Provides, Obsoletes,
Auto*, Prefix, BuildRequires, BuildArchitectures, ExcludeArch,
ExclusiveArch, BuildRoot.  Andere Tags benutzen wir (momentan) nicht.

3. Release-Nummern fr Owl-Pakete sind von folgender Form:

	owlREVISION

oder wenn man fr eine alpha/beta/prerelease Version eines bestimmten
Softwarestckes packt und der Versions-Tag auf die kommende Version
gesetzt ist:

	owl0.REVISION

oder wenn man eine ltere Sparte von Owl updatet:

	BRANCH_POINT_RELEASE.BRANCH.REVISION

wobei REVISION eine Owl spezifische Paket-Revisions Nummer ist, die
nach jedem Update inkrementiert wird.  BRANCH_POINT_RELEASE ist die
Zeichenkette, die das Erstellungsdatum der Sparte enthlt. BRANCH
ist die Spartennummer (ist "0.1" fr Owl 0.1-stable).

Wenn man auf eine neue Version updatet, sollte man REVISION auf 1
zurcksetzten und fr ltere Sparten BRANCH_POINT_RELEASE auf "owl0"
setzen.

4. Der korrekte BuildRoot Tag fr ein Owl-Paket ist:

	BuildRoot: /override/%name-%version

Unsere Arbeitsumgebung wird diesen Tag trotzdem berschreiben, aber
er wird viele daran erinnern den BuildRoot Tag zu berschreiben, wenn
sie manuell Pakete erstellen, besonders in nicht-Owl Umgebungen.

5. Verschiedene Tag's und Einstellungen kann man mit einem einzelnen
Leerzeichen setzen.  Es werden Kommata, gefolgt von einem Leerzeichen benutzt um
verschiedene Abhngigkeits-Eintrge zu trennen.  Aufzhlungen mit einem
Punkt abschliessen. In beiden Fllen, Aufzhlung und %description (wie
auch bei anderer Dokumentation), sollte vermieden werden Befehle gross zu
schreiben, selbst wenn es das erste Wort im Satz ist.  Es sei denn die
gross geschriebene Form ist der offizielle Name der Software.  Um Stze
zu trennen sollten zwei Leerzeichen benutzt werden.

6. Unsere Arbeitsumgebung setzt die optimierenden C/C++ compiler flags
in %optflag. Dort werden sie so gesetzt, dass sie fr einzelne Programme
optimal sind und nicht zu viele Warnungen produzieren.  Wenn man
Bibilotheken bersetzt kann man andere flags benutzen, indem man die
folgenden zwei Zeilen genau ber der %build Sektion platziert:

	# Use optflags_lib for this package if defined.
	%{expand:%%define optflags %{?optflags_lib:%optflags_lib}%{!?optflags_lib:%optflags}}

Dies wird eine Optimierung ausschalten die verhindert, dass man die
Programme, die gegen diese Bibilothek gelinkt werden, debuggen kann
(selbst wenn die Programme selber korrekt zum debuggen bersetzt worden
sind).  Auf dem x86 wird zustzlich ein korrektes Stack-Verhalten fr
effizientere Gleitkomma- und MMX-Operationen gewhrleistet.  (Wir sind
nur wegen der Dritt-Software so freundlich. Wir haben, bei der Software
die Teil von Owl ist, keinen grossen Anteil an Fliesskomma Arithmetik.
Deswegen brauchen wir kein korrekteres Stack Verhalten, wenn wir unsere
Software bersetzen.)

Es wird auch empfohlen, dass die Quelltexte sauber genug sind, damit
keine einzige Kompilerwarnung erscheint, wenn man mit "gcc -Wall" ber-
setzt.  Wenn dem so ist, ist der richtige Weg um die -Wall Option zu
bergeben, einfach folgende Zeile vor der %build Sektion einfgen:

	%{expand:%%define optflags %optflags -Wall}

7. Subshells whrend des Erstellens, pre/post-install/uninstall und
sonstige Scripts sind zu vermeiden, da sich in ihnen potentielle Fehler
verstecken knnen.  Wenn man eine Subshell verwenden will um kurz-
zeitig das Verzeichnis zu wechseln, sollte man pushd und popd stattdessen verwenden.
Wird wirklich eine Subshell verwendet, empfehlen wir dass man
die Kommandos der Subshell manuell in der Elternshell eingibt.

8. Benutze Tabulatoren um Anweisungsblcke oder umgebrochene Zeilen
in Scripts einzurcken.  pushd ... popd Blcke sollten allerdings
nicht eingerckt werden.

9. Um numerische Werte zu vergleichen, benutze -eq oder -ne und nicht =
oder !=. Dies gilt besonders fr das $1 Argument, was RPM zu den Scripts
weiterleitet. Das $1 nicht in Anfhrungszeichen setzen, das Paket muss dem
Paket-Manager vertrauen, dass es eine korrekte Eingabe bekommt.

10. Anstatt von $RPM_BUILD_ROOT sollte das %buildroot Makro verwendet werden,
ebenso %_sourcedir anstatt von $RPM_SOURCE_DIR.  Quelltexte sollte nicht mit
Zahlen (z.B. mit %SOURCE1), sondern mit %_sourcedir/HIERDIEDATEI referenziert
werden.

11. Um die verschiedenen Tools aufzurufen, die beim bersetzen bentigt werden,
sollten die entsprechenden RPM Makros benutzt werden.  Zum Beispiel %__make
anstatt dem direkten Aufruf von make oder %__cc anstatt von gcc usw.  Fr Shell
Kommandos, wie z.B. cp, mv oder rm sollten die Makros allerdings nicht
verwendet werden.

12. Die Option "-f" (force) von Shell Kommandos sollte nicht untig eingesetzt
werden.  Dies gilt insbesondere fr "rm".  Dadurch, dass "-f" nicht benutzt
wird, knnen wir Dateien sehen, ob diese obsoltet geworden sind oder einer
berarbeitung bedrfen (z.B., weil ein Datei nach einem Update einen neuen
Dateinamen hat oder dann an einer anderen Stelle liegt).  Zudem hilft es Fehler
beim bersetzen zu entdecken, wo eine Datei von ihrer erwarteten Stelle
verschwunden ist.  Sollte "-f" aus bestimmten Grnden doch verwendet werden,
den Grund bitte in einem kurzen, einzeiligen Kommentar ber dem entsprechenden
Kommando festhalten.

13. In %changelog das Datum eintragen.  Zwei Zeichen fr den Tag, evtl.
mit einer fhrenden Null.  Wenn in %changelog ein neuer Eintrag gemacht wird,
bitte die aktuelle Version und das Release hinter der E-Mail Adresse eintragen,
zum Beispiel so:

	* Mon Mar 10 2003 Your Name <you@example.com> 1.0-owl1

14. Um unsere spec Dateien portabel zu halten, sollten sich diese auf einem
nicht-Owl System entwerder einwandfrei bersetzen lassen oder gar nicht
funktionieren.  Die spec Dateien, die whrend der bersetzung in archive/*tar.gz
kommen, sollten auf jeden Fall auf nicht-Owl System portierbar sein.  In allen
spec Dateien, egal ob portierbar oder nicht, sollte die %clean Sektion vermieden
werden (die Owl Umgebung ignoriert diese Einstellung sowieso und es sollte nicht
nachteillig sein, wenn der bersetzte Quelltext am Ende nicht gelscht wird).

	Namen der Patch-Dateien.

Die folgende Syntax wird fr Patch-Dateinamen benutzt:

	NAME-VERSION-ORIGIN-WHAT.diff

wobei NAME und VERSION selbiges vom Paket sind, ORIGIN ist eine Ab-
krzung der Distribution, von der der Patch stammt und WHAT ist eine
Beschreibung was der Patch macht oder wofr er ist.

Sollte ein einziger Patch aus mehreren Stcken von verschiedenen
Distributionen bestehen, schreibt man alle, geordnet nach der Relevanz,
in ORIGIN.  Fr Patches, die als ein Teil von Owl entwickelt wurden,
setzt man ORIGIN auf "owl".  Wenn der Patch von einer anderen Distribution
stammt, aber signifikante nderungen vorgenommen wurden, sollte ORIGIN
zustzlich "-owl-" enthalten (das zeigt an, dass auftretende Fehler
unser Problem sind).  Wenn ein Patch aus einem CVS Archiv entnommen
wurde, sollte ORIGIN auf "cvs" gesetzt werden. Zustzlich sollte WHAT
auf das koresspondierende Datum (JJJJMMDD) gesetzt werden.  Bei Patches
von Maintainern die (noch?) nicht im primren CVS tree (sofern einer
existiert) sind, knnte ORIGIN auf "up" gesetzt werden.

Hier ein paar gebruchliche WHATs zum benutzen:

Makefile	- Nur fr Makefile* Patches (Grossschreibung)
bound		- bound checking (Speicher- oder Zahlenberlauf)
config		- Nur fr Patches der Konfiguration (compile- oder Laufzeit)
doc		- Nur fr Dokumentations Patches
fixes		- Sicherheitspatches, Zuverlssigkeit
format		- Zeichenketten fixes im printf Stil
		  (nicht nur Sicherheitsrelevante)
info		- Nur fr texinfo Dokumentations Patches
install-no-root	- nderungen an "make install" oder hnliches als
		  nicht-root
linux		- nderungen, damit portierte Software auf Linux
		  luft
man		- Nur fr Manual-Seiten Patches
tmp		- Patches die mit temporren Dateien arbeiten
vitmp		- Patches die vitmp(1) Untersttzung hinzufgen
warnings	- Vernderungen an den Kompiler-Warnungen

Dies bedeutet NICHT, Modifikationen so zu verndern, dass
sie in eine dieser Kategorien passen.  Meistens ist es vorteilhaft
bestimmte Sachen anders zu machen.  Dies bedeutet nur, falls man einen
Patch hat, der in eine dieser Kategorien passt, ihn auch passend
benennt (zum Beispiel "tmp" und nicht "mkstemp").


	Patches (wieder-) erstellen.

Patches sollten folgendermassen erstellt werden:

	TZ=UTC diff -urpN NAME-VERSION.orig NAME-VERSION >
		NAME-VERSION-ORIGIN-WHAT.diff

wobei NAME-VERSION.orig und NAME-VERSION die Verzeichnisse der Original-
und modifizierten-Version des Paketes sind.  Die "-p" und "-N" Optionen
von diff(1) knnen weggelassen werden, falls sie nicht gebraucht werden.

Wenn Patches nochmal erstellt werden um zustzliche nderungen einzubringen,
sollten die bestehenden Patches mit "patch -Z" hinzugefgt werden. Zum
Beispiel wie hier:

	cd NAME-VERSION
	patch -p1 -Z < ../NAME-VERSION-ORIGIN-WHAT.diff

Durch das Benutzen von UTC Zeitstempeln knnen wir diese auch bei updates
beibehalten und zudem die Anzahl der nderungen zwischen Revisions reduzieren.


	C-Quelltext Formatierung.

Wenn man Teile von C-Code entwickelt oder importiert, die weiterhin
als Teil von Owl gepflegt werden sollen, sollte man ident(1) einmalig
mit den folgenden Optionen benutzen:

	indent -kr -i8 -nlp -nbbo -l79 -lc79

Das entspricht nicht ganz unserem bevorzugten Code-Stil und wird
deswegen bei Quelltexten in Owl noch nicht eingesetzt.


	Behandeln von temporren Dateien.

Normalerweise sollte man keine temporren Dateien benutzen.  Sollte es aber doch
einmal der Fall sein, kann man den folgenden Code verwenden:


	TMPFILE="`mktemp -t program.XXXXXXXXXX`" || exit
	trap 'rm -f -- "$TMPFILE"' EXIT
	trap 'trap - EXIT; rm -f -- "$TMPFILE"; exit 1' HUP INT QUIT TERM

Fr temporre Verzeichnisse gilt das folgende:

	TMPD="`mktemp -dt program.XXXXXXXXXX`" || exit
	trap 'rm -rf -- "$TMPD"' EXIT
	trap 'trap - EXIT; rm -rf -- "$TMPD"; exit 1' HUP INT QUIT TERM

Diese Art kann in unseren eigenen Skripts sowie Patches verwendet werden.
Das Paket sollte dann die korrekte Version von mktemp(1) verlangen:

	Requires: mktemp >= 1:1.3.1

Benutze Requires, PreReq und/oder BuildRequires wie gewhnlich nur an den
Stellen im Paket, wo mktemp auftritt.

$Owl: Owl/doc/de/CONVENTIONS,v 1.12 2005/11/16 11:59:01 solar Exp $
