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 and v6.2.beta on Redhat Linux 7.2, Debian Woody,
45 FreeBSD 4.5, Solaris v2.8, and Microsoft Windows XP.</para></listitem>
46 <listitem><para>&lw; v4.2 on Redhat Linux 7.2 and Microsoft Windows XP.</para></listitem>
47 <listitem><para>&cmucl; 18d-pre on Redhat Linux 7.2, FreeBSD 4.5, and Solaris 2.8</para></listitem>
49 <para>Beta code is included with &uffi; for
51 <itemizedlist mark="opencircle">
52 <listitem><para>&mcl; with MacOSX</para></listitem>
59 <title>Overview</title>
61 &uffi; was designed as a cross-implementation
62 compatible <emphasis>Foreign Function Interface</emphasis>.
64 only a common subset of functionality can be
65 provided. Likewise, not every optimization for that a specific
66 implementation provides can be supported. Wherever possible,
67 though, implementation-specific optimizations are invoked.
72 <title>Priorities</title>
74 The design of &uffi; is dictated by the order of these priorities:
79 Code using &uffi; must operate correctly on all
80 supported implementations.
85 Take advantage of implementation-specific optimizations. Ideally,
86 there will not a situation where an implementation-specific
87 &ffi; will be chosen due to lack of optimizations in &uffi;.
91 <para>Provide a simple interface to developers using
92 &uffi;. This priority is quite a bit lower than the above priorities.
93 This lower priority is manifest by programmers having to pass types in
94 pointer and array dereferencing, needing to use
95 <constant>cstring</constant> wrapper functions, and the use of
96 ensure-char-character and ensure-char-integer functions. My hope is
97 that the developer inconvenience will be outweighed by the generation
98 of optimized code that is cross-implementation compatible.