Package: cffi

Macro define-foreign-library

Lambda List

define-foreign-library (name-and-options &body pairs)


name-and-options ::= name | (name &key convention search-path)
load-clause ::= (feature library &key convention search-path)


feature -- A feature expression.
library -- A library designator.
convention -- One of :cdecl (default) or :stdcall
search-path -- A path or list of paths where the library will be searched if not found in system-global directories. Paths specified in a load clause take priority over paths specified as library option, with *foreign-library-directories* having lowest priority.

Return Value

A Symbol


Creates a new library designator called name. The load-clauses describe how to load that designator when passed to load-foreign-library or use-foreign-library.

When trying to load the library name, the relevant function searches the load-clauses in order for the first one where feature evaluates to true. That happens for any of the following situations:
  1. If feature is a symbol present in *features*.
  2. If feature is a list, depending on (first feature), a keyword:
    All of the feature expressions in (rest feature) are true.
    At least one of the feature expressions in (rest feature) is true.
    The feature expression (second feature) is not true.
  3. Finally, if feature is t, this load-clause is picked unconditionally.
Upon finding the first true feature, the library loader then loads the library. The meaning of "library designator" is described in load-foreign-library.

Functions associated to a library defined by define-foreign-library, e.g. through defcfun's :library option, will inherit the library's options. The precedence is as follows:
  1. defcfun/foreign-funcall specific options;
  2. load-clause options;
  3. global library options (the name-and-options argument)


See "Loading foreign libraries".

See also