@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 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.
+ 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.
* Load Suffixes:: Details about the suffixes that @code{load} tries.
* 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
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
@samp{.el} or @samp{.elc} (possibly extended with a compression
suffix), 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
+(@samp{.elc}, @samp{.el}, etc.)@: has been modified most recently.
+
If @var{filename} is a relative file name, such as @file{foo} or
@file{baz/foo.bar}, @code{load} searches for the file using the variable
@code{load-path}. It appends @var{filename} to each of the directories
it skips the former group, and if @var{must-suffix} is non-@code{nil},
it skips the latter group.
+@defopt load-prefer-newer
+If this option is non-@code{nil}, then rather than stopping at the
+first suffix that exists, @code{load} tests them all, and uses
+whichever file is the newest.
+@end defopt
+
@node Library Search
@section Library Search
@cindex library search
in a list of directories specified by the variable @code{load-path}.
@defvar load-path
-@cindex @env{EMACSLOADPATH} environment variable
The value of this variable is a list of directories to search when
loading files with @code{load}. Each element is a string (which must be
a directory name) or @code{nil} (which stands for the current working
directory).
@end defvar
- Each time Emacs starts up, it sets up the value of @code{load-path}
-in several steps. First, it initializes @code{load-path} to the
-directories specified by the environment variable @env{EMACSLOADPATH},
-if that exists. The syntax of @env{EMACSLOADPATH} is the same as used
-for @code{PATH}; directory names are separated by @samp{:} (or
-@samp{;}, on some operating systems), and @samp{.} stands for the
-current default directory. Here is an example of how to set
-@env{EMACSLOADPATH} variable from @command{sh}:
+ When Emacs starts up, it sets up the value of @code{load-path}
+in several steps. First, it initializes @code{load-path} using
+default locations set when Emacs was compiled. Normally, this
+is a directory something like
@example
-export EMACSLOADPATH
-EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
+"/usr/local/share/emacs/@var{version}/lisp"
@end example
-@noindent
-Here is how to set it from @code{csh}:
-
-@example
-setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
-@end example
+(In this and the following examples, replace @file{/usr/local} with
+the installation prefix appropriate for your Emacs.)
+These directories contain the standard Lisp files that come with
+Emacs. If Emacs cannot find them, it will not start correctly.
+
+If you run Emacs from the directory where it was built---that is, an
+executable that has not been formally installed---Emacs instead
+initializes @code{load-path} using the @file{lisp}
+directory in the directory containing the sources from which it
+was built.
+@c Though there should be no *.el files in builddir/lisp, so it's pointless.
+If you built Emacs in a separate directory from the
+sources, it also adds the lisp directories from the build directory.
+(In all cases, elements are represented as absolute file names.)
@cindex site-lisp directories
- If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs
-initializes @code{load-path} with the following two directories:
+Unless you start Emacs with the @option{--no-site-lisp} option,
+it then adds two more @file{site-lisp} directories to the front of
+@code{load-path}. These are intended for locally installed Lisp files,
+and are normally of the form:
@example
"/usr/local/share/emacs/@var{version}/site-lisp"
@end example
@noindent
-The first one is for locally installed packages for a particular Emacs
-version; the second is for locally installed packages meant for use
-with all installed Emacs versions.
-
- If you run Emacs from the directory where it was built---that is, an
-executable that has not been formally installed---Emacs puts two more
-directories in @code{load-path}. These are the @code{lisp} and
-@code{site-lisp} subdirectories of the main build directory. (Both
-are represented as absolute file names.)
-
- Next, Emacs ``expands'' the initial list of directories in
-@code{load-path} by adding the subdirectories of those directories.
-Both immediate subdirectories and subdirectories multiple levels down
-are added. But it excludes subdirectories whose names do not start
-with a letter or digit, and subdirectories named @file{RCS} or
-@file{CVS}, and subdirectories containing a file named
-@file{.nosearch}.
-
- Next, Emacs adds any extra load directory that you specify using the
-@samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The
+The first one is for locally installed files for a specific Emacs
+version; the second is for locally installed files meant for use
+with all installed Emacs versions. (If Emacs is running uninstalled,
+it also adds @file{site-lisp} directories from the source and build
+directories, if they exist. Normally these directories do not contain
+@file{site-lisp} directories.)
+
+@cindex @env{EMACSLOADPATH} environment variable
+If the environment variable @env{EMACSLOADPATH} is set, it modifies
+the above initialization procedure. Emacs initializes
+@code{load-path} based on the value of the environment variable.
+
+The syntax of @env{EMACSLOADPATH} is the same as used for @code{PATH};
+directory names are separated by @samp{:} (or @samp{;}, on some
+operating systems).
+@ignore
+@c AFAICS, does not (yet) work right to specify non-absolute elements.
+and @samp{.} stands for the current default directory.
+@end ignore
+Here is an example of how to set @env{EMACSLOADPATH} variable (from a
+@command{sh}-style shell):
+
+@example
+export EMACSLOADPATH=/home/foo/.emacs.d/lisp:
+@end example
+
+An empty element in the value of the environment variable, whether
+trailing (as in the above example), leading, or embedded, is replaced
+by the default value of @code{load-path} as determined by the standard
+initialization procedure. If there are no such empty elements, then
+@env{EMACSLOADPATH} specifies the entire @code{load-path}. You must
+include either an empty element, or the explicit path to the directory
+containing the standard Lisp files, else Emacs will not function.
+(Another way to modify @code{load-path} is to use the @option{-L}
+command-line option when starting Emacs; see below.)
+
+ For each directory in @code{load-path}, Emacs then checks to see if
+it contains a file @file{subdirs.el}, and if so, loads it. The
+@file{subdirs.el} file is created when Emacs is built/installed,
+and contains code that causes Emacs to add any subdirectories of those
+directories to @code{load-path}. Both immediate subdirectories and
+subdirectories multiple levels down are added. But it excludes
+subdirectories whose names do not start with a letter or digit, and
+subdirectories named @file{RCS} or @file{CVS}, and subdirectories
+containing a file named @file{.nosearch}.
+
+ Next, Emacs adds any extra load directories that you specify using the
+@option{-L} command-line option (@pxref{Action Arguments,,,emacs, The
GNU Emacs Manual}). It also adds the directories where optional
packages are installed, if any (@pxref{Packaging Basics}).
(push "~/.emacs.d/lisp" load-path)
@end example
- Dumping Emacs uses a special value of @code{load-path}. If the
-value of @code{load-path} at the end of dumping is unchanged (that is,
-still the same special value), the dumped Emacs switches to the
-ordinary @code{load-path} value when it starts up, as described above.
-But if @code{load-path} has any other value at the end of dumping,
-that value is used for execution of the dumped Emacs also.
+ Dumping Emacs uses a special value of @code{load-path}. If you use
+a @file{site-load.el} or @file{site-init.el} file to customize the
+dumped Emacs (@pxref{Building Emacs}), any changes to @code{load-path}
+that these files make will be lost after dumping.
@deffn Command locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library @var{library}. It
@node Loading Non-ASCII
@section Loading Non-@acronym{ASCII} Characters
+@cindex loading, and non-ASCII characters
+@cindex non-ASCII characters in loaded files
When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
characters, these can be represented within Emacs either as unibyte
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
symbol @var{function}.
@cindex function cell in autoload
-if @var{function} already has non-void function definition that is not
+If @var{function} already has a non-void function definition that is not
an autoload object, this function does nothing and returns @code{nil}.
Otherwise, it constructs an autoload object (@pxref{Autoload Type}),
and stores it as the function definition for @var{function}. The
@noindent
In this case, @code{"prolog"} is the name of the file to load, 169681
refers to the documentation string in the
-@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
+@file{emacs/etc/DOC} file (@pxref{Documentation Basics}),
@code{t} means the function is interactive, and @code{nil} that it is
not a macro or a keymap.
@end defun
@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
@node Where Defined
@section Which File Defined a Certain Symbol
+@cindex symbol, where defined
+@cindex where was a symbol defined
@defun symbol-file symbol &optional type
This function returns the name of the file that defined @var{symbol}.
@end defvar
If you want code to be executed when a @emph{particular} library is
-loaded, use the function @code{eval-after-load}:
+loaded, use the macro @code{with-eval-after-load}:
-@defun eval-after-load library form
-This function arranges to evaluate @var{form} at the end of loading
+@defmac with-eval-after-load library body@dots{}
+This macro arranges to evaluate @var{body} at the end of loading
the file @var{library}, each time @var{library} is loaded. If
-@var{library} is already loaded, it evaluates @var{form} right away.
-Don't forget to quote @var{form}!
+@var{library} is already loaded, it evaluates @var{body} right away.
You don't need to give a directory or extension in the file name
@var{library}. Normally, you just give a bare file name, like this:
@example
-(eval-after-load "edebug" '(def-edebug-spec c-point t))
+(with-eval-after-load "edebug" (def-edebug-spec c-point t))
@end example
To restrict which files can trigger the evaluation, include a
@file{my_inst.el}:
@example
-(eval-after-load "foo/bar/my_inst.elc" @dots{})
+(with-eval-after-load "foo/bar/my_inst.elc" @dots{})
@end example
@var{library} can also be a feature (i.e., a symbol), in which case
-@var{form} is evaluated at the end of any file where
+@var{body} is evaluated at the end of any file where
@code{(provide @var{library})} is called.
-An error in @var{form} does not undo the load, but does prevent
-execution of the rest of @var{form}.
-@end defun
+An error in @var{body} does not undo the load, but does prevent
+execution of the rest of @var{body}.
+@end defmac
Normally, well-designed Lisp programs should not use
@code{eval-after-load}. If you need to examine and set the variables
If you need to call functions defined by that library, you should load
the library, preferably with @code{require} (@pxref{Named Features}).
-@defvar after-load-alist
-This variable stores an alist built by @code{eval-after-load},
-containing the expressions to evaluate when certain libraries are
-loaded. Each element looks like this:
+@node Dynamic Modules
+@section Emacs Dynamic Modules
+@cindex dynamic modules
-@example
-(@var{regexp-or-feature} @var{forms}@dots{})
-@end example
+@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.
-The key @var{regexp-or-feature} is either a regular expression or a
-symbol, and the value is a list of forms. The forms are evaluated
-when the key matches the absolute true name or feature name of the
-library being loaded.
+@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.