Seite 3: Programmierung allgemein

Inhaltsverzeichnis

Programmierung allgemein

Wie kommt man zu Schreibrechten beim CVS?

Erst einmal noch gar nicht. Aber wir freuen uns über gut getestete und dokumentierte Patches, die uns per E-Mail unter ct-sim@heise.de erreichen. Ob wir besonders aktiven Entwicklern später einen direkten Zugang zum CVS gewähren können, wird sich zeigen — nicht zuletzt anhand der Qualität der eingesandten Patches.

Wie erstelle ich einen Patch in Eclipse?

Ein Patch besteht aus einer Textdatei, die alle Unterschiede zwischen der lokalen Kopie des Codes und dem aktuellen Stand des CVS-Repositories aufführt. Haben Sie an einem oder mehreren Source-Files des c't-Sim etwas geändert, so stellen Sie zunächst über "Team/Synchronize with Repository" sicher, dass Eclipse der aktuelle Zustand des Codes im CVS bekannt ist. Um Ihre lokalen Änderungen in einen Patch zu verpacken, wählen Sie "Team/Create Patch..." Anschließend wählen Sie einen sprechenden Dateinamen für Ihren Patch (z.B. "zeitlupe.txt") und suchen sich einen Ort zum Speichern auf Ihrem System aus. Das "Diff output format" sollte "Unified" sein, das erleichtert hinterher anderen Nutzern, Ihren Patch zu übernehmen.

Dokumentieren Sie Ihren Patch — so fällt es uns und den anderen Lesern leichter zu verstehen, inwiefern Ihre Erweiterung den Simulator verbessert. Zum einen sollten Sie einen kurzen Text beilegen, der als Beschreibung auf der Projektseite veröffentlicht werden kann und — bei Übernahme ins offizielle Release — Eingang in die Changelog-Datei finden soll. Im Quellcode Ihrer neuen Funktionen selbst sollten ausführliche Javadoc-konforme Kommentare zu finden sein. Bei neuen Methoden können Sie sich unter dem Tag "@author" mit Namen und E-Mail-Adresse verewigen.

Um einen Patch einzuspielen, wählen Sie unter "Team/Apply Patch" den Ordner des Projekts aus, das Sie erweiteren wollen (z.B. ct-Sim). Den Pfad zur Patch-Datei können Sie entweder per Hand einfügen oder Sie suchen die Datei über "Browse...". Wird Ihnen im nächsten Schritt gemeldet, bestimmte zu erweiternde Dateien würden nicht existieren, ist wahrscheinlich der falsche Ordner ausgewählt. "Finish" schließt den Vorgang ab. Weitere Details lassen sich in der Hilfe von Eclipe ("Working with patches") nachlesen.

Wie erstelle ich Patches, die sich auf wesentliches konzentrieren und nicht alle meine Experimente enthalten?

Damit die Patches möglichst kompatibel zueinander sind und überschaubar bleiben, sollten sie schlank sein. Ein Patch pro Thema. Insbesondere Formatierungsänderungen usw. blähen den Patch stark auf und machen ihn im Zweifelsfall inkompatibel zu anderen.

Wir empfehlen, das Repository zweimal aus dem CVS in Eclipse zu importieren. Einmal zum beliebigen eigenen Experimentieren, einmal um die fertig debugten Ergebnisse zum Export vorzubereiten.

Im "privaten"-Repository bastelt und experimentiert man. Dann erstellt man einen Patch und spielt ihn in sein "export"-Repository ein. Dabei kann man sehr einfach und detailliert auswählen, welche Teile man übernehmen will. Am Ende erstellt man aus dem "export"-Repository wieder einen Patch, den man bei uns einreicht. Patch-Dateien sind übrigens reine ASCII-Files, man kann zur Not auch mit einem Texteditor noch Teile löschen.

Bei allen Änderungen bitte die Changelog-Einträge nicht vergessen.

Warum eigentlich Eclipse und nicht Visual Studio, Jbuilder, WinAVR, CodeWarrior oder Programmierumgebung XYZ?

Der Code für c't-Bot und c't-Sim setzt sich aus zwei Teilen zusammen, die in verschiedenen Sprachen geschrieben wurden (C und Java). Der Code läuft auf zwei verschiedenen CPU-Architekturen (x86 und AVR) und zwei Betriebssystemen (Linux und Windows). Das ergibt eine Vielzahl an Konstellationen. Um dennoch nicht den Überblick zu verlieren bietet sich eine Umgebung an, die auf allen Betriebssystemen verfügbar ist und alle Codeversionen verwalten kann. Auch ein Debugging aller Zielsysteme sollte möglich sein. Des Weiteren sollte die Entwicklungsumgebung Lesern die Möglichkeit geben ständig am aktuellen Code mitzuarbeiten und eigene Vorschläge als Patches einzureichen. Um die Dokumentation eines solchen Projektes sollte sich die IDE ebenfalls kümmern.

Eclipse gibt es für Linux und für Windows. Es ist selbst eine Java-Applikation und kann von Haus aus mit Java-Source-Code umgehen. Zum Übersetzen bindet es den Compiler aus einem Java JDK ein. Für den C-Code greift es auf den gcc zurück. Dieser wiederum kann Binaries für Windows, Linux und den Mikrocontroller übersetzen. Andere Entwicklungsumgebungen bringen teils auch andere Compiler mit. Ob diese sich mit unserem Code vertragen ist nicht getestet.

Eclipse greift direkt, ohne umständliche Tools auf unser Code-Repository (CVS) zu und erstellt im Handumdrehen Patches. Diese können wir nach Prüfung bequem importieren. Inoffizielle Patches kann jeder selbst bequem einspielen. Die beiden Hilfsprogramme javadoc und doxygen integrieren sich nahtlos in Eclipse und generieren aus dem Quelltext die Dokumentation.

Des Weiteren ist Eclipse mit den nötigen Hilfspaketen in der Lage Code für jede dieser Plattformen im Einzelschrittmodus zu debuggen. Der Mikrocontroller wird dabei komplett emuliert. Wenn man möchte kann man eclipse sogar das Flashen des Mikrocontrollers beibringen. Als letzter Punkt bleibt anzumerken, dass alle hier vorgestellten Werkzeuge kostenlos sind.

Wer sich dennoch nicht mit Eclipse anfreunden kann, muss selbst experimentieren. Für Puristen, die zum C-Programmieren nur einen Editor und eine Kommandozeile brauchen, haben wir allerdings ein Makefile vorbereitet. Dankenswerter Weise hat ein Leser ein entsprechendes Ant-File für den Java-Teil beigesteuert.

Muss ich alle Pfade für das C-Projekt ct-Bot unter Eclipse immer wieder neu an mein eigenes System anpassen, wenn ich die aktuelle Version aus dem CVS heruntergeladen habe?

Eclipse legt diese Pfade in einer Datei namens .cdtbuild ab, die direkt im Wurzelverzeichnis des Projekts legt, also beispielsweise in ...\workspace\ct-Bot\. Diese Datei wird normalerweise bei jedem Auslesen des CVS erneut überschrieben. Man kann das verhindern, indem man im gleichen Verzeichnis eine Datei namens .cvsignore anlegt (Dateiformat: Plain text Ascii). Das CVS überspringt beim Aktualisieren alle Dateien und Verzeichnisse, die in dieser Datei aufgeführt werden (jeweils durch Zeilenumbrüche getrennt). Schreibt man also in .cvsignore den Dateinamen .cdtbuild hinein, verändert CVS die Projektpfade beim nächsten Auslesen nicht mehr.

Ab wann lohnt es sich einen Patch einzuschicken?

Das hängt von der Art des Patches ab: Bugfixes: Wer einen Fehler findet und sicher ist, dass seine Lösung funktioniert, sollte ihn uns umgehend schicken, damit andere nicht in die gleichen Probleme laufen.

Feature-Adds: Sinnvolle neue Features nehmen wir ebenfalls immer gerne entgegen. Beispiele für Erweiterungen von Lesern, die bereits aufgenommen wurden sind: das Verhalten bot_glance(), die Little/Big-Endian-Unterstützung, aber auch der Support für mehr als einen Screen oder das Remote-Display und die Flash-Skripte. Wichtig ist hier, dass sie gut getestet sind.

Eigene Anpassungen: wie veränderte Listen der RC5-Fernbedienungscodes, oder minimale Veränderungen dürften nur bedingt für andere von Interesse sein. Sie kommen meist nicht in den offiziellen Tree. Wir können Sie jedoch auf die Patches-Seite stellen, sofern genug Erklärung mitkommt.

Formatierungen: Was wir nicht einbauen können sind Patches nach dem Motto: "Ich hab mal eben alle Einrückungen etwas kleiner gemacht". Das liegt schlicht und ergreifend daran, dass diese Patches hunderte von Zeilen betreffen, die wir alle per Hand gegen das Original vergleichen müssen.

Insgesamt, sollte man vor dem Einreichen selbst abwägen:

• ist mein Patch für andere von Interesse
• ist er groß/wichtig genug, dass es sich für uns lohnt ihn zu analysieren. Wir müssen nämlich jeden Patch prüfen.
  
• ist er ordentlich programmiert
  
• ist er dokumentiert

Ein paar Beispiele für Patches, die sicherlich lohnen würden:

• neue Verhalten, die einen Bot sinnvoll steuern und nicht mit den anderen Verhalten kollidieren
  
• Abgleich der Sensorwerte
  
• Nützliche Testprogramme (die sich in den bestehenden Code integrieren lassen)
  
• Alles, was TODO-Stellen im Code ersetzt
  
• Ein optisch ansprechendes Remote-Display für den c't-Sim

Alle weiteren Rahmenbedingungen stehen bereits in der FAQ und auf der Patches-Seite. Patches, die den Richtlinien nicht entsprechen, können wir nicht integrieren.