1 <!-- -*- DocBook -*- -->
4 <title>Introduction</title>
7 <para> This reference guide describes
8 &uffi;, a package that provides a cross-implementation
9 interface from Common Lisp to C-language compatible libraries.
17 Every Common Lisp implementation has
18 a method for interfacing to C-language compatible
19 libraries. These methods are often termed a
20 <emphasis>Foreign Function Library Interface</emphasis>
21 (&ffi;). Unfortunately, these methods vary widely
23 implementations, thus preventing the writing of a portable FFI to a
27 &uffi; gathers a common subset of functionality between Common Lisp
28 implementations. &uffi; wraps this common subset of functionality with
29 it's own syntax and provides macro translation of uffi functions into
30 the specific syntax of supported Common Lisp implementations.
33 Developers who use &uffi; to interface with C libraries will
34 automatically have their code function in each of uffi's supported
40 <title>Supported Implementations</title>
41 <para> The primary tested and supported platforms for &uffi; are:
43 <itemizedlist mark="opencircle">
44 <listitem><para>&acl; v6.1 on Redhat Linux 7.2, FreeBSD 4.5, and Microsoft Windows.</para></listitem>
45 <listitem><para>&lw; v4.2 on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
46 <listitem><para>&cmucl; 18c on Redhat Linux 7.2, FreeBSD 4.5, and Solaris 2.8</para></listitem>
53 <title>Overview</title>
55 &uffi; was designed as a cross-implementation
56 compatible <emphasis>Foreign Function Interface</emphasis>.
58 only a common subset of functionality can be
59 provided. Likewise, not every optimization for that a specific
60 implementation provides can be supported. Wherever possible,
61 though, implementation-specific optimizations are invoked.
66 <title>Priorities</title>
68 The design of &uffi; is dictated by the order of these priorities:
73 Code using &uffi; must operate correctly on all
74 supported implementations.
79 Take advantage of implementation-specific optimizations. Ideally,
80 there will not a situation where an implementation-specific
81 &ffi; will be chosen due to lack of optimizations in &uffi;.
85 <para>Provide a simple interface to developers using
86 &uffi;. This priority is quite a bit lower than the above priorities.
87 This lower priority is manifest by programmers having to pass types in
88 pointer and array dereferencing, needing to use
89 <constant>cstring</constant> wrapper functions, and the use of
90 ensure-char-character and ensure-char-integer functions. My hope is
91 that the developer inconvenience will be outweighed by the generation
92 of optimized code that is cross-implementation compatible.