From b4937f64cd97ff6bf93538987c014f8ea8ff9d34 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 16 May 2020 11:54:37 +0300 Subject: [PATCH] Improve documentation of manually installing Lisp packages * doc/emacs/building.texi (Lisp Libraries): Describe how to manually load packages in the init file. Mention the 'site-lisp' subdirectory of the default 'load-path'. * doc/emacs/package.texi (Packages): Describe manual installation of ELisp packages. Suggested by Jean-Christophe Helary . --- doc/emacs/building.texi | 32 ++++++++++++++++++++++++++++++++ doc/emacs/package.texi | 32 +++++++++++++++++++++++--------- 2 files changed, 55 insertions(+), 9 deletions(-) diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index e866eea4a29..fa60ce26621 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -1509,6 +1509,11 @@ putting a line like this in your init file (@pxref{Init File}): (add-to-list 'load-path "/path/to/my/lisp/library") @end example +It is customary to put locally installed libraries in the +@file{site-lisp} directory that is already in the default value of +@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}. + @cindex autoload Some commands are @dfn{autoloaded}; when you run them, Emacs automatically loads the associated library first. For instance, the @@ -1538,6 +1543,33 @@ compiled with XEmacs, a modified version of Emacs---they can cause Emacs to crash. Set the variable @code{load-dangerous-libraries} to @code{t} if you want to try loading them. + Once you put your library in a directory where Emacs can find and +load it, you may wish to make it available at startup. This is useful +when the library defines features that should be available +automatically on demand, and manually loading the library is thus +inconvenient. In these cases, make sure the library will be loaded by +adding suitable forms to your init file: either @code{load} or +@code{require} (if you always need to load the library at startup), or +@code{autoload} if you need Emacs to load the library when some +command or function is invoked. For example: + +@smalllisp +@group + ;; Loads @file{my-shining-package.elc} unconditionally. + (require 'my-shining-package) +@end group +@group + ;; Will load @file{my-shining-package.elc} when @code{my-func} is invoked. + (autoload 'my-func "my-shining-package") +@end group +@end smalllisp + + Note that installing a package using @code{package-install} +(@pxref{Package Installation}) takes care of placing the package's +Lisp files in a directory where Emacs will find it, and also writes +the necessary initialization code into your init files, making the +above manual customizations unnecessary. + @node Lisp Eval @section Evaluating Emacs Lisp Expressions @cindex Emacs Lisp mode diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index 6bf4fc7e10c..517d2b75aa2 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -5,23 +5,37 @@ @node Packages @chapter Emacs Lisp Packages @cindex Package -@cindex Emacs Lisp package archive @cindex Package archive -Emacs includes a facility that lets you easily download and install -@dfn{packages} that implement additional features. Each package is a -separate Emacs Lisp program, sometimes including other components such -as an Info manual. + Emacs is extended by implementing additional features in +@dfn{packages}, which are Emacs Lisp libraries. These could be +written by you or provided by someone else. If you want to install +such a package so it is available in your future Emacs session, you +need to compile it and put it in a directory where Emacs looks for +Lisp libraries. @xref{Lisp Libraries}, for more details about this +manual installation method. Many packages provide installation and +usage instructions in the large commentary near the beginning of the +Lisp file; you can use those instructions for installing and +fine-tuning your use of the package. - @kbd{M-x list-packages} brings up a buffer named @file{*Packages*} -with a list of all packages. You can install or uninstall packages -via this buffer. @xref{Package Menu}. +@cindex Emacs Lisp package archive + Packages can also be provided by @dfn{package archives}, which are +large collections of Emacs Lisp packages. Each package is a separate +Emacs Lisp program, sometimes including other components such as an +Info manual. Emacs includes a facility that lets you easily download +and install packages from such archives. The rest of this chapter +describes this facility. + + To list the packages available for installation from package +archives, type @w{@kbd{M-x list-packages @key{RET}}}. It brings up a +buffer named @file{*Packages*} with a list of all packages. You can +install or uninstall packages via this buffer. @xref{Package Menu}. The command @kbd{C-h P} (@code{describe-package}) prompts for the name of a package, and displays a help buffer describing the attributes of the package and the features that it implements. - By default, Emacs downloads packages from a @dfn{package archive} + By default, Emacs downloads packages from a package archive maintained by the Emacs developers and hosted by the GNU project. Optionally, you can also download packages from archives maintained by third parties. @xref{Package Installation}. -- 2.39.2