doc/intro.xml

   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">
   5 %myents;
   6 ]>
   7
   8 <chapter id="introduction">
   9   <title>Introduction</title>
  10   <sect1 id="purpose">
  11     <title>Purpose</title>
  12     <para>
  13       This reference guide describes &uffi;, a package that provides a
  14       cross-implementation interface from Common Lisp to C-language
  15       compatible libraries.
  16     </para>
  17   </sect1>
  18
  19   <sect1 id="background">
  20     <title>Background
  21     </title>
  22     <para>
  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.
  29     </para>
  30     <para>
  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.
  36     </para>
  37     <para>
  38       Developers who use &uffi; to interface with C libraries will
  39       automatically have their code function in each of uffi's supported
  40       implementations.
  41     </para>
  42   </sect1>
  43
  44   <sect1 id="supported-impl">
  45     <title>Supported Implementations</title>
  46     <para>The primary tested and supported platforms for &uffi; are:
  47     </para>
  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>
  56     </itemizedlist>
  57     <para>Beta code is included with &uffi; for
  58     </para>
  59     <itemizedlist mark="opencircle">
  60       <listitem><para>&openmcl; and &mcl; with MacOSX</para></listitem>
  61     </itemizedlist>
  62   </sect1>
  63
  64   <sect1 id="design">
  65     <title>Design</title>
  66     <sect2>
  67       <title>Overview</title>
  68       <para>
  69         &uffi; was designed as a cross-implementation
  70         compatible <emphasis>Foreign Function Interface</emphasis>.
  71         Necessarily,
  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.
  76       </para>
  77     </sect2>
  78
  79     <sect2>
  80       <title>Priorities</title>
  81       <para>
  82         The design of &uffi; is dictated by the order of these priorities:
  83       </para>
  84       <itemizedlist>
  85         <listitem>
  86           <para>
  87             Code using &uffi; must operate correctly on all
  88             supported implementations.
  89           </para>
  90         </listitem>
  91         <listitem>
  92           <para>
  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;.
  96           </para>
  97         </listitem>
  98         <listitem>
  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.
 107           </para>
 108         </listitem>
 109       </itemizedlist>
 110     </sect2>
 111   </sect1>
 112
 113 </chapter>