Doc Tool

h1. C++ Projektvorlage

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

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

h1. Generische und flexible Projektvorlage für SDP3

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 Haupt- 

logging 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 Codegeruest 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