Automatisierte Erstellung von Software-Builds und -dokumentationen Teil 1 Autoren: Hagedorn, Robert; Denninger, Oliver Kontakt: {hagedorn denninger}@fzi.de Web: http://zfs.fzi.de Ort, Datum: Karlsruhe, Februar 2008
Inhalt: Einführung und Zielstellung MSBuild Doxygen Batch und Taskplaner Fazit und Ausblick Quellen Einführung und Zielstellung Im Zuge eines aktuellen Projektes entstand beiläufig die Frage, ob die Möglichkeit einer automatisierten Kompilierung des erzeugten Quelltextes besteht. Da verschiedene Programmierer zusammen als Team das Projekt bearbeiten, befindet sich der Code für alle abrufbar zentral auf einem Server. Auf diesem soll anschließend auch ein tagesaktueller Build zu Testzwecken vorgehalten werden. Außerdem entstand die Idee, diesen täglichen Build, wenn möglich, mit einer automatischen Dokumentation zu verbinden. Diese sollte aus den bereits im Quelltext vorhandenen Kommentaren eine Softwaredokumentation erstellen, die später in einem üblichen Browser aufgerufen werden kann. Dazu wird im Folgenden zuerst die Erstellung eines Builds geprüft, anschließend ein Tool zur automatischen Dokumentation gesucht und zum Schluss versucht, beides automatisiert auf einem entsprechenden Server zu arrangieren. Aufgrund der fehlenden Größe und Komplexität des folgenden Beispielprojektes soll zunächst auf die Einrichtung eines dedizierten Build-Servers verzichtet werden. Das zugrunde liegende OS ist WindowsServer2003 SP2. MSBuild [1] Grundsätzlich kommen zur automatisierten Erstellung von Builds mehrere Tools, wie zum Beispiel Make, NAnt, ant usw., in Frage. Da als Entwicklungsumgebung Microsoft Visual Studio 2005 (VS2005) eingesetzt wird, soll allerdings ein Tool verwendet werden, dass.net vollständig unterstützt. Aus diesem Grund bietet sich die frei verfügbare Microsoft Build Engine (MSBuild) an, die bereits Bestandteil von VS2005 ist. Darüber hinaus kann sie als autonome Build-Umgebung verwendet werden, wenn VS2005 nicht installiert ist. Diese Tatsache könnte sich später noch als Vorteil erweisen, wenn die Kompilierung auf einem Server stattfinden soll, auf dem kein Visual Studio installiert ist. MSBuild ist vollständig transparent und unterstützt so die komfortable Erstellung komplexer Build- Vorgänge. Für MSBuild-Projektdateien kommt die moderne XML-Syntax zum Einsatz. Projektdateien bestehen aus den sogenannten Zielen (Targets), Aufgaben (Tasks), Eigenschaften (Properties) und Elementen (Items). Die Ziele dienen der Gruppierung der durchzuführenden Aufgaben. Ein Ziel kann zum Beispiel das Löschen, Anlegen oder Kopieren eines Verzeichnisses beinhalten. Die einzelnen unteilbaren Tätigkeiten, die zum Beispiel für einen Löschvorgang von Nöten sind, werden als sogenannte Aufgabe zusammengefasst. In den Eigenschaften befinden sich Schlüssel- und Wertpaare, die zur Konfiguration von Builds verwendet werden. Hier werden Werte an Aufgaben übergeben, Werte gespeichert oder auch Bedingungen ausgewertet. Zuletzt beinhalten die Elemente diejenigen Dateien, welche kompiliert werden sollen. Hier können mehrere Projekte in listenartiger Form benannt werden. 2
Zur Beantwortung der eingangs gestellten Frage nach grundlegender Realisierbarkeit wurde ein triviales Projekt erstellt (vgl. Abbildung 1 - Beispielprojekt), das allein über eine grafische Oberfläche und keinerlei Funktionen verfügt. Abbildung 1 - Beispielprojekt Anschließend wurde eine MSBuild Projektdatei (*.proj) erstellt, in welcher der gesamte Build-Prozess beschrieben wird und welche dann in der Konsole über das Kommando MSBuild.exe [Projektdatei] aufgerufen werden kann. Im Anschluss nun der Code unserer Beispielprojektdatei. <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" DefaultTargets="Build"> <ItemGroup> <! - In die ProjectsToBuild werden alle zu kompilierenden Projekte eingetragen. --> <ProjectsToBuild Include="MSBuildSample\MSBuildSample.sln"> <Properties>Configuration=Debug</Properties> </ProjectsToBuild> </ItemGroup> <! - Führt den Build-Prozess mit den in ProjectsToBuild bestimmten Solutions aus. --> <Target Name="Build"> <MSBuild Projects="@(ProjectsToBuild)"/> </Target> </Project> Codebeispiel 1 - MSBuild-Projektdatei Das Code-Beispiel beginnt zunächst mit dem Namespace und der Benennung eines DefaultTargets, das benutzt wird, wenn beim Aufruf kein explizites Target angegeben wird. Anschließend folgt die sogenannte ItemGroup, in die alle zu kompilierenden Projekte eingetragen werden. Zuletzt definieren wir das Target, welches wir am Anfang als DefaultTarget angegeben haben. Dieses beinhaltet den Aufruf MSBuild und verweist 3
auf die Items, welche wir vorher in der ItemGroup hinzugefügt haben. Der Aufruf MSBuild kompiliert Projekt- und Solution-Dateien. Klassen werden durch den Aufruf CSC kompiliert. Ruft man nun diese Projektdatei durch MSBuild in der Konsole auf, wird die Solution MSBuildSample kompiliert, als würde man sie aus VS2005 heraus kompilieren. Doxygen [2] Nun sollen die Kommentare aus dem Quellcode heraus in ein Format extrahiert werden, dass sich nachher durch einen Browser aufrufen lässt. In diesem Fall versuchen wir eine einfache HTML-Seite zu erzeugen. Zur automatischen Dokumentation existieren bereits frei verfügbare Werkzeuge, die aus Quellcode oder sogar aus UML-Diagrammen multiple Ausgabeformate (zum Beispiel PostScript, PDF, XML) erstellen können. Auch hier beeinflusst die Entwicklungsumgebung die Auswahl. Das kostenlose Werkzeug Doxygen bietet sich für unser Vorhaben besonders an, da es die Verarbeitung von VS2005- Projektdateien und das Ausgabeformat HTML unterstützt. Doxygen lässt sich über die Befehlszeile aufrufen und benutzt eine Konfigurationsdatei, in welcher sich die spezifischen Anforderungen festlegen lassen. Diese kann durch den Wizard, erreichbar über das Doxygen GUI frontend, erstellt werden und enthält Angaben wie den Pfad zu dem jeweiligen Projekt, Hochsprachen-Optimierungen, ein Ausgabeformat (in diesem Fall HTML), einen Aufgabepfad sowie viele weitere mögliche Einstellungen (vgl. Abbildung 2 - Doxygen doxywizard). Abbildung 2 - Doxygen doxywizard Wichtig ist, dass im Code die zu extrahierenden Kommentare durch eine spezielle Kommentarsyntax gekennzeichnet sind. Da mehrere Formate angeboten werden, hier ein Beispiel für die von uns gewählte Syntax: /// <summary> /// Hier wird das Objekt foo genauer Kommentiert /// </summary> /// <param name="a">hier Informationen über a</param> /// <param name="b">hier Informationen über b</param> /// <returns>dieses Objekt gibt null zurück</returns> public object foo (int a, int b){ 4
return null; } Codebeispiel 2 - Kommentar Wir achten also während der Erstellung des Codes darauf, dass ausführlich und im richtigen Stil kommentiert wird. Dazu werden nach Fertigstellung der betreffenden Klasse oder eines Objektes die 3 Slashes /// gesetzt und Visual Studio erstellt nach Betätigen der Eingabetaste automatisch den Kommentarrumpf mit den in der Klasse oder dem Objekt enthaltenen Parametern und dem Rückgabewert. Nach der Kompilierung durch MSBuild führen wir dann Doxygen aus, welches uns automatisch unsere Dokumentation in einem Browser-abrufbaren Format erzeugt. Batch [3] und TaskPlaner Um die Vorgänge des Kompilierens und anschließenden Dokumentieren zu automatisieren greifen wir auf eine naheliegende und einfache Methode zurück. Es soll eine Batch-Datei erstellt werden, die die nötigen Aufgaben enthält und die dann täglich zu einem bestimmten Zeitpunkt durch den TaskPlaner ausgeführt wird. Die Erstellung einer Batch-Datei ist denkbar einfach. Wir erstellen eine neue Datei und speichern sie mit der Endung.bat. Anschließend geben wir die Aufgaben im Stil von DOS-Kommandos an, sowie den Pfad, wo die Ausführung der jeweiligen Anwendung (hier MSBuild und Doxygen) stattfinden soll. Nun rufen wir die Anwendung auf und übergeben alle nötigen Parameter, insofern diese nicht schon in den jeweiligen Konfigurationsdatei festgelegt wurden. Der folgende Beispiel-Code führt zuerst die Kompilierung unserer Test- Solution durch und ruft anschließend Doxygen auf, um die Dokumentation zu erstellen: cd F:\EveryDayCompile\Test_Project1\ msbuild MSBuildSample.csproj /t:rebuild /p:configuration=debug cd\ cd F:\EveryDayCompile\Documentation\ doxygen Doxyfile_TestProject1 exit Codebeispiel 3 Batchdatei Es ist darauf zu achten, dass wir bei MSBuild direkt das Projekt angeben und bei Doxygen die Konfigurationsdatei, wo der Pfad zu dem jeweiligen Projekt enthalten ist. Fazit und Ausblick Unser eingangs beschriebenes Vorhaben die automatische Ausführung von Kompilierung und Dokumentation konnte mit Hilfe von MSBuild und Doyxgen erfolgreich umgesetzt werden. Die Automatisierung lässt sich einfach, unkompliziert und kostenlos realisieren und bietet darüber hinaus auch das Potential für komplizierte Build-Vorgänge. So soll demnächst untersucht werden, ob der Code aus einem SVN Repository automatisch kompiliert werden und die Dokumentation anschließend im Intranet verfügbar gemacht werden kann. 5
Quellen [1] http://msdn2.microsoft.com/en-us/library/ms171452.aspx [2] http://www.stack.nl/~dimitri/doxygen/ [3] http://de.wikibooks.org/wiki/batch-programmierung 6