Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-02-16 09:14:18 +00:00
Code Issues Projects Releases Packages Wiki Activity

; Improve documentation of the User Lisp directory.

Browse source
This commit is contained in:
Sean Whitton 2025-12-08 16:53:16 +00:00
parent 154d6f0a15
commit 70d24d0dd5
1 changed files with 24 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
doc/emacs/custom.texi
View file

@ -3106,42 +3106,50 @@ Gather and activate autoload cookies. This means that you can use
autoloaded commands and other entry points for the files in your
@code{user-lisp-directory} without explicitly loading any of the
files in your initialization file. (@pxref{Autoload,,, elisp, The
Emacs Lisp Reference Manual})
Emacs Lisp Reference Manual}.)
@item
Byte-compile all files, and if supported on your system, natively
compile them too. This speeds up the execution of the code in the
files when they are loaded. (@pxref{Byte Compilation,,, elisp, The
Emacs Lisp Reference Manual})
Emacs Lisp Reference Manual}.)
@item
Adjust @code{load-path} such that all the files can be loaded and
autoloaded in the usual ways. (@pxref{Library Search,,, elisp, The
Emacs Lisp Reference Manual})
Emacs Lisp Reference Manual}.)
@end itemize
Keep in mind that as the User Lisp directory is processed at startup,
before loading the @ref{Init File} file, adjustment have to be made in
your early-init file (@pxref{Early Init File}).
The User Lisp directory is processed before loading the @ref{Init
File} file. Therefore any customizations to the user options discussed
below must be made in your early init file (@pxref{Early Init File}) in
order to have any effect.
@vindex user-lisp-ignored-directories
@vindex user-lisp-auto-scrape
@findex prepare-user-lisp
By default, Emacs considers all Lisp files within
@code{user-lisp-directory}, even in subdirectories. You prevent Emacs
from descending into specific subdirectories by customizing
@code{user-lisp-ignored-directories}. You can disable scraping at
startup by setting @code{user-lisp-auto-scrape} to @code{nil}. All
preparations automatically occur at startup if necessary, but can be
manually invoked during a session using the @code{prepare-user-lisp}
command. It is recommended to run the command with a prefix argument
after upgrading Emacs, to force all generated files to be updated.
@code{user-lisp-directory}, including within subdirectories. You can
prevent Emacs from descending into specific subdirectories by
customizing @code{user-lisp-ignored-directories}. You can completely
disable scraping at startup by customizing @code{user-lisp-auto-scrape}
to @code{nil}. In addition to how Emacs prepares the Lisp files
automatically at startup, you can manually invoke preparation using the
command @code{prepare-user-lisp}.
Although Emacs automatically handles recompilation when the contents
of any Lisp files within the User Lisp directory have changed, there are
other reasons why recompilation can become necessary that Emacs can't
autodetect. A good rule of thumb that will catch most (but not all)
such issues is to force recompilation each time you upgrade to a new
release of Emacs. Start the new version of Emacs, type @w{@kbd{C-u M-x
prepare-user-lisp}}, then quit and restart Emacs again.
The User Lisp directory is a simpler mechanism than package
installations (@pxref{Packages}). In particular, there is no automatic
installation (@pxref{Packages}). In particular, there is no automatic
dependency resolution or upgrading for files in the User Lisp directory,
or any facility for building and registering package documentation.
This means that usually the User Lisp directory is best for code you
have written only for yourself. However, it is possible to use the User
Lisp directory for third party packages or packages you maintain.
Lisp directory for third party packages or public packages you maintain.
@node Authentication
@section Keeping Persistent Authentication Information