Download CFFI User Manual - Common

Transcript
Chapter 11: Libraries
98
11 Libraries
11.1 Defining a library
Almost all foreign code you might want to access exists in some kind of shared library. The
meaning of shared library varies among platforms, but for our purposes, we will consider it
to include ‘.so’ files on unix, frameworks on Darwin (and derivatives like Mac OS X), and
‘.dll’ files on Windows.
Bringing one of these libraries into the Lisp image is normally a two-step process.
1. Describe to CFFI how to load the library at some future point, depending on platform
and other factors, with a define-foreign-library top-level form.
2. Load the library so defined with either a top-level use-foreign-library form or by
calling the function load-foreign-library.
See Section 4.3 [Loading foreign libraries], page 5, for a working example of the above
two steps.
11.2 Library definition style
Looking at the libcurl library definition presented earlier, you may ask why we did not
simply do this:
(define-foreign-library libcurl
(t (:default "libcurl")))
Indeed, this would work just as well on the computer on which I tested the tutorial. There
are a couple of good reasons to provide the ‘.so’’s current version number, however. Namely,
the versionless ‘.so’ is not packaged on most unix systems along with the actual, fullyversioned library; instead, it is included in the “development” package along with C headers
and static ‘.a’ libraries.
The reason CFFI does not try to account for this lies in the meaning of the version numbers. A full treatment of shared library versions is beyond this manual’s scope; see Section
“Library interface versions” in GNU Libtool, for helpful information for the unfamiliar. For
our purposes, consider that a mismatch between the library version with which you tested
and the installed library version may cause undefined behavior.1
Implementor’s note: Maybe some notes should go here about OS X, which I know
little about. –stephen
1
Windows programmers may chafe at adding a unix-specific clause to define-foreign-library. Instead,
ask why the Windows solution to library incompatibility is “include your own version of every library
you use with every program”.