doc/intro.sgml

   1 <!-- -*- DocBook -*- -->
   2
   3 <chapter>
   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.1 on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
  45       <listitem><para>&lw; v4.2 on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
  46       <listitem><para>&cmucl; 18c on Redhat Linux 7.2.</para></listitem>
  47     </itemizedlist>
  48   </sect1>
  49
  50     <sect1>
  51       <title>Design Overview</title>
  52       <para>
  53         &uffi; was designed as a cross-implementation compatible
  54         <emphasis>Foreign Function Interface</emphasis>. Necessarily,
  55         only a common subset of functionality can be
  56         provided. Likewise, not every optimization for that a specific
  57         implementation provides can be supported. Wherever possible,
  58         though, implementation-specific optimizations are invoked.
  59       </para>
  60     </sect1>
  61
  62 </chapter>