masscollaborationlabs/emacs
2
0
Fork 0
mirror of https://github.com/masscollaborationlabs/emacs.git synced 2025-07-04 11:23:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

; Improve documentation of loading *.eln files

Browse source 
* doc/lispref/loading.texi (How Programs Do Loading):
* doc/emacs/building.texi (Lisp Libraries): Some additional
details about what happens with natively-compiled files.
This commit is contained in:
Eli Zaretskii 2023-02-26 19:51:59 +02:00
parent 7c552be89d
commit dde9d149af
2 changed files with 39 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

37
doc/emacs/building.texi
View file

@ -1556,18 +1556,26 @@ command prompts for a @dfn{library name} rather than a file name; it
searches through each directory in the Emacs Lisp load path, trying to searches through each directory in the Emacs Lisp load path, trying to
find a file matching that library name. If the library name is find a file matching that library name. If the library name is
@samp{@var{foo}}, it tries looking for files named @samp{@var{foo}}, it tries looking for files named
@file{@var{foo}.elc}, @file{@var{foo}.el}, and @file{@var{foo}}. The @file{@var{foo}.elc}, @file{@var{foo}.el}, and @file{@var{foo}}. (If
default behavior is to load the first file found. This command Emacs was built with native compilation enabled, @code{load-library}
prefers @file{.elc} files over @file{.el} files because compiled files looks for a @samp{.eln} file that corresponds to @file{@var{foo}.el}
load and run faster. If it finds that @file{@var{lib}.el} is newer and loads it instead of @file{@var{foo}.elc}.) The default behavior
than @file{@var{lib}.elc}, it issues a warning, in case someone made is to load the first file found. This command prefers @file{.eln}
changes to the @file{.el} file and forgot to recompile it, but loads files over @file{.elc} files, and prefers @file{.elc} files over
the @file{.elc} file anyway. (Due to this behavior, you can save @file{.el} files, because compiled files load and run faster. If it
unfinished edits to Emacs Lisp source files, and not recompile until finds that @file{@var{lib}.el} is newer than @file{@var{lib}.elc}, it
your changes are ready for use.) If you set the option issues a warning, in case someone made changes to the @file{.el} file
@code{load-prefer-newer} to a non-@code{nil} value, however, then and forgot to recompile it, but loads the @file{.elc} file anyway.
rather than the procedure described above, Emacs loads whichever (Due to this behavior, you can save unfinished edits to Emacs Lisp
version of the file is newest. source files, and not recompile until your changes are ready for use.)
If you set the option @code{load-prefer-newer} to a non-@code{nil}
value, however, then rather than the procedure described above, Emacs
loads whichever version of the file is newest. If Emacs was built
with native compilation, and it cannot find the @samp{.eln} file
corresponding to @file{@var{lib}.el}, it will load a
@file{@var{lib}.elc} and start native compilation of
@file{@var{lib}.el} in the background, then load the @samp{.eln} file
when it finishes compilation.
Emacs Lisp programs usually load Emacs Lisp files using the Emacs Lisp programs usually load Emacs Lisp files using the
@code{load} function. This is similar to @code{load-library}, but is @code{load} function. This is similar to @code{load-library}, but is
@ -1604,6 +1612,11 @@ It is customary to put locally installed libraries in the
@code{load-path}, or in some subdirectory of @file{site-lisp}. This @code{load-path}, or in some subdirectory of @file{site-lisp}. This
way, you don't need to modify the default value of @code{load-path}. way, you don't need to modify the default value of @code{load-path}.
@vindex native-comp-eln-load-path
Similarly to @code{load-path}, the list of directories where Emacs
looks for @file{*.eln} files with natively-compiled Lisp code is
specified by the variable @code{native-comp-eln-load-path}.
@cindex autoload @cindex autoload
Some commands are @dfn{autoloaded}; when you run them, Emacs Some commands are @dfn{autoloaded}; when you run them, Emacs
automatically loads the associated library first. For instance, the automatically loads the associated library first. For instance, the

25
doc/lispref/loading.texi
View file

@ -75,17 +75,20 @@ file exists, and Emacs was compiled with native-compilation support
(@pxref{Native Compilation}), @code{load} attempts to find a (@pxref{Native Compilation}), @code{load} attempts to find a
corresponding @samp{.eln} file, and if found, loads it instead of corresponding @samp{.eln} file, and if found, loads it instead of
@file{@var{filename}.elc}. Otherwise, it loads @file{@var{filename}.elc}. Otherwise, it loads
@file{@var{filename}.elc}. If there is no file by that name, then @file{@var{filename}.elc} (and starts a background native compilation
@code{load} looks for a file named @file{@var{filename}.el}. If that to produce the missing @samp{.eln} file, followed by loading that
file exists, it is loaded. If Emacs was compiled with support for file). If there is no @file{@var{filename}.elc}, then @code{load}
dynamic modules (@pxref{Dynamic Modules}), @code{load} next looks for looks for a file named @file{@var{filename}.el}. If that file exists,
a file named @file{@var{filename}.@var{ext}}, where @var{ext} is a it is loaded. If Emacs was compiled with support for dynamic modules
system-dependent file-name extension of shared libraries. Finally, if (@pxref{Dynamic Modules}), @code{load} next looks for a file named
neither of those names is found, @code{load} looks for a file named @file{@var{filename}.@var{ext}}, where @var{ext} is a system-dependent
@var{filename} with nothing appended, and loads it if it exists. (The file-name extension of shared libraries (@samp{.so} on GNU and Unix
@code{load} function is not clever about looking at @var{filename}. systems). Finally, if neither of those names is found, @code{load}
In the perverse case of a file named @file{foo.el.el}, evaluation of looks for a file named @var{filename} with nothing appended, and loads
@code{(load "foo.el")} will indeed find it.) it if it exists. (The @code{load} function is not clever about
looking at @var{filename}. In the perverse case of a file named
@file{foo.el.el}, evaluation of @code{(load "foo.el")} will indeed
find it.)
If Auto Compression mode is enabled, as it is by default, then if If Auto Compression mode is enabled, as it is by default, then if
@code{load} can not find a file, it searches for a compressed version @code{load} can not find a file, it searches for a compressed version