1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
<TeXmacs|1.0.1.11>
<style|tmdoc>
<\body>
<expand|tmdoc-title|Linking your system as a dynamic library>
Instead of connecting your system to <apply|TeXmacs> using a pipe, it is
also possible to connect it as a dynamically linked library. Although
communication through pipes is usually easier to implement, more robust and
compatible with gradual output, the second option is faster.
<section|Connections via dynamically linked libraries>
Let us now describe the steps you have to go through in order to link your
system as a dynamic library.
<\enumerate>
<item>Modify the architecture of your system in such a way that the main
part of it can be linked as a shared library; your binary should
typically become a very small program, which handles verbatim input and
output, and which is linked with your shared library at runtime.
<item>Copy the include file <verbatim|$TEXMACS_PATH/include/TeXmacs.h>
into the include directory of your system's source and write the
input/output routines as required by the last <TeXmacs> communication
protocol as explained below.
<item>Include a line of the form:\
<\verbatim>
\ \ \ \ (package-declare "myplugin" "libmyplugin.so" "get_name_package"
"init")
</verbatim>
in your file <verbatim|init-myplugin.scm> which has been described in the
case of communication by pipes. Here <verbatim|libmyplugin.so> is the
corresponding shared library, <verbatim|get_name_package> the function
which will be called by <apply|TeXmacs> in order to link your system to
<apply|TeXmacs>, and <verbatim|init> some initialization string for your
package.
<item>Proceed in a similar way as in the case of communication by pipes.
</enumerate>
<section|The <TeXmacs> communication protocol>
The <apply|TeXmacs> communication protocol is used for linking libraries
dynamically to <apply|TeXmacs>. The file
<verbatim|$TEXMACS_PATH/include/TeXmacs.h> contains the declarations of all
data structures and functions used by the protocol. Actually, we foresee a
succession of different protocols. Each of these protocols have the
abstract data structures <verbatim|TeXmacs_exports> and
<verbatim|package_exports> in common, with information about the versions
of the protocol, <apply|TeXmacs> and your package.
The <with|mode|math|n>-th concrete version of the communication protocol
should provide two data structures <verbatim|TeXmacs_exports_n> and
<verbatim|package_exports_n>. The first structure contains all routines and
data of <apply|TeXmacs>, which may be necessary for the package. The second
structure contains all routines and data of your package, which should be
visible inside <apply|TeXmacs>.
In order to link your system to <apply|TeXmacs>, you have to implement a
function:
<\verbatim>
\ \ \ \ package_exports* get_my_package (int version);
</verbatim>
This function takes the highest <apply|TeXmacs> communication protocol
supported by your <apply|TeXmacs> system on input. It should return a
pointer to an instance of a concrete structure
<verbatim|package_exports_n>, where <verbatim|n> is inferior or equal to
<verbatim|version>.
<section|Version 1 of the <TeXmacs> communication protocol>
In the first version of the <TeXmacs> communication protocol, your package
should export an instance of the following data structure:\
<\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>
The string <verbatim|version_protocol> should contain <verbatim|"TeXmacs
communication protocol 1"> and the string <verbatim|version_package> the
version of your package.
The routine <verbatim|install> will be called once by <apply|TeXmacs> in
order to initialize your system with options <verbatim|options>. It
communicates the routines exported by <apply|TeXmacs> to your system in the
form of <verbatim|TM>. The routine should return a status message like:\
<\verbatim>
\ \ \ \ "yourcas-version successfully linked to TeXmacs"
</verbatim>
If installation failed, then you should return <verbatim|NULL> and
<verbatim|*errors> should contain an error message. Both <verbatim|what>
and the returned string have a special format, in which it is possible to
encode arbitrary <apply|TeXmacs> documents. This format will be explained
in the next section.
The routine <verbatim|evaluate> is used to evaluate the expression
<verbatim|what> inside a <apply|TeXmacs>-session with name
<verbatim|session>. It should return the evaluation of <verbatim|what> or
<verbatim|NULL> if an error occurred. <verbatim|*errors> either contains
one or more warning messages or an error message, if the evaluation failed.
The command:\
<\verbatim>
\ \ \ \ (package-format "yourcas" "input-format" "output-format")
</verbatim>
is used in order to specify the input and output formats for evaluations,
in a similar way as in the case of pipes.
The routine <verbatim|execute> has a similar specification as
<verbatim|evaluate>, except that it is not used for the evaluation of
expressions inside a <apply|TeXmacs>-session, but rather for other
communication purposes between <apply|TeXmacs> and your package.
<\remark>
All strings returned by the routines <verbatim|install>,
<verbatim|evaluate> and <verbatim|execute>, as well as all warning and
error messages should be allocated using <verbatim|malloc>. They will be
freed by <apply|TeXmacs> using <verbatim|free>.
</remark>
The first version of the <apply|TeXmacs> communication protocol also
requires <apply|TeXmacs> to export an instance of the data structure:
<\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>
The string <verbatim|version_protocol> contains the version
<verbatim|"TeXmacs communication protocol 1"> of the protocol and
<verbatim|version_TeXmacs> the current version of <TeXmacs>.
<apply|tmdoc-copyright|1998--2002|Joris van der Hoeven>
<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|english>
</collection>
</initial>
<\references>
<\collection>
<associate|toc-1|<tuple|1|?>>
<associate|idx-1|<tuple|<uninit>|?>>
<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>
|
