Clozure CL Documentation

12.5. Using Interface Directories

12.5.1. Overview

As distributed, the "ccl:headers;" (for LinuxPPC) directory is organized like:

        headers/
        headers/gl/
        headers/gl/C/
        headers/gl/C/populate.sh
        headers/gl/constants.cdb
        headers/gl/functions.cdb
        headers/gl/records.cdb
        headers/gl/objc-classes.cdb
        headers/gl/objc-methods.cdb
        headers/gl/types.cdb
        headers/gnome/
        headers/gnome/C/
        headers/gnome/C/populate.sh
        headers/gnome/constants.cdb
        headers/gnome/functions.cdb
        headers/gnome/records.cdb
        headers/gnome/objc-classes.cdb
        headers/gnome/objc-methods.cdb
        headers/gnome/types.cdb
        headers/gtk/
        headers/gtk/C/
        headers/gtk/C/populate.sh
        headers/gtk/constants.cdb
        headers/gtk/functions.cdb
        headers/gtk/records.cdb
        headers/gtk/objc-classes.cdb
        headers/gtk/objc-methods.cdb
        headers/gtk/types.cdb
        headers/libc/
        headers/libc/C/
        headers/libc/C/populate.sh
        headers/libc/constants.cdb
        headers/libc/functions.cdb
        headers/libc/records.cdb
        headers/libc/objc-classes.cdb
        headers/libc/objc-methods.cdb
        headers/libc/types.cdb

e.g, as a set of parallel subdirectories, each with a lowercase name and each of which contains a set of 6 database files and a "C" subdirectory which contains a shell script used in the database creation process.

As one might assume, the database files in each of these subdirectories contain foreign type, constant, and function definitions - as well as Objective-C class and method info -that correspond (roughly) to the information contained in the header files associated with a "-dev" package in a Linux distribution. "libc" corresponds pretty closely to the interfaces associated with "glibc/libc6" header files, "gl" corresponds to an "openGL+GLUT" development package, "gtk" and "gnome" contain interface information from the GTK+1.2 and GNOME libraries, respectively.

For Darwin, the "ccl:darwin-headers" directory contains a "libc" subdirectory, whose contents roughly correspond to those of "/usr/include" under Darwin, as well as subdirectories corresponding to the MacOSX Carbon and Cocoa frameworks.

To see the precise set of .h files used to generate the database files in a given interface directory, consult the corresponding "populate.sh" shell script (in the interface directory's "C" subdirectory.)

The intent is that this initial set can be augmented to meet local needs, and that this can be done in a fairly incremental fashion: one needn't have unrelated header files installed in order to generate interface databases for a package of interest.

Hopefully, this scheme will also make it easier to distribute patches and bug fixes.

CCL maintains a list of directories; when looking for a foreign type, constant, function, or record definition, it'll consult the database files in each directory on that list. Initially, the list contains an entry for the "libc" interface directory. CCL needs to be explicitly told to look in other interface directories should it need to do so.

12.5.2. Creating new interface directories

This example refers to "ccl:headers;", which is appropriate for LinuxPPC. The procedure's analogous under Darwin, where the "ccl:darwin-headers;" directory would be used instead.

To create a new interface directory, "foo", and a set of database files in that directory:

Create a subdirectory of "ccl:headers;" named "foo".
Create a subdirectory of "ccl:headers;foo;" named "C".

Create a file in "ccl:headers;foo;C;" named "populate.sh".

One way of accomplishing the above steps is:

            ? (close (open "ccl:headers;foo;C;populate.sh" :direction :output :
                           if-does-not-exist :create :if-exists :overwrite))

Edit the file created above, using the "populate.sh" files in the distribution as guidelines.

The file might wind up looking something like:
```
#/bin/sh
            h-to-ffi.sh `foo-config -cflags` /usr/include/foo/foo.h
```

Refer to Section 12.7, “The Interface Translator” for information about running the interface translator and .ffi parser.

Assuming that all went well, there should now be .cdb files in "ccl:headers;foo;". You can then do

          ? (use-interface-dir :foo)

whenever you need to access the foreign type information in those database files.