(lispref.info)How Programs Do Loading


Next: Autoload Up: Loading

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

   There are several interface functions for loading.  For example, the
`autoload' function creates a Lisp object that loads a file when it is
evaluated (Note: Autoload.).  `require' also causes files to be
loaded (Note: Features.).  Ultimately, all these facilities call the
`load' function to do the work.

 - Function: load FILENAME &optional MISSING-OK NOMESSAGE NOSUFFIX
     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 has `.elc'
     appended.  If such a file exists, it is loaded.  But if there is
     no file by that name, then `load' looks for a file whose name has
     `.el' appended.  If that file exists, it is loaded.  Finally, if
     there is no file by either name, `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 it is represented as `nil'.  All
     three possible suffixes are tried in the first directory in
     `load-path', then all three in the second directory in
     `load-path', etc.

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

     Messages like `Loading foo...' and `Loading foo...done' appear in
     the echo area during loading unless NOMESSAGE is non-`nil'.

     Any errors that are encountered while loading a file cause `load'
     to abort.  If the load was done for the sake of `autoload', certain
     kinds of top-level forms, those which define functions, are undone.

     The error `file-error' is signaled (with `Cannot open load file
     FILENAME') if no file is found.  No error is signaled if
     MISSING-OK is non-`nil'--then `load' just returns `nil'.

     `load' returns `t' if the file loads successfully.

 - User Option: load-path
     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 it exists; otherwise it is
     set to the default specified in `emacs/src/paths.h' when Emacs is
     built.

     The syntax of `EMACSLOADPATH' is the same as that of `PATH';
     fields are separated by `:', 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")
                 load-path))

     In this example, the path searches the current working directory
     first, followed then by the `/user/bil/emacs' directory and then by
     the `/usr/local/lisplib' directory, which are then followed by the
     standard directories for Lisp code.

     When Emacs version 18 processes command options `-l' or `-load'
     which specify Lisp libraries to be loaded, it temporarily adds the
     current directory to the front of `load-path' so that files in the
     current directory can be specified easily.  Newer Emacs versions
     also find such files in the current directory, but without
     altering `load-path'.

 - Variable: load-in-progress
     This variable is non-`nil' if Emacs is in the process of loading a
     file, and it is `nil' otherwise.  This is how `defun' and
     `provide' determine whether a load is in progress, so that their
     effect can be undone if the load fails.

   To learn how `load' is used to build Emacs, see Note: Building
Emacs.


automatically generated by info2www