use-package.texi: New section "Manual installation"

* doc/misc/use-package.texi (Manual installation): New section.
(Load path, Manual autoloads): Make into subsections of above new
section.
This commit is contained in:
Stefan Kangas 2022-12-12 08:45:40 +01:00
parent f4ce6fa7d3
commit 06ef030f93

View file

@ -248,10 +248,6 @@ packages using the built-in @code{install-package} command, it will do
this automatically for you. Packages shipped with Emacs (built-in this automatically for you. Packages shipped with Emacs (built-in
packages) are always available. packages) are always available.
If you install packages manually, you must make sure they are
available on your @code{load-path}. @xref{Lisp Libraries,,, emacs,
GNU Emacs Manual}, for details.
Some packages have more than one library. In those cases, you might Some packages have more than one library. In those cases, you might
need more than one @code{use-package} declaration to make sure the need more than one @code{use-package} declaration to make sure the
package is properly loaded. For complex configurations, you might package is properly loaded. For complex configurations, you might
@ -267,8 +263,7 @@ on Emacs start. @xref{Installing packages}, for details.
* Conditional loading:: Loading packages conditionally. * Conditional loading:: Loading packages conditionally.
* Loading sequentially:: Loading packages in sequence. * Loading sequentially:: Loading packages in sequence.
* Load dependencies:: Don't load without dependencies. * Load dependencies:: Don't load without dependencies.
* Load path:: Using a custom @code{load-path}. * Manual installation:: Loading manually installed packages.
* Manual autoloads:: Setting up autoloads manually.
@end menu @end menu
@node Loading basics @node Loading basics
@ -623,36 +618,54 @@ As a convenience, a list of such packages may be specified:
For more complex logic, such as that supported by @code{:after}, For more complex logic, such as that supported by @code{:after},
simply use @code{:if} and the appropriate Lisp expression. simply use @code{:if} and the appropriate Lisp expression.
@node Manual installation
@section Manually installed package
When installing packages manually, without Emacs' built-in package
manager (@file{package.el}), it will obviously not help you set up
autoloads or add it to your @code{load-path}. You must do it
yourself. However, use-package makes this more convenient.
@menu
* Load path:: Using a custom @code{load-path}.
* Manual autoloads:: Setting up autoloads manually.
@end menu
@node Load path @node Load path
@section Setting a custom @code{load-path} @subsection Setting a custom @code{load-path}
@cindex custom @code{load-path} for loading a package @cindex custom @code{load-path} for loading a package
@cindex @code{load-path}, add directories for loading a package @cindex @code{load-path}, add directories for loading a package
When installing packages manually, you must make sure its libraries
are available on your @code{load-path}. @xref{Lisp Libraries,,,
emacs, GNU Emacs Manual}, for more details about package loading.
@findex :load-path @findex :load-path
If a package resides in some directory that is not in your The @code{:load-path} keyword provides a convenient way to add
@code{load-path}, use the @code{:load-path} keyword to add it. It directories to your load path. It takes as argument a symbol, a
takes as argument a symbol, a function, a string or a list of strings. function, a string or a list of strings. If a directory is specified
If a directory is specified as a relative file name, it is expanded as a relative file name, it is expanded relative to
relative to @code{user-emacs-directory}. @code{user-emacs-directory}.
For example: For example:
@lisp @lisp
@group @group
(use-package ess-site (use-package org
:load-path "site-lisp/ess/lisp/" :load-path "site-lisp/org/lisp/"
:commands R) :commands org-mode)
@end group @end group
@end lisp @end lisp
Note that when using a symbol or a function to provide a dynamically When using a symbol or a function to provide a dynamically generated
generated list of directories, you must inform the byte-compiler of this list of directories, you must inform the byte-compiler of this
definition so that the value is available at byte-compilation time. definition, so that the value is available at byte-compilation time.
This is done by using the special form @code{eval-and-compile} (as This is done by using the special form @code{eval-and-compile} (as
opposed to @code{eval-when-compile}, @pxref{Eval During Compile,,, opposed to @code{eval-when-compile}, @pxref{Eval During Compile,,,
elisp, GNU Emacs Lisp Reference Manual}). Further, this value is fixed at elisp, GNU Emacs Lisp Reference Manual}). Furthermore, this value is
whatever was determined during compilation, to avoid looking up the fixed to the value it had during compilation. If the operation is
same information again on each startup. For example: costly, you do not have to repeat it again on each startup. For
example:
@lisp @lisp
@group @group
@ -669,20 +682,25 @@ same information again on each startup. For example:
@end lisp @end lisp
@node Manual autoloads @node Manual autoloads
@section Setting up autoloads manually @subsection Setting up autoloads manually
Packages often document how to set up its autoloads when it is being
manually installed. If it does, follow those instructions.
Otherwise, you might want to set them up manually.
@cindex autoloads for packages, setting up manually @cindex autoloads for packages, setting up manually
@cindex package autoloads, setting up manually @cindex package autoloads, setting up manually
@findex :commands @findex :commands
@findex :autoload @findex :autoload
To autoload an interactive command, use the @code{:commands} keyword. To autoload an interactive command, use the @code{:commands} keyword,
When you use the @code{:commands} keyword, it creates autoloads for which takes either a symbol or a list of symbols as its argument. It
those commands (which defers loading of the module until those commands are creates autoloads for those commands (which defers loading of the
used). The @code{:commands} keyword takes either a symbol or a list module until those commands are used).
of symbols as its argument.
The @code{:autoload} keyword works like @code{:commands}, but is used The @code{:autoload} keyword takes the same arguments as
to autoload non-interactive functions. Here is an example: @code{:commands}, but is used to autoload non-interactive functions.
Here is an example:
@lisp @lisp
@group @group