# The ORBLink IDL to Lisp Compiler

An IDL file may be compiled by using the `corba:idl` function with a single argument, the pathname of the file to be compiled. By default the preprocessor symbol "LISP" is defined.

## Basic usage of `corba:idl`

The effect of the function

    (corba:idl pathname)

is to load into the Lisp image those Lisp values defined by the official mapping that correspond to the IDL file denoted by `pathname`.

This includes:

- constant definitions,
- type definitions,
- class definitions,
- proxy definitions,
- servant definitions,
- struct definitions,
- union definitions, and
- marshalling and unmarshalling functions for each of the data types and operations defined in the IDL file.

## Include files

When the parser sees

>     #include "..."

where ... is a relative name, it searches for ... in the directory containing the source file.

When the parser sees

>     #include <...>

where ... is a relative name, it searches for ... in the directories whose names it finds in the special variable `orblink:*default-system-include-path-list*`.

The default value of that variable is `nil`, which will result in failure to find the include file.

The user should setq or bind `orblink:*default-system-include-path-list*` to a list of pathnames to be searched to find <...> include files.

## Generating fasl files from IDL files: Advanced usage of `corba:idl`

The `corba:idl` function can also be used to generate a `.fasl` file from an IDL file. This .fasl can later be loaded into a Lisp image into which ORBLink has been loaded. When the `.fasl` file is loaded, the effect on the Lisp world is the same as if the original IDL file had been passed as sole argument to the `corba:idl` function. The name of the generated fasl file is determined by keyword arguments passed to `corba:idl`. The allowed keyword arguments to `corba:idl` are:

- :compile
  Set to `T` if a `fasl` is to be generated from the argument IDL file. The default is `nil`. If set to `T`, a fasl file is generated from the argument IDL file. The default name of this fasl file is the same as the concatenation of the name of the IDL file without extension concatenated to the string "-tmp" with the file extension replaced by ".fasl". Note that by default, when the value of `:compile` is set to `T`, the fasl file is generated but is not loaded; thus, it is necessary subsequently to load manually the generated fasl file.
- :compile-and-load
  Set to `T` if a `fasl` file is to be generated from the argument IDL file and subsequently loaded into the running Lisp image. The name of the generated `fasl` file follows the conventions of the `:compile` keyword argument.
- :lisp-file
  The name of the intermediate Lisp file that is generated. The default is the name (without extension) of the given IDL file concatenated to the string "-tmp.cl". This argument should be set only if either `:compile` or `:compile-and-load` were set to `T`.
- :retain-lisp-file
  Set to `T` if the intermediate Lisp file is to be retained after compilation; by default it is deleted. This option is included for didactic purposes only; in particular, the operation of recompiling this generated Lisp file by the user is explicitly not supported, as the compilation must be done in a particular environment controlled by the ORB.
- [all other keyword arguments]
  All other keyword arguments are passed through to `compile-file` without change.

For example, given a file /a/b/x.idl, the form `(corba:idl "/a/b/x.idl" :compile t)` will generate a fasl file named /a/b/x-tmp.fasl. When loaded into another Lisp world, the effect will be the same as if `(corba:idl "/a/b/x.idl" )` were evaluated.