@top use-package User Manual
The @code{use-package} macro allows you to isolate package configuration in your
-@code{.emacs} file in a way that is both performance-oriented and, well, tidy. I
+@code{.emacs} file in a way that is both performance-oriented and, well, tidy. I
created it because I have over 80 packages that I use in Emacs, and things
-were getting difficult to manage. Yet with this utility my total load time is
+were getting difficult to manage. Yet with this utility my total load time is
around 2 seconds, with no loss of functionality!
@insertcopying
@chapter Introduction
The @code{use-package} macro allows you to isolate package configuration in your
-@code{.emacs} file in a way that is both performance-oriented and, well, tidy. I
+@code{.emacs} file in a way that is both performance-oriented and, well, tidy. I
created it because I have over 80 packages that I use in Emacs, and things
-were getting difficult to manage. Yet with this utility my total load time is
+were getting difficult to manage. Yet with this utility my total load time is
around 2 seconds, with no loss of functionality!
More text to come@dots{}
@node Installing from an Elpa Archive
@section Installing from an Elpa Archive
-use-package is available from Melpa and Melpa-Stable. If you haven't used
+use-package is available from Melpa and Melpa-Stable. If you haven't used
Emacs' package manager before, then it is high time you familiarize yourself
with it by reading the documentation in the Emacs manual, see
-@ref{Packages,,,emacs,}. Then add one of the archives to @code{package-archives}:
+@ref{Packages,,,emacs,}. Then add one of the archives to @code{package-archives}:
@itemize
@item
@section Post-Installation Tasks
After installing use-package you should verify that you are indeed using the
-use-package release you think you are using. It's best to restart Emacs before
+use-package release you think you are using. It's best to restart Emacs before
doing so, to make sure you are not using an outdated value for @code{load-path}.
@example
@node Getting Started
@chapter Getting Started
-TODO@. For now, see @code{README.md}.
+TODO@. For now, see @code{README.md}.
@node Basic Concepts
@chapter Basic Concepts
@code{use-package} was created for few basic reasons, each of which drove the
-design in various ways. Understanding these reasons may help make some of
+design in various ways. Understanding these reasons may help make some of
those decisions clearer:
@itemize
@item
To allow byte-compilation of one's init file so that any warnings or
-errors seen are meaningful. In this way, even if byte-compilation is not
+errors seen are meaningful. In this way, even if byte-compilation is not
used for speed (reason 3), it can still be used as a sanity check.
@end itemize
Sometimes it only makes sense to configure a package after another has been
loaded, because certain variables or functions are not in scope until that
-time. This can achieved using an @code{:after} keyword that allows a fairly rich
-description of the exact conditions when loading should occur. Here is an
+time. This can achieved using an @code{:after} keyword that allows a fairly rich
+description of the exact conditions when loading should occur. Here is an
example:
@lisp
@end lisp
In this case, because all of these packages are demand-loaded in the order
-they occur, the use of @code{:after} is not strictly necessary. By using it,
+they occur, the use of @code{:after} is not strictly necessary. By using it,
however, the above code becomes order-independent, without an implicit
depedence on the nature of your init file.
By default, @code{:after (foo bar)} is the same as @code{:after (:all foo bar)}, meaning
that loading of the given package will not happen until both @code{foo} and @code{bar}
-have been loaded. Here are some of the other possibilities:
+have been loaded. Here are some of the other possibilities:
@lisp
:after (foo bar)
@strong{NOTE}: Pay attention if you set @code{use-package-always-defer} to t, and also use
the @code{:after} keyword, as you will need to specify how the declared package is
-to be loaded: e.g., by some @code{:bind}. If you're not using one of the mechanisms
+to be loaded: e.g., by some @code{:bind}. If you're not using one of the mechanisms
that registers autoloads, such as @code{:bind} or @code{:hook}, and your package manager
does not provide autoloads, it's possible that without adding @code{:demand t} to
those declarations, your package will never be loaded.
@section @code{:bind-keymap}, @code{:bind-keymap*}
Normally @code{:bind} expects that commands are functions that will be autoloaded
-from the given package. However, this does not work if one of those commands
+from the given package. However, this does not work if one of those commands
is actually a keymap, since keymaps are not functions, and cannot be
autoloaded using Emacs' @code{autoload} mechanism.
To handle this case, @code{use-package} offers a special, limited variant of
-@code{:bind} called @code{:bind-keymap}. The only difference is that the "commands"
+@code{:bind} called @code{:bind-keymap}. The only difference is that the "commands"
bound to by @code{:bind-keymap} must be keymaps defined in the package, rather than
-command functions. This is handled behind the scenes by generating custom code
+command functions. This is handled behind the scenes by generating custom code
that loads the package containing the keymap, and then re-executes your
keypress after the first load, to reinterpret that keypress as a prefix key.
@end lisp
When you use the @code{:commands} keyword, it creates autoloads for those commands
-and defers loading of the module until they are used. Since the @code{:init} form
+and defers loading of the module until they are used. Since the @code{:init} form
is always run---even if @code{ace-jump-mode} might not be on your system---remember
to restrict @code{:init} code to only what would succeed either way.
The @code{:commands} keyword likewise takes either a symbol or a list of symbols.
NOTE: Special keys like @code{tab} or @code{F1}-@code{Fn} can be written in square brackets,
-i.e. @code{[tab]} instead of @code{"tab"}. The syntax for the keybindings is similar to
+i.e. @code{[tab]} instead of @code{"tab"}. The syntax for the keybindings is similar to
the "kbd" syntax: see @uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html, the Emacs Manual} for more information.
Examples:
bind the key @code{C-c h} to @code{helm-execute-persistent-action} within Helm's local
keymap, @code{helm-mode-map}.
-Multiple uses of @code{:map} may be specified. Any binding occurring before the
+Multiple uses of @code{:map} may be specified. Any binding occurring before the
first use of @code{:map} are applied to the global keymap:
@lisp
@end lisp
This loads in the package @code{foo}, but only if @code{foo} is available on your
-system. If not, a warning is logged to the @code{*Messages*} buffer. If it
+system. If not, a warning is logged to the @code{*Messages*} buffer. If it
succeeds, a message about @code{"Loading foo"} is logged, along with the time it
took to load, if it took over 0.1 seconds.
@node @code{defer} @code{demand}
@section @code{:defer}, @code{:demand}
-In almost all cases you don't need to manually specify @code{:defer t}. This is
-implied whenever @code{:bind} or @code{:mode} or @code{:interpreter} is used. Typically, you
+In almost all cases you don't need to manually specify @code{:defer t}. This is
+implied whenever @code{:bind} or @code{:mode} or @code{:interpreter} is used. Typically, you
only need to specify @code{:defer} if you know for a fact that some other package
will do something to cause your package to load at the appropriate time, and
thus you would like to defer loading even though use-package isn't creating
any autoloads for you.
-You can override package deferral with the @code{:demand} keyword. Thus, even if
+You can override package deferral with the @code{:demand} keyword. Thus, even if
you use @code{:bind}, using @code{:demand} will force loading to occur immediately and
not establish an autoload for the bound key.
@section @code{:diminish}, @code{:delight}
@code{use-package} also provides built-in support for the diminish and delight
-utilities---if you have them installed. Their purpose is to remove or change
+utilities---if you have them installed. Their purpose is to remove or change
minor mode strings in your mode-line.
@uref{https://github.com/myrjola/diminish.el, diminish} is invoked with the @code{:diminish} keyword, which is passed either a
@uref{https://elpa.gnu.org/packages/delight.html, delight} is invoked with the @code{:delight} keyword, which is passed a minor mode
symbol, a replacement string or quoted @uref{https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Data.html, mode-line data} (in which case the minor
mode symbol is guessed to be the package name with "-mode" appended at the
-end), both of these, or several lists of both. If no arguments are provided,
+end), both of these, or several lists of both. If no arguments are provided,
the default mode name is hidden completely.
@lisp
@node @code{ensure} @code{pin}
@section @code{:ensure}, @code{:pin}
-You can use @code{use-package} to load packages from ELPA with @code{package.el}. This
+You can use @code{use-package} to load packages from ELPA with @code{package.el}. This
is particularly useful if you share your @code{.emacs} among several machines; the
relevant packages are downloaded automatically once declared in your @code{.emacs}.
The @code{:ensure} keyword causes the package(s) to be installed automatically if
By default @code{package.el} prefers @code{melpa} over @code{melpa-stable} due to the
versioning @code{(> evil-20141208.623 evil-1.0.9)}, so even if you are tracking
only a single package from @code{melpa}, you will need to tag all the non-@code{melpa}
-packages with the appropriate archive. If this really annoys you, then you can
+packages with the appropriate archive. If this really annoys you, then you can
set @code{use-package-always-pin} to set a default.
If you want to manually keep a package updated and ignore upstream updates,
@section @code{:hook}
The @code{:hook} keyword allows adding functions onto hooks, here only the basename
-of the hook is required. Thus, all of the following are equivalent:
+of the hook is required. Thus, all of the following are equivalent:
@lisp
(use-package ace-jump-mode
@section @code{:load-path}
If your package needs a directory added to the @code{load-path} in order to load,
-use @code{:load-path}. This takes a symbol, a function, a string or a list of
-strings. If the path is relative, it is expanded within
+use @code{:load-path}. This takes a symbol, a function, a string or a list of
+strings. If the path is relative, it is expanded within
@code{user-emacs-directory}:
@lisp
Note that when using a symbol or a function to provide a dynamically generated
list of paths, you must inform the byte-compiler of this definition so the
-value is available at byte-compilation time. This is done by using the special
-form @code{eval-and-compile} (as opposed to @code{eval-when-compile}). Further, this
+value is available at byte-compilation time. This is done by using the special
+form @code{eval-and-compile} (as opposed to @code{eval-when-compile}). Further, this
value is fixed at whatever was determined during compilation, to avoid looking
up the same information again on each startup:
Similar to @code{:bind}, you can use @code{:mode} and @code{:interpreter} to establish a
deferred binding within the @code{auto-mode-alist} and @code{interpreter-mode-alist}
-variables. The specifier to either keyword can be a cons cell, a list of cons
+variables. The specifier to either keyword can be a cons cell, a list of cons
cells, or a string or regexp:
@lisp
Similar to @code{:mode} and @code{:interpreter}, you can also use @code{:magic} and
@code{:magic-fallback} to cause certain function to be run if the beginning of a
-file matches a given regular expression. The difference between the two is
-that @code{:magic-fallback} has a lower priority than @code{:mode}. For example:
+file matches a given regular expression. The difference between the two is
+that @code{:magic-fallback} has a lower priority than @code{:mode}. For example:
@lisp
(use-package pdf-tools
Normally, @code{use-package} will load each package at compile time before
compiling the configuration, to ensure that any necessary symbols are in scope
-to satisfy the byte-compiler. At times this can cause problems, since a
+to satisfy the byte-compiler. At times this can cause problems, since a
package may have special loading requirements, and all that you want to use
-@code{use-package} for is to add a configuration to the @code{eval-after-load} hook. In
+@code{use-package} for is to add a configuration to the @code{eval-after-load} hook. In
such cases, use the @code{:no-require} keyword:
@lisp
While the @code{:after} keyword delays loading until the dependencies are loaded,
the somewhat simpler @code{:requires} keyword simply never loads the package if the
dependencies are not available at the time the @code{use-package} declaration is
-encountered. By "available" in this context it means that @code{foo} is available
-of @code{(featurep 'foo)} evaluates to a non-nil value. For example:
+encountered. By "available" in this context it means that @code{foo} is available
+of @code{(featurep 'foo)} evaluates to a non-nil value. For example:
@lisp
(use-package abbrev
projects / emacs.git / commitdiff