Doc Tool

h1. [Archiv] Generische und flexible Projektvorlage für SDP3

*Dieser Eintrag betrifft nur die Alte C++ Projektvorlage für Linux.*

https://projects.nwrk.biz/attachments/download/1/Cpp_Template.tar.gz

h2. Abhängigkeiten

Um diese Vorlage verwenden zu können werden folgende Programme vorrausgesetzt 

(ein großteil ist normalerweiße standardmäßig installiert):

perl, texlive-full, doxygen, graphviz, tcl, whiptail, liblib-abs-perl, libmoose-perl,

tk, libany-moose-perl,libnamespace-autoclean-perl, libperl6-junction-perl,

libmoosex-role-parameterized-perl, libhash-fieldhash-perl, libcapture-tiny-perl, 

libc-bin, libdata-section-simple-perl, libmoo-perl, libipc-run3-perl, libwant-perl, 

libtype-tiny-perl, exuberant-ctags, dia2code

Diese Abhängigkeiten können mit dem generate script auf einer Debian basierenden 

GNU/Linux Distribution (apt) wie folgt Installiert werden:

> $ ./generate install

Diese weiteren Programme werden außerdem empfohlen: dia, codeblocks

h2. Deckblatt

Die Angabe muss sich im Unterordner 'Dateien/doc' befinden und in 'Angabe.pdf' 

umbenannt werden. Das Angabeblatt wird automatisch beim erstellen der Latex Doku

mit den in der Abgabe.tex Datei enthaltenen Eingaben ausgefüllt. Falls

nötig können die Koordinaten der Eingaben in der 'Dateien/config/docsettings.tex' Datei 

angepasst werden.

h2. Quellcode

Der Quellcode des SDP Projekts gehört in den Unterordner 'Dateien/src'. In disem Unterordner 

befindet sich auch ein Makefile welches automatisch alle *.cpp Dateien kompiliert

und linkt. (mit und ohne Debugging Informationen). Genauere 

Infos zur Handhabung dieses Makefiles kann man aus den darin enthaltenen Kommentaren entnehmen. 

Alle Source und Header Dateien in diesem Ordner werden automatisch in die Latex Doku eingebunden.

h2. Dokumentation

Generell sollte der Sourcecode mit DoxyGen Kommentarblöcken kommentiert werden. Systemdokumentation, 

Organisatorische Informationen, Erläuterungen zum Testtreiber, und die Ausgabe des Testtreibers sollen 

in die dementsprechenden Dateien im 'Dateien/doc' Verzeichnis eingetragen werden. Allgemeine Infos 

zum Projekt sollen in der 'Abgabe.tex' Datei im Wurzelverzeichnis ergänzt werden.

h2. UML Diagramm

Diese Projektvorlage arbeitet mit zwei Diagrammformaten:

- .dot Graphviz Diagramme

- .dia Dia Diagramme

Das UML Diagramm muss sich im Unterordner 'Dateien/uml' befinden. Für die Abgabe muss es außerdem im PNG Format 

gespeichert sein und den Dateinamen 'UML.png' besitzen. Standardmäßig ('$ ./generate all') erzeugt das generate 

Script aus dem Quellcode automatisch ein Graphviz UML Diagramm und generiert daraus ein Bild im PNG Format nach

'Dateien/uml/UML.png' (*ACHTUNG:* +existiert diese Datei bereits wird sie überschrieben!+). Dieses Diagramm ist 

aber in der Regel nicht Fehlerfrei, man kann es aber mit 'dotty' editieren. Es wird auch ein mit DIA editierbares 

Diagramm erzeugt. Generell wird jedoch empfohlen selbst ein DIA UML Diagramm zu erstellen, weil man sich daraus

schon ein Codegerüst gnerieren lassen kann ('$ ./generate src'). Dazu muss das DIA Diagramm unter 'Dateien/uml/UML.dia'

gespeichert sein. Das Codegerüst wird nach 'Dateien/src/generated_from_uml' generiert. Um ein Handout mit einem 

selbstgezeichneten UML Diagramm zu erstellen muss man dieses nach 'Dateien/uml/UML.png' kopieren

und die Abgabe mittels '$ ./generate handout' zu erzeugen.

h2. Log Dateien

Sollte irgendetwas nicht Funktionieren, kann man in den Log Dateien unter 'Dateien/log' nach Hinweisen 

suchen. Die Hauptlogging Datei mit den wahrscheindlich wichtigeren Infos ist hierbei 

'Dateien/log/general.log'.

h2. Design anpassen

Das Design der Vorlage kann mit den '*.tex' Dateien im Verzeichnis

'Dateien/config' angepasst werden. Genaueres kann aus den Kommentaren

dieser Dateien entnommen werden. 

> Beschreibung der Dateien:

> packages.tex		- Beinhaltet alle verwendeten Pakete.

> setup_doxygen.tex 	- Beinhaltet alle von DoxyGen benötigten 

> 			  Pakete, und für DoxyGen extra definierte 

> 			  Befehle (aus refman.tex übernommen).

> codesettings.tex	- Beinhaltet Einstellungen für das Syntax

> 			  Highlighting der Quellcode Dateien.

> docsettings.tex		- Beinhaltet generelle Dokumenteinstellungen (

> 			  Kopf- und Fußzeile, Inhaltsverzeichnis,

> 			  Deckblatt, ...).

h2. Handhabung des generate Scripts

Das Script MUSS immer im Hauptverzeichnis mit der Verknüpfung 

im Hauptverzeichnis ausgeführt werden.

/SDP/hauptverzeichnis $ ./generate [option]

> Verfügbare Optionen:

> all     - generiert komplette Abgabe (incl. UML.png + UML.dia)

> handout - generiert komplette Abgabe (ohne UML.png + UML.dia)

> uml     - generiert nur UML.png und UML.dia

> src	- generiert ein Codegerüst aus einem bestehenden UML.dia 

> 	  Diagramm

> pdf     - generiert nur Abgabe.pdf

> clean   - löscht alle temporär angelegte Dateien

> install - installiert benötigte Paket

h2. Zusammenfassung

Damit dass "generate" Script verlässlich eine Abgabe generiert muss

folgendes gegeben sein:

- alle Abhängigkeiten Installiert ($ ./generate install)

- Angabe.pdf im Dateien/doc Ordner

- Quellcode mit DoxyGen Kommentaren im Dateien/src Ordner

- allgemeine Infos in der Abgabe.tex ausgefüllt

- ausgabe des Testtreibers in Dateien/doc/Output_Testtreiber.tex

- Resultat Testtreiber in Dateien/doc/Erlauterung_Test.tex beschrieben

- Aufgabenverteilung in Dateien/doc/Organisatorisches.tex eingetragen

- Systemspezifikation in Dateien/doc/Systemspezifikation.tex beschrieben

- UML Diagramm als Dateien/uml/UML.png gespeichert

Bleibt das generate script 'hängen' fehlt meist eine der oben genannten

Dateien.

(C) 2016 Daniel Giritzer

daniel@giritzer.eu

FH-Hagenberg, HSD