Diese Dokumentation ist in DocBook™ - XML geschrieben. Zum Bearbeiten reicht grundsätzlich ein Text-Editor. - Mehr Komfort bekommt man, wenn man einen dedizierten XML-fähigen - Editor nutzt, der spezielle Unterstützung für - DocBook™ mitbringt. Wir empfehlen dafür den - XMLmind XML - Editor, der bei nicht kommerzieller Nutzung kostenlos - ist.
Bei DocBook™ ist Prinzip, dass - ausschließlich die XML-Quelldatei bearbeitet wird. Aus dieser werden - dann mit entsprechenden Stylesheets andere Formate wie PDF oder HTML - erzeugt. Bei Lx-Office übernimmt diese Aufgabe das Shell-Script - scripts/build_doc.sh.
Das Script benötigt zur Konvertierung verschiedene - Softwarekomponenten, die im normalen Lx-Office-Betrieb nicht benötigt - werden:
- Java - in einer halbwegs aktuellen Version
Das Java-Build-System Apache Ant -
Das Dokumentations-System Dobudish für
- DocBook™ 4.5, eine Zusammenstellung
- diverser Stylesheets und Grafiken zur Konvertierung von
- DocBook™ XML in andere Formate. Das
- Paket, das benötigt wird, ist zum Zeitpunkt der
- Dokumentationserstellung
- dobudish-nojre-1.1.4.zip, aus auf code.google.com
- bereitsteht.
Apache Ant sowie ein dazu passendes Java Runtime Environment - sind auf allen gängigen Plattformen verfügbar. Beispiel für - Debian/Ubuntu:
apt-get install ant openjdk-7-jre
Nach dem Download von Dobudish muss Dobudish im Unterverzeichnis
- doc/build entpackt werden. Beispiel unter der
- Annahme, das Dobudish™ in
- $HOME/Downloads heruntergeladen wurde:
cd doc/build -unzip $HOME/Downloads/dobudish-nojre-1.1.4.zip
Die eigentliche Konvertierung erfolgt nach Installation der - benötigten Software mit einem einfachen Aufruf direkt aus dem - Lx-Office-Installationsverzeichnis heraus:
./scripts/build_doc.sh
Sowohl die XML-Datei als auch die erzeugten PDF- und - HTML-Dateien sind Bestandteil des Git-Repositories. Daraus folgt, dass - nach Änderungen am XML die PDF- und HTML-Dokumente ebenfalls gebaut - und alles zusammen in einem Commit eingecheckt werden sollten.
Die "dobudish"-Verzeichnisse bzw.
- symbolischen Links gehören hingegen nicht in das Repository.
kivitendo enthält eine Suite für automatisierte Tests. Sie
+ basiert auf dem Standard-Perl-Modul
+ Test::More.
Die grundlegenden Fakten sind:
Alle Tests liegen im Unterverzeichnis
+ t/.
Ein Script (bzw. ein Test) in t/
+ enthält einen oder mehrere Testfälle.
Alle Dateinamen von Tests enden auf .t.
+ Es sind selbstständig ausführbare Perl-Scripte.
Die Test-Suite besteht aus der Gesamtheit aller Tests,
+ sprich aller Scripte in t/, deren Dateiname
+ auf .t endet.
Für die Ausführung werden neben den für kivitendo eh schon + benötigten Module noch weitere Perl-Module benötigt. Diese + sind:
+ Test::Deep (Debian-Paketname:
+ libtest-deep-perl; Fedora:
+ perl-Test-Deep; openSUSE:
+ perl-Test-Deep)
+ Test::Exception (Debian-Paketname:
+ libtest-exception-perl; Fedora:
+ perl-Test-Exception; openSUSE:
+ perl-Test-Exception)
+ Test::Output (Debian-Paketname:
+ libtest-output-perl; Fedora:
+ perl-Test-Output; openSUSE:
+ perl-Test-Output)
+ Test::Harness 3.0.0 oder höher. Dieses
+ Modul ist ab Perl 5.10.1 Bestandteil der Perl-Distribution und
+ kann für frühere Versionen aus dem CPAN bezogen werden.
+ LWP::Simple aus dem Paket
+ libwww-perl (Debian-Panetname:
+ libwww-perl; Fedora:
+ perl-libwww-perl; openSUSE:
+ perl-libwww-perl)
+ URI::Find (Debian-Panetname:
+ liburi-find-perl; Fedora:
+ perl-URI-Find; openSUSE:
+ perl-URI-Find)
+ Sys::CPU (Debian-Panetname:
+ libsys-cpu-perl; Fedora und openSUSE: nicht
+ vorhanden)
+ Thread::Pool::Simple (Debian-Panetname:
+ libthread-pool-simple-perl; Fedora und
+ openSUSE: nicht vorhanden)
Weitere Voraussetzung ist, dass die Testsuite ihre eigene
+ Datenbank anlegen kann, um Produktivdaten nicht zu gefährden. Dazu
+ müssen in der Konfigurationsdatei im Abschnit
+ testing/database Datenbankverbindungsparameter
+ angegeben werden. Der hier angegebene Benutzer muss weiterhin das
+ Recht haben, Datenbanken anzulegen und zu löschen.
Der so angegebene Benutzer muss nicht zwingend über + Super-User-Rechte verfügen. Allerdings gibt es einige + Datenbank-Upgrades, die genau diese Rechte benötigen. Für den Fall + kann man in diesem Konfigurationsabschnitt einen weiteren + Benutzeraccount angeben, der dann über Super-User-Rechte verfügt, und + mit dem die betroffenen Upgrades durchgeführt werden. In der + Beispiel-Konfigurationsdatei finden Sie die benötigten + Parameter.
Es gibt mehrere Möglichkeiten zum Ausführen der Tests: entweder,
+ man lässt alle Tests auf einmal ausführen, oder man führt gezielt
+ einzelne Scripte aus. Für beide Fälle gibt es das Helferscript
+ t/test.pl.
Will man die komplette Test-Suite ausführen, so muss man einfach
+ nur t/test.pl ohne weitere Parameter aus dem
+ kivitendo-Basisverzeichnis heraus ausführen.
Um einzelne Test-Scripte auszuführen, übergibt man deren Namen
+ an t/test.pl. Beispielsweise:
t/test.pl t/form/format_amount.t t/background_job/known_jobs.t
Die Test-Suite umfasst Tests sowohl für Funktionen als auch für + Programmierstil. Einige besonders zu erwähnende, weil auch während der + Entwicklung nützliche Tests sind:
+ t/001compile.t -- compiliert alle
+ Quelldateien und bricht bei Fehlern sofort ab
+ t/002goodperl.t -- überprüft alle
+ Perl-Dateien auf Anwesenheit von 'use
+ strict'-Anweisungen
+ t/003safesys.t -- überprüft Aufrufe von
+ system() und exec() auf
+ Gültigkeit
+ t/005no_tabs.t -- überprüft, ob Dateien
+ Tab-Zeichen enthalten
+ t/006spelling.t -- sucht nach häufigen
+ Rechtschreibfehlern
+ t/011pod.t -- überprüft die Syntax von
+ Dokumentation im POD-Format auf Gültigkeit
Weitere Test-Scripte überprüfen primär die Funktionsweise + einzelner Funktionen und Module.
Es wird sehr gern gesehen, wenn neue Funktionalität auch gleich + mit einem Test-Script abgesichert wird. Auch bestehende Funktion darf + und soll ausdrücklich nachträglich mit Test-Scripten abgesichert + werden.
Ideen, die abgesehen von Funktionen noch nicht umgesetzt + wurden:
Ãberprüfung auf fehlende symbolische Links
Suche nach Nicht-ASCII-Zeichen in Perl-Code-Dateien (mit + gewissen Einschränkungen wie das Erlauben von deutschen + Umlauten)
Test auf DOS-Zeilenenden (\r\n anstelle von nur \n)
Ãberprüfung auf Leerzeichen am Ende von Zeilen
Test, ob alle zu übersetzenden Strings in
+ locale/de/all vorhanden sind
Test, ob alle Webseiten-Templates in
+ templates/webpages mit vom Perl-Modul
+ Template compiliert werden können
Es gibt momentan eine wenige Richtlinien, wie Test-Scripte zu + benennen sind. Bitte die folgenden Punkte als Richtlinie betrachten + und ihnen soweit es geht folgen:
Die Dateiendung muss .t
+ lauten.
Namen sind englisch, komplett klein geschrieben und
+ einzelne Wörter mit Unterstrichten getrennt (beispielsweise
+ bad_function_params.t).
Unterverzeichnisse sollten grob nach dem Themenbereich
+ benannt sein, mit dem sich die Scripte darin befassen
+ (beispielsweise background_jobs für Tests
+ rund um Hintergrund-Jobs).
Test-Scripte sollten einen überschaubaren Bereich von + Funktionalität testen, der logisch zusammenhängend ist (z.B. nur + Tests für eine einzelne Funktion in einem Modul). Lieber mehrere + Test-Scripte schreiben.
Der folgenden Programmcode enthält das kleinstmögliche + Testscript und kann als Ausgangspunkt für eigene Tests verwendet + werden:
use Test::More tests => 0; + +use lib 't'; + +use Support::TestSetup; + +Support::TestSetup::login();
Wird eine vollständig initialisierte kivitendo-Umgebung
+ benötigt (Stichwort: alle globalen Variablen wie
+ $::auth, $::form oder
+ $::lxdebug), so muss in der Konfigurationsdatei
+ config/kivitendo.conf im Abschnitt
+ testing.login ein gültiger Login-Name eingetragen
+ sein. Dieser wird für die Datenbankverbindung benötigt.
Wir keine vollständig initialisierte Umgebung benötigt, so + kann die letzte Zeile
Support::TestSetup::login();
+ weggelassen werden, was die Ausführungszeit des Scripts leicht + verringert.