A symbol or string specifying the Lisp name the module will be registered under.
A keyword specifying the lifetime of the connection. One of
:session. The default value is
Overrides the name for identifying the actual dynamic library to connect to.
Controls use of
dlopen on Unix-based systems. One of
:local-lazy, or a fixnum. The default value is
nil on Darwin, and
t on other platforms.
register-module explicitly informs LispWorks of the presence of a DLL or shared object file, referred to here as a dynamic library. Functions such as make-pointer and define-foreign-function have a module keyword which can be used to specify which module the function refers to.
If an application is delivered after calling
register-module, then the application attempts to reload the module on startup but does not report any errors. Therefore it is strongly recommended that you call
register-module during initialization of your application, rather than at compile time or build time. Loading the module at run time allows you to:
name is used for explicit look up from the
:module keyword of functions such as define-foreign-function. If name is a symbol, then real-name should also be passed to provide a filename. If real-name is not specified then name must be a string and specifies the actual name of the dynamic library to connect to.
On Windows, if the module is declared without an extension, "
.DLL" is automatically appended to the name. To declare a name without an extension it must end with the period character ("
."). On other platforms, you should provide the extension, since there is more than one library format. Typical would be
.so on Linux, x86/x64 Solaris or FreeBSD,
.a on AIX and
.dylib on Macintosh.
The simplest approach is usually to place the DLL in the same directory as the LispWorks executable or application. However if you really need different directories then be sure to call
register-module at run time with the appropriate pathname.
/usr/lib, followed by
If connection-style is
:manual then the system only connects to the dynamic library if the symbol to resolve is explicitly marked as coming from this module via the
:module keyword of functions such as define-foreign-function.
If connection-style is
:immediate then the connection to the dynamic library is made immediately. This checks that the library can actually be loaded before its symbols are actually needed: an error is signalled if loading fails.
You should load only libraries of the correct architecture into LispWorks. You will need to obtain a 32-bit dynamic library for use with 32-bit LispWorks and similarly you need a 64-bit dynamic library for use with 64-bit LispWorks. (If you build the dynamic library, pass
-m64 as appropriate to
cc.) You can conditionalize the argument to
register-module as in the example below.
dlopen-flags has an effect only on Unix-based systems. It controls the value that is passed to
dlopen as second argument when the module is connected, and on Darwin it also controls whether
dlopen is used at all.
The keyword values of dlopen-flags correspond to combinations of
RTLD_* constants (see
/usr/include/dlfcn.h). The value
t means the same as
:local-lazy. The value
nil means the same as
t except on Darwin. On Darwin the value
nil means do not use
dlopen, and use the older interfaces instead.
register-moduleduring initialization of your application, rather than at compile time or build time.
(fli:register-module :user-dll :real-name "user32")
LispWorks Foreign Language Interface User Guide and Reference Manual - 16 Feb 2015