(emacs)Lisp Libraries


Next: Lisp Interaction Prev: Executing Lisp Up: Building

Libraries of Lisp Code for Emacs
================================

   Lisp code for Emacs editing commands is stored in files whose names
conventionally end in `.el'.  This ending tells Emacs to edit them in
Emacs-Lisp mode (Note: Executing Lisp.).

   To execute a file of Emacs Lisp code, use `M-x load-file'.  This
command reads a file name using the minibuffer and then executes the
contents of that file as Lisp code.  It is not necessary to visit the
file first; in any case, this command reads the file as found on disk,
not text in an Emacs buffer.

   Once a file of Lisp code is installed in the Emacs Lisp library
directories, users can load it using `M-x load-library'.  Programs can
load it by calling `load-library', or with `load', a more primitive
function that is similar but accepts some additional arguments.

   `M-x load-library' differs from `M-x load-file' in that it searches
a sequence of directories and tries three file names in each directory.
Suppose your argument is LIB; the three names are `LIB.elc', `LIB.el',
and lastly just `LIB'.  If `LIB.elc' exists, it is by convention the
result of compiling `LIB.el'; it is better to load the compiled file,
since it will load and run faster.

   If `load-library' finds that `LIB.el' is newer than `LIB.elc' file,
it prints a warning, because it's likely that somebody made changes to
the `.el' file and forgot to recompile it.

   Because the argument to `load-library' is usually not in itself a
valid file name, file name completion is not available.  Indeed, when
using this command, you usually do not know exactly what file name will
be used.

   The sequence of directories searched by `M-x load-library' is
specified by the variable `load-path', a list of strings that are
directory names.  The default value of the list contains the directory
where the Lisp code for Emacs itself is stored.  If you have libraries
of your own, put them in a single directory and add that directory to
`load-path'.  `nil' in this list stands for the current default
directory, but it is probably not a good idea to put `nil' in the list.
If you find yourself wishing that `nil' were in the list, most likely
what you really want to do is use `M-x load-file' this once.

   Often you do not have to give any command to load a library, because
the commands defined in the library are set up to "autoload" that
library.  Running any of those commands causes `load' to be called to
load the library; this replaces the autoload definitions with the real
ones from the library.

   If autoloading a file does not finish, either because of an error or
because of a `C-g' quit, all function definitions made by the file are
undone automatically.  So are any calls to `provide'.  As a consequence,
if you use one of the autoloadable commands again, the entire file will
be loaded a second time.  This prevents problems where the command is no
longer autoloading but it works wrong because not all the file was
loaded.  Function definitions are undone only for autoloading; explicit
calls to `load' do not undo anything if loading is not completed.

   Emacs Lisp code can be compiled into byte-code which loads faster,
takes up less space when loaded, and executes faster.  Note: Byte
Compilation.

   By convention, the compiled code for a library goes in a separate
file whose name consists of the library source file with `c' appended.
Thus, the compiled code for `foo.el' goes in `foo.elc'.  That's why
`load-library' searches for `.elc' files first.


automatically generated by info2www