doc/lispref/loading.texi

2 @c This is part of the GNU Emacs Lisp Reference Manual.
12   Loading a file of Lisp code means bringing its contents into the
13 Lisp environment in the form of Lisp objects.  Emacs finds and opens
39 For on-demand loading of external libraries which are known in advance
55 @end menu
68 This function finds and opens a file of Lisp code, evaluates all the
79 system-dependent file-name extension of shared libraries.  Finally, if
80 neither of those names is found, @code{load} looks for a file named
83 In the perverse case of a file named @file{foo.el.el}, evaluation of
88 of the file before trying other file names.  It decompresses and loads
90 of the suffixes in @code{jka-compr-load-suffixes} to the file name.
91 The value of this variable must be a list of strings.  Its standard
104 @code{load} insists that the file name used must end in either
110 searching suffixes, @code{load} selects whichever version of a file
115 @code{load-path}.  It appends @var{filename} to each of the directories
124 directory where Emacs found it, Emacs sets the value of the variable
142 up the execution of uncompiled code.  Sometimes, this macro expansion
144 example of this, the file you are loading refers to a macro defined
148 giving details of the problem, but it still loads the file, just
160 load was done for the sake of @code{autoload}, any function definitions
170 for @code{load} to use instead of @code{read} for reading expressions.
174 @end defun
183 @end deffn
189 @end deffn
192 This variable is non-@code{nil} if Emacs is in the process of loading a
194 @end defvar
197 When Emacs is in the process of loading a file, this variable's value
198 is the name of that file, as Emacs found it during the search
200 @end defvar
203 @anchor{Definition of load-read-function}
206 @code{load} and @code{eval-region} to use instead of @code{read}.
212 Instead of using this variable, it is cleaner to use another, newer
214 @code{eval-region}.  @xref{Definition of eval-region,, Eval}.
215 @end defvar
226 This is a list of suffixes indicating (compiled or source) Emacs Lisp
231 @end defvar
234 This is a list of suffixes that indicate representations of the same
241 Compression mode removes them again.  The standard value of
243 @code{("")}.  Given that the standard value of
245 of @code{load-file-rep-suffixes} if Auto Compression mode is enabled
247 @end defvar
250 This function returns the list of all suffixes that @code{load} should
258 @end defun
261 value of @code{(get-load-suffixes)} and then those in
270 @end defopt
278 in a list of directories specified by the variable @code{load-path}.
281 The value of this variable is a list of directories to search when
285 @end defvar
287   When Emacs starts up, it sets up the value of @code{load-path}
294 @end example
313 it then adds two more @file{site-lisp} directories to the front of
315 and are normally of the form:
319 @end example
326 @end example
339 @code{load-path} based on the value of the environment variable.
341 The syntax of @env{EMACSLOADPATH} is the same as used for @env{PATH};
347 @end ignore
348 Here is an example of how to set @env{EMACSLOADPATH} variable (from a
353 @end example
355 An empty element in the value of the environment variable, whether
357 by the default value of @code{load-path} as determined by the standard
368 and contains code that causes Emacs to add any subdirectories of those
385 @end example
387   Dumping Emacs uses a special value of @code{load-path}.  If you use
399 If the @var{path} is non-@code{nil}, that list of directories is used
400 instead of @code{load-path}.
406 @end deffn
410 This command shows a list of @dfn{shadowed} Emacs Lisp files.  A
412 in a directory on @code{load-path}, due to the existence of another
419 @end example
428 shadowed files, instead of displaying them in a buffer.  If the
431 @end deffn
442 it is read with decoding into multibyte representation, the text of the
445 example) is read without decoding, the text of the program will be
463   The @dfn{autoload} facility lets you register the existence of a
468 Autoloading can also be triggered by looking up the documentation of
470 of variable and function names (@pxref{Autoload by Prefix} below).
475 @end menu
490 specifies the file to load to get the real definition of @var{function}.
494 of these suffixes, and it will not load from a file whose name is just
516 keymap.  Various parts of Emacs need to know this information without
521 for other kinds of access to the keymap.  In particular, it does not
522 happen when a Lisp program gets the keymap from the value of a variable
535 @end example
543 @end group
544 @end example
547 In this case, @code{"prolog"} is the name of the file to load, 169681
552 @end defun
561 @end smallexample
562 @end defun
567 (due to an error in the evaluation of its contents), any function
571 this, then some of the functions in the file might be defined by the
572 aborted load, but fail to work properly for the lack of certain
585 consists of @samp{;;;###autoload}, on a line by itself,
586 just before the real definition of the function in its
589 (The string that serves as the autoload cookie and the name of the
596   The same magic comment can copy any kind of form into
598 verbatim, @emph{except} if it is one of the forms which the autoload
621 @end table
640 @end example
650 @end example
659 in the usage part of the documentation string is replaced with the
664 one of the known and recognized function definition methods, use of an
673 @end example
681 The value of this variable should be a string whose syntax is a Lisp
684 value of this variable is @code{";;;###autoload"}.
685 @end defvar
688 The value of this variable names an Emacs Lisp file where the autoload
690 override that, e.g., in the local variables section of a
693 @end defvar
702 @var{autoload}; in that case, the return value of this function is the
703 symbol's new function value.  If the value of the optional argument
706 @end defun
719 the corresponding list of files to load for it.  Entries to this
741 major-mode for editing Python code, autoload the definition of the
748 library being loaded.  (An example of this might be something like
760 explicit autoload @emph{statement}.
761 @end itemize
774 rather than a non-compiled file of similar name.  If you rewrite a file
777 of your newer, non-compiled file!  If that happens, the message
791 @end example
799 @end example
813 @end example
824 @code{autoload} for loading files automatically.  They work in terms of
829   A feature name is a symbol that stands for a collection of functions,
832 @dfn{requiring} the feature.  This loads the file of definitions if it
836   To require the presence of a feature, call @code{require} with the
843   For example, in @file{idlwave.el}, the definition for
844 @code{idlwave-complete-filename} includes the following code:
847 (defun idlwave-complete-filename ()
854 @end example
862 important that the @code{require} statement be outside the body of the
871 @end example
888 ensure that a file of definitions is loaded before it is byte-compiled
897 @end group
898 @end example
912 The direct effect of calling @code{provide} is to add @var{feature} to
913 the front of @code{features} if it is not already in that list and
918 If provided, @var{subfeatures} should be a list of symbols indicating
919 a set of specific subfeatures provided by this version of
920 @var{feature}.  You can test the presence of a subfeature using
921 @code{featurep}.  The idea of subfeatures is that you use them when a
923 useful to give names to various parts or functionalities of the
936 @end example
939 error in the evaluation of its contents, any function definitions or
942 @end defun
950 with @code{load}.  If @var{filename} is not supplied, then the name of
959 loading of the file.  In that case, @code{require} returns @code{nil}
965 @end defun
969 the current Emacs session (i.e., if @var{feature} is a member of
972 (i.e., if @var{subfeature} is a member of the @code{subfeature}
973 property of the @var{feature} symbol.)
974 @end defun
977 The value of this variable is a list of symbols that are the features
979 with a call to @code{provide}.  The order of the elements in the
981 @end defvar
989 This function returns the name of the file that defined @var{symbol}.
990 If @var{type} is @code{nil}, then any kind of definition is acceptable.
999 @end defun
1005 The value of this variable is an alist that associates the names of
1006 loaded library files with the names of the functions and variables
1011 is the absolute file name of the library (a string).  The rest of the
1037 @end table
1039 The value of @code{load-history} may have one element whose @sc{car} is
1042 @end defvar
1063 (Loading saves these in the @code{autoload} property of the symbol.)
1067 hooks.  These hooks include variables whose names end in @samp{-hook}
1074 Standard unloading activities also undoes ELP profiling of functions
1092 @end deffn
1098 This variable holds a list of hooks to be scanned before unloading a
1100 @end defvar
1112 hook is called with a single argument, the absolute filename of the
1114 @end defvar
1120 This macro arranges to evaluate @var{body} at the end of loading
1129 @end example
1141 @end example
1144 @var{body} is evaluated at the end of any file where
1148 execution of the rest of @var{body}.
1149 @end defmac
1172 This variable holds the system-dependent value of the file-name
1173 extension of the module files.  Its value is @file{.so} on POSIX hosts
1175 @end defvar
1180 @code{emacs_module_init}, which Emacs will call as part of the call to
1189 documented in the header file @file{emacs-module.h} that is part of
1191 of using that API when writing your own modules.
1207 @end defun
1211 specified @var{file} and perform the necessary initialization of the
1224 @code{load-file}, @code{load-library}, or @code{require} instead of
1226 @end defun