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