Eine Anwendung als „dynamic library” einbinden.

Die Kommunikation zwischen TeXmacs und einer Anwendung kann außer über eine „Pipeline“ auch dadurch erfolgen, dass die Anwendung als „dynamically linked library”, DLL, eingebunden wird. Pipelines sind meist leichter zu implementieren, oft sehr robust und flexibel in Bezug auf Daten, die nur nach und nach erzeugt werden. Aber DLLs sind schneller.

1.Kommunikation über DLLs.

Die folgenden Schritte müssen getan werden, um eine Anwendung als DLL in TeXmacs einzubinden:

1. Die Anwendung Muße so umgestaltet werden, dass das Hauptprogramm als DLL eingebunden werden kann. Damit erhalten Sie ein sehr kleines Binär-Programm, das die wörtliche Ein- und Ausgabe steuert und das erst zur Laufzeit mit den DLLs der Anwendung gelinkt wird.
2. Kopieren die Datei „TeXmacs.h“ aus dem TeXmacs-Unterverzeichnis include in das Include-Verzeichnis Ihrer Anwendung und schreiben Sie die laut TeXmacs-Kommunikations-Protokoll benötigten Eingabe/Ausgabe-Routinen wie weiter unten beschrieben:

3. Schreiben Sie eine Zeile der Form

       (package-declare "myplugin" "libmyplugin.so" "get_name_package" "init")

   in die Datei init-myplugin.scm, die für den Fall der Kommunikation über Pipelines bereits beschrieben wurde. Hier ist libmyplugin.so die entsprechende DLL, get_name_package die Funktion, die TeXmacs aufruft, um Ihre Anwendung mit TeXmacs zu linken und init eine Initialisierungs-Zeichenkette, die Ihre Anwendung vielleicht benötigt.

4. Weiter geht es analog zum Pipeline-Fall.

2.Das TeXmacs Kommunikations-Protokoll.

Das TeXmacs Kommunikations-Protokoll dient dazu, DLLs dynamisch in TeXmacs einzubinden. Die Datei include/TeXmacs.h enthält die Definition aller Daten-Strukturen und Funktionen, die von dem Protokoll benutzt werden. In Zukunft erwarten wir eine Folge von unterschiedlichen Protokollen, die alle die abstrakten Daten-Strukturen TeXmacs_exports und package_exports gemein haben, in denen die Informationen über die Protokoll-, TeXmacs- und Anwendungs-Version, enthalten ist.

Die n-te konkrete Version des Kommunikations-Protokolls sollte zwei Datenstrukturen TeXmacs_exports_n und package_exports_n bereitstellen. Die erste davon enthält alle Routinen und Daten von TeXmacs, die in der Anwendung benötigt werden könnten. Die zweite enthält alle Routinen und Daten der Anwendung, die innerhalb TeXmacs gebraucht werden könnten.

Um die Anwendung mit TeXmacs zu linken, müssen Sie die Funktion

    package_exports* get_my_package (int version);

implementieren. Die Funktion übernimmt das oberste TeXmacs Kommunikations-Protokoll, das von Ihrer TeXmacs-Version unterstützt wird. Es sollte einen Zeiger zurückgeben, der auf eine Instanz einer konkreten Struktur package_exports_n zeigt mit n kleiner oder gleich „version”.

3.Version 1 des TeXmacs Kommunikations-Protokolls.

In der ersten Version des TeXmacs Kommunikations-Protokolls sollte Ihre Anwendung eine Instanz der folgenden Daten-Struktur exportieren:

    typedef struct package_exports_1 {

      char* version_protocol; /* "TeXmacs communication protocol 1" */

      char* version_package;

      char* (*install) (TeXmacs_exports_1* TM, char* options, char** errors);

      char* (*evaluate) (char* what, char* session, char** errors);

      char* (*execute) (char* what, char* session, char** errors);

    } package_exports_1;

Die Zeichenkette version_protocol sollte „TeXmacs communication protocol 1" und die Zeichenkette version_package die Version Ihrer Anwendung enthalten.

Die Funktion install wird einmal von TeXmacs mit den Optionen options aufgerufen, um Ihre Anwendung zu initialisieren. Es überträgt die Routinen, die von TeXmacs exportiert werden, als TM. Diese Routine sollte, sofern erfolgreich, eine Statusmeldung zurückgeben, z.B.:

    "Ihre CAS-Version wurde erfolgreich in TeXmacs eingebunden"

Wenn die Installation ohne Erfolg blieb, sollten Sie NULL zurückgeben und *errors sollte eine erklärende Meldung enthalten. Sowohl what als auch die zurückgegebene Zeichenkette haben ein spezielles Format, in dem beliebige TeXmacs-Dokumente kodiert werden können. Dieses Format wird im nächsten Abschnitt beschrieben.

Die evaluate-Funktion dient zur Evaluierung von what in einer TeXmacs-Sitzung mit dem Namen session. Sie sollte das Ergebnis der Evaluierung von what zurückgeben, falls erfolgreich, oder NULL, wenn ein Fehler auftrat. *errors kann, je nach Verlauf der Evaluierung, eine oder mehrere Warnungen enthalten oder eine Fehlermeldung, wenn die Evaluierung versagte. Der Befehl

    (package-format "yourcas" "input-format" "output-format")

wird analog zur Verwendung von Pipelines zur Spezifikation der Ein- und Ausgabe-Formate benutzt.

Die Routine execute ähnelt evaluate dient aber nicht zur Evaluierung innerhalb einer TeXmacs-Sitzung sondern zur Kommunikation zwischen TeXmacs und Ihrer Anwendung.

Bemerkung 1. Alle Zeichenketten, die von den Routinen install, evaluate und execute, sowie alle Warn- und Fehlermeldungen müssen Speicherplatz mit malloc reservieren. Der Speicherplatz wird von TeXmacs mit free wieder freigegeben..

In der ersten Version des TeXmacs Kommunikations-Protokoll muss TeXmacs eine Instanz folgender Daten-Struktur exportieren:

    typedef struct TeXmacs_exports_1 {

      char* version_protocol; /* "TeXmacs communication protocol 1" */

      char* version_TeXmacs;

    } TeXmacs_exports_1;

Die Zeichenkette version_protocol enthält "TeXmacs communication protocol 1" und version_TeXmacs die vorliegende Version von TeXmacs.