define-foreign-library

define-foreign-library

Syntax

Macro: define-foreign-library name-and-options { load-clause }* ⇒ name

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

Arguments and Values

name

A symbol.

feature

A feature expression.

library

A library designator.

canary

A string denoting a foreign symbol that will be searched in core before attempting to load the library. If that symbol is found, the library is assumed to be statically linked and load-foreign-library only marks the library as loaded.

Some implementations (Clisp, ECL, SBCL) natively support static linking, sometimes referred to as a link kit.

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.

Description

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 common-lisp:*features*.
2. If feature is a list, depending on (first feature), a keyword:

   :and

   All of the feature expressions in (rest feature) are true.

   :or

   At least one of the feature expressions in (rest feature) is true.

   :not

   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)

Examples

See Loading foreign libraries.

See Also

close-foreign-library
load-foreign-library