*foreign-library-directories*

*foreign-library-directories*

Syntax

Special Variable: *foreign-library-directories*

Value type

A list, in which each element is a string, a pathname, or a simple Lisp expression.

Initial value

The empty list.

Description

You should not have to use this variable.

Most, if not all, Lisps supported by CFFI have a reasonable default search algorithm for foreign libraries. For example, Lisps for UNIX usually call dlopen(3), which in turn looks in the system library directories. Only if that fails does CFFI look for the named library file in these directories, and load it from there if found.

Thus, this is intended to be a CFFI-only fallback to the library search configuration provided by your operating system. For example, if you distribute a foreign library with your Lisp package, you can add the library’s containing directory to this list and portably expect CFFI to find it.

A simple Lisp expression is intended to provide functionality commonly used in search paths such as ASDF’s¹³, and is defined recursively as follows:¹⁴

1. A list, whose ‘first’ is a function designator, and whose ‘rest’ is a list of simple Lisp expressions to be evaluated and passed to the so-designated function. The result is the result of the function call.
2. A symbol, whose result is its symbol value.
3. Anything else evaluates to itself.

The result of evaluating the simple Lisp expression should yield a designator for a list of pathname designators.

Note: in Common Lisp, #p"/foo/bar" designates the bar file within the /foo directory whereas #p"/foo/bar/" designates the /foo/bar directory. Keep that in mind when customising the value of *foreign-library-directories*.

Examples

$ ls
-| liblibli.so    libli.lisp

In libli.lisp:

  (pushnew #P"/home/sirian/lisp/libli/" *foreign-library-directories*
           :test #'equal)
   
  (load-foreign-library '(:default "liblibli"))

The following example would achieve the same effect:

  (pushnew '(merge-pathnames #p"lisp/libli/" (user-homedir-pathname))
            *foreign-library-directories*
            :test #'equal)
  ⇒ ((MERGE-PATHNAMES #P"lisp/libli/" (USER-HOMEDIR-PATHNAME)))
   
  (load-foreign-library '(:default "liblibli"))

See also

*darwin-framework-directories*
define-foreign-library