LP_XMLConverter

Kommandozeilentool zur Konvertierung von GSM-Objekten in XML-Dateien. Der Konverter ist Bestandteil jeder ArchiCAD-Installation und findet sich im Haupt-Installationsverzeichnis. Hier findet sich die Dokumentation für Version 16.

GDLnucleus.EXE (Windows)

Tool zur Aufteilung von XML-Objektdateien in separat bearbeitbare Skripte und anschließendem Zusammenführen wieder zu einer Datei. Erhältlich über den Online-Shop auf b-prisma.de und Beister Software.

Sublime Text

Externer Quellcode-Editor. Kommerzielles Produkt, das mit vollem Funktionsumfang getestet werden kann. Empfehlung derzeit: Version 2.02.

Package control (optional)

Erweiterung von Sublime Text um eine Paketverwaltung zur automatischen Installation von Erweiterungen.

GDL-Package

GDL-Syntax-Paket als Erweiterung von Sublime Text von Runxel. Download von github, dieser Seite oder über Package control.

Installieren Sie, sofern noch nicht geschehen, die ArchiCAD-Version für die sie Objekte entwickeln wollen.

Installieren Sie Sublime Text, und fügen Package control hinzu. Folgen Sie den Anweisungen auf der Downloadseite. Wenn sie die ZIP-Datei direkt herunterladen, kopieren sie diese in das Verzeichnis:
C:\Users\Benutzername\AppData\Roaming\Sublime Text 2\Packages\

Dabei ist Benutzername Ihr Anmeldename mit Ihrem Windows-Profil.

Starten Sie Sublime Text und wählen im Menü Preferences „Package control“.

Wählen Sie "Install Package" und tippen sie GDL ein. Es sollte das GDL-Package angezeigt werden. Installieren Sie es durch einfachen Klick.

Alternativ können Sie das GDL-Package von github auch direkt herunterladen. Die Archivdatei entpacken Sie. Den erzeugten Ordner benennen sie in "GDL" um und verschieben ihn ebenso nach
C:\Users\Benutzername\AppData\Roaming\Sublime Text 2\Packages\

Dabei ist Benutzername wieder Ihr Anmeldename mit Ihrem Windows-Profil.

Laden Sie nun GDLnucleus herunter und entpacken Sie das Archiv. Verschieben Sie das Programmverzeichnis (GDLnucleus) z.B. nach
C:\Tools\GDLnucleus
Wollen Sie es in ein Windows Programmverzeichnis verschieben, z.B. nach C:\Programme (x86)\GDLnucleus, müssen Sie auf das Verzeichnis noch entsprechende Schreibrechte vergeben, da im Programmverzeichnis Einstellungen und Logdateien abgelegt werden.

Das GDLnucleus beiliegende Standardprojekt (GDLdevelop.project) können Sie sich in ein beliebiges Vorlagenverzeichnis als Kopiervorlage sichern.

Zur Neuanlage eines Projektes muss in einem eigenständigen Projektverzeichnis mindestens ein Unterverzeichnis für die Aufnahme der GSM-Objekte angelegt werden. Außerdem wird die Definitionsdatei des Projektes benötigt, die die Einstellungen für sublime text enthält. Diese muss an Ihre Ordnerstruktur angepasst werden.

Projektverzeichnis anlegen

Als erster vereinfachter Schritt kopieren Sie sich den Standard-Projektordner (liegt GDLnucleus bei) an die Stelle, wo Sie in Zukunft Objekte entwickeln wollen. Z.B. in den Dokumentenordner Ihres Profiles:
C:\Users\Benutzername\Documents\Objektentwicklung

Dabei ist Benutzername Ihr Anmeldename mit Ihrem Windows-Profil.

Geben Sie dem Projektordner (GDLdevelop.project) einen neuen Namen (z.B. "MeinErstesProjekt").

In dem Bibliothekenverzeichnis liegt zu Testzwecken ein leeres ArchiCAD 18-Objekt (GDLnucleus 2D standard.gsm) das im Regelfall einfach gelöscht werden kann.

Projekteinstellungen in Sublime Text

Starten Sie nun Sublime Text und öffnen dieses Projekt über Project>Open Project... und wählen in diesem neu angelegten Projektverzeichnis die Datei "standard.sublime-project".

Öffnen Sie nun die Einstellungsdatei durch Project>Edit Project

Nun wird folgende Datei angezeigt:

 

---

{
    "folders":
    [
        {
            "path": "C:/Users/Username/Documents/Objektentwicklung/GDLdevelop.project",
            "folder_exclude_patterns": ["library_gsm","library_xml","log"],
            "file_exclude_patterns": ["*.sublime*","*.bat"],
            "name": "Projectname"
        }
    ],
        "settings":
    {
        "color_scheme": "Packages/dawnGDL.tmTheme",
        "font_face": "Courier New",
        "tab_size": 4
    },
    "build_systems":
    [
        {
            "name": "XML2GSM",
           "cmd": ["C:/Tools/GDLnucleus/GDLnucleus.exe","-s2a","-projectdir:$project_path","-tmpfolder:library_xml","-library:library_gsm","-filter:*","-silent","-ProcessAfterFusion:'C:/Program Files/Graphisoft/ArchiCAD 18/LP_XMLConverter.exe'||x2l -img '%projectdir/bitmaps' '%projectdir/%tmpfolder' '%projectdir/%library'"]
            },
        {
            "name": "GSM2XML",
            "cmd": ["C:/Tools/GDLnucleus/GDLnucleus.exe","-a2s","-projectdir:$project_path","-library:library_gsm","-xmlfolder:library_xml","-filter:*","-silent","-ProcessBeforeFission:'C:/Program Files/Graphisoft/ArchiCAD 18/LP_XMLConverter.exe'||l2x -revids -compatibility 18 '%projectdir/%library' '%projectdir/%xmlfolder'"]
   }]

}

---

 

(Alle zwingend anzupassenden Stellen sind rot, die optional änderbaren blau markiert.)

Das Minimum ist nun, dass Sie hier den Pfad zu dem Projektverzeichnis angeben.

Beachten Sie bitte, dass für alle Pfadangaben das Verzeichnistrennzeichen ein Slash "/" und nicht ein Backslash "\" sein muss. Alle weiteren zur Objektbearbeitung notendigen Dateien und Ordner werden bei der ersten Konvertierung des Objektes in XML automatisch angelegt.

Außerdem müssen Sie den Pfad zu Ihrem ArchiCAD-Installationsverzeichnis und zum Installationsverzeichnis des GDLnucleus-Tools angeben. Wenn Sie in Standardverzeichnisse installiert haben, sind das folgende Verzeichnisse:

C:/Program Files/GRAPHISOFT/ArchiCAD 18
und
C:/Tools/GDLnucleus

Beim Konvertieren von GSM zu XML kann im Konverter ein Downgrade des Objektes mit dem Schalter "-compatibility" definiert werden. Geben Sie dort eine Zielversion an oder löschen den kompletten Schalter (-compatibility 18)

Speichern Sie die Datei mit STRG-S. Hiermit ist Ihr neues GDL-Projekt grundsätzlich angelegt. Haben Sie Filter zum Ausblenden von Ordnern ("folder_exclude_patterns") und Dateien ("file_exclude_patterns") festgelegt, werden diese aus Sublime Text heraus nun unsichtbar.

Im folgenden wird von einer Ordnerstruktur innerhalb des Projektes ausgegangen, die weiter unten beschrieben ist und den Einstellungen in der Standard-Projekt-Definitionsdatei entspricht. Sie können die Ordner in der Projekteinstellungsdatei aber auch anders benennen. Siehe Liste der Kommandozeilenparameter weiter unten.

Objekt anlegen

Wechseln Sie nun in ArchiCAD, fügen das Bibliothekenverzeichnis des Projektes (library_gsm) Ihrem Projekt hinzu (Bibliothekenmanager). Legen Sie ein neues Objekt über Ablage>Bibliotheken und Objekte>Neues Objekt... an. Speichern Sie es als neues Objekt in dem Bibliothekenverzeichnis (library_gsm) Ihres neuen Projektordners (z.B. "MeinErstesProjekt"):

C:\Users\Benutzername\Documents\Objektentwicklung\MeinErstesProjekt\library_gsm

Alternativ können Sie auch bestehende Objekte in dieses Verzeichnis kopieren.

Erste Konvertierung

Damit erstmalig die XML-Dateien und Ordenerstruktur erzeugt wird, müssen Sie einmal das Objekt in Richtung Sublime Text synchronisieren. Wählen Sie in Sublime Text Tools>Build System>GSM2XML.

Bitte achten Sie darauf, dass in der Folge im Menü Tools immer ein Haken vor Save All on Build gesetzt ist. Damit ist sicher gestellt, dass immer alle Dateien gesichert sind, bevor der Build-Prozess startet.

Drücken Sie nun STRG-B oder wählen Tools>Build

Nun erscheint sofort für jedes Objekt im Bibliothekenordner ein neuer Ordner, der mit "source." beginnt. Dieser enthält nun alle Dateien, die Sie zum Editieren Ihres Projektes benötigen. Siehe Beschreibung weiter unten.

Stellen Sie am Besten gleich die Richtung der Entwicklung von ArchiCAD->Sublime Text um auf Sublime Text->ArchiCAD indem Sie das Build System wechseln: Tools>Build System>XML2GSM.

Dies ist immer nötig, wenn Sie die Entwicklungsumgebung wechseln. Haben Sie also in ArchiCAD Änderungen vorgenommen, müssen Sie diese Änderungen in die Entwicklungsumgebung von Sublime Text synchronisieren: Umstellen des Build-Systems auf GSM2XML und Build auslösen.

Backup

Enthält alle Backups, die automatisch beim Build-Prozess angelegt werden.

bitmaps

Ordner mit den Bitmaps, die in die Objekte hineinkopiert werden sollen. Für jedes Bitmap muss ein Tag in der Datei 95_Pictures.xml erzeugt werden.

documentation

Optionaler Ordner zur Aufnahme von Projektnotizen.

library_gsm

"Bibliothekenordner" zur Einbindung in ArchiCAD. Enthält die fertigen GSM-Dateien.

library_xml

Ordner für die kompletten, zusammengefügten XML-Dateien. (= XML-Format der Dateien aus dem "library_gsm"-Ordner)

source.objektname

Enthält die editierbaren und zerlegten Fragmente der Objekt-XML-Datei.

01_build.xm

Diese Datei enthält alle Teile der Original-XML-Datei, die nicht extrahiert wurden. Die Stellen, an denen die übrigen Dateien später wieder eingefügt werden, sind textlich markiert. Wer weiß, was er hier tut, kann hier auch Änderung direkt an den Nicht-GDL-Skriptteilen vornehmen.

10_Master-Script.gdl

20_2D-Script.gdl

30_3D-Script.gdl

40_Parameter-Script.gdl

50_User-Interface-Script.gdl

60_Forward-Migration-Script.gdl

70_Backward-Migration-Script.gdl

80_Properties-Script.gdl

Die separierten, reinen GDL-Text-Skripte.

90_Parameters.xml

Enthält die Liste aller Parameter, allerdings in einer schwer lesbaren XML-Struktur. In Sublime Text angezeigt schafft die Tastenkombination STRG-K und STRG-3 eine bessere Übersicht.

95_Pictures.xml

Diese Datei enthält alle im Objekt eingebundenen Bilddateien und ist eine besondere Datei. Sie wird nur dann in der Richtung von ArchiCAD zu Sublime Text erzeugt, insofern diese im Zielverzeichnis nicht schon vorhanden ist. Also in der Regel nur bei der ersten Synchronisierung. Die aus dem GSM-Objekt übertragenen Bitmaps liegen dann kodiert vor.

Liegt die Datei in der Folge bereits vor, werden die Tags für Bitmaps und das Vorschaubild bei jeder Synchronisation von ArchiCAD zu Sublime Text ebenfalls aus der Original-XML-Datei "herausgeschnitten" und sind dann nicht mehr in der Build.xml enthalten. Sie werden aber nicht mehr in die Datei 95_Pictures.xml übertragen und auch sonst nicht mehr gesichert, da der Einbindevorgang von zusätzlichen Bitmpas ausschließlich von Sublime Text zu ArchiCAD erfolgen kann.

Sie können nun in der Datei 95_Pictures.xml beliebige Bitmaps zur Einbindung während der Konvertierung eintragen. Siehe FAQ auf der allgemeinen GDLnucleus-Seite oder allgemeiner Extra-Abschnitt zum Einbinden von neuen Bitmaps in Objekte.

Pictures & Parameters

Diese beiden XML-Dateien sind kein GDL-Quellcode, sondern reiner XML-Code. Diese beiden Dateien erhalten bei der Separierung durch GDLnucleus programmtechnisch bedingt klammernde XML-Tags. Diese werden beim Zusammenbau mit GDLnucleus wieder entfernt. Die Tags dürfen manuell nicht entfernt oder verändert werden, auch wenn sie nicht direkt zu der XML-Struktur des Objektes gehören. Fügte man die XML-Dateien manuell zusammen würde der Konverter mit einer Fehlermeldung abbrechen, dennoch benötigt das Tool GDLnucleus die Tags zur fehlerfreien Funktionsweise.

Backups

Mit jedem Build-Prozess wird derjenige Zielordner des Prozesses (also Bibliotheken- oder source-Ordner) mit Zeitstempel versehen als Backup in den Ordner "backup" verschoben. So kann jederzeit der letzte Zwischenstand reproduziert werden. Z.B. wenn man aus Versehen vergessen hat die Entwicklungsrichtung umzustellen und dennoch "Build" ausgelöst hat.

Durch das permanente Backup sammelt sich natürlich im Lauf der Zeit eine erhebliche Datenmenge an. Man sollte den Ordner "Backup" also regelmäßig bereinigen und auf Meilenstein-backups reduzieren.

Die Backups lassen sich in der Windowsversion durch den Kommandozeilenparameter -NoBackup abschalten.

LOG-Dateien

Tritt bei der Konvertierung durch GDLnucleus ein Konvertierungsfehler auf, wird dieser in der log-Datei gespeichert. Diese findet sich im Verzeichnis "log" des Programmverzeichnisses. Hat der Benutzer keine Schreibrechte auf den Programmordner, wird die Datei allerdings nicht erzeugt.

Die Meldungen werden aber auch bei Verwendung des GUI im (schwarzen) Protokollfenster ausgegeben oder beim Start aus Sublime Text heraus im Konsolenfenster am unteren Programmfensterrand.

Meldungen des GSM-XML-Konverters werden nicht protokolliert.

Folgende Parameter sind für den Aufruf von GDLnucleus zulässig:

-silent

Um die GUI abzuschalten diesen Parameter übergeben. Ansonsten wird nach dem Start des build-Prozesses in Sublime Text das GUI und ein Protokollfenster angezeigt. In den Eingabefeldern erscheinen dann die über Kommandozeile übergebenen Werte. Die Ausführung muss dann mit Execute nochmal bestätigt werden.

-NoBackup

Per Default wird immer ein Backup angelegt. Dieser Parameter schaltet die Backupfunktionen ab.

-projectdir:"C:\temp\ProjektA"
-projectdir:C:\temp\ProjektA

Der Parameter enthält nach dem Doppelpunkt das gewünschte Projektverzeichnis. Enthält der Pfad Leerzeichen muss der Pfad in Anführungszeichen stehen.

-s2a

Ruft die Funktion Sublime2Archicad auf.

-a2s

Ruft die Funktion  Archicad2Sublime auf.

-filter:"Pfosten ABC,XYZ"

Optionale Liste von Objekten auf die gefiltert werden soll. Sind keine Leerzeichen im Dateinamen kann auf die Anführungszeichen verzichtet werden.

-xmlfolder:library_xml
-tmpfolder:library_xml
-library:library_gsm

Optionale Parameter um die Namen des Quell-, Ziel- und Temporär- Verzeichnisses unterhalb des Projektordners anzupassen.

-ProcessBeforeFission:"'C:/Program Files/Graphisoft/ArchiCAD 18/LP_XMLConverter.exe'||l2x -revids -compatibility 18 '%projectdir/%library' '%projectdir/%xmlfolder'"
-ProcessAfterFusion:"C:/Program Files/Graphisoft/ArchiCAD 18/LP_XMLConverter.exe'||x2l -img '%projectdir/bitmaps' '%projectdir/%tmpfolder' '%projectdir/%library'"

Optionale Parameter um vor der Extrahieren, bzw. nach dem Zusammenbauen einen weiteren externen Prozess zu starten. Das kann auch direkt z.B. eine EXE sein oder über eine Batchdatei erfolgen um weitere Aktionen einzubinden.

Gedacht ist hier den Aufruf des ArchiCAD-eigenen Library-XML-Konverter inkl. Kommandozeilenparameter festzulegen.

Da hier wieder Pfade und Dateinamen mit Leerzeichen verwendet werden können, ist es sinnvoll diese mit alternativen Textauszeichnungen ' (=Hochkomma) zu umfassen.

Die Trennung zwischen Konverteraufruf und Parametern erfolgt über zwei senkrechte Striche (||).

Da die Verzeichnisse und Pfade des Projektes bereits für den GDLnucleus-Aufruf selbst übergeben wurden, gibt es Platzhalter, um die Werte nicht redundant eingeben zu müssen:

%projectdir, %xmlfolder, %tmpfolder, %library

Hinweis:

1.    -s2a und -a2s können zwar beide übergeben werden, allerdings wird nur der als zuletzt übergebene ausgeführt.
2.    Parameter können mehrfach übergeben werden, allerdings wird nur der als zuletzt übergebene ausgeführt.

3.    Die Reihenfolge der Parameterübergabe ist egal mit Ausnahme von Punkt 1 und 2.
4.    Enthalten Pfade und Dateinamen Leerzeichen, sind sie mit " einzufassen. Bei -ProcessAfterFusion und -ProcessBeforeFission jedoch mit '.
5.   Backslashes sind von Sublime Text aus mit Slashes oder \\ anzugeben.

GDLnucleus ist nicht freeware. Die Lizenz wird an den Rechner auf dem das Tool installiert ist gebunden.

Nach dem ersten Start und der ersten Konvertierung wird im Programmverzeichnis unter settings eine Datei common.xml erzeugt. Diese bitte an XXX@XXX.XX senden. Sie erhalten umgehend eine freigeschaltete Version der Datei zurück, die sie an gleiche Stelle kopieren und die alte damit überschreiben. Danach entfällt der Motivationscountdown.

Pro Lizenznehmer können zwei Rechner freigeschaltet werden.