mirror of https://github.com/texmacs/doc.git
212 lines
8.7 KiB
Tcl
212 lines
8.7 KiB
Tcl
<TeXmacs|1.0.1.11>
|
|
|
|
<style|tmdoc>
|
|
|
|
<\body>
|
|
<expand|tmdoc-title|Transformation de votre système en librairie dynamique>
|
|
|
|
Au lieu de connecter votre système à <apply|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.
|
|
|
|
<section|Connexion en tant que librairie dynamique>
|
|
|
|
Voici les étapes à suivre pour lier votre système en tant que librairie
|
|
dynamique :
|
|
|
|
<\enumerate>
|
|
<item>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.
|
|
|
|
<item>Copiez le fichier <verbatim|$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.
|
|
|
|
<item>Incluez une ligne de la forme :
|
|
|
|
<\verbatim>
|
|
\ \ \ \ (package-declare "myplugin" "libmyplugin.so" "get_name_package"
|
|
"init")
|
|
</verbatim>
|
|
|
|
dans le fichier <verbatim|init-myplugin.scm> qui a été décrit dans le cas
|
|
de la communication via des tubes. Ici, <verbatim|libmyplugin.so> est la
|
|
librairie partagée, <verbatim|get_name_package> la fonction qui sera
|
|
appelée par <apply|TeXmacs> pour lier votre système à <apply|TeXmacs> et
|
|
<verbatim|init> une chaîne d'initialisation pour votre package.
|
|
|
|
<item>Procédez ensuite de la même façon que dans le cas de la
|
|
communication par tubes.
|
|
</enumerate>
|
|
|
|
<section|Le protocole de communication de <TeXmacs>>
|
|
|
|
Le protocole de communication de <apply|TeXmacs> est utilisé pour lier
|
|
dynamiquement des librairies à <apply|TeXmacs>. Le fichier
|
|
<verbatim|$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
|
|
<verbatim|TeXmacs_exports> et <verbatim|package_exports>, ainsi que des
|
|
informations sur les versions du protocole, de <apply|TeXmacs> et de votre
|
|
package.
|
|
|
|
La <with|mode|math|n<rsup|ième>> version \ concrète du protocole de
|
|
communication doit fournir deux structures de données
|
|
<verbatim|TeXmacs_exports_n> et <verbatim|package_exports_n>. La première
|
|
structure contient toutes les routines et données de <apply|TeXmacs>
|
|
nécessaires au package. La seconde structure contient toutes les routines
|
|
et données de votre package qui doivent être visibles dans <apply|TeXmacs>.
|
|
|
|
Pour lier votre système à <apply|TeXmacs>, vous devez implémenter une
|
|
fonction :
|
|
|
|
<\verbatim>
|
|
\ \ \ \ package_exports* get_my_package (int version);
|
|
</verbatim>
|
|
|
|
Cette fonction prend en entrée le dernier protocole de communication de
|
|
<apply|TeXmacs> accepté par votre système. Il doit retourner un pointeur
|
|
vers une instance d'une structure concrète <verbatim|package_exports_n>, où
|
|
<verbatim|n> est inférieur ou égal à <verbatim|version>.
|
|
|
|
<section|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 :
|
|
|
|
<\verbatim>
|
|
\ \ \ \ typedef struct package_exports_1 {<format|next line>
|
|
\ \ \ \ \ char* version_protocol; /* "TeXmacs communication protocol 1"
|
|
*/<format|next line> \ \ \ \ \ char* version_package;<format|next line>
|
|
\ \ \ \ \ char* (*install) (TeXmacs_exports_1* TM, char* options, char**
|
|
errors);<format|next line> \ \ \ \ \ char* (*evaluate) (char* what, char*
|
|
session, char** errors);<format|next line> \ \ \ \ \ char* (*execute)
|
|
(char* what, char* session, char** errors);<format|next line> \ \ \ }
|
|
package_exports_1;
|
|
</verbatim>
|
|
|
|
La chaîne <verbatim|version_protocol> doit contenir <verbatim|"TeXmacs
|
|
communication protocol 1"> et la chaîne <verbatim|version_package> la
|
|
version de votre package.
|
|
|
|
La routine <verbatim|install> est appelée par <apply|TeXmacs> pour
|
|
initialiser votre système avec les options <verbatim|options>. Elle
|
|
communique à votre système les routines exportées par <apply|TeXmacs> sous
|
|
la forme de <verbatim|TM>. La routine doit retourner un message de statut
|
|
tel que :
|
|
|
|
<\verbatim>
|
|
\ \ \ \ "yourcas-version successfully linked to TeXmacs"
|
|
</verbatim>
|
|
|
|
Si l'installation échoue, vous devez retourner <verbatim|NULL> et
|
|
<verbatim|*errors> doit contenir un message d'erreur. <verbatim|what> et la
|
|
chaîne retournée ont tous les deux un format spécial, dans lequel il est
|
|
possible d'encoder des documents <apply|TeXmacs>. Ce format sera décrit
|
|
dans la prochaine section.
|
|
|
|
La routine <verbatim|evaluate> est utilisée pour évaluer l'expression
|
|
<verbatim|what> dans une session <apply|TeXmacs> dont le nom est
|
|
<verbatim|session>. Elle doit retourner l'évaluation de <verbatim|what> ou
|
|
<verbatim|NULL> en cas d'erreur. <verbatim|*errors> contient soit un ou
|
|
plusieurs message d'attention ou un message d'erreur, si l'évaluation
|
|
échoue. La commande :
|
|
|
|
<\verbatim>
|
|
\ \ \ \ (package-format "yourcas" "input-format" "output-format")
|
|
</verbatim>
|
|
|
|
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 <verbatim|execute> possède une spécification similaire à celle
|
|
de <verbatim|evaluate>, sauf qu'elle n'est pas utilisée pour l'évaluation
|
|
d'expressions dans une session <apply|TeXmacs>, mais plutôt pour d'autres
|
|
besoins de communication entre <apply|TeXmacs> et votre package.
|
|
|
|
<\remark>
|
|
Toutes les chaînes retournées par les routines <verbatim|install>,
|
|
<verbatim|evaluate> et <verbatim|execute>, ainsi que les messages
|
|
d'attention et d'erreur doivent être allouées avec <verbatim|malloc>.
|
|
Elle seront libérées par <apply|TeXmacs> avec <verbatim|free>.
|
|
</remark>
|
|
|
|
La première version du protocole de communication de <apply|TeXmacs>
|
|
suppose aussi que <apply|TeXmacs> exporte une instance de la structure de
|
|
données :
|
|
|
|
<\verbatim>
|
|
\ \ \ \ typedef struct TeXmacs_exports_1 {<format|next line>
|
|
\ \ \ \ \ char* version_protocol; /* "TeXmacs communication protocol 1"
|
|
*/<format|next line> \ \ \ \ \ char* version_TeXmacs;<format|next line>
|
|
\ \ \ } TeXmacs_exports_1;
|
|
</verbatim>
|
|
|
|
La chaîne <verbatim|version_protocol> contient la version
|
|
<verbatim|"TeXmacs communication protocol 1"> du protocole et
|
|
<verbatim|version_TeXmacs> la version courante de <TeXmacs>.
|
|
|
|
<apply|tmdoc-copyright|1998--2003|Joris van der Hoeven|Michèle Garoche>
|
|
|
|
<expand|tmdoc-license|Permission is granted to copy, distribute and/or
|
|
modify this document under the terms of the GNU Free Documentation License,
|
|
Version 1.1 or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
|
Back-Cover Texts. A copy of the license is included in the section entitled
|
|
"GNU Free Documentation License".>
|
|
</body>
|
|
|
|
<\initial>
|
|
<\collection>
|
|
<associate|paragraph width|150mm>
|
|
<associate|odd page margin|30mm>
|
|
<associate|shrinking factor|4>
|
|
<associate|page right margin|30mm>
|
|
<associate|page top margin|30mm>
|
|
<associate|reduction page right margin|25mm>
|
|
<associate|page type|a4>
|
|
<associate|reduction page bottom margin|15mm>
|
|
<associate|even page margin|30mm>
|
|
<associate|reduction page left margin|25mm>
|
|
<associate|page bottom margin|30mm>
|
|
<associate|reduction page top margin|15mm>
|
|
<associate|language|french>
|
|
</collection>
|
|
</initial>
|
|
|
|
<\references>
|
|
<\collection>
|
|
<associate|idx-1|<tuple|<uninit>|?>>
|
|
<associate|toc-1|<tuple|1|?>>
|
|
<associate|toc-2|<tuple|2|?>>
|
|
<associate|idx-2|<tuple|<uninit>|?>>
|
|
<associate|toc-3|<tuple|3|?>>
|
|
<associate|toc-4|<tuple|4.|?>>
|
|
</collection>
|
|
</references>
|
|
|
|
<\auxiliary>
|
|
<\collection>
|
|
<\associate|toc>
|
|
<vspace*|1fn><with|font series|<quote|bold>|math font
|
|
series|<quote|bold>|1<space|2spc>Connections via dynamically linked
|
|
libraries><value|toc-dots><pageref|toc-1><vspace|0.5fn>
|
|
|
|
<vspace*|1fn><with|font series|<quote|bold>|math font
|
|
series|<quote|bold>|2<space|2spc>The TeXmacs communication
|
|
protocol><value|toc-dots><pageref|toc-2><vspace|0.5fn>
|
|
|
|
<vspace*|1fn><with|font series|<quote|bold>|math font
|
|
series|<quote|bold>|3<space|2spc>Version 1 of the TeXmacs communication
|
|
protocol><value|toc-dots><pageref|toc-3><vspace|0.5fn>
|
|
</associate>
|
|
</collection>
|
|
</auxiliary>
|