Info Catalog emacs: Executing Lisp emacs: Building emacs: Lisp Eval

emacs: Lisp Libraries

 
 27.8 Libraries of Lisp Code for Emacs
 =====================================
 
 Emacs Lisp code is stored in files whose names conventionally end in
 ‘.el’.  Such files are automatically visited in Emacs Lisp mode.
 
    Emacs Lisp code can be compiled into byte-code, which loads faster,
 takes up less space, and executes faster.  By convention, compiled Emacs
 Lisp code goes in a separate file whose name ends in ‘.elc’.  For
 example, the compiled code for ‘foo.el’ goes in ‘foo.elc’.  Byte
 Compilation (elisp)Byte Compilation.
 
    To “load” an Emacs Lisp file, type ‘M-x load-file’.  This command
 reads a file name using the minibuffer, and executes the contents of
 that file as Emacs Lisp code.  It is not necessary to visit the file
 first; this command reads the file directly from disk, not from an
 existing Emacs buffer.
 
    If an Emacs Lisp file is installed in the Emacs Lisp “load path”
 (defined below), you can load it by typing ‘M-x load-library’, instead
 of using ‘M-x load-file’.  The ‘M-x load-library’ command prompts for a
 “library name” rather than a file name; it searches through each
 directory in the Emacs Lisp load path, trying to find a file matching
 that library name.  If the library name is ‘FOO’, it tries looking for
 files named ‘FOO.elc’, ‘FOO.el’, and ‘FOO’.  The default behavior is to
 load the first file found.  This command prefers ‘.elc’ files over ‘.el’
 files because compiled files load and run faster.  If it finds that
 ‘LIB.el’ is newer than ‘LIB.elc’, it issues a warning, in case someone
 made changes to the ‘.el’ file and forgot to recompile it, but loads the
 ‘.elc’ file anyway.  (Due to this behavior, you can save unfinished
 edits to Emacs Lisp source files, and not recompile until your changes
 are ready for use.)  If you set the option ‘load-prefer-newer’ to a
 non-‘nil’ value, however, then rather than the procedure described
 above, Emacs loads whichever version of the file is newest.
 
    Emacs Lisp programs usually load Emacs Lisp files using the ‘load’
 function.  This is similar to ‘load-library’, but is lower-level and
 accepts additional arguments.  (elisp)How Programs Do Loading.
 
    The Emacs Lisp load path is specified by the variable ‘load-path’.
 Its value should be a list of directory names (strings).  These
 directories are searched, in the specified order, by the ‘M-x
 load-library’ command, the lower-level ‘load’ function, and other Emacs
 functions that find Emacs Lisp libraries.  A list entry in ‘load-path’
 can also have the special value ‘nil’, which stands for the current
 default directory, but it is almost always a bad idea to use this.  (If
 you find yourself wishing that ‘nil’ were in the list, most likely what
 you really want is to use ‘M-x load-file’.)
 
    The default value of ‘load-path’ is a list of directories where the
 Lisp code for Emacs itself is stored.  If you have libraries of your own
 in another directory, you can add that directory to the load path.
 Unlike most other variables described in this manual, ‘load-path’ cannot
 be changed via the Customize interface (Easy Customization), but
 you can add a directory to it by putting a line like this in your init
 file (Init File):
 
      (add-to-list 'load-path "/path/to/my/lisp/library")
 
    Some commands are “autoloaded”; when you run them, Emacs
 automatically loads the associated library first.  For instance, the
 ‘M-x compile’ command (Compilation) is autoloaded; if you call
 it, Emacs automatically loads the ‘compile’ library first.  In contrast,
 the command ‘M-x recompile’ is not autoloaded, so it is unavailable
 until you load the ‘compile’ library.
 
    Automatic loading can also occur when you look up the documentation
 of an autoloaded command (Name Help), if the documentation
 refers to other functions and variables in its library (loading the
 library lets Emacs properly set up the hyperlinks in the ‘*Help*’
 buffer).  To disable this feature, change the variable
 ‘help-enable-auto-load’ to ‘nil’.
 
    By default, Emacs refuses to load compiled Lisp files which were
 compiled with XEmacs, a modified versions of Emacs—they can cause Emacs
 to crash.  Set the variable ‘load-dangerous-libraries’ to ‘t’ if you
 want to try loading them.
 

Info Catalog emacs: Executing Lisp emacs: Building emacs: Lisp Eval