procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of manually installing Lisp packages

Browse source 
* 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
<jean.christophe.helary@traduction-libre.org>.
This commit is contained in:
Eli Zaretskii 2020-05-16 11:54:37 +03:00
parent efd4e973a4
commit b4937f64cd
2 changed files with 55 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
doc/emacs/building.texi
View file

@ -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

32
doc/emacs/package.texi
View file

@ -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}.