Linking your system as a dynamic library

Instead of connecting your system to 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.

1.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.

1. 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.
2. Copy the include file $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.

3. Include a line of the form:

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

   in your file init-myplugin.scm which has been described in the case of communication by pipes. Here libmyplugin.so is the corresponding shared library, get_name_package the function which will be called by TeXmacs in order to link your system to TeXmacs, and init some initialization string for your package.

4. Proceed in a similar way as in the case of communication by pipes.

2.The TeXmacs communication protocol

The TeXmacs communication protocol is used for linking libraries dynamically to TeXmacs. The file $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 TeXmacs_exports and package_exports in common, with information about the versions of the protocol, TeXmacs and your package.

The n-th concrete version of the communication protocol should provide two data structures TeXmacs_exports_n and package_exports_n. The first structure contains all routines and data of TeXmacs, which may be necessary for the package. The second structure contains all routines and data of your package, which should be visible inside TeXmacs.

In order to link your system to TeXmacs, you have to implement a function:

    package_exports* get_my_package (int version);

This function takes the highest TeXmacs communication protocol supported by your TeXmacs system on input. It should return a pointer to an instance of a concrete structure package_exports_n, where n is inferior or equal to version.

3.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:

    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;

The string version_protocol should contain "TeXmacs communication protocol 1" and the string version_package the version of your package.

The routine install will be called once by TeXmacs in order to initialize your system with options options. It communicates the routines exported by TeXmacs to your system in the form of TM. The routine should return a status message like:

    "yourcas-version successfully linked to TeXmacs"

If installation failed, then you should return NULL and *errors should contain an error message. Both what and the returned string have a special format, in which it is possible to encode arbitrary TeXmacs documents. This format will be explained in the next section.

The routine evaluate is used to evaluate the expression what inside a TeXmacs-session with name session. It should return the evaluation of what or NULL if an error occurred. *errors either contains one or more warning messages or an error message, if the evaluation failed. The command:

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

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 execute has a similar specification as evaluate, except that it is not used for the evaluation of expressions inside a TeXmacs-session, but rather for other communication purposes between TeXmacs and your package.

Remark 1. All strings returned by the routines install, evaluate and execute, as well as all warning and error messages should be allocated using malloc. They will be freed by TeXmacs using free.

The first version of the TeXmacs communication protocol also requires TeXmacs to export an instance of the data structure:

    typedef struct TeXmacs_exports_1 {

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

      char* version_TeXmacs;

    } TeXmacs_exports_1;

The string version_protocol contains the version "TeXmacs communication protocol 1" of the protocol and version_TeXmacs the current version of TeXmacs.