' coding: UTF-8

LiesMich.txt zu h_2_bi.bas, Version 0.2.1:

h_2_bi ist ein Programm, mit welchem Header-Dateien der
Programmiersprache C in (eine) Header-Datei(en) für die
Programmiersprache FreeBasic übersetzt werden können. Ziel ist
es, in C geschriebene Bibliotheken unter FreeBasic nutzbar zu
machen, wie z.B. GTK+, sqlite3 u.a.

Copyright (C) 2010-2011 by Thomas.Freiherr@gmx.net, GPLv3


Lizenz:

Dieses Programm ist freie Software. Es kann weiteregegeben oder
modifiziert werden unter den Bedingungen der GNU General Public
License, entweder Version 3 oder wahlweise auch spätere
Versionen.

Das Programm wird zur öffentlichen Verwendung angeboten, in der
Hoffnung dass es hilfreich ist. Es wird keinerlei Garantie und
auch keinerlei rechtliche Verpflichtung übernommen, für die
Folgen der Anwendung dieses Programmes. Einzelheiten unter
<http://www.gnu.org/licenses/>.


Zip-Inhalt:

    ReadMe.txt  Diese Datei in Englisch
  LiesMich.txt  Diese Datei mit Infos und Anleitung
           src  Ordner mit FreeBasic Quelltexten (h_2_bi.bas kompilieren)
  example.h2bi  Beispiel einer Steuer-Datei


Beschreibung:

h_2_bi.bas ist der Quelltext zu einem Kommandozeilenprogramm. Es
wird durch Texteingabe in der Kommandozeile und durch eine
Steuer-Datei gesteuert. Als grafische Bedienoberfläche bzw. IDE
wird die Verwendung von Geany empfohlen (http://www.geany.org).

Vor der ersten Verwendung muss h_2_bi.bas mit dem fbc
(FreeBasic-Kompiler) kompiliert werden. Das dabei erzeugte,
ausführbare Programm wird im folgenden h_2_bi genannt.

h_2_bi wurde unter Ubuntu LINUX entwickelt. Es sollte
problemlos für WIN32 und auch für DOS zu kompilieren sein (wird
vom Autor jedoch nicht getestet).

h_2_bi erzeugt immer genau eine Ergebnis-Datei (Ausnahmen: Option
'-g' oder '-P_oSI'). Diese wird im Arbeitsordner erstellt. Sie trägt
den Namen der Steuerdatei, gefolgt von der Endung '.bi'. Die
Ergebnis-Datei enthält das Ergebnis der Übersetzung, ggf. C-Quelltext
als Kommentar und ggf. auch Kommentare zu Problemen, welchen beim
Übersetzungsprozeß aufgetreten sind. Diese Datei wird im folgenden
Text mit 'Ergebnis.bi' bezeichnet.

Der Anwender ist selbst dafür verantwortlich, ggf. Backups von der
Ergebnis-Datei zu erstellen. h_2_bi wird beim nächsten Lauf diese
Datei ohne Vorwarnung überschreiben.

h_2_bi ist ein Tool für die interaktive Benutzung, welches im Laufe
eines Übersetzungsprozesses üblicherweise mehrfach aufgerufen wird.
Zwischenergebnisse werden mit dem fbc überprüft. Dazu erzeugt h_2_bi
die Datei 'test.bas', welche beim Aufruf des fbc die Datei 'Ergebnis.bi'
inkludiert. 'test.bas' wird nicht überschrieben, falls sie im
Arbeitsverzeichnis bereits vorhanden ist.

h_2_bi kann nicht alle möglichen C-Strukturen übersetzen, die in
einem C-Header vorkommen können. Ein gewisser Teil an Handarbeit
wird immer übrig bleiben. h_2_bi wurde mit dem Ziel entwickelt,
zunächst eine zuverlässige Übersetzung zu gewährleisten und dann
den verbleibenden Rest möglichst gut für die händische Übersetzung
aufzubereiten.

h_2_bi ist ein 'dummer' Übersetzer, d.h. es werden keine Typ-
Prüfungen vorgenommen. Dies erledigt später der fbc. Vorteil
der 'dummen' Übersetzung ist, dass in jedem Fall ein Ergebnis
vorliegt. Die Qualität des Ergebnisses hängt jedoch davon ab,
wie gut h_2_bi durch die Steuer-Datei parametrisiert ist.


Dateien, welche von h_2_bi verwendet werden (Zusammenfassung):

       xxx.h2bi  Steuer-Datei für die Übersetzung
       xxx.bi    Ergebnis-Datei (übersetzter FB Header)
  xxx_Test.bas   FreeBasic Quelltext zum Test des Headers
       xyz.h     Start-Datei einer Übersetzung


Die Kommandozeile:

h_2_bi wird hauptsächlich über die Steuer-Datei gesteuert. Es ist
jedoch auch möglich, einzelne Optionen pber die Kommandozeile zu
spezifizieren. Diese Optionen gelten solange, bis sie ggf. von einer
Option in einer Steuerdatei überschrieben werden.

Eine leere Kommandozeile veranlaßt h_2_bi dazu, nach Standard-Dateien
im aktuellen Ordner zu suchen. Zuerst wird eine Steuer-Datei gesucht,
die nach dem Namen der Ordners benannt ist ('ORDNERNAME.h2bi'). Wird
diese nicht gefunden, sucht h_2_bi nach der Datei 'h_2_bi.h2bi'. Wird
eine dieser Dateien gefunden, so wird deren Inhalt abgearbeitet. Kann
jedoch keine Standard-Datei gefunden werden, so bietet h_2_bi an, eine
leere Steuer-Datei 'ORDNERNAME.h2bi' zu erstellen.

Optionen in der Kommandozeile beginnen mit einem '-' Zeichen. Worte
ohne dieses Zeichen werden als Dateinamen interpretiert. Dateinamen
werden ohne Endung angegeben, alos z. B. 'MyConfig' (anstelle von
'MyConfig.h2bi'). Wenn kein Dateiname angegeben ist, sucht h_2_bi nach
Standard-Dateien, wie im vorherigen Absatz beschrieben.

Einige Optionen führen zum Programmabbruch:
  -v gibt Informationen zur Version aus und stoppt
  -h gibt einen Hilfetext aus und stoppt
  -g tut nichts, wenn kein stdin Datenstrom definiert ist

Weitere Optionen sind im Quelltext beschrieben (h_2_bi.bas).


Die Steuer-Datei (xxx.h2bi), Details:

Diese Datei steuert den Übersetzungsprozeß. Sie enthält in ihren
Sektionen unterschiedliche Informationen. Eine Sektion startet mit einer
Überschrift. Die folgenden Zeilen enthalten jeweils eine Information
(oder nichts). Leer zeilen werden überlesen.

Die unübliche Endung der Sektionsüberschriften ('(){};') ermöglicht es,
dass die Überschriften in einem Editor für C-Quelltext als Funktionen
interpretiert werden und ein index erstellt wird, über den die
Überschriften auch in langen Steuer-Dateien schnell gefunden werden
können.

Die Steuer-Datei kann Kommentare enthalten, welche mit der C-Syntax vom
Text getrennt werden, also so /* zum Beispiel ein mehrzeiliger
Kommentar */ und so // einer am Zeilenende.

Eine leere Steuerdatei mit korrekten Sektionsüberschriften kann von
h_2_bi erzeugt werden (siehe leere Kommandozeile).

Die erste Sektion der Steuer-Datei hat keine Überschrift. Sie enthält
die Namen der Start-Dateien, bei welchen der Überseztungsprozeß
begonnen wird. Jede Zeile enthält genau einen Dateinamen (am besten
ohne Zugriffspfad).


Sektion __FOLDERS__:

Diese Sektion enthält weitere Zugriffspfade, die zum Auffinden einer
Datei verwendet werden. Pfade werden entweder relativ zum aktuellen
Verzeichnis angegeben oder als absoluter Pfad (mit Laufwerkskennung).
h_2_bi sucht zuerst nach einer #include Datei im aktuellen Pfad und
bei Mißerfolg werden die Ordner dieser Sektion in der gegebenen
Reihenfolge durchsucht.

Beispielzeile:
  Zusatz/Pfad/              /* h_2_bi sucht in
      /Aktueller/Pfad/Datei.h              und
      /Aktueller/Pfad/Zusatz/Pfad/Datei.h   */

Es werden nur die angegebenen Pfade, nicht aber Kombinationen davon
geprüft. Wenn also eine Datei im Ordner 'Pfad/' und eine weitere im
Ordner 'Pfad/Unterpfad/' liegt, so müssen beide Pfade in dieser
Sektion eingetragen werden.

Wenn eine Datei in keinem Ordner gefunden werden kann, dann wird eine
Fehlermeldung '??? file not found' in die Ergebnis-Datei eingetragen.


Sektion __HEADERS__:

In dieser Sektion können bereits übersetzte Header aufgelistet werden,
welche von h_2_bi anstelle einer neuerlichen Übersetzung in die
Ergebnis-Datei eingebunden werden. Fertige Übersetzungen sind z.B. im
FreeBasic Packet enthalten oder können bei der vorherigen Arbeit mit
h_2_bi entstanden sein.

Beispiel:
MeinHeader.h>MeinHeader.bi  //           oder
Pfad/Header.h>neuer/Pfad/AndererName.bi

h_2_bi enthält bereits Ersetzungsregeln für die Header-Dateien des
FreeBasic Packetes (Version 0.21 - können mit der Option '-P_cFO'
abgeschaltet werden.). Zusätzliche Ersetzungen, die in dieser Sektion
spezifiziert werden, werden mit höherer Priorität bearbeitet.


Sektion __PARAMETERS__:

In dieser Sektion können weitere Optionen für den Übersetzungsprozeß
definiert werden. (Gilt nicht für Optionen der Gruppe '-PcXX'.)
Detailierte Informationen zu den verfügbaren Optionen sind in der Datei
"h_2_bi.bi" zu finden.

Beispiele:
  -S2 // Einrückung 2 Leerzeichen
  -nw // Namen und Zeilenumbruch in Parameterlisten
  -P_iALL_oWR_oUD // Kombination mehrerer -P Optionen

Die Optionen der Gruppe '-P_cXX' werden nicht berücksichtigt (erst beim
Einlesen der nächsten Steuer-Datei).


Sektion __MACROS__:

In dieser Sektion können Makros definiert werden, die vor der
Übersetzung expandiert werden sollen. Dies ist notwendig, wenn der
endgültige C Quelltext erst nach der Makroexpansion entsteht. Um eine
Makroexpansion zu spezifizieren, wird die Makro-Definition aus dem
C Header in diese Sektion kopiert.

Beispiel:
#define AL_ARRAY(type, name) extern type name[]

Eine Makro-Definition wird reinen C Quelltext enthalten, wenn das Makro
in C Quelltextzeilen verwendet wird. Wird das Makro dagegen in weiteren
#define zeilen eingesetzt, ist es oft sinnvoll, das Makro von Hand in
FreeBasic Quelltext zu übersetzen.


Sektion __TYPES__:

Diese Sektion enthält Ersetzungsregeln für Variablen-Typen. h_2_bi
enthält bereits eingebaute Regeln für die C Standard-Typen (welche mit
der Option '-P_cTY' abgeschaltet werden können). Zusätzliche Regeln
können in dieser Sektion definiert werden, welche vorangig vor den
eingebauten behandelt werden.

Beispiel:
int>INT32 // all C types 'int' will be replaced by 'INT32'

Diese Regeln werden während der Übersetzung angewendet, d. h. es wird
auf der rechten Seite der C Quelltext und auf der linken Seite FreeBasic
Quelltext angegeben.

Der C Standard-Typ 'void' ist immer definiert und kann nicht
abgeschaltet werden.


Sektion __POST_REPS__:

Unter Verwendung dieser Sektion können einzelne Wörter in der
Ergebnis-Datei ersetzt werden. Dies ist wirkungsvoll, wenn doppelte
Definitionen dadurch entstehen, dass Symbole im C Header mit gleichem
Namen in unterschiedlicher Schreibweise definiert sind. Da C Kompiler
Groß- und Kleinschreibung unterscheiden, sind z. B. die Symbole
'G_CSET_A_2_Z' und 'G_CSET_a_2_z' dort unterschiedlich, in FreeBasic
jedoch identisch. h_2_bi kann unter Beachtung der Schreibweise einzelne
Worte ersetzen oder durch einen Anhang verändern, so dass
Namenskonflikte aufgelöst werden.

Eine Regel in dieser Sektion kann als Trennzeichen entweder '>' oder '&'
verwenden. '&' führt zur Beibehaltung der Wortanfangs und Ergänzung
desselben mit dem definierten Anhang. Wenn kein Anhang spezifiziert ist,
wird der Standard-Anhang "_" verwendet.

Beispiele:
TYPE>Type         // ersetzt das FB Schlüsselwort (TYPE wird zu Type)
G_CSET_A_2_Z&_MY  // ersetzt G_CSET_A_2_Z durch G_CSET_A_2_Z_MY
G_QUEUE_INIT&     // ersetzt G_QUEUE_INIT durch G_QUEUE_INIT_

Wie im ersten Beispiel ersichtlich, kann diese Sektion auch dazu genutzt
werden, die von h_2_bi vorgegebene Schreibweise der FreeBasic
Schlüsselwörter (nur Großbuchstaben) an die eigenen Bedürfnisse
anzupassen.

Diese Ersetzungsregeln werden nach der Übersetzung angewendet (FreeBasic
Quelltext auf beiden Seiten des Trennzeichens). Es können nur ganze
Wörter ersetzt werden (keine Leerzeichen links vom Trennzeichen).


Sektion __START_BI__:

Der Inhalt dieser Sektion wird unverändert an den Anfang der Ergebnis-
Datei übernommen (nur C-Kommentare werden entfernt). Sie enthält also
ausschließlich FreeBasic Quelltext.

Hier können z. B. Copyright Informationen eingefügt werden, die Befehle
zur Einbindung der Bibliothek-Dateien platziert werden oder globale
FreeBasic Befehle aufgelistet werden.


Sektion __END_BI__:

Der Inhalt dieser Sektion wird unverändert an das Ende der Ergebnis-
Datei übernommen (nur C-Kommentare werden entfernt). Sie enthält also
ausschließlich FreeBasic Quelltext.

Hier können globale Befehle, die in der Sektion __START_BI__ geöffnet
wurden, wieder abgeschlossen werden. Oder es können abschließende
Kommentare definiert werden.


Die Option '-g' (Geany mode):

Dieser Modus ist für die Verwendung in Geany, einer FreeBasic IDE.

Es ist wie Magie: Selektiere einen Block C Header Quelltext, drücke
eine Taste und der Block enthält die FreeBasic Übersetzung.

Wie es geht: Zunächst wird h_2_bi.bas kompiliert und als 'sende Text an'
Kommando in Geany angemeldet. Dazu im Menü
'Bearbeiten->Format->Auswahl senden an->Benutzerdefiniertes Kommando einstellen'
auswählen und einen neuen Eintrag 'hinzufügen'. Dann den Zugriffspfad
und das Kommando zum Start des h_2_bi Programmes eingeben, gefolgt von
der Option ' -g'. Ab jetzt kann Geany die aktuelle Auswahl an h_2_bi
senden und anschließend die Auswahl durch das von h_2_bi
zurückgelieferte Übersetzungsergebnis ersetzen.

Technischer Hintergrund: h_2_bi liest in diesem Modus keine Dateien.
Stattdessen wird der C Quelltext aus dem 'stdin' Datenstrom gelesen und
das Übersetzungsergebnis auf den 'stdout' Datenstrom geschrieben. Da
keine Dateinamen spezifiziert werden, liest h_2_bi die Spezifikationen
für die Überseztung aus einer standard Steuer-Datei 'Geany.h2bi' im
Verzeichnis des h_2_bi Programmes. Falls die Datei nicht vorhanden ist,
werden die Standardeinstellungen verwendet.


Anwendungsbeispiel:

Der folgende Text erläutert, auf welche Weise der Autor erfolgreiche
Übersetzungen mit h_2_bi durchgeführt hat. Die C-Header von
GTK Version 2.18.6 (441 Dateien, 1,8 Mb FB-Header) und
SQLITE-3.6.23.1 (2 Dateien, 65 Kb FB-Header) wurden so übersetzt.

1.) Arbeitsverzeichnis erstellen
Es wird ein Verzeichnis für die C Quellen und die h_2_bi Ergebnisse
erstellt.

2.) Quelldateien in das Verzeichnis kopieren
Alle C-Header, welche übersetzt werden sollen, werden in das
Arbeitsverzeichnis kopiert. In einfachen Fällen handelt es sich
um eine einzele Header Datei. Größere Projekte können durchaus
aus mehreren hundert Header Dateien bestehen. Die Header werden
mit ihrer Ordnerstruktur in das Arbeitsverzeichnis kopiert.

3.) h_2_bi in den Arbeitsordner kopieren
Dies gilt für die einmalige Verwendung oder einen ersten Test.
Wenn h_2_bi oftmals verwendet werden soll, ist es sinnvoll,
h_2_bi so im EDV-System zu installieren, dass es aus jedem
Arbeitsordner ausgerufen werden kann.

4.) Steuer-Datei erzeugen
h_2_bi wird mit leerer Kommandozeile gestartet. Das Angebot eine leere
Steuer-Datei zu erstellen wird mit 'y' bestätigt. Die Steuer-Datei
erhält den Namen des Arbeitsordners mit der Endung '.h2bi'. Sie wird
in einem Editor geöffnet und der Name des C Start-Headers wird in die
erste Zeile eingetragen
  gtk.h
und in die Sektion __FOLDERS__ wird der Zugriffspfad eingetragen
  gtk/

5.) Probelauf h_2_bi
Beim nächsten Aufruf von h_2_bi (leere Kommandozeile) sollte eine Zeile
=> gtk/gtk.h
und weitere Informationen über den Übersetzungsprozeß ausgegeben werden.
Nach dem Programmende befinden sich zwei neue Dateien im
Arbeitsverzeichnis, die Ergenis-Datei und die Test-Datei. Wenn diese
Dateien nicht existieren, konnte h_2_bi die Startdatei nicht finden.
Korrigieren Sie Namen und Zugriffspfad und starten Sie h_2_bi erneut.

6.) Dateizugriff sicherstellen
Am Ende der Ergebnis-Datei befindet sich das Protokoll. In diesem sind
die Anzahl und die Namen von Dateien aufgelistet, die im Start-Header
oder in einem weiteren Headern mit einem #include Befehl eingebunden
werden sollen, aber nicht gefunden werden konnten. Für diese Dateien
werden entweder weitere Zugriffspafade in der Sektion __FOLDERS__ oder
Ersetzungsregeln in der Sektion __HEADERS__ definiert. Die Steuer-Datei
wird gespeichert und h_2_bi erneut gestartet.
Durch die Einbindung neuer Dateien können weitere Zugriffspfade oder
Ersetzungsregeln notwendig werden. Der Prozeß wird wiederholt, bis alle
wichtigen Headerdateien gefunden werden können.

7.) Übersetzung beginnen
Die Test-Datei wird mit dem FreeBasic Kompiler übersetzt. Wenn bei der
Kompilierung kein Fehler auftritt, bei Schritt 9) fortgefahren.

8.) Optimieren
In den meisten Fällen wird der fbc jedoch Fehler in der Ergebnis-Datei
finden. Ein Optimierungsprozeß sollte folgen, für den leider keine
allgemeingültige Vorgangsweise beschrieben werden kann. Erfolgreiche
Strategien können entsprechend der Art und der Funktion der Bibliothek
sehr unterschiedlich sein.

h_2_bi bietet drei Sektionen zur Optimierung des Übersetzungsergebnises:
     __MACROS__  vor der Übersetzung,
      __TYPES__  während der Übersetzung, wirkt nur auf Typen,
  __POST_REPS__  nach der Übersetzung, wirkt auf Wörter.
Zusätzlich kann in der Sektion
   __START_BI__  kein Einfluß auf die Übersetzung
FreeBasic Quelltext eingefügt werden. (Wenn hier Blöcke geöffnet werden,
sollten sie in der Sektion __END_BI__ wieder geschlossen werden.)

Häufig auftretende Fehler:

'expected identifier':
Der verwendete Typ ist nicht noch bekannt. Wird durch globale
TYPE-Definitionen in der Sektion __START_BI__ oder durch Einträge in
der Sektion __TYPES__ behoben.

'duplicated definition':
Entsteht einerseits durch Groß- und Kleinschreibung im C-Code oder
andererseits auch durch die Verwendung von FB Schlüsselworten im C-Code
(z. B. als Macro-Name). Behebung üblicherweise durch Eintrag in
__POST_REPS__, seltener in __MACROS__.

In einer Basic-ähnlichen Syntax kann das Prozedere des Schrittes 8)
etwa so beschrieben werden:
Schritt8:
  WHILE RUN fbc test.bas reports errors
    EDIT "__TYPES__"
    EDIT "__POST_PEPS__"
    EDIT "__MACROS__"
    EDIT "__START_BI__" [, "__END_BI_"]
    RUN h_2_bi
  WEND
Schritt9:
  EDIT "result file" ' final fine tuning

Oftmals ist es hilfreich einzelne Fehlerzeilen, deren Problem nicht
sofort gelöst werden kann, zunächst einmal auszukommentieren und die
Arbeit an den einfachen Fehlern abzuschließen. Dann ergibt sich
folgender Ablauf:
Schritt8:
  WHILE RUN fbc test.bas reports errors
    EDIT "__TYPES__"
    EDIT "__POST_PEPS__"
    EDIT "__MACROS__"
    EDIT "__START_BI__" [, "__END_BI_"]
    RUN h_2_bi
    WHILE RUN fbc test.bas reports errors
      EDIT "result file" ' markt error line as comment
      EDIT "__TYPES__"
      EDIT "__POST_PEPS__"
      EDIT "__MACROS__"
      EDIT "__START_BI__" [, "__END_BI_"]
    WEND
    SOLVE "big problems"
  WEND
Schritt9:
  EDIT "result file" ' final fine tuning

9.) End-Optimierung in Handarbeit:
Die Übersetzungsmöglichkeiten von h_2_bi sind nun erschöpft. Die
Ergebnis-Datei wird jetzt umbenannt, um ein Überschreiben zu verhindern.
Der manuelle Feinschliff kann nun beginnen. Er wird in einer
Entwicklungsumgebung durchgeführt und betrifft zunächst die Ergänzung
von Lizenzinformationen zu Beginn der Ergebnisdatei. Auch wird der
(oder die) Befehl(e) zur Einbindung der Bibliothek ('#INCLUDE "..."')
vor der Übersetzung eingefügt.
Es werden Zeilen überprüft, welche drei Fragezeichen '???' enthalten,
wodurch h_2_bi auf Probleme während der Überseztung hinweist. Ebenso
sollten Zeilen überprüft werden, in welchen Namen durch "_" ergänzt
wurden und die veränderte Funktion dokumentiert werden.
Dann sollten Präprozessorzeilen (beginnend mit '#') überprüft werden.
Besonders Makro-Definitionen erfordern je nach Einsatzzweck sehr
unterschiedliche Übersetzungen. (Und #if-Blöcke sind - je nach Inhalt -
im FreeBasic Quelltext ggf. belanglos und können entfernt werden.)
Abschließend wird der Dateikopf aus der Ergebnis-Datei in die Sektion
__START_BI__ kopiert und der Dateifuß in die Sektion __END_BI__, damit
diese Informationen für die nächste Übersetzung bereitet stehen.
Abschließend wird die Ergebnis-Datei in eigenen Projekten ausgiebig
geprüft und schließlich auf einem FreeBasic Portal zum allgemeinen
Download verfügbar gemacht (gute Beschreibung nicht vergessen).


Was h_2_bi nicht kann:
h_2_bi kann keine komplexen #define-Zeilen übersetzen.
h_2_bi scheitert bislang an komplexen C-Strukturen mit Klammerwald,
wie z.B.:
  void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
Dennoch: es stellt eine wertvolle Hilfe bei der Übersetzung von C
Headern dar.

Viel Erfolg und veröffentlichen Sie die Ergebnisse!
