1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % myents SYSTEM "entities.inc">
8 <chapter id="introduction">
9 <title>Introduction</title>
11 <title>Purpose</title>
13 This reference guide describes &uffi;, a package that provides a
14 cross-implementation interface from Common Lisp to C-language
19 <sect1 id="background">
23 Every Common Lisp implementation has a method for interfacing to
24 C-language compatible libraries. These methods are often termed
25 a <emphasis>Foreign Function Library Interface</emphasis>
26 (&ffi;). Unfortunately, these methods vary widely amongst
27 implementations, thus preventing the writing of a portable FFI
28 to a particular C-library.
31 &uffi; gathers a common subset of functionality between Common
32 Lisp implementations. &uffi; wraps this common subset of
33 functionality with it's own syntax and provides macro
34 translation of uffi functions into the specific syntax of
35 supported Common Lisp implementations.
38 Developers who use &uffi; to interface with C libraries will
39 automatically have their code function in each of uffi's supported
44 <sect1 id="supported-impl">
45 <title>Supported Implementations</title>
46 <para>The primary tested and supported platforms for &uffi; are:
48 <itemizedlist mark="opencircle">
49 <listitem><para>&acl; v6.2 on Debian GNU/Linux
50 FreeBSD 4.5, Solaris v2.8, and Microsoft Windows XP.</para></listitem>
51 <listitem><para>&lw; v4.2 on Debian GNU/Linux and Microsoft Windows XP.</para></listitem>
52 <listitem><para>&cmucl; 18d on Debian GNU/Linux, FreeBSD 4.5, and Solaris 2.8</para></listitem>
53 <listitem><para>&sbcl; 0.7.8 on Debian GNU/Linux</para></listitem>
54 <listitem><para>&scl; 1.1.1 on Debian GNU/Linux</para></listitem>
55 <listitem><para>&openmcl; 0.13 on Debian GNU/Linux for PowerPC</para></listitem>
57 <para>Beta code is included with &uffi; for
59 <itemizedlist mark="opencircle">
60 <listitem><para>&openmcl; and &mcl; with MacOSX</para></listitem>
67 <title>Overview</title>
69 &uffi; was designed as a cross-implementation
70 compatible <emphasis>Foreign Function Interface</emphasis>.
72 only a common subset of functionality can be
73 provided. Likewise, not every optimization for that a specific
74 implementation provides can be supported. Wherever possible,
75 though, implementation-specific optimizations are invoked.
80 <title>Priorities</title>
82 The design of &uffi; is dictated by the order of these priorities:
87 Code using &uffi; must operate correctly on all
88 supported implementations.
93 Take advantage of implementation-specific optimizations. Ideally,
94 there will not a situation where an implementation-specific
95 &ffi; will be chosen due to lack of optimizations in &uffi;.
99 <para>Provide a simple interface to developers using
100 &uffi;. This priority is quite a bit lower than the above priorities.
101 This lower priority is manifest by programmers having to pass types in
102 pointer and array dereferencing, needing to use
103 <constant>cstring</constant> wrapper functions, and the use of
104 ensure-char-character and ensure-char-integer functions. My hope is
105 that the developer inconvenience will be outweighed by the generation
106 of optimized code that is cross-implementation compatible.