# Introduction

## Purpose

This reference guide describes &uffi;, a package that provides a cross-implementation interface from Common Lisp to C-language compatible libraries.

## Background

Every Common Lisp implementation has a method for interfacing to C-language compatible libraries. These methods are often termed a Foreign Function Library Interface (&ffi;). Unfortunately, these methods vary widely amongst implementations, thus preventing the writing of a portable FFI to a particular C-library.

&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.

Developers who use &uffi; to interface with C libraries will automatically have their code function in each of uffi's supported implementations.

## Supported Implementations

The primary tested and supported platforms for &uffi; are:

- &acl; v6.2 on Debian GNU/Linux FreeBSD 4.5, Solaris v2.8, and Microsoft Windows XP.

- &lw; v4.2 on Debian GNU/Linux and Microsoft Windows XP.

- &cmucl; 18d on Debian GNU/Linux, FreeBSD 4.5, and Solaris 2.8

- &sbcl; 0.7.8 on Debian GNU/Linux

- &scl; 1.1.1 on Debian GNU/Linux

- &openmcl; 0.13 on Debian GNU/Linux for PowerPC

Beta code is included with &uffi; for

- &openmcl; and &mcl; with MacOSX

## Design

### Overview

&uffi; was designed as a cross-implementation compatible Foreign Function Interface. 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.

### Priorities

The design of &uffi; is dictated by the order of these priorities:

- Code using &uffi; must operate correctly on all supported implementations.

- 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;.

- 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 `cstring` 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.