GNU Info

(elisp)How Programs Do Loading

---

Next: Library Search Up: Loading

---

Enter node , (file) or (file)node

How Programs Do Loading
=======================

   Emacs Lisp has several interfaces for loading.  For example,
`autoload' creates a placeholder object for a function defined in a
file; trying to call the autoloading function loads the file to get the
function's real definition (Note: Autoload).  `require' loads a file
if it isn't already loaded (Note: Named Features).  Ultimately, all
these facilities call the `load' function to do the work.

 - Function: load filename &optional missing-ok nomessage nosuffix
          must-suffix
     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.  By specifying the precise file
     name and using `t' for NOSUFFIX, you can prevent perverse file
     names such as `foo.el.el' from being tried.

     If the optional argument MUST-SUFFIX is non-`nil', then `load'
     insists that the file name used must end in either `.el' or
     `.elc', unless it contains an explicit directory name.  If
     FILENAME does not contain an explicit directory name, and does not
     end in a suffix, then `load' insists on adding one.

     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.  Note: Library Search.

     If you get a warning that `foo.elc' is older than `foo.el', it
     means you should consider recompiling `foo.el'.  Note: Byte
     Compilation.

     When loading a source file (not compiled), `load' performs
     character set translation just as Emacs would do when visiting the
     file.  Note: Coding Systems.

     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.

 - Command: load-file filename
     This command loads the file FILENAME.  If FILENAME is a relative
     file name, then the current default directory is assumed.
     `load-path' is not used, and suffixes are not appended.  Use this
     command if you wish to specify precisely the file name to load.

 - Command: load-library library
     This command loads the library named LIBRARY.  It is equivalent to
     `load', except in how it reads its argument interactively.

 - Variable: load-in-progress
     This variable is non-`nil' if Emacs is in the process of loading a
     file, and it is `nil' otherwise.

 - Variable: load-read-function
     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'.

     *Note:* Instead of using this variable, it is cleaner to use
     another, newer feature: to pass the function as the READ-FUNCTION
     argument to `eval-region'.  Note: Eval.

   For information about how `load' is used in building Emacs, see
Note: Building Emacs.