doc/intro.xml

   1 <?xml version='1.0' ?>   <!-- Mode: Docbook -->
   2
   3 <chapter id="introduction">
   4   <title>Introduction</title>
   5   <sect1>
   6     <title>Purpose</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.
  10     </para>
  11   </sect1>
  12
  13   <sect1>
  14     <title>Background
  15     </title>
  16     <para>
  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
  22       amongst
  23       implementations, thus preventing the writing of a portable FFI to a
  24 particular C-library.
  25     </para>
  26     <para>
  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.
  31     </para>
  32     <para>
  33       Developers who use &uffi; to interface with C libraries will
  34       automatically have their code function in each of uffi's supported
  35       implementations.
  36     </para>
  37   </sect1>
  38
  39   <sect1>
  40     <title>Supported Implementations</title>
  41     <para>The primary tested and supported platforms for &uffi; are:
  42     </para>
  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>
  51     </itemizedlist>
  52     <para>Beta code is included with &uffi; for
  53     </para>
  54     <itemizedlist mark="opencircle">
  55       <listitem><para>&openmcl; and &mcl; with MacOSX</para></listitem>
  56     </itemizedlist>
  57   </sect1>
  58
  59     <sect1>
  60       <title>Design</title>
  61       <sect2>
  62         <title>Overview</title>
  63         <para>
  64           &uffi; was designed as a cross-implementation
  65           compatible <emphasis>Foreign Function Interface</emphasis>.
  66           Necessarily,
  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.
  71         </para>
  72       </sect2>
  73
  74       <sect2>
  75         <title>Priorities</title>
  76         <para>
  77           The design of &uffi; is dictated by the order of these priorities:
  78         </para>
  79         <itemizedlist>
  80           <listitem>
  81             <para>
  82               Code using &uffi; must operate correctly on all
  83               supported implementations.
  84             </para>
  85           </listitem>
  86           <listitem>
  87             <para>
  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;.
  91             </para>
  92           </listitem>
  93           <listitem>
  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.
 102             </para>
 103           </listitem>
 104         </itemizedlist>
 105       </sect2>
 106     </sect1>
 107
 108 </chapter>