doc/intro.xml

   1 <?xml version='1.0' ?>   <!-- -*- DocBook -*- -->
   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.xml">
   5 %myents;
   6 ]>
   7
   8 <chapter id="introduction">
   9   <title>Introduction</title>
  10   <sect1 id="purpose">
  11     <title>Purpose</title>
  12     <para> This reference guide describes
  13       &uffi;, a package that provides a cross-implementation
  14       interface from Common Lisp to C-language compatible libraries.
  15     </para>
  16   </sect1>
  17
  18   <sect1 id="background">
  19     <title>Background
  20     </title>
  21     <para>
  22       Every Common Lisp implementation has
  23       a method for interfacing to C-language compatible
  24       libraries. These methods are often termed a
  25       <emphasis>Foreign Function Library Interface</emphasis>
  26       (&ffi;). Unfortunately, these methods vary widely
  27       amongst
  28       implementations, thus preventing the writing of a portable FFI to a
  29 particular C-library.
  30     </para>
  31     <para>
  32       &uffi; gathers a common subset of functionality between Common Lisp
  33       implementations. &uffi; wraps this common subset of functionality with
  34       it's own syntax and provides macro translation of uffi functions into
  35       the specific syntax of 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>