Kurze Einführung in RCS_TOOLS.PAS zur Benutzung mit FoldMaster Version 1.50 oder höher (*{{{ 1. Einführung*) Dieses Makromodul bindet RCS in FoldMaster ein. Bei RCS handelt es sich um ein frei erhältliches und schon seit vielen Jahren verfügbares Versions- Kontroll- System (Revison Control System). Zur Benutzung dieser Tools benötigen Sie RCS das auf vielen Freeware Servern kostenlos erhältlich ist. RCS unterliegt der GNU- Public Licence, die die Lizensierung und Benutzung dieses Tools regelt. (*{{{ Aus der RCS Beschreibung*) "The Revision Control System (RCS) manages multiple revisions of files. RCS automates the storing, retrieval, logging, identification, and merging of revisions. RCS is useful for text that is revised frequently, e.g., programs, documentation, graphics. " (*}}}*) (*}}}*) (*{{{ 2. Installation von RCS*) (*{{{ Herunterladen von RCS*) RCS ist unter anderem zu finden unter: http://www.gnu.org/software/rcs/rcs.html oder unter einem der Mirror- sites z.B.: ftp.cs.uni-bonn.de/pub/gnu/ Sollten Sie gleich unter NT ausführbare Dateien wollen so können Sie unter http://www.winsite.com die Datei gr564bnt.zip herunterladen (evtl. nach RCS unter Win NT suchen). (*}}}*) Diese Version des Makros wurde getestet mit der Version 5.6.4 von RCS. Wenn Sie RCS über das Internet heruntergeladen haben, erhalten Sie ein ZIP- Archiv. Den Inhalt dieses Archivs einfach in ein vorbereitetes Verzeichnis(z.B.: C:\programme\rcs) auspacken. Zur Verwendung dieser Tools in und mit FoldMaster genügt das bereits. Achten Sie darauf, daß Sie die korrekten ausführbaren Dateien erhalten, die auf Ihrem Rechner unter Win32 ausführbar sind. Wollen Sie RCS auch ohne FoldMaster verwenden, beachten Sie bitte die entsprechenden im Paket enthaltenen Hinweise. (*}}}*) (*{{{ 3. Installation von RCS_TOOLS.PAS*) RCS_TOOLS.PAS ist eine Makrodatei, die die Funktionalität von RCS in FoldMaster einbindet. RCS_TOOLS.PAS erhalten sie auf der Homepage von FoldMaster normalerweise zusammen mit dieser Datei. Wenn Sie RCS_TOOLS.PAS vorliegen haben, die Datei in das Unterverzeichnis "macros" des Installationsverzeichnisses von FoldMaster kopieren. Im Menü "Automation" den Unterpunkt "Module anzeigen" aufrufen. Daraufhin erscheint der Dialog "Makromodule bearbeiten" zur Verwaltung der in FoldMaster bekannten Makromodule. Hier "Hinzufügen" auswählen und RCS_TOOLS.PAS suchen, auswählen und hinzufügen. Dateidialog schließen. In der Liste erscheint das Makromodul RCS_TOOLS.PAS. Dieses selektieren. Für das selektierte Modul die Option "Optionen bei Startup : Modul ausführen" aktivieren. Dialog "Makromodule bearbeiten" schließen. Optionen speichern. FoldMaster beenden. FoldMaster neu starten. Dabei sollte RCS_TOOLS.PAS automatisch gestartet werden. Das Makro überprüft die Installation von RCS und setzt alle notwendigen Umgebungsvariablen. Dazu sind jedoch einige Informationen notwendig, die das Makro von Ihnen jetzt anfordert. Die Warnung, daß RCSPATH nicht korrekt gesetzt ist, mit OK quittieren. Beim Dialog "RCS- Installationspfad suchen" die Datei "rcs.exe" lokalisieren und auswählen. Von nun an steht im Menü "Automation" ein weiteres Untermenü mit dem Namen RCS zur Verfügung. Eine Beschreibung der einzelnen Einträge in diesem Menü folgt weiter unten. Weitere Hinweise sind auch in der Datei RCS_TOOLS.PAS enthalten. Folgende Tools werden durch das Makro angelegt: - IntCheckIn - IntCheckOut - IntRCS - IntRDiff - IntRLog Diese werden durch die Makros mit den entsprechenden Parametern aufgerufen, und stehen für einen direkten Aufruf nicht zur Verfügung. (*}}}*) (*{{{ 4. Mit RCS und FoldMaster arbeiten*) Zur Arbeit mit RCS sollten Sie Erfahrung mit diesem oder ähnlichen Tools haben, obwohl Sie FoldMaster hier weitgehend unterstützt. (*{{{ 4.1 RCS- Verzeichnis*) Das Makromodul implementiert einige Makrofunktionen, die über das Menü "Automation" aufgerufen werden können. Dabei geht das Makro davon aus, daß Sie die RCS- Dateien, die die Versions- Historie enthalten (Repository), getrennt von den Quelldateien speichern wollen. Dazu muß ein RCS- Verzeichnis angelegt werden, in dem eine weitere Verzeichnisstruktur die Unterscheidung von einzelnen Projekten erlaubt. Sie können auch für jedes Projekt ein eigenes RCS- Verzeichnis verwenden. Was dieses Makro nicht unterstützt sind RCS- Verzeichnisse in den jeweiligen Quelldatei- Verzeichnissen. Es kann also folgende Verzeichnisstruktur entstehen: Z.B.: Projektverzeichnisse C:\PROJECTS\XYZ123\ C:\PROJECTS\ABC345\ C:\MYPRJ Dazu können Sie folgende RCS- Verzeichnisse anlegen C:\RCS\XYZ123 C:\RCS\ABC345 C:\RCS\MYPRJ Das Makro ist auf diese Struktur abgestimmt. Es legt selbständig im RCS Verzeichnis alle Unterverzeichnisse bei Bedarf automatisch an, wie sie im Projektverzeichnisbaum auch vorkommen. Achten Sie darauf, daß das RCS Verzeichnis den Teilstring /RCS/ oder \RCS\ enthält. Hierbei ist auch die Schreibweise wichtig. Das Makro unterstützt Sie hier, indem keine anderen Eingaben zulässig sind, oder falsche Eintragungen angezeigt werden. Z.B.: C:\PROJECTS\XYZ\ mit dem Unterverzeichnis dir1 und den darin enthaltenen Dateien a.c, b.c, a.h und b.h und dem Unterverzeichnis dir2 und den darin enthaltenen Dateien d.c und d.h Wird zu C:\RCS\XYZ\dir1 mit den RCS- Dateien a.c, b.c, a.h, b.h C:\RCS\XYZ\dir2 mit den RCS- Dateien d.c und d.h Dabei legen Sie als Anwender nur das Verzeichnis C:\RCS\XYZ an. Ihre FoldMaster- Projektdatei muß sich hierbei im Verzeichnis C:\PROJECTS\XYZ befinden. Alle anderen Unterverzeichnisse (dir1 und dir2) werden durch das Makro automatisch angelegt. (*}}}*) (*{{{ 4.2 RCS- Verzeichnis setzen*) Bevor mit der Arbeit begonnen werden kann muß das RCS- Verzeichnis festgelegt werden. Dazu gibt es den Menüeintrag "SetRCSPath". Hierbei wird eine globale Variable angelegt, die für verschiedene Projekte dienen kann, oder für Dateien, verwendet wird, die nicht im Zusammenhang mit einem bestimmten Projekt stehen. Für die Arbeit mit verschiedenen Projekten ist es jedoch sinnvoll in der Projektdatei selbst eine projektspezifische Variable anzulegen, die auf das RC- Verzeichnis verweist. Dazu wechseln Sie in das Projektfenster und führen "PRJ_Insert_RCSPath" aus. Dieses Makro fragt ein RCS- Verzeichnis ab und legt eine lokale Variable mit dem Namen "RCSPATH" in der Projektdatei an. (*}}}*) (*{{{ 4.3 Ablauf*) In der Makrodatei RCS_TOOLS.PAS sind einige Makro- Funktionen enthalten, die RCS für jedes Modul der Projektdatei aufrufen. Die Parameter werden durch die Makros selbst festgelegt, jenachdem welche Funktion benötigt wird. RCS und die entsprechenden Hilfsprogramme co ci und diff müssen daher als Tools in FoldMaster eingebunden sein. Dies geschieht bereits bem ersten Aufruf des Makros. (*}}}*) (*{{{ 4.4 Ausgaben der Programme und Makros*) Die Ausgaben dieser externen Programme werden in das Messagefenster umgeleitet oder durch weitere Makros gefiltert und ausgewertet. Verschiedentlich werden die Ausgaben auch in eine besondere Datei geschrieben ("PRJ_Log_All"). In der Makro- Konsole werden zudem Statusmeldungen und evtl. Fehlermeldungen der Makros ausgegeben. (*}}}*) (*{{{ 4.5 Makros die auf das ganze Projekt angewendet werden*) Es stehen folgende Makros zur Verfügung, die sich auf das ganze Projekt auswirken. - PRJ_Insert_RcsPath - PRJ_Check_IN_ALL - PRJ_Check_Out_ALL - PRJ_Log_ALL - PRJ_Diff_ALL - PRJ_Lock_ALL - PRJ_Lock_State Rufen Sie eines dieser Makros auf wird die Projektdatei in den Vordergrund gebracht. Die Makros bleiben ohne Wirkung, wenn sie aus Dateien aufgerufen werden, die nicht Teil eines Projekts sind. (*}}}*) (*{{{ 4.6 LogMessage setzen*) Die LogMessage wird bei jeder Check- In Aktion angegeben und soll die Änderungen beschreiben, die an einer Datei vorgenommen wurden. Das Makro verwendet eine gloable Variable (RCSLogMessage), um eine LogMessage zu speichern. Diese Variable kann mit "SetLogMessage" gesetzt und mit "ClearLogMessage" wieder gelöscht werden. Ist diese Message eingetragen wird deren Inhalt für jede weitere Check- In Aktion verwendet. Ist diese Variable nicht gesetzt oder leer wird für jedes Modul eine eigene LogMessage abgefragt. In diesem Fall können dann von Modul zu Modul unterschiedliche Informationen eingetragen werden. Die LogMessage kann mehrzeilig eingegeben werden. FoldMaster bietet dazu einen entsprechenden Dialog an, der die Eingabe eines mehrzeiligen Textes erlaubt. (*}}}*) (*{{{ 4.7 Username / Login Name*) RCS verwendet den im System gesetzten UserNamen, um die Dateien zu verriegeln. Hier sollten Sie darauf achten, besonders wenn mehrere Personen in dem Projekt arbeiten, daß diese Namen eindeutig sind. Es sollte sich nicht gerade jeder als "Administrator" einloggen. (*}}}*) (*{{{ 4.8 Projekt Einchecken*) Das Makro "PRJ_Check_IN_ALL" erlaubt das Einchecken eines kompletten Projekts. Es werden hier alle Dateien, die im Projekt enthalten sind, eingechecked. Es werden jedoch nur solche Dateien bearbeitet, die sich im Verzeichnis der Projektdatei oder eines Unterverzeichnisses davon befinden. Dateien, die noch nicht im RCS- Verzeichnis angelegt wurden, werden entsprechend angelegt. Andere Dateien werden eingechecked. (*}}}*) (*{{{ 4.9 Einzelne Datei einchecken*) Dazu einfach die entsprechende Datei öffnen und fokusieren. Aus dem RCS- Menü den Punkt "CHECK_In_Locked" ausführen. Dies ist die Standard- Aktion zum Einchecken. (*}}}*) (*{{{ 4.10 Einzelne Datei auschecken*) Dazu einfach die entsprechende Datei öffnen und fokusieren. Aus dem RCS- Menü den Punkt "CHECK_Out_Locked" ausführen. Dies ist die Standard- Aktion zum Auschecken. RCS kopiert eine neue Datei in das Arbeitsverzeichnis. Dabei wird Zeit und Datum der Datei verändert. FoldMaster fragt in diesem Fall nach ob die Datei nachgeladen werden soll. Bestätigen Sie diesen Dialog immer mit "JA", da die ausgecheckten Dateien unter Umständen einen anderen Inhalt haben als die eingecheckten Dateien z.B. wenn die aktuelle Version durch RCS in der Datei eingetragen werden soll. (*}}}*) (*{{{ 4.11 Projekt auschecken*) Das ganze Projekt auschecken ist evtl. notwendig, wenn Sie ein altes Projekt wieder regenerieren wollen, oder wenn Sie einen älteren Zwischenstand der Software bearbeiten wollen. Denkbar ist auch, daß Sie Änderungen ausprobieren und Testen wollen ohne die aktuelle Software zu ändern. Hier spricht man auch von einer Sandbox. In diesen Fällen kopieren sie die Projektdatei in ein anderes Verzeichnis, und rufen das Makro "PRJ_Check_Out_ALL" auf. Alle Dateien werden nun nicht gelockt zum editieren ausgecheckt. Bei Bedarf kann das Makro entsprechend angepasst werden. (*}}}*) (*{{{ 4.12 Log anzeigen / erstellen*) Um die Verisons- Historie einer Datei anzuzeigen, den Punkt "RCS_LOG" aus dem RCS- Menü ausführen. Die Ausgaben des Programms erscheinen im Messagefenster. Alternativ kann auch für das gesamte Projekt eine Logdatei erstellt werden. Dazu den Punkt "PRJ_Log_AlL" ausführen. Für jede Datei des Projekts werden die Log- Angaben abgerufen und gesammelt. Diese Informationen werden zum Schluß in einer Datei mit dem Name des Projekts und der Endung ".LOG" gespeichert. Diese Datei wird im Verzeichnis der Projektdatei angelegt. Existiert die Datei noch nicht, erscheint ein Dialog, der nachfragt, ob die Datei angelegt werden soll. Hier sollten Sie grundsätzlich mit "JA" antworten. Die Ausgaben werden umformatiert. Sollte Sie hier eigene Wünsche haben können Sie die Makrofunktion "Cap_RCS_Log" entsprechend anpassen, die für jede ausgegebene Zeile aufgerufen wird. (*}}}*) (*{{{ 4.13 Diff*) Mit DIFF werden verschiedene Versionen einer Datei miteinander verglichen. Hier bietet das RCS- Menü folgende drei Möglichkeiten: - Diff_to_work - Diff_rev_to_work - Diff_rev_to_rev Diff_to_work ermittelt die Unterschiede von der letzten eingecheckten Version zur aktuellen Arbeitsdatei. Diff_ref_to_work fragt eine Version ab die mit der aktuellen Arbeitsdatei verglichen werden soll. Diff_ref_to_ref zeigt die Unterschiede zweier bereits eingecheckter Versionen an. (*}}}*) (*{{{ 4.14 Diff für das gesamte Projekt aufrufen*) Sie können mit dem Makro PRJ_Diff_ALL eine Zusammenfassung aller Änderungen der aktuellen Arbeitskopien und der letzten eingecheckten Version der Datei erstellen. Das Makro bearbeitet alle Dateien des Projekts. Die gesammelten Ausgaben werden zum Schluß in einer Datei mit dem Name des Projekts und der Endung ".DIFF" gespeichert. Diese Datei wird im Verzeichnis der Projektdatei angelegt. Existiert die Datei noch nicht, erscheint ein Dialog, der nachfragt, ob die Datei angelegt werden soll. Hier sollten Sie grundsätzlich mit "JA" antworten. (*}}}*) (*{{{ 4.15 Lock- Status generieren*) Bei der Arbeit in einer Gruppe kann es hilfreich sein, zu wissen, wer welche Dateien bearbeitet. Dazu kann der Lock-Status generiert werden, wobei für jede Datei im Projekt angegeben wird, wer diese Datei aktuell gelockt hat. Die Informationen werden gesammelt und am Schluß in eine LOG- Datei geschrieben. Ist diese Datei noch nicht vorhanden erscheint ein Dialog, der nachfragt, ob die Datei angelegt werden soll. Hier sollten Sie grundsätzlich mit "JA" antworten. Ansonsten werden die Informationen an die Datei angehängt. (*}}}*) (*{{{ 4.16 RCS selber aufrufen*) Um RCS selbst aufzurufen sollten Sie aus FoldMaster heraus eine Kommandozeile öffnen. In dieser sind alle notwendigen Einstellungen vorhanden, die zum Aufruf von RCS notwendig sind. Dazu ist auf der FoldMaster Homepage auch das Makro "ToolDos.PAS" verfügbar, das lediglich einmal ausgeführt werden muß, um das entsprechende Tool anzulegen. Das Tool erscheint im Menü "TOOL" unter dem Namen "DOS- Kommandozeile". Dieses Tool öffnet ein Kommandozeilen- fenster. (*}}}*) (*}}}*)