<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "entities.xml">
%myents;
]>
<title>Introduction</title>
<sect1 id="purpose">
<title>Purpose</title>
- <para> This reference guide describes
- &uffi;, a package that provides a cross-implementation
- interface from Common Lisp to C-language compatible libraries.
+ <para>
+ This reference guide describes &uffi;, a package that provides a
+ cross-implementation interface from Common Lisp to C-language
+ compatible libraries.
</para>
</sect1>
<title>Background
</title>
<para>
- Every Common Lisp implementation has
- a method for interfacing to C-language compatible
- libraries. These methods are often termed a
- <emphasis>Foreign Function Library Interface</emphasis>
- (&ffi;). Unfortunately, these methods vary widely
- amongst
- implementations, thus preventing the writing of a portable FFI to a
-particular C-library.
+ Every Common Lisp implementation has a method for interfacing to
+ C-language compatible libraries. These methods are often termed
+ a <emphasis>Foreign Function Library Interface</emphasis>
+ (&ffi;). Unfortunately, these methods vary widely amongst
+ implementations, thus preventing the writing of a portable FFI
+ to a particular C-library.
</para>
<para>
- &uffi; gathers a common subset of functionality between Common Lisp
- implementations. &uffi; wraps this common subset of functionality with
- it's own syntax and provides macro translation of uffi functions into
- the specific syntax of supported Common Lisp implementations.
+ &uffi; gathers a common subset of functionality between Common
+ Lisp implementations. &uffi; wraps this common subset of
+ functionality with it's own syntax and provides macro
+ translation of uffi functions into the specific syntax of
+ supported Common Lisp implementations.
</para>
<para>
Developers who use &uffi; to interface with C libraries will
</para>
<itemizedlist mark="opencircle">
<listitem><para>&acl; v6.2 on Debian GNU/Linux
-FreeBSD 4.5, Solaris v2.8, and Microsoft Windows XP.</para></listitem>
+ FreeBSD 4.5, Solaris v2.8, and Microsoft Windows XP.</para></listitem>
<listitem><para>&lw; v4.2 on Debian GNU/Linux and Microsoft Windows XP.</para></listitem>
<listitem><para>&cmucl; 18d on Debian GNU/Linux, FreeBSD 4.5, and Solaris 2.8</para></listitem>
<listitem><para>&sbcl; 0.7.8 on Debian GNU/Linux</para></listitem>
</itemizedlist>
</sect1>
- <sect1 id="design">
- <title>Design</title>
- <sect2>
- <title>Overview</title>
- &uffi; was designed as a cross-implementation
- compatible <emphasis>Foreign Function Interface</emphasis>.
- Necessarily,
- only a common subset of functionality can be
- provided. Likewise, not every optimization for that a specific
- implementation provides can be supported. Wherever possible,
- though, implementation-specific optimizations are invoked.
- </para>
- </sect2>
+ <sect1 id="design">
+ <title>Design</title>
+ <sect2>
+ <title>Overview</title>
+ <para>
+ &uffi; was designed as a cross-implementation
+ compatible <emphasis>Foreign Function Interface</emphasis>.
+ Necessarily,
+ only a common subset of functionality can be
+ provided. Likewise, not every optimization for that a specific
+ implementation provides can be supported. Wherever possible,
+ though, implementation-specific optimizations are invoked.
+ </para>
+ </sect2>
- <sect2>
- <title>Priorities</title>
- The design of &uffi; is dictated by the order of these priorities:
- </para>
- <itemizedlist>
- <listitem>
- Code using &uffi; must operate correctly on all
- supported implementations.
- </para>
- </listitem>
- <listitem>
- Take advantage of implementation-specific optimizations. Ideally,
- there will not a situation where an implementation-specific
- &ffi; will be chosen due to lack of optimizations in &uffi;.
- </para>
- </listitem>
- <listitem>
-
<para>Provide a simple interface to developers using
-&uffi;. This priority is quite a bit lower than the above priorities.
-This lower priority is manifest by programmers having to pass types in
-pointer and array dereferencing, needing to use
-<constant>cstring</constant> wrapper functions, and the use of
-ensure-char-character and ensure-char-integer functions. My hope is
-that the developer inconvenience will be outweighed by the generation
-of optimized code that is cross-implementation compatible.
- </para>
- </listitem>
- </itemizedlist>
- </sect2>
- </sect1>
+ <sect2>
+ <title>Priorities</title>
+ <para>
+ The design of &uffi; is dictated by the order of these priorities:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Code using &uffi; must operate correctly on all
+ supported implementations.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Take advantage of implementation-specific optimizations. Ideally,
+ there will not a situation where an implementation-specific
+ &ffi; will be chosen due to lack of optimizations in &uffi;.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Provide a simple interface to developers using
+ &uffi;. This priority is quite a bit lower than the above priorities.
+ This lower priority is manifest by programmers having to pass types in
+ pointer and array dereferencing, needing to use
+ <constant>cstring</constant> wrapper functions, and the use of
+ ensure-char-character and ensure-char-integer functions. My hope is
+ that the developer inconvenience will be outweighed by the generation
+ of optimized code that is cross-implementation compatible.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
</chapter>
projects / uffi.git / commitdiff