lispref.info: How Programs Do Loading

Loading

Autoload

Back to Software Index

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

   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 (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
     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'.  Note: 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.

 - 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 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'.

 - Function: locate-file FILENAME PATH-LIST &optional SUFFIXES MODE
     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|writeable|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.

 - Function: locate-file-clear-hashing PATH
     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:

        * changes of any sort to the list of directories to be searched.

        * addition and deletion of non-shadowing files (see below) from
          the directories in the list.

        * byte-compilation of a .el file into a .elc file.

     `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'.

 - 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'.

 - User Option: load-warn-when-source-newer
     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.

 - User Option: load-warn-when-source-only
     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.

 - User Option: load-ignore-elc-files
     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 Note: Building
XEmacs.