1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
<?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" [
<!ENTITY % myents SYSTEM "entities.inc">
%myents;
]>
<chapter id="introduction">
<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>
</sect1>
<sect1 id="background">
<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.
</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.
</para>
<para>
Developers who use &uffi; to interface with C libraries will
automatically have their code function in each of uffi's supported
implementations.
</para>
</sect1>
<sect1 id="supported-impl">
<title>Supported Implementations</title>
<para>The primary tested and supported platforms for &uffi; are:
</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>
<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>
<listitem><para>&scl; 1.1.1 on Debian GNU/Linux</para></listitem>
<listitem><para>&openmcl; 0.13 on Debian GNU/Linux for PowerPC</para></listitem>
</itemizedlist>
<para>Beta code is included with &uffi; for
</para>
<itemizedlist mark="opencircle">
<listitem><para>&openmcl; and &mcl; with MacOSX</para></listitem>
</itemizedlist>
</sect1>
<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>
<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>
|
