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>&scl; 1.1.1 on Debian GNU/Linux</para></listitem>
50 <listitem><para>&openmcl; 0.13 on Debian GNU/Linux for PowerPC</para></listitem>
52 <para>Beta code is included with &uffi; for
54 <itemizedlist mark="opencircle">
55 <listitem><para>&openmcl; and &mcl; with MacOSX</para></listitem>
62 <title>Overview</title>
64 &uffi; was designed as a cross-implementation
65 compatible <emphasis>Foreign Function Interface</emphasis>.
67 only a common subset of functionality can be
68 provided. Likewise, not every optimization for that a specific
69 implementation provides can be supported. Wherever possible,
70 though, implementation-specific optimizations are invoked.
75 <title>Priorities</title>
77 The design of &uffi; is dictated by the order of these priorities:
82 Code using &uffi; must operate correctly on all
83 supported implementations.
88 Take advantage of implementation-specific optimizations. Ideally,
89 there will not a situation where an implementation-specific
90 &ffi; will be chosen due to lack of optimizations in &uffi;.
94 <para>Provide a simple interface to developers using
95 &uffi;. This priority is quite a bit lower than the above priorities.
96 This lower priority is manifest by programmers having to pass types in
97 pointer and array dereferencing, needing to use
98 <constant>cstring</constant> wrapper functions, and the use of
99 ensure-char-character and ensure-char-integer functions. My hope is
100 that the developer inconvenience will be outweighed by the generation
101 of optimized code that is cross-implementation compatible.