Using interface directories in OpenMCL

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

headers/
  gl/
    C/
      populate.sh
    constants.db
    functions.db
    records.db
    types.db
  gnome/
    C/
      populate.sh
    constants.db
    functions.db
    records.db
    types.db
  gtk/
    C/
      populate.sh
    constants.db
    functions.db
    records.db
    types.db
  libc/
    C/
      populate.sh
    constants.db
    functions.db
    records.db
    types.db

e.g, as a set of parallel subdirectories, each with a lowercase name and each of which contains a set of 4 Berkeley DB v1 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 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" developmnent 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.

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.

OpenMCL 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. OpenMCL needs to be explicitly told to look in other interface directories should it need to do so.

Functional Reference

use-interface-dir [Function]

Syntax
use-interface-dir dir-id 
Description Tells OpenMCL to add the interface directory denoted by dir-id to the list of interface directories which it consults for foreign type and function information. Arranges that that directory is searched before any others.
Arguments
dir-id
A keyword whose pname, mapped to lower case, names a subdirectory of "ccl:headers;".

unuse-interface-dir [Function]

Syntax
unuse-interface-dir dir-id 
Description Tells OpenMCL to remove the interface directory denoted by dir-id to the list of interface directories which it consults for foreign type and function information. Returns T if the directory was on the search list, NIL otherwise.
Arguments
dir-id
A keyword whose pname, mapped to lower case, names a subdirectory of "ccl:headers;".

An example


;;; One typically wants interface information to be available at compile-time
;;; (or, in many cases, at read-time.)  A typical idiom would be:

(eval-when (:compile-toplevel :execute)
  (use-interface-dir :GTK))

;;; It should now be possiible to say things like:

  (#_gtk_widget_destroy w)

    

Note that USE-INTERFACE-DIR merely adds an entry to a search list. If the named directory doesn't exist in the file system or doesn't contain a set of database files, a runtime error may occur when OpenMCL tries to open some database file in that directory, and it will try to open such a database file whenever it needs to find any foreign type or function information. UNUSE-INTERFACE-DIR may come in handy in that case.

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:

    1. Create a subdirectory of "ccl:headers;" named "foo".
    2. Create a subdirectory of "ccl:headers;foo;" named "C".
    3. 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))
    
  1. 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
    	
    Or maybe not ...
  2. Refer to the interface translator documentation for information about running the interface translator and .ffi parser.

Assuming that all went well, there should now be .db 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.


Last modified: Tue Jan 22 14:25:32 PST 2002