[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Loading a file of Lisp code means bringing its contents into the Lisp environment in the form of Lisp objects. XEmacs finds and opens the file, reads the text, evaluates each form, and then closes the file.
The load functions evaluate all the expressions in a file just
as the eval-current-buffer
function evaluates all the
expressions in a buffer. The difference is that the load functions
read and evaluate the text in the file as found on disk, not the text
in an Emacs buffer.
The loaded file must contain Lisp expressions, either as source code or as byte-compiled code. Each form in the file is called a top-level form. There is no special format for the forms in a loadable file; any form in a file may equally well be typed directly into a buffer and evaluated there. (Indeed, most code is tested this way.) Most often, the forms are function definitions and variable definitions.
A file containing Lisp code is often called a library. Thus, the “Rmail library” is a file containing code for Rmail mode. Similarly, a “Lisp library directory” is a directory of files containing Lisp code.
20.1 How Programs Do Loading | The load function and others.
| |
20.2 Autoload | Setting up a function to autoload. | |
20.3 Repeated Loading | Precautions about loading a file twice. | |
20.4 Features | Loading a library if it isn’t already loaded. | |
20.5 Unloading | How to “unload” a library that was loaded. | |
20.6 Hooks for Loading | Providing code to be run when particular libraries are loaded. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
XEmacs Lisp has several interfaces for loading. For example,
autoload
creates a placeholder object for a function in a file;
trying to call the autoloading function loads the file to get the
function’s real definition (see section Autoload). require
loads a
file if it isn’t already loaded (see section Features). Ultimately, all
these facilities call the load
function to do the work.
This function finds and opens a file of Lisp code, evaluates all the forms in it, and closes the file.
To find the file, load
first looks for a file named
‘filename.elc’, that is, for a file whose name is
filename with ‘.elc’ appended. If such a file exists, it is
loaded. If there is no file by that name, then load
looks for a
file named ‘filename.el’. If that file exists, it is loaded.
Finally, if neither of those names is found, load
looks for a
file named filename with nothing appended, and loads it if it
exists. (The load
function is not clever about looking at
filename. In the perverse case of a file named ‘foo.el.el’,
evaluation of (load "foo.el")
will indeed find it.)
If the optional argument nosuffix is non-nil
, then the
suffixes ‘.elc’ and ‘.el’ are not tried. In this case, you
must specify the precise file name you want.
If filename is a relative file name, such as ‘foo’ or
‘baz/foo.bar’, load
searches for the file using the variable
load-path
. It appends filename to each of the directories
listed in load-path
, and loads the first file it finds whose name
matches. The current default directory is tried only if it is specified
in load-path
, where nil
stands for the default directory.
load
tries all three possible suffixes in the first directory in
load-path
, then all three suffixes in the second directory, and
so on.
If you get a warning that ‘foo.elc’ is older than ‘foo.el’, it means you should consider recompiling ‘foo.el’. See section Byte Compilation.
Messages like ‘Loading foo...’ and ‘Loading foo...done’ appear
in the echo area during loading unless nomessage is
non-nil
.
Any unhandled errors while loading a file terminate loading. If the
load was done for the sake of autoload
, any function definitions
made during the loading are undone.
If load
can’t find the file to load, then normally it signals the
error file-error
(with ‘Cannot open load file
filename’). But if missing-ok is non-nil
, then
load
just returns nil
.
You can use the variable load-read-function
to specify a function
for load
to use instead of read
for reading expressions.
See below.
load
returns t
if the file loads successfully.
The value of this variable is a list of directories to search when
loading files with load
. Each element is a string (which must be
a directory name) or nil
(which stands for the current working
directory). The value of load-path
is initialized from the
environment variable EMACSLOADPATH
, if that exists; otherwise its
default value is specified in ‘emacs/src/paths.h’ when XEmacs is
built.
The syntax of EMACSLOADPATH
is the same as used for PATH
;
‘:’ (or ‘;’, according to the operating system) separates
directory names, and ‘.’ is used for the current default directory.
Here is an example of how to set your EMACSLOADPATH
variable from
a csh
‘.login’ file:
setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp |
Here is how to set it using sh
:
export EMACSLOADPATH EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp |
Here is an example of code you can place in a ‘.emacs’ file to add
several directories to the front of your default load-path
:
(setq load-path (append (list nil "/user/bil/emacs" "/usr/local/lisplib" "~/emacs") load-path)) |
In this example, the path searches the current working directory first, followed then by the ‘/user/bil/emacs’ directory, the ‘/usr/local/lisplib’ directory, and the ‘~/emacs’ directory, which are then followed by the standard directories for Lisp code.
The command line options ‘-l’ or ‘-load’ specify a Lisp
library to load as part of Emacs startup. Since this file might be in
the current directory, Emacs 18 temporarily adds the current directory
to the front of load-path
so the file can be found there. Newer
Emacs versions also find such files in the current directory, but
without altering load-path
.
Dumping Emacs uses a special value of load-path
. If the value of
load-path
at the end of dumping is unchanged (that is, still the
same special value), the dumped Emacs switches to the ordinary
load-path
value when it starts up, as described above. But if
load-path
has any other value at the end of dumping, that value
is used for execution of the dumped Emacs also.
Therefore, if you want to change load-path
temporarily for
loading a few libraries in ‘site-init.el’ or ‘site-load.el’,
you should bind load-path
locally with let
around the
calls to load
.
This function searches for a file in the same way that load
does,
and returns the file found (if any). (In fact, load
uses this
function to search through load-path
.) It searches for
filename through path-list, expanded by one of the optional
suffixes (string of suffixes separated by ‘:’s), checking for
access mode (0|1|2|4 = exists|executable|writable|readable),
default readable.
locate-file
keeps hash tables of the directories it searches
through, in order to speed things up. It tries valiantly to not get
confused in the face of a changing and unpredictable environment, but
can occasionally get tripped up. In this case, you will have to call
locate-file-clear-hashing
to get it back on track. See that
function for details.
This function clears the hash records for the specified list of
directories. locate-file
uses a hashing scheme to speed lookup, and
will correctly track the following environmental changes:
locate-file
will primarily get confused if you add a file that
shadows (i.e. has the same name as) another file further down in the
directory list. In this case, you must call
locate-file-clear-hashing
.
This variable is non-nil
if Emacs is in the process of loading a
file, and it is nil
otherwise.
This variable specifies an alternate expression-reading function for
load
and eval-region
to use instead of read
.
The function should accept one argument, just as read
does.
Normally, the variable’s value is nil
, which means those
functions should use read
.
This variable specifies whether load
should check whether the
source is newer than the binary. If this variable is true, then when a
‘.elc’ file is being loaded and the corresponding ‘.el’ is
newer, a warning message will be printed. The default is nil
,
but it is bound to t
during the initial loadup.
This variable specifies whether load
should warn when loading a
‘.el’ file instead of an ‘.elc’. If this variable is true,
then when load
is called with a filename without an extension,
and the ‘.elc’ version doesn’t exist but the ‘.el’ version
does, then a message will be printed. If an explicit extension is
passed to load
, no warning will be printed. The default is
nil
, but it is bound to t
during the initial loadup.
This variable specifies whether load
should ignore ‘.elc’
files when a suffix is not given. This is normally used only to
bootstrap the ‘.elc’ files when building XEmacs, when you use the
command ‘make all-elc’. (This forces the ‘.el’ versions to be
loaded in the process of compiling those same files, so that existing
out-of-date ‘.elc’ files do not make it mess things up.)
To learn how load
is used to build XEmacs, see Building XEmacs.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The autoload facility allows you to make a function or macro known in Lisp, but put off loading the file that defines it. The first call to the function automatically reads the proper file to install the real definition and other associated code, then runs the real definition as if it had been loaded all along.
There are two ways to set up an autoloaded function: by calling
autoload
, and by writing a special “magic” comment in the
source before the real definition. autoload
is the low-level
primitive for autoloading; any Lisp program can call autoload
at
any time. Magic comments do nothing on their own; they serve as a guide
for the command update-file-autoloads
, which constructs calls to
autoload
and arranges to execute them when Emacs is built. Magic
comments are the most convenient way to make a function autoload, but
only for packages installed along with Emacs.
This function defines the function (or macro) named function so as to load automatically from filename. The string filename specifies the file to load to get the real definition of function.
The argument docstring is the documentation string for the
function. Normally, this is identical to the documentation string in
the function definition itself. Specifying the documentation string in
the call to autoload
makes it possible to look at the
documentation without loading the function’s real definition.
If interactive is non-nil
, then the function can be called
interactively. This lets completion in M-x work without loading
the function’s real definition. The complete interactive specification
need not be given here; it’s not needed unless the user actually calls
function, and when that happens, it’s time to load the real
definition.
You can autoload macros and keymaps as well as ordinary functions.
Specify type as macro
if function is really a macro.
Specify type as keymap
if function is really a keymap.
Various parts of Emacs need to know this information without loading the
real definition.
An autoloaded keymap loads automatically during key lookup when a prefix
key’s binding is the symbol function. Autoloading does not occur
for other kinds of access to the keymap. In particular, it does not
happen when a Lisp program gets the keymap from the value of a variable
and calls define-key
; not even if the variable name is the same
symbol function.
If function already has a non-void function definition that is not
an autoload object, autoload
does nothing and returns nil
.
If the function cell of function is void, or is already an autoload
object, then it is defined as an autoload object like this:
(autoload filename docstring interactive type) |
For example,
(symbol-function 'run-prolog) ⇒ (autoload "prolog" 169681 t nil) |
In this case, "prolog"
is the name of the file to load, 169681
refers to the documentation string in the ‘DOC’ file
(see section Documentation Basics), t
means the function is
interactive, and nil
that it is not a macro or a keymap.
The autoloaded file usually contains other definitions and may require
or provide one or more features. If the file is not completely loaded
(due to an error in the evaluation of its contents), any function
definitions or provide
calls that occurred during the load are
undone. This is to ensure that the next attempt to call any function
autoloading from this file will try again to load the file. If not for
this, then some of the functions in the file might appear defined, but
they might fail to work properly for the lack of certain subroutines
defined later in the file and not loaded successfully.
XEmacs as distributed comes with many autoloaded functions.
The calls to autoload
are in the file ‘loaddefs.el’.
There is a convenient way of updating them automatically.
If the autoloaded file fails to define the desired Lisp function or
macro, then an error is signaled with data "Autoloading failed to
define function function-name"
.
A magic autoload comment looks like ‘;;;###autoload’, on a line
by itself, just before the real definition of the function in its
autoloadable source file. The command M-x update-file-autoloads
writes a corresponding autoload
call into ‘loaddefs.el’.
Building Emacs loads ‘loaddefs.el’ and thus calls autoload
.
M-x update-directory-autoloads is even more powerful; it updates
autoloads for all files in the current directory.
The same magic comment can copy any kind of form into
‘loaddefs.el’. If the form following the magic comment is not a
function definition, it is copied verbatim. You can also use a magic
comment to execute a form at build time without executing it when
the file itself is loaded. To do this, write the form on the same
line as the magic comment. Since it is in a comment, it does nothing
when you load the source file; but update-file-autoloads
copies
it to ‘loaddefs.el’, where it is executed while building Emacs.
The following example shows how doctor
is prepared for
autoloading with a magic comment:
;;;###autoload (defun doctor () "Switch to *doctor* buffer and start giving psychotherapy." (interactive) (switch-to-buffer "*doctor*") (doctor-mode)) |
Here’s what that produces in ‘loaddefs.el’:
(autoload 'doctor "doctor" "\ Switch to *doctor* buffer and start giving psychotherapy." t) |
The backslash and newline immediately following the double-quote are a
convention used only in the preloaded Lisp files such as
‘loaddefs.el’; they tell make-docfile
to put the
documentation string in the ‘DOC’ file. See section Building XEmacs.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You may load one file more than once in an Emacs session. For example, after you have rewritten and reinstalled a function definition by editing it in a buffer, you may wish to return to the original version; you can do this by reloading the file it came from.
When you load or reload files, bear in mind that the load
and
load-library
functions automatically load a byte-compiled file
rather than a non-compiled file of similar name. If you rewrite a file
that you intend to save and reinstall, remember to byte-compile it if
necessary; otherwise you may find yourself inadvertently reloading the
older, byte-compiled file instead of your newer, non-compiled file!
When writing the forms in a Lisp library file, keep in mind that the
file might be loaded more than once. For example, the choice of
defvar
vs. defconst
for defining a variable depends on
whether it is desirable to reinitialize the variable if the library is
reloaded: defconst
does so, and defvar
does not.
(See section Defining Global Variables.)
The simplest way to add an element to an alist is like this:
(setq minor-mode-alist (cons '(leif-mode " Leif") minor-mode-alist)) |
But this would add multiple elements if the library is reloaded. To avoid the problem, write this:
(or (assq 'leif-mode minor-mode-alist) (setq minor-mode-alist (cons '(leif-mode " Leif") minor-mode-alist))) |
To add an element to a list just once, use add-to-list
(see section How to Alter a Variable Value).
Occasionally you will want to test explicitly whether a library has already been loaded. Here’s one way to test, in a library, whether it has been loaded before:
(defvar foo-was-loaded) (if (not (boundp 'foo-was-loaded)) execute-first-time-only) (setq foo-was-loaded t) |
If the library uses provide
to provide a named feature, you can
use featurep
to test whether the library has been loaded.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
provide
and require
are an alternative to
autoload
for loading files automatically. They work in terms of
named features. Autoloading is triggered by calling a specific
function, but a feature is loaded the first time another program asks
for it by name.
A feature name is a symbol that stands for a collection of functions, variables, etc. The file that defines them should provide the feature. Another program that uses them may ensure they are defined by requiring the feature. This loads the file of definitions if it hasn’t been loaded already.
To require the presence of a feature, call require
with the
feature name as argument. require
looks in the global variable
features
to see whether the desired feature has been provided
already. If not, it loads the feature from the appropriate file. This
file should call provide
at the top level to add the feature to
features
; if it fails to do so, require
signals an error.
Features are normally named after the files that provide them, so that
require
need not be given the file name.
For example, in ‘emacs/lisp/prolog.el’,
the definition for run-prolog
includes the following code:
(defun run-prolog () "Run an inferior Prolog process, input and output via buffer *prolog*." (interactive) (require 'comint) (switch-to-buffer (make-comint "prolog" prolog-program-name)) (inferior-prolog-mode)) |
The expression (require 'comint)
loads the file ‘comint.el’
if it has not yet been loaded. This ensures that make-comint
is
defined.
The ‘comint.el’ file contains the following top-level expression:
(provide 'comint) |
This adds comint
to the global features
list, so that
(require 'comint)
will henceforth know that nothing needs to be
done.
When require
is used at top level in a file, it takes effect
when you byte-compile that file (see section Byte Compilation) as well as
when you load it. This is in case the required package contains macros
that the byte compiler must know about.
Although top-level calls to require
are evaluated during
byte compilation, provide
calls are not. Therefore, you can
ensure that a file of definitions is loaded before it is byte-compiled
by including a provide
followed by a require
for the same
feature, as in the following example.
(provide 'my-feature) ; Ignored by byte compiler,
; evaluated by |
The compiler ignores the provide
, then processes the
require
by loading the file in question. Loading the file does
execute the provide
call, so the subsequent require
call
does nothing while loading.
This function announces that feature is now loaded, or being loaded, into the current XEmacs session. This means that the facilities associated with feature are or will be available for other Lisp programs.
The direct effect of calling provide
is to add feature to
the front of the list features
if it is not already in the list.
The argument feature must be a symbol. provide
returns
feature.
features ⇒ (bar bish) (provide 'foo) ⇒ foo features ⇒ (foo bar bish) |
When a file is loaded to satisfy an autoload, and it stops due to an
error in the evaluating its contents, any function definitions or
provide
calls that occurred during the load are undone.
See section Autoload.
This function checks whether feature is present in the current
XEmacs session (using (featurep feature)
; see below). If it
is not, then require
loads filename with load
. If
filename is not supplied, then the name of the symbol
feature is used as the file name to load.
If loading the file fails to provide feature, require
signals an error, ‘Required feature feature was not
provided’.
This function returns t
if feature fexp is present in this
Emacs. Use this to conditionalize execution of lisp code based on the
presence or absence of emacs or environment extensions.
fexp can be a symbol, a number, or a list.
If fexp is a symbol, it is looked up in the features
variable,
and t
is returned if it is found, nil
otherwise.
If fexp is a number, the function returns t
if this Emacs
has an equal or greater number than fexp, nil
otherwise.
Note that minor Emacs version is expected to be 2 decimal places wide,
so (featurep 20.4)
will return nil
on XEmacs 20.4—you
must write (featurep 20.04)
, unless you wish to match for XEmacs
20.40.
If fexp is a list whose car is the symbol and
, the function
returns t
if all the features in its cdr are present, nil
otherwise.
If fexp is a list whose car is the symbol or
, the function
returns t
if any the features in its cdr are present, nil
otherwise.
If fexp is a list whose car is the symbol not
, the function
returns t
if the feature is not present, nil
otherwise.
Examples:
(featurep 'xemacs) ⇒ ; t on XEmacs. (featurep '(and xemacs gnus)) ⇒ ; t on XEmacs with Gnus loaded. (featurep '(or tty-frames (and emacs 19.30))) ⇒ ; t if this Emacs supports TTY frames. (featurep '(or (and xemacs 19.15) (and emacs 19.34))) ⇒ ; t on XEmacs 19.15 and later, or on ; FSF Emacs 19.34 and later. |
Please note: The advanced arguments of this function (anything other than a symbol) are not yet supported by FSF Emacs. If you feel they are useful for supporting multiple Emacs variants, lobby Richard Stallman at ‘<bug-gnu-emacs@prep.ai.mit.edu>’.
The value of this variable is a list of symbols that are the features
loaded in the current XEmacs session. Each symbol was put in this list
with a call to provide
. The order of the elements in the
features
list is not significant.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can discard the functions and variables loaded by a library to
reclaim memory for other Lisp objects. To do this, use the function
unload-feature
:
This command unloads the library that provided feature feature.
It undefines all functions, macros, and variables defined in that
library with defconst
, defvar
, defun
,
defmacro
, defsubst
, define-function
and
defalias
. It then restores any autoloads formerly associated
with those symbols. (Loading saves these in the autoload
property of the symbol.)
Ordinarily, unload-feature
refuses to unload a library on which
other loaded libraries depend. (A library a depends on library
b if a contains a require
for b.) If the
optional argument force is non-nil
, dependencies are
ignored and you can unload any library.
The unload-feature
function is written in Lisp; its actions are
based on the variable load-history
.
This variable’s value is an alist connecting library names with the names of functions and variables they define, the features they provide, and the features they require.
Each element is a list and describes one library. The CAR of the list is the name of the library, as a string. The rest of the list is composed of these kinds of objects:
(require . feature)
indicating
features that were required.
(provide . feature)
indicating
features that were provided.
The value of load-history
may have one element whose CAR is
nil
. This element describes definitions made with
eval-buffer
on a buffer that is not visiting a file.
The command eval-region
updates load-history
, but does so
by adding the symbols defined to the element for the file being visited,
rather than replacing that element.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.