Previous Section | Next Section | Table of Contents | Index | Title Page

## Appendix 2: Intgen

This documentation describes Intgen, a program for generating XLISP to C

interfaces. Intgen works by scanning `.h` files with special comments in them. Intgen builds stubs that implement XLISP SUBR's. When the SUBR is called, arguments are type-checked and passed to the C routine declared in the `.h` file. Results are converted into the appropriate XLISP type and returned to the calling XLISP function. Intgen lets you add C functions into the XLISP environment with very little effort.

### Overview

The interface generator will take as command-line input:

- the name of the `.c` file to generate (do not include the `.c` extension; e.g. write `xlexten`, not `xlexten.c`);
- a list of `.h` files.

Alternatively, the command line may specify a command file from which to read file names. The command file name should be preceded by "@", for example:

    intgen @sndfns.cl

reads sndfns.cl to get the command-line input. Only one level of indirection is allowed.

The output is:

- a single `.c` file with one SUBR defined for each designated routine in a `.h` file.
- a `.h` file that declares each new C routine. E.g. if the `.c` file is named `xlexten.c`, this file will be named `xlextendefs.h`;
- a `.h` file that extends the SUBR table used by Xlisp. E.g. if the `.c` file is named `xlexten.c`, then this file is named `xlextenptrs.h`;
- a `.lsp` file with lisp initialization expressions copied from the `.h` files. This file is only generated if at least one initialization expression is encountered.

For example, the command line

    intgen seint ~setypes.h access.h

generates the file `seint.c`, using declarations in `setypes.h` and `access.h`. Normally, the `.h` files are included by the generated file using `#include` commands. A `~` before a file means do not include the `.h` file. (This may be useful if you extend `xlisp.h`, which will be included anyway). Also generated will be `setintdefs.h` and `seintptrs.h`.

#### Extending Xlisp

Any number of `.h` files may be named on the command line to Intgen, and Intgen will make a single `.c` file with interface routines for all of the `.h` files. On the other hand, it is not necessary to put all of the extensions to Xlisp into a single interface file. For example, you can run Intgen once to build interfaces to window manager routines, and again to build interfaces to a new data type. Both interfaces can be linked into Xlisp.

To use the generated files, you must compile the `.c` files and link them with all of the standard Xlisp object files. In addition, you must edit the file `localdefs.h` to contain an `#include` for each `*defs.h` file, and edit the file `localptrs.h` to include each `*ptrs.h` file. For example, suppose you run Intgen to build `soundint.c`, `fugueint.c`, and `tableint.c`. You would then edit `localdefs.h` to contain the following:

    #include "soundintdefs.h"
    #include "fugueintdefs.h"
    #include "tableintdefs.h"

and edit `localptrs.h` to contain:

    #include "soundintptrs.h"
    #include "fugueintptrs.h"
    #include "tableintptrs.h"

These `localdefs.h` and `localptrs.h` files are in turn included by `xlftab.c` which is where Xlisp builds a table of SUBRs.

To summarize, building an interface requires just a few simple steps:

- Write C code to be called by Xlisp interface routines. This C code does the real work, and in most cases is completely independent of Xlisp.
- Add comments to `.h` files to tell Intgen which routines to build interfaces to, and to specify the types of the arguments.
- Run Intgen to build interface routines.
- Edit `localptrs.h` and `localdefs.h` to include generated `.h` files.
- Compile and link Xlisp, including the new C code.

### Header file format

Each routine to be interfaced with Xlisp must be declared as follows:

    type-name routine-name(); /* LISP: (func-name type1 type2 ...) */

The comment may be on the line following the declaration, but the declaration and the comment must each be on no more than one line. The characters `LISP:` at the beginning of the comment mark routines to put in the interface. The comment also gives the type and number of arguments. The function, when accessed from lisp will be known as func-name, which need not bear any relationship to routine-name. By convention, underscores in the C routine-name should be converted to dashes in func-name, and func-name should be in all capitals. None of this is enforced or automated though.

Legal type_names are:

`LVAL`
  returns an Xlisp datum.
`atom_type`
  equivalent to `LVAL`, but the result is expected to be an atom.
`value_type`
  a value as used in Dannenberg's score editor.
`event_type`
  an event as used in Dannenberg's score editor.
`int`
  interface will convert int to Xlisp `FIXNUM`.
`boolean`
  interface will convert int to `T` or `nil`.
`float` or `double`
  interface converts to `FLONUM`.
`char *` or `string` or `string_type`
  interface converts to `STRING`. The result string will be copied into the XLISP heap.
void
  interface will return `nil`.

It is easy to extend this list. Any unrecognized type will be coerced to an `int` and then returned as a `FIXNUM`, and a warning will be issued.

The “`*`” after char must be followed by routine-name with no intervening space.

Parameter types may be any of the following:

`FIXNUM`
  C routine expects an int.
`FLONUM` or `FLOAT`
  C routine expects a `double`.
`STRING`
  C routine expects `char *`, the string is not copied.
`VALUE`
  C routine expects a `value_type`. (Not applicable to Fugue.)
`EVENT`
  C routine expects an `event_type`. (Not applicable to Fugue.)
`ANY`
  C routine expects `LVAL`.
`ATOM`
  C routine expects `LVAL` which is a lisp atom.
`FILE`
  C routine expects `FILE *`.
`SOUND`
  C routine expects a `SoundPtr`.

Any of these may be followed by “`*`”: `FIXNUM*`, `FLONUM*`, `STRING*`, `ANY*`, `FILE*`, indicating C routine expects `int *`, `double *`, `char **`, `LVAL *`, or `FILE **` . This is basically a mechanism for returning more than one value, not a mechanism for clobbering XLisp values. In this spirit, the interface copies the value (an `int`, `double`, `char *`, `LVAL`, or `FILE *`) to a local variable and passes the address of that variable to the C routine. On return, a list of resulting “`*`” parameters is constructed and bound to the global XLisp symbol `*RSLT*`. (Strings are copied.) If the C routine is void, then the result list is also returned by the corresponding XLisp function.

Note 1: this does not support C routines like strcpy that modify strings, because the C routine gets a pointer to the string in the XLisp heap. However, you can always add an intermediate routine that allocates space and then calls `strcpy`, or whatever.

Note 2: it follows that a new XLisp `STRING` will be created for each `STRING*` parameter.

Note 3: putting results on a (global!) symbol seems a bit unstructured, but note that one could write a multiple-value binding macro that hides this ugliness from the user if desired. In practice, I find that pulling the extra result values from `*RSLT*` when needed is perfectly acceptable.

For parameters that are result values only, the character “`^`” may be substituted for “`*`”. In this case, the parameter is not to be passed in the XLisp calling site. However, the address of an initialized local variable of the given type is passed to the corresponding C function, and the resulting value is passed back through `*RSLT*` as ordinary result parameter as described above. The local variables are initialized to zero or `NULL`.

### Using #define'd macros

If a comment of the form:

    /* LISP: type-name (routine-name-2 type-1 type-2 ...) */

appears on a line by itself and there was a `#define` on the previous line, then the preceding `#define` is treated as a C routine, e.g.

    #define leftshift(val, count) ((val) << (count))
    /* LISP: int (LOGSHIFT INT INT) */

will implement the LeLisp function `LOGSHIFT`.

The type-name following “`LISP:`” should have no spaces, e.g. use `ANY*`, not `ANY *`.

### Lisp Include Files

Include files often define constants that we would like to have around in the Lisp world, but which are easier to initialize just by loading a text file. Therefore, a comment of the form:

    /* LISP-SRC: (any lisp expression) */

will cause Intgen to open a file name`.lsp` and append

    (any lisp expression)

to name`.lsp`, where name is the interface name passed on the command line. If none of the include files examined have comments of this form, then no name`.lsp` file is generated. Note: the LISP-SRC comment must be on a new line.

### Example

This file was used for testing Intgen. It uses a trick (ok, it's a hack) to interface to a standard library macro (tolower). Since tolower is already defined, the macro ToLower is defined just to give Intgen a name to call. Two other routines, strlen and tough, are interfaced as well.

    /* igtest.h -- test interface for intgen */

    #define ToLower(c) tolower(c)
    /* LISP: int (TOLOWER FIXNUM) */

    int strlen();	/* LISP: (STRLEN STRING) */

    void tough();
      /* LISP: (TOUGH FIXNUM* FLONUM* STRING ANY FIXNUM) */

### More Details

Intgen has some compiler switches to enable/disable the use of certain types, including `VALUE` and `EVENT` types used by Dannenberg's score editing work, the `SOUND` type used by Fugue, and `DEXT` and `SEXT` types added for Dale Amon. Enabling all of these is not likely to cause problems, and the chances of an accidental use of these types getting through the compiler and linker seems very small.

Previous Section | Next Section | Table of Contents | Index | Title Page