Transformation de votre système en librairie dynamique

Au lieu de connecter votre système à TeXmacs via un tube, vous pouvez aussi le lier en tant que librairie dynamique. Bien que la communication via des tubes soit généralement plus facile à implémenter, plus robuste et compatible avec une sortie graduelle, la seconde option est plus rapide.

1.Connexion en tant que librairie dynamique

Voici les étapes à suivre pour lier votre système en tant que librairie dynamique :

1. Modifiez l'architecture de votre système de telle façon que sa plus grande partie puisse être liée en tant que librairie partagée ; le binaire deviendra alors un tout petit programme que gérera les entrées et sorties verbatim et qui sera lié à votre libraire partagé lors de l'exécution.
2. Copiez le fichier $TEXMACS_PATH/include/TeXmacs.h dans le répertoire include de votre source et écrivez les routines d'entrée/sortie en suivant le dernier protocole de communication de TeXmacs décrit ci-dessous.

3. Incluez une ligne de la forme :

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

   dans le fichier init-myplugin.scm qui a été décrit dans le cas de la communication via des tubes. Ici, libmyplugin.so est la librairie partagée, get_name_package la fonction qui sera appelée par TeXmacs pour lier votre système à TeXmacs et init une chaîne d'initialisation pour votre package.

4. Procédez ensuite de la même façon que dans le cas de la communication par tubes.

2.Le protocole de communication de TeXmacs

Le protocole de communication de TeXmacs est utilisé pour lier dynamiquement des librairies à TeXmacs. Le fichier $TEXMACS_PATH/include/TeXmacs.h contient les déclarations de toutes les structures de données et toutes les fonctions utilisées par le protocole. En fait, nous prévoyons une succession de différents protocoles. Ils possèdent tous en commun les structures de données abstraites TeXmacs_exports et package_exports, ainsi que des informations sur les versions du protocole, de TeXmacs et de votre package.

La n^ième version concrète du protocole de communication doit fournir deux structures de données TeXmacs_exports_n et package_exports_n. La première structure contient toutes les routines et données de TeXmacs nécessaires au package. La seconde structure contient toutes les routines et données de votre package qui doivent être visibles dans TeXmacs.

Pour lier votre système à TeXmacs, vous devez implémenter une fonction :

    package_exports* get_my_package (int version);

Cette fonction prend en entrée le dernier protocole de communication de TeXmacs accepté par votre système. Il doit retourner un pointeur vers une instance d'une structure concrète package_exports_n, où n est inférieur ou égal à version.

3.Version 1 du protocole de communication de TeXmacs

Dans la première version du protocole de communication de TeXmacs, votre package doit exporter une instance de la structure de données suivante :

    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;

La chaîne version_protocol doit contenir "TeXmacs communication protocol 1" et la chaîne version_package la version de votre package.

La routine install est appelée par TeXmacs pour initialiser votre système avec les options options. Elle communique à votre système les routines exportées par TeXmacs sous la forme de TM. La routine doit retourner un message de statut tel que :

    "yourcas-version successfully linked to TeXmacs"

Si l'installation échoue, vous devez retourner NULL et *errors doit contenir un message d'erreur. what et la chaîne retournée ont tous les deux un format spécial, dans lequel il est possible d'encoder des documents TeXmacs. Ce format sera décrit dans la prochaine section.

La routine evaluate est utilisée pour évaluer l'expression what dans une session TeXmacs dont le nom est session. Elle doit retourner l'évaluation de what ou NULL en cas d'erreur. *errors contient soit un ou plusieurs message d'attention ou un message d'erreur, si l'évaluation échoue. La commande :

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

est utilisée pour spécifier les formats d'entrée/sortie des évaluations, de la même façon que dans le cas des tubes.

La routine execute possède une spécification similaire à celle de evaluate, sauf qu'elle n'est pas utilisée pour l'évaluation d'expressions dans une session TeXmacs, mais plutôt pour d'autres besoins de communication entre TeXmacs et votre package.

Remarque 1. Toutes les chaînes retournées par les routines install, evaluate et execute, ainsi que les messages d'attention et d'erreur doivent être allouées avec malloc. Elle seront libérées par TeXmacs avec free.

La première version du protocole de communication de TeXmacs suppose aussi que TeXmacs exporte une instance de la structure de données :

    typedef struct TeXmacs_exports_1 {

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

      char* version_TeXmacs;

    } TeXmacs_exports_1;

La chaîne version_protocol contient la version "TeXmacs communication protocol 1" du protocole et version_TeXmacs la version courante de TeXmacs.