@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Loading
way.) Most often, the forms are function definitions and variable
definitions.
-For on-demand loading of external libraries, @pxref{Dynamic Libraries}.
+ Emacs can also load compiled dynamic modules: shared libraries that
+provide additional functionality for use in Emacs Lisp programs, just
+like a package written in Emacs Lisp would. When a dynamic module is
+loaded, Emacs calls a specially-named initialization function which
+the module needs to implement, and which exposes the additional
+functions and variables to Emacs Lisp programs.
+
+For on-demand loading of external libraries which are known in advance
+to be required by certain Emacs primitives, @pxref{Dynamic Libraries}.
@menu
* How Programs Do Loading:: The @code{load} function and others.
* Repeated Loading:: Precautions about loading a file twice.
* Named Features:: Loading a library if it isn't already loaded.
* Where Defined:: Finding which file defined a certain symbol.
-* Unloading:: How to "unload" a library that was loaded.
+* Unloading:: How to unload a library that was loaded.
* Hooks for Loading:: Providing code to be run when
particular libraries are loaded.
+* Dynamic Modules:: Modules provide additional Lisp primitives.
@end menu
@node How Programs Do Loading
@var{filename} with the extension @samp{.elc} appended. If such a
file exists, it is loaded. If there is no file by that name, then
@code{load} looks for a file named @file{@var{filename}.el}. If that
-file exists, it is loaded. Finally, if neither of those names is
-found, @code{load} looks for a file named @var{filename} with nothing
-appended, and loads it if it exists. (The @code{load} function is not
-clever about looking at @var{filename}. In the perverse case of a
-file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will
-indeed find it.)
+file exists, it is loaded. If Emacs was compiled with support for
+dynamic modules (@pxref{Dynamic Modules}), @code{load} next looks for
+a file named @file{@var{filename}.@var{ext}}, where @var{ext} is a
+system-dependent file-name extension of shared libraries. Finally, if
+neither of those names is found, @code{load} looks for a file named
+@var{filename} with nothing appended, and loads it if it exists. (The
+@code{load} function is not clever about looking at @var{filename}.
+In the perverse case of a file named @file{foo.el.el}, evaluation of
+@code{(load "foo.el")} will indeed find it.)
If Auto Compression mode is enabled, as it is by default, then if
@code{load} can not find a file, it searches for a compressed version
of the file before trying other file names. It decompresses and loads
it if it exists. It looks for compressed versions by appending each
of the suffixes in @code{jka-compr-load-suffixes} to the file name.
-The value of this variable must be a list of strings. Its standard
+The value of this variable must be a list of strings. Its standard
value is @code{(".gz")}.
If the optional argument @var{nosuffix} is non-@code{nil}, then
If the optional argument @var{must-suffix} is non-@code{nil}, then
@code{load} insists that the file name used must end in either
@samp{.el} or @samp{.elc} (possibly extended with a compression
-suffix), unless it contains an explicit directory name.
+suffix) or the shared-library extension, unless it contains an
+explicit directory name.
If the option @code{load-prefer-newer} is non-@code{nil}, then when
searching suffixes, @code{load} selects whichever version of a file
@code{load} and @code{eval-region} to use instead of @code{read}.
The function should accept one argument, just as @code{read} does.
-Normally, the variable's value is @code{nil}, which means those
-functions should use @code{read}.
+By default, this variable's value is @code{read}. @xref{Input
+Functions}.
Instead of using this variable, it is cleaner to use another, newer
feature: to pass the function as the @var{read-function} argument to
the function or macro (@pxref{Documentation Basics}).
There are two ways to set up an autoloaded function: by calling
-@code{autoload}, and by writing a special ``magic'' comment in the
+@code{autoload}, and by writing a ``magic'' comment in the
source before the real definition. @code{autoload} is the low-level
primitive for autoloading; any Lisp program can call @code{autoload} at
any time. Magic comments are the most convenient way to make a function
@defvar generated-autoload-file
The value of this variable names an Emacs Lisp file where the autoload
calls should go. The default value is @file{loaddefs.el}, but you can
-override that, e.g., in the ``Local Variables'' section of a
+override that, e.g., in the local variables section of a
@file{.el} file (@pxref{File Local Variables}). The autoload file is
assumed to contain a trailer starting with a formfeed character.
@end defvar
The feature @var{feature} was required.
@item (provide . @var{feature})
The feature @var{feature} was provided.
+@item (cl-defmethod @var{method} @var{specializers})
+The named @var{method} was defined by using @code{cl-defmethod}, with
+@var{specializers} as its specializers.
+@item (define-type . @var{type})
+The type @var{type} was defined.
@end table
The value of @code{load-history} may have one element whose @sc{car} is
@end defmac
Normally, well-designed Lisp programs should not use
-@code{eval-after-load}. If you need to examine and set the variables
-defined in another library (those meant for outside use), you can do
-it immediately---there is no need to wait until the library is loaded.
-If you need to call functions defined by that library, you should load
-the library, preferably with @code{require} (@pxref{Named Features}).
+@code{with-eval-after-load}. If you need to examine and set the
+variables defined in another library (those meant for outside use),
+you can do it immediately---there is no need to wait until the library
+is loaded. If you need to call functions defined by that library, you
+should load the library, preferably with @code{require} (@pxref{Named
+Features}).
+
+@node Dynamic Modules
+@section Emacs Dynamic Modules
+@cindex dynamic modules
+
+@c FIXME: This is intentionally incomplete, as the module integration
+@c is not yet finished. To be refined later.
+ A @dfn{dynamic Emacs module} is a shared library that provides
+additional functionality for use in Emacs Lisp programs, just like a
+package written in Emacs Lisp would.
+
+ Functions that load Emacs Lisp packages can also load dynamic
+modules. They recognize dynamic modules by looking at their file-name
+extension, a.k.a.@: ``suffix''. This suffix is platform-dependent.
+
+@defvar module-file-suffix
+This variable holds the system-dependent value of the file-name
+extension of the module files. Its value is @file{.so} on Posix hosts
+and @file{.dll} on MS-Windows.
+@end defvar
+
+@findex emacs_module_init
+@vindex plugin_is_GPL_compatible
+Every dynamic module should export a C-callable function named
+@code{emacs_module_init}, which Emacs will call as part of the call to
+@code{load} or @code{require} which loads the module. It should also
+export a symbol named @code{plugin_is_GPL_compatible} to indicate that
+its code is released under the GPL or compatible license; Emacs will
+refuse to load modules that don't export such a symbol.
+
+If a module needs to call Emacs functions, it should do so through the
+API defined and documented in the header file @file{emacs-module.h}
+that is part of the Emacs distribution.
+
+@cindex user-ptr object
+Modules can create @code{user-ptr} Lisp objects that embed pointers to
+C struct's defined by the module. This is useful for keeping around
+complex data structures created by a module, to be passed back to the
+module's functions. User-ptr objects can also have associated
+@dfn{finalizers} -- functions to be run when the object is GC'ed; this
+is useful for freeing any resources allocated for the underlying data
+structure, such as memory, open file descriptors, etc.
+
+@defun user-ptrp object
+This function returns @code{t} if its argument is a @code{user-ptr}
+object.
+@end defun
+
+Loadable modules in Emacs are enabled by using the
+@kbd{--with-modules} option at configure time.