@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-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.
+ 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
@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
+(@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} 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
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
@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}.
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 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
-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}).
-
-@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:
+@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
-@example
-(@var{regexp-or-feature} @var{forms}@dots{})
-@end example
+@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
-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.
-@end defvar
+Loadable modules in Emacs are enabled by using the
+@kbd{--with-modules} option at configure time.