Zmake and ANT

Topic=.Zmake.

pStyle=std

.

Topic=.Zmake.motivation.

pStyle=std

Zmake setzt auf ANT auf =>Eclipse - ANT auf. ANT ist der XML-like Maker aus dem Eclipse-Umfeld. ANT hat einige Vorteile:

• XML-Syntax ist besser als die von klassischen makern bekannte, auch besser lesbar und pflegbar

• Es lassen sich sehr gut Nebenaufgaben wie mkdir, delete usw erledigen.

Wenn man aus a, b und c nach einem komplexen Algorithmus D und E 'maken' möchte, dann ist ANT jedenfalls die geeignete Wahl! Wenn man aber heute aus a, b und c D und E maken möchte, morgen aber aus k, l und m Q und P, und übermorgen nach dem adäquaten Algorithmus noch was anderes, dann ist die Pflege des ANT-xml-Files schon nervig. Die make-Aufgaben stellen oft diejenigen Bearbeiter, die eigentlich gar nicht XML und ANT wollen sondern nur ihre Ergebnisse maken. Hier greift nun Zmake ein.

Zmake ermöglicht die Formulierung der make-Ziele nach möglichst einfach zu formulierenden Regeln. Die Abbildung von a, b und c nach D und E ist ein zu benennender Algorithmus. Wie er genau funktioniert, ist dem make-wollendem egal. Zmake basiert auf einem syntaktisch einfachem Textfile. Aus diesem Textfile wird ein ANT.xml-Makefile generiert. Was genau generiert wird, ist in einem XSLT-Script beschrieben, das aber von dem End-User nicht gepflegt und auch nicht angesehen werden braucht, nur vom jeweils Tool-Verantwortlichen. Hier wird die Arbeit des ANT-xml-Formulierens hineingesteckt. Aber nicht bezogen auf die End-User-Belange, sondern allgemein hauseigen, projektspezifisch (domain specific) bereitgestellt.

Topic=.Zmake.SamleZmake.

pStyle=std

Ein Beispiel sei aus dem Bereich ByteDataAccess herausgegriffen. Hier geht es um die Umsetzung eines C(++)-Headerfiles in einen java-Quellfile, um auf Strukturen, die im C-Headerfile definiert werden, javamäßig zuzugreifen. Headerfiles müssen nach *.java konvertiert werden. Das ist nicht ganz trivial, aber immer auf die selbe Art lösbar. Dem End-User interessiert nicht das wie sondern nur das was. Dem zufolge schreib er in einem Zmake-Script:

 JavaSrc:myPackage/subPkg/_File1_h.java := CHeader2JavaByteCoding(../incl/File1.h);
 JavaSrc:myPackage/subPkg/_File2_h.java := CHeader2JavaByteCoding(../../src/incl/File2.h);

Ziel des Makens ist es, aus File1.h und File2.h an verschiedenen Speicherorten zwei passende java-Files zu erstellen. Der Algorithmus ist als CHeader2JavaByteCoding benannt - und fertig.

Der daraus erzeugte ANT.xml ist wesenlich komplexer. Er enthält die Auflösung des Algorithmus.

Topic=.Zmake.ZmakeStd.variable.

pStyle=std

Für Bearbeitungen des selben Files mit verschiedenen Routinen sollen nicht die selben Files jeweils mehrfach aufgeführt werden, sondern nur einmal. Dazu ist eine Schreibweise

 $variable = fileset(filepath, filepath);

vorgesehen. Die Variable nimmt hier nur die Informationen auf, einschließlich der Zerlegung der File-pathes in die Bestandteile. Die Verarbeitung der Variablen wird dann in den entsprechenden Routinen besorgt.

Variablen können weitere Informationen aufnehmen, der Mechanismus kann erweitert werden. Bisher sind nur das fileset() berücksichtigt.

Topic=.Zmake.ZmakeStd.fileRoutine.

pStyle=std

Die folgenden Routinen zur Filenbehandlung bieten ein komplexes Level oberhalb des üblichen copy, mkdir und delete.

Topic=.Zmake.ZmakeStd.fileRoutine.copyNewerFiles.

pStyle=std

Die Leistung, Files nur dann zu kopieren, wenn sie neuer sind als die jeweiligen Zielfiles, wird im ANT mit der ANT-Tasl <copy> bereits berücksichtigt. Die vorliegende Umsetzung auf Zmake vereinfacht die Formulierung der Aufgabe in der Form:

 targetpath/** := copyNewerFiles(target="Target", srcpath="srcpath", sourcefiles, $fileset);

Anstatt targetpath/** kann auch ein bestimmter File oder so etwas wie targetpath/*.ext angegeben werden. Dann werden die entsprechenden sourcefiles umbenannt. Anstatt des * im targetpath wird dann der localpath aus dem sourcefile eingesetzt, wie es im Abschnitt #Topic.Zmake.ZmakeStd.filePath beschrieben ist. Bei einer Angabe targetpath/**.ext werden die Angaben des local path und filename ohne extension vom Inputfile benutzt, die angegebene Extension des Outputfiles aber gesetzt.

Bei der Angabe mehrerer sourcefiles werden pro Sourcefile je eine ANT-Task <copy> erzeugt. Bei den Sourcefiles kann es ebenfalls wieder Wildcards geben in der Form path/**.ext, path/file*.ext oder path/file*.*.

Topic=.Zmake.ZmakeStd.fileRoutine.copyNewerFiles..

pStyle=std

 test1/** := copyNewerFiles(task="test1", ../Xml/docuSrc:UmlDocu.topic.txt
                                        , ../Xml/html:UmlDocu.html);

Hierbei werden aus zwei verschiedenen Verzeichnissen zwei verschiedene Files geholt, die aber im Zielverzeichnis flach nebeneinander liegen sollen. Das wird ausgedrückt durch die Lage des : in den Quellverzeichnisangaben vor dem Filenamen ausgedrückt. Es wird das folgende ANT-Target erzeugt:

 <target name="test1">
     <copy todir="${curDir}/test1/">
        <fileset dir="${curDir}/../Xml/docuSrc/">
           <include name="UmlDocu.topic.txt"/>
        </fileset>
     </copy>
     <copy todir="${curDir}/test1/">
        <fileset dir="${curDir}/../Xml/html/">
           <include name="UmlDocu.html"/>
        </fileset>
     </copy>
 </target>

Im nächsten Beispiel sollen die selben Files mit ihren lokalen Pfaden kopiert werden. Der Unterschied ist die Lage des ::

 test2/** := copyNewerFiles(task="test2", ../Xml:docuSrc/UmlDocu.topic.txt, ../Xml:html/UmlDocu.html);

wird zu

 <target name="test2">
     <copy todir="${curDir}/test2/">
        <fileset dir="${curDir}/../Xml/">
           <include name="docuSrc/UmlDocu.topic.txt"/>
        </fileset>
     </copy>
     <copy todir="${curDir}/test2/">
        <fileset dir="${curDir}/../Xml/">
           <include name="html/UmlDocu.html"/>
        </fileset>
     </copy>
 </target>

Das selbe Ergebnis lässt sich erzielen, indem man für alle Sourcefiles ein gemeinsames Basisverzeichnis angibt. Das ist bei mehr als zwei Files eine Schreibvereinfachung.

 test2/** := copyNewerFiles(task="test2a", srcpath="../Xml", docuSrc/UmlDocu.topic.txt, html/UmlDocu.html);

Topic=.Zmake.ZmakeStd.fileRoutine.copyNewerFiles..

pStyle=std

 test3/** := copyNewerFiles(task="test3", ../Xml/docuSrc:**);

ANT-<copy> kann hier nicht direkt etwa mit einem Attribut dir="..." arbeiten sondern löst dies über ein <fileset>. Ein <fileset> ist grundsätzlich viel leistungsfähiger. Hier wird das dir= angegeben, wie es vor dem /** steht. Das <include>-Element enthält dann die Information: Alle files in allen sub-Verzeichnissen:

 <target name="test3">
   <copy todir="${curDir}/test3/">
     <fileset dir="${curDir}/../Xml/docuSrc/">
       <include name="**/*"/>
     </fileset>
   </copy>
 </target>

Dieses Beispiel variiert nimmt auch mehrere Verzeichnisbäume ohne, oder hier mit den zugehörigen lokalen Pfaden:

 test4/** := copyNewerFiles(task="test4", ../Xml:docuSrc/**, ../Xml:html/**);

wird in ANT abgebildet mit

 <target name="test4">
   <copy todir="${curDir}/test4/">
      <fileset dir="${curDir}/../Xml/">
         <include name="docuSrc/**/*"/>
      </fileset>
   </copy>
   <copy todir="${curDir}/test4/">
      <fileset dir="${curDir}/../Xml/">
         <include name="html/**/*"/>
      </fileset>
   </copy>
 </target>

Eine Schreibvereinfachung lässt sich auch hier wieder erreichen mit Angabe von

 test4/** := copyNewerFiles(task="test4a", srcpath="../Xml", docuSrc/**, html/**);

Selbst ein Mix aus Angabe von srcpath="..." und einem Basispfad mit : getrennt klappt wie folgend gezeigt:

 test5/** := copyNewerFiles(task="test5", srcpath="../Xml", docuSrc:**, html/**);

In diesem Beispiel werden die Files aus docuSrc flach hinüberkopiert, da der : dahinter steht. Dagegen wird der html/**-Baum einschließlich des Verzeichnisses html übernommen:

 <target name="test5">
   <copy todir="${curDir}/test5/">
     <fileset dir="${curDir}/../Xml/docuSrc/">
       <include name="**/*"/>
     </fileset>
   </copy>
   <copy todir="${curDir}/test5/">
     <fileset dir="${curDir}/../Xml/">
       <include name="html/**/*"/>
     </fileset>
   </copy>
 </target>

Topic=.Zmake.ZmakeStd.fileRoutine.copyNewerFiles..

pStyle=std

TODO

 test5/** := copyNewerFiles(task="test5", srcpath="../Xml", docuSrc:**, html/**);

Topic=.Zmake.ZmakeStd.fileRoutine.copyChangedPathFiles.

pStyle=std

Wenn Files ein Resultat eines Generierprozesses sind, dann ist es eine typische Situation, dass Files zwar mit neuerem Datum vorhanden sind, aber inhaltsgleich mit den vorigen Versionen. Da die meisten Tools für einen Test der Neuigkeit zunächst nur auf das Datum des Files schauen, würden die Files als neu erscheinen obwohl sie es nicht sind.

Abhilfe schafft ein vergleichendes Kopieren von der Generierposition generatepath auf eine Zielposition targetpath. Dabei werden nur diejenigen Files kopiert, deren Inhalt verschieden vom Original ist. Das erfolgt unabhängig vom Zeitstempel. Auf der Zielposition bleiben dann Files unberührt, wenn neu generierte (auf der Generierposition) identisch sind.

Der Aufruf erfolgt mit

 targetpath/** := copyChangedFiles(target="Target", srcpath="srcpath", sourcefiles, $fileset);

Dabei gibt es genau die gleichen Möglichkeiten der Fileauswahl wie bei copyNewerFiles.

Vor dem Kopieren wird Byte für Byte verglichen. Die Rechenzeit dazu ist bei den heute üblichen Computern nicht auffällig. Das Vergleichen und Kopieren wird mit einem speziellen Java-Programm javadoc-src:_org/vishia/ant/Zcopy realisiert. Dieses Programm baut intern auf org.apache.tools.ant.taskdefs.condition.FilesMatch auf. Die Zcopy-Routine ist ein Beispiel für direktes Aufrufen einer Java-Task. Sie ist grundsätzlich erweiterbar in der Richtung eines spezifischen Inhaltstestes. So kann ein Kopieren nicht erfolgen, wenn nur formale Änderungen in den Files vorgefunden wurden, wie Rückschreibe-Werte eines Source-Management-Tools oder wie Kommentare.

Die Aufrufsyntax ist identisch mit der von copyNewerFiles. Im generiertem ANT-Script wird aber nicht <copy> sonder die Java-class <Zcopy> aufgerufen. Diese wird deklariert am Anfang des ANT.xml:

  <taskdef name="Zcopy" classname="org.vishia.ant.Zcopy"/>

Aufgrund einer ZmakeStd-Zeile

 test5/** := copyChangedFiles(task="test5c", srcpath="../Xml", docuSrc:**, html/**);

ergibt sich dann folgender generierte ANT.xml-Code:

 <target name="test5c">
     <Zcopy todir="${curDir}/test5/" dir="${curDir}/../Xml/docuSrc/" file="**/*"/>
     <Zcopy todir="${curDir}/test5/" dir="${curDir}/../Xml/"         file="html/**/*"/>
  </target>

Zcopy arbeitet nicht mit den <fileset> sondern mit Attributen dir und file, wobei bei ..file wildcards angegeben werden können ähnlich wie in den <fileset> bzw. für die hier vorgestellten Zwecke genauso.

Topic=.Zmake.ZmakeStd.fileRoutine.zip.

pStyle=std

Das Archivieren in ein zip-Archiv wird vom ANT standardgemäß geboten. Hier wird es ebenfalls unterstützt, auf dem Level der Filenagaben wie oben beschrieben:

 targetpathfile.zip := zipFiles(files, files);

Beim Zippen umfangreicher filetrees ist es angebracht, mit Wildchars zu arbeiten. Bei den files ist folgendes zulässig:

Angabe	Bedeutung
path/**	alle Files und Pathes unterhalb des Path
path/**	alle Files und Pathes unterhalb des Path

Dabei wird jedenfalls berücksichtigt, dass ein Base-Path nicht mit ins zip-Archiv kopiert wird, wohl aber darauf aufbauende Pathes. Im Folgenden Beispiel:

 targetpathfile.zip := zipFiles(pathBase1:path1/**, path2/**);

Erscheinen im zip-Archiv

 path1/**
 path2/**

Topic=.Zmake.ZmakeStd.fileRoutine..

pStyle=std

TODO

Topic=.Zmake.ZmakeStd.cmd.

pStyle=std

Grundlage hierfür ist der Kommandozeileninterpreter des eingesetzten Betriebssystemes, bzw. adäquat dass, was ant als

 <exec executable="..."> <arg line="..."> ...

ausführen kann. Für die Formulierung der Kommandozeilen kann im ZmakeStd die Filesets benutzt werden. Das ist relativ leistungsfähig. Dazu ein Beispiel:

In einem Set werden Source-Files für eine Compilierung zusammengetstellt:

 $src_Rmos=fileset
 ( ../../OSAL/src_Rmos/os_atomic.c
 , ../../OSAL/src_Rmos/os_mem.c
 , ../../OSAL/src_Rmos/os_mutex.c
 , ../../OSAL/src_Rmos/os_sema.c
 , ../../OSAL/src_Rmos/os_socket.c
 , ../../OSAL/src_Rmos/os_sync.c
 , ../../OSAL/src_Rmos/os_thread.c
 , ../../OSAL/src_Rmos/os_time.c
 );

In einer Variable wird der Aufbau einer cmd-Zeile zum Compilieren angegeben:

 $RmosCC= "objRmos/" + @file + ".obj" :=
 cmd("rm-gcc.exe"), arg("-x c++ -c -Wa,-adhls=../make/lstRmos/" + $file + ".lst -fno-common -I src -I ../../OSAL/inc -I ../../../inc_Rmos -I d:/Progs/RM3DEV/INC " + $path + $file + $ext + " -o ../make/objRmos/" + $file + ".obj")
 ;

Der Aufruf des Comilers einzeln für alle Sourcefiles erfolgt dann mit

 ../make/objRmos/** := for($src_Rmos): exec { $RmosCC; };

Es werden also für alle Angaben des filesets (for($src_Rmos)) jeweils ein Target entsprechend der Kommandozeilenangabe in der Variable RmosCC zusammengebaut. Dabei erfolgt eine Zusammensetzung der Aufrufargumente als String, getrennt mit +, angebbar sind "stringliteral", Variablen und wieder eine for(fileset: string)-Angabe. Letztere wird für das Bilden einer Library wie folgt genutzt:

 ../make/libRmos/libOSAL.a := exec{ cmd("ar"), arg ("-r ../make/libRmos/libOSAL.a"), arg( for($src_Rmos: " ../make/objRmos/" + $file + ".obj") ); };

Die Variable sind Attribute aus den angegebenen Files des Filesets.

Topic=.Zmake.ZmakeStd.HeaderProcessing.

pStyle=std

Headerfiles sind aus Sicht der C/C++-Entwicklung einfach die Definition von Strukturen und Konstanten und Deklaration von Funktion/Methodenaufrufen. Für eine übergreifende Verwendung: Datenaustausch, Dokumentation der Strukturen, Einlesen von Daten unter Java oder adäquaten Programmierumgebungen ist eine Verarbeitung von Headerfiles interessant. Dabei kann wiederum der ZBNF-Parser und XSLT-Generierungen eingesetzt werden. Die ZmakeStd-Scripts enthalten einige Konvertierungen, die innerhalb des vishia-Projektes entwickelt worden sind.

Topic=.Zmake.ZmakeStd.HeaderProcessing.Zbnf.

pStyle=std

Für eine weitere Verarbeitung müssen die Headerfiles erstmal in XML gewandelt werden. Das geschieht mit einer Routine:

 targetpath/*.zbnf.xml := zbnfCheader(target="CheaderXml", headerfiles);

Die Routine erzeugt pro headerfile ein ANT-<target> für das ZBNF-Parsen, mit Test der Neuigkeit (file-timestamp). Bezüglich Angabe der headerfiles gelten alle Ausführungen im Abschnitt Angabe von File-Pathes im ZmakeStd. Es wird also im targetpath gegebenenfalls ein Verzeichnisbaum erzeugt, wenn ein lokaler Pfad bei den headerfiles angegeben wurde. Die Extension (meist .h) wird bei den erzeugten Files nicht mit hinübergezogen und statt dessen die hier angegebene Extension erzeugt.

Topic=.Zmake.ZmakeStd..

pStyle=std

TODO

Topic=.Zmake.XmlDocuGen.

pStyle=std

Für die Dokumentengenerierung XmlDocuGen-Overview wird das Zmake-Prinzip verwendet. Der Inputfile für den Maker ist hier gleichzeitig derjenige File, der auch das Aussehen des Dokumentes bestimmt. Daher wird dieser File mehrfach verwendet. Sein Inhalt kann über XSLT sowohl in einen ANT.xml-Makefile als auch in einen XSL-Steuerfile für Dokumentenaufbereitung gewandelt werden. ...