From 98e54f597e11fa760553bf7b12d8ebb388b5a488 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Thu, 8 Dec 2022 00:47:04 +0100 Subject: [PATCH] Add new use-package manual * doc/misc/use-package.texi: Rewrite manual. --- doc/misc/use-package.texi | 2045 ++++++++++++++++++++++++++----------- 1 file changed, 1456 insertions(+), 589 deletions(-) diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi index 573baac89aa..d39125c4555 100644 --- a/doc/misc/use-package.texi +++ b/doc/misc/use-package.texi @@ -1,29 +1,32 @@ \input texinfo @c -*- texinfo -*- @c %**start of header -@setfilename use-package.info +@setfilename ../../use-package.info @settitle use-package User Manual -@documentencoding UTF-8 -@documentlanguage en +@include docstyle.texi +@syncodeindex vr cp +@syncodeindex fn cp @c %**end of header @copying -@quotation -Copyright (C) 2012-2022 Free Software Foundation, Inc. - -You can redistribute this document and/or modify it under the terms -of the GNU General Public License as published by the Free Software -Foundation, either version 3 of the License, or (at your option) any -later version. +This manual is for use-package, a configuration macro for simplifying +your init file. -This document is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU -General Public License for more details. +Copyright @copyright{} 2022 Free Software Foundation, Inc. +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License''. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' @end quotation @end copying -@dircategory Emacs +@dircategory Emacs misc features @direntry * use-package: (use-package). Declarative package configuration for Emacs. @end direntry @@ -31,8 +34,8 @@ General Public License for more details. @finalout @titlepage @title use-package User Manual -@subtitle for version 2.4.1-119-g0be480e+1 -@author John Wiegley +@subtitle for version 2.4.5 +@author John Wiegley & Stefan Kangas @page @vskip 0pt plus 1filll @insertcopying @@ -44,353 +47,707 @@ General Public License for more details. @node Top @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 -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 -around 2 seconds, with no loss of functionality! +The @code{use-package} macro allows you to isolate package +customization in your init file in a declarative way. It takes care +of a lot of things for you that would otherwise require a lot of +repetitive boilerplate code. It can help with common customization, +such as binding keys, setting up hooks, customizing user options and +faces, autoloading, and more. It also helps you keep Emacs startup +fast, even when you use many (even hundreds) of packages. + +Note that use-package is not a package manager. Although use-package +does have the useful capability to interface with the Emacs package +manager, its primary purpose is for the configuration and loading of +packages. @insertcopying -@end ifnottex @menu -* Introduction:: -* Installation:: -* Getting Started:: -* Basic Concepts:: -* Issues/Requests:: -* Keywords:: -* Debugging Tools:: - -@detailmenu ---- The Detailed Node Listing --- - -Installation - -* Installing from GNU ELPA:: -* Installing from the Git Repository:: -* Post-Installation Tasks:: - -Keywords - -* @code{after}:: @code{:after}. -* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap}, @code{:bind-keymap*}. -* @code{bind} @code{bind*}:: @code{:bind}, @code{:bind*}. -* @code{commands}:: @code{:commands}. -* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init}, @code{:config}. -* @code{custom}:: @code{:custom}. -* @code{custom-face}:: @code{:custom-face}. -* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}. -* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}. -* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}. -* @code{disabled}:: @code{:disabled}. -* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}. -* @code{hook}:: @code{:hook}. -* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when}, @code{:unless}. -* @code{load-path}:: @code{:load-path}. -* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}. -* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}. -* @code{no-require}:: @code{:no-require}. -* @code{requires}:: @code{:requires}. - -@code{bind}, @code{bind*} - -* Binding to local keymaps:: - - -@end detailmenu +* Basic Concepts:: Basic concepts of use-package. +* Getting Started:: A gentle introduction to use-package. +* Loading Packages:: How and when packages are loaded. +* Configuring Packages:: Package configuration keywords. +* Installing packages:: Ensuring packages are available. +* Byte-compiling:: Byte-compiling your init file. +* Troubleshooting:: What to do when there's trouble. + +Appendices +* Keyword extensions:: Adding new use-package keywords. +* History:: History and acknowledgments. +* GNU Free Documentation License:: The license for this manual. +* Index:: @end menu +@end ifnottex -@node Introduction -@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 -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 -around 2 seconds, with no loss of functionality! +@c ---------------------------------------------------------------------------- +@node Basic Concepts +@chapter Basic Concepts -More text to come@dots{} +use-package provides the @code{use-package} macro, that simplifies the +customization and use of packages in Emacs. It was created for a few +basic reasons, each of which drove the design. Understanding these +reasons may help make some of those decisions clearer: -@node Installation -@chapter Installation +@enumerate +@item +To gather all configuration details of a package into one place, +making it easier to copy, disable, or move it elsewhere in the init +file. -use-package can be installed using Emacs' package manager or manually from -its development repository. +@item +To reduce duplication and boilerplate, capturing several common +practices as mere keywords both easy and intuitive to use. -@menu -* Installing from GNU ELPA:: -* Installing from the Git Repository:: -* Post-Installation Tasks:: -@end menu +@item +To make startup time of Emacs as quick as possible, without +sacrificing the quantity of add-on packages used. -@node Installing from GNU ELPA -@section Installing from GNU ELPA +@item +To make it so errors encountered during startup disable only the +package raising the error, and as little else as possible, leaving as +close to a functional Emacs as possible. -use-package is available from GNU ELPA. 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}: +@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 used for speed (reason 3), it can still be used as a sanity check. +@end enumerate -First, you need to update the local package list using: +It is worth noting that use-package is not intended to replace the +standard @w{@code{M-x customize}}. On the contrary, it is designed to +work together with it, for things that customize cannot do. -@example -M-x package-refresh-contents RET -@end example +@c ---------------------------------------------------------------------------- +@node Getting Started +@chapter Getting Started -Once you have done that, you can install use-package and its -dependencies using: +This chapter provides instructions and examples for quickly getting +started with use-package. The first thing you need to do is make sure +that @samp{use-package} itself is loaded. To do that, put this at the +top of your init file: -@example -M-x package-install RET use-package RET -@end example +@lisp +(require 'use-package) +(require 'bind-key) ; if you use any :bind variant +@end lisp -Now see @ref{Post-Installation Tasks}. +The above makes the @code{use-macro} for in the rest of your init +file. In this manual, we call each call to @code{use-macro} a +@dfn{declaration}, to highlight the declarative nature of its +semantic. -@node Installing from the Git Repository -@section Installing from the Git Repository +To unconditionally load a package named @samp{foo}, add the following +declaration to your init file: -First, use Git to clone the use-package repository: +@lisp +(use-package foo) +@end lisp -@example -$ git clone https://github.com/jwiegley/use-package.git ~/.emacs.d/site-lisp/use-package -$ cd ~/.emacs.d/site-lisp/use-package -@end example +@noindent +This declaration is equivalent to using @code{require}, with some +use-package specific error handling added in. Just like require, it +needs the package @samp{foo} to be installed and available in your +@code{load-path} (@pxref{Installing packages}). -Then compile the libraries and generate the info manuals: +To evaluate Lisp code @emph{before} the @samp{foo} package is loaded, +use the @code{:init} keyword: -@example -$ make -@end example +@lisp +(use-package foo + :init + (setq foo-variable t)) +@end lisp -You may need to create @code{/path/to/use-package/config.mk} with the following -content before running @code{make}: +Similarly, @code{:config} can be used to execute code @emph{after} a +package is loaded. In cases where loading is done lazily +(@pxref{Loading Packages}), this execution is deferred until after the +autoload occurs. As you might expect, you can use @code{:init} and +@code{:config} together: -@example -LOAD_PATH = -L /path/to/use-package -@end example +@lisp +(use-package foo + :init + (setq foo-variable t) + :config + (foo-mode 1)) +@end lisp -Finally add this to your init file: +The above declarations will all load the @samp{foo} package +immediately. In most cases, this is not necessary or desirable, as +that will slow down Emacs startup. Instead, you should try to set +things up so that packages are only loaded when they are actually +needed (autoloading). If you have installed a package from +@acronym{GNU ELPA} that provides it's own autoloads, it is often +enough to say: @lisp -(add-to-list 'load-path "~/.emacs.d/site-lisp/use-package") -(require 'use-package) - -(with-eval-after-load 'info - (info-initialize) - (add-to-list 'Info-directory-list - "~/.emacs.d/site-lisp/use-package/")) +(use-package foo + :defer t) @end lisp -Note that elements of @code{load-path} should not end with a slash, while those of -@code{Info-directory-list} should. +@noindent +This will avoid loading the package. Now, when you run any autoloaded +command, the package @samp{foo} is loaded automatically. Package +authors will make their own decisions about which commands are marked +to autoload by default. -Instead of running use-package directly from the repository by adding it to -the @code{load-path}, you might want to instead install it in some other directory -using @code{sudo make install} and setting @code{load-path} accordingly. +In some cases, you might need or want to provide your own autoloads. +The below more complex example autoloads the commands +@code{isearch-moccur} and @code{isearch-all} from +@file{color-moccur.el}, and binds keys both globally and in +@code{isearch-mode-map}. When one of these commands are used, the +package is loaded. At that point, @code{moccur-edit} is also loaded, +to allow editing of the @code{moccur} buffer. -To update use-package use: +@lisp +(use-package color-moccur + :commands (isearch-moccur isearch-all) + :bind (("M-s O" . moccur) + :map isearch-mode-map + ("M-o" . isearch-moccur) + ("M-O" . isearch-moccur-all)) + :init + (setq isearch-lazy-highlight t) + :config + (use-package moccur-edit)) +@end lisp -@example -$ git pull -$ make -@end example +Some packages will suggest ready-made @code{use-package} declarations +that you can use. Where possible, it is a good idea to copy them, and +use that as a starting point. -At times it might be necessary to run @code{make clean all} instead. +That should be enough to get you started! -To view all available targets use @code{make help}. +@c ---------------------------------------------------------------------------- +@node Loading Packages +@chapter Loading Packages -Now see @ref{Post-Installation Tasks}. +@cindex loading packages +Before use-package can load an Emacs Lisp package, it must be +available in a directory on your @code{load-path}. When you install +packages using the built-in @code{install-package} command, it will do +this automatically for you. Packages shipped with Emacs (built-in +packages) are always available. -@node Post-Installation Tasks -@section Post-Installation Tasks +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. -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 -doing so, to make sure you are not using an outdated value for @code{load-path}. +Some packages have more than one library. In those cases, you might +need more than one @code{use-package} declaration to make sure it is +properly loaded. For complex configurations, you might also need more +than one declaration for a package with the same name. -@example -C-h v use-package-version RET -@end example +use-package can interface with @samp{package.el} to install packages +on Emacs start. @xref{Installing packages} for details. -should display something like +@menu +* Loading basics:: How and when packages are loaded. +* Deferring loading:: Loading packages later. +* Forcing loading:: Loading packages immediately. +* Conditional loading:: Loading packages conditionally. +* Loading sequentially:: Loading packages in sequence. +* Load dependencies:: Don't load without dependencies. +* Load path:: Using a custom @code{load-path}. +* Manual autoloads:: Setting up autoloads manually. +@end menu -@example -use-package-version’s value is "2.4.3" -@end example +@node Loading basics +@section How and when use-package loads packages -If you are completely new to use-package then see @ref{Getting Started}. +The @code{use-package} macro either will either load a package +immediately, or when they are first used (autoloading). In the +simplest case, a @code{use-package} declaration loads a package when +it is evaluated.@footnote{This happens both at run-time and at +compile-time. @xref{Byte-compiling}.} If the declaration is in your +init file, this happens automatically each time Emacs is started. -If you run into problems, then please see the @ref{Debugging Tools}. +For example, the below declaration immediately loads the library +@code{foo}, just like @code{require} would. If the library @samp{foo} +is not available in your @code{load-path}, it logs a warning to the +@samp{*Messages*} buffer: -@node Getting Started -@chapter Getting Started +@lisp +(use-package foo) +@end lisp -TODO@. For now, see @code{README.md}. +Note that a ``package'' is different from an Emacs Lisp ``library''. +The above declaration tells use-package to load the @emph{library} +@file{foo.el}, which the overwhelming majority of cases also resides +in a @emph{package} named @code{foo}. But the @code{foo} package +might also contain a library named @file{foo-extra.el}. If that +library is not loaded automatically, you will need a separate +@code{use-package} declaration to make sure that it is. This manual +will often use these terms interchangeably, as this distinction does +not usually matter, but you should keep it in mind for the cases when +it does. + +The details of how and when you should load a package might differ +from one package to another. When in doubt, refer to the package +documentation for details. + +@node Deferring loading +@section Deferring package loading + +@cindex autoloading packages +@cindex loading lazily +In the examples we have seen so far, use-package loads packages every +time you start Emacs, even if that package is never used. That will +make starting Emacs slower. use-package therefore tries to set things +up in such a way that it only loads packages when a command is first +used (either with @kbd{M-x} or some key binding). This is based on +autoloading, a full description of which is outside the scope of this +manual. @xref{Autoload,,, elisp, GNU Emacs Lisp Reference Manual} for +the full story. + +@cindex triggers, for loading packages +Some @code{use-package} keywords provide autoload @dfn{triggers} that +cause a package to be loaded when certain events occur. For example, +the @code{:hook} keyword sets up a trigger that fires when the +specified hook is run, and then loads the package automatically. The +other trigger keywords, all of which are described later in this +manual, are @code{:commands}, @code{:bind}, @code{:bind*}, +@code{:bind-keymap}, @code{:bind-keymap*}, @code{:mode}, and +@code{:interpreter}. + +@subheading The @code{:defer} keyword + +@findex :defer +If you did not specify any autoloading keyword, use-package will fall +back to loading the package immediately (typically when Emacs is +starting up). This can be overridden using the @code{:defer} keyword. +It takes one boolean argument: a non-@code{nil} value means to stop +this package from being immediately loaded. Here is an example of +using @code{:defer} to postpone loading the package @samp{foo}: -@node Basic Concepts -@chapter Basic Concepts +@lisp +(use-package foo + :defer t) +@end lisp -@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 -those decisions clearer: +Using @code{:defer t} by itself like this is rarely useful. +Typically, you would only use it together with a keyword like +@code{:config} (@pxref{Lisp Configuration}), or @code{:ensure} +(@pxref{Installing packages}). -@itemize -@item -To gather all configuration details of a package into one place, -making it easier to copy, disable, or move it elsewhere in the init -file. +@subheading Defer loading until idle for N seconds -@item -To reduce duplication and boilerplate, capturing several common -practices as mere keywords both easy and intuitive to use. +You can also give a numeric argument @var{N} to @w{@code{:defer}} to +specify that a package should be loaded (if it hasn't already) after +Emacs has been idle for @var{N} seconds. For example, use this to +make use-package load @samp{foo} after 30 seconds of idle time: -@item -To make startup time of Emacs as quick as possible, without -sacrificing the quantity of add-on packages used. +@lisp +(use-package foo + :defer 30) +@end lisp -@item -To make it so errors encountered during startup disable only the -package raising the error, and as little else as possible, leaving a -close to a functional Emacs as possible. +@subheading When to use @code{:defer} + +When using autoloading keywords, there is no need to also use +@code{:defer}. It doesn't hurt anything to add it in this case, +perhaps for extra clarity, but it is redundant. + +You should use @code{:defer} to force deferred loading, in cases when +use-package isn't creating any autoloads for you. For example, you +might know that some other package will already do something to cause +your package to load at the appropriate time. This is usually the +case when you install a package using @code{package-install}, as +packages installed in this way normally always have their own +autoloads already set up. + +@subheading Making @w{@code{:defer t}} the default + +@vindex use-package-always-defer +If you customize the user option @code{use-package-always-defer} to +non-@code{nil}, the @code{use-package} macro will behave as if +@w{@code{:defer t}} is always specified. This can be overridden for +individual declarations using either @w{@code{:defer nil}} or +@w{@code{:demand t}} (@pxref{Forcing loading}). + +@node Forcing loading +@section Forcing package to load immediately + +@findex :demand +The presence of autoloading trigger keywords can be overridden using +@code{:demand t}, which forces the package to load immediately. Thus, +even if you use an autoloading keyword such as @code{:bind} +(@pxref{Key bindings}), adding @code{:demand} will force loading to +occur immediately. It will also avoid creating an autoload for the +bound key, as it would be redundant. + +If you specify both @w{@code{:demand t}} and @w{@code{:defer t}}, the +@code{:defer} keyword will take precedence. + +@node Conditional loading +@section Loading packages conditionally + +@findex :if +@findex :when +@findex :unless +The @code{:if}, @code{:when}, and @code{:unless} keywords predicates +the loading and initialization of packages. They all accept one +argument, an Emacs Lisp form that is evaluated at run-time. + +If the argument of the @code{:if} keyword evaluates to non-@code{nil}, +the package will be loaded and initialized. The @code{:when} keyword +is provided as an alias for @code{:if}. Finally, the @code{:unless} +keyword is the inverse of @code{:if}, such that @w{@code{:unless foo}} +means the same thing as @w{@code{:if (not foo)}}. + +For example, if you only want @samp{foo} in graphical Emacs sessions, +you could use the following: -@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 -used for speed (reason 3), it can still be used as a sanity check. -@end itemize +@lisp +(use-package foo + :if (display-graphic-p)) +@end lisp -@node Issues/Requests -@chapter Issues/Requests +Another common use case is to make it conditional on the operating +system: -@node Keywords -@chapter Keywords +@lisp +(use-package foo + :if (memq window-system '(mac ns))) +@end lisp -@menu -* @code{after}:: @code{after}. -* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap}, @code{:bind-keymap*}. -* @code{bind} @code{bind*}:: @code{bind} @code{:bind*}. -* @code{commands}:: @code{:commands}. -* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init}, @code{:config}. -* @code{custom}:: @code{:custom}. -* @code{custom-face}:: @code{:custom-face}. -* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}. -* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}. -* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}. -* @code{disabled}:: @code{:disabled}. -* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}. -* @code{hook}:: @code{:hook}. -* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when}, @code{:unless}. -* @code{load-path}:: @code{:load-path}. -* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}. -* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}. -* @code{no-require}:: @code{:no-require}. -* @code{requires}:: @code{:requires}. -@end menu +@cindex conditional loading before @code{:preface} or @code{:ensure} +If you need to conditionalize a use-package form so that the condition +occurs before even @code{:ensure} or @code{:preface}, use @code{when} +around the use-package form itself. For example: -@node @code{after} -@section @code{:after} +@lisp +(when (memq window-system '(mac ns)) + (use-package foo + :ensure t)) +@end lisp -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 -example: +@node Loading sequentially +@section Loading packages in sequence + +@findex :after +Sometimes it only makes sense to configure a package after another one +has been loaded, because certain variables or functions are not in +scope until that time. This can achieved with the @code{:after} +keyword, which allows a fairly rich description of the exact +conditions when loading should occur. It takes either a symbol +indicating the package name, a list of such symbols, or a list of +selectors (see below). + +Here is an example of using the @acronym{GNU ELPA} packages hydra, +ivy, and ivy-hydra. Note that ivy-hydra will always be loaded last: @lisp -(use-package hydra - :load-path "site-lisp/hydra") +(use-package hydra) -(use-package ivy - :load-path "site-lisp/swiper") +(use-package ivy) (use-package ivy-hydra :after (ivy hydra)) @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, -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: - -@lisp +In this case, because the declarations are evaluated in the order they +occur, the use of @code{:after} is not strictly necessary. However, +if @samp{hydra} and @samp{ivy} were to be autoloaded, using +@code{:after} guarantees that @samp{ivy-hydra} is not loaded until it +is actually needed. By using @code{:after}, the above code will also +work even if the order of the declaration changes. This means that +moving things around in your init file is less likely to break things. + +@subheading Using @code{:after} selectors + +@findex :all (with :after) +@findex :any (with :after) +The @code{:after} keyword also accepts a list of selectors. By +default, @code{:after (foo bar)} is the same as @w{@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: + +@verbatim :after (foo bar) :after (:all foo bar) :after (:any foo bar) :after (:all (:any foo bar) (:any baz quux)) :after (:any (:all foo bar) (:all baz quux)) +@end verbatim + +When you nest selectors, such as @code{(:any (:all foo bar) (:all baz +quux))}, it means that the package will be loaded when either both +@code{foo} and @code{bar} have been loaded, or when both @code{baz} +and @code{quux} have been loaded. + +Pay attention when setting @code{use-package-always-defer} to a +non-@code{nil} value, and also using the @code{:after} keyword. In +this case, you will need to specify how the declared package is to be +loaded: for example, by some @code{:bind}. If you are not using one +of the keywords that registers autoloads, such as @code{:bind} or +@code{:hook}, and your package manager does not provide autoloads, it +is possible that your package will never be loaded if you do not add +@code{:demand t} to those declarations. + +@node Load dependencies +@section Prevent loading if dependencies are missing + +@findex :requires +While the @code{:after} keyword delays loading until the dependencies +are loaded, the somewhat simpler @code{:requires} keyword @emph{never} +loads the package if the dependencies are not available when the +@code{use-package} declaration is evaluated. In this context, +``available'' means that @code{foo} is available if @w{@code{(featurep +'foo)}} evaluates to a non-@code{nil} value. For example: + +@lisp +(use-package abbrev + :requires foo) @end lisp -When you nest selectors, such as @code{(:any (:all foo bar) (:all baz quux))}, it -means that the package will be loaded when either both @code{foo} and @code{bar} have -been loaded, or both @code{baz} and @code{quux} have been loaded. +This is the same as: -@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 -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. +@lisp +(use-package abbrev + :if (featurep 'foo)) +@end lisp -@node @code{bind-keymap} @code{bind-keymap*} -@section @code{:bind-keymap}, @code{:bind-keymap*} +As a convenience, a list of such packages may be specified: -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 -is actually a keymap, since keymaps are not functions, and cannot be -autoloaded using Emacs' @code{autoload} mechanism. +@lisp +(use-package abbrev + :requires (foo bar baz)) +@end lisp + +For more complex logic, such as that supported by @code{:after}, +simply use @code{:if} and the appropriate Lisp expression. + +@node Load path +@section Setting a custom @code{load-path} -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" -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 -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. +If a package resides in some directory that is not in your +@code{load-path}, use the @code{:load-path} keyword to add it. It +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}. For example: @lisp -(use-package projectile - :bind-keymap - ("C-c p" . projectile-command-map) +(use-package ess-site + :load-path "site-lisp/ess/lisp/" + :commands R) +@end 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 that 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 fixed at +whatever was determined during compilation, to avoid looking up the +same information again on each startup. For example: + +@lisp +(eval-and-compile + (defun ess-site-load-path () + (shell-command "find ~ -path ess/lisp"))) + +(use-package ess-site + :load-path (lambda () (list (ess-site-load-path))) + :commands R) @end lisp -@node @code{bind} @code{bind*} -@section @code{:bind}, @code{:bind*} +@node Manual autoloads +@section Setting up autoloads manually -Another common thing to do when loading a module is to bind a key to primary -commands within that module: +@findex :commands +@findex :autoload +To autoload an interactive command, use the @code{:commands} keyword. +When you use the @code{:commands} keyword, it creates autoloads for +those commands (which defers loading of the module until they are +used). The @code{:commands} keyword takes either a symbol or a list +of symbols. + +The @code{:autoload} keyword works like @code{:commands}, but is used +to autoload non-interactive functions. Here is an example: @lisp -(use-package ace-jump-mode - :bind ("C-." . ace-jump-mode)) +(use-package org-crypt + :autoload org-crypt-use-before-save-magic) @end lisp -This does two things: first, it creates an autoload for the @code{ace-jump-mode} -command and defers loading of @code{ace-jump-mode} until you actually use it. -Second, it binds the key @code{C-.} to that command. After loading, you can use -@code{M-x describe-personal-keybindings} to see all such keybindings you've set -throughout your @code{.emacs} file. +@c ---------------------------------------------------------------------------- +@node Configuring Packages +@chapter Configuring Packages -A more literal way to do the exact same thing is: +This chapter describes the various keywords provided by +@code{use-package} that helps you configure packages. + +@menu +* Lisp Configuration:: Using Lisp to configure packages. +* Key bindings:: Making your own keybindings. +* Hooks:: Adding functions to hooks. +* Modes and interpreters:: Enabling modes automatically. +* Magic handlers:: Using regexps to enable modes. +* User options:: Setting user options. +* Faces:: Customizing faces. +* Hiding minor modes:: Tidying up the mode line. +@end menu + +@node Lisp Configuration +@section Using Lisp code for configuring packages + +The most general way to add customizations are the @code{:preface}, +@code{:init}, and @code{:config} keywords. They all accept one or +more Emacs Lisp forms, up to the next keyword, that are evaluated in +order. This lets you add arbitrary Lisp code to your +@code{use-package} declarations. + +The only difference between these keywords is when they are evaluated. + +@menu +* Preface keyword:: Evaluate code before anything else. +* Init keyword:: Evaluate code before loading package. +* Config keyword:: Evaluate code after loading package. +* Best practices:: When to use @code{:config}, @code{:init}, and @code{:preface}. +@end menu + +@node Preface keyword +@subsection @code{:preface} is evaluated first + +@findex :preface +The @code{:preface} section is evaluated before anything else, except +@code{:disabled} and @code{:ensure}. It can be used to establish +function and variable definitions that will: + +@enumerate +@item +Make the byte-compiler happy. It will not complain about functions +whose definitions are unknown because you have them within a guard +block. + +@item +Define code that can be used in an @code{:if} test. +@end enumerate + +Note that whatever is specified within @code{:preface} is evaluated +both at load time and at byte-compilation time, in order to ensure +that definitions are seen by both the Lisp evaluator and the +byte-compiler. Therefore, you should avoid having any side-effects in +your preface, and restrict it to symbol declarations and definitions. + +@node Init keyword +@subsection @code{:init} is evaluated before loading package + +@findex :init +The @code{:init} section is evaluated just before the package is +loaded. Note that the @code{:init} form is run unconditionally -- +even if the @code{foo} package happens to not exist on your system. +You must therefore remember to restrict @code{:init} code to only what +would succeed either way. @code{:init} also always happens before +package load, whether @code{:config} has been deferred or not. + +@node Config keyword +@subsection @code{:config} is evaluated after loading package + +@findex :config +The @code{:config} section is evaluated after the package has been +loaded. If the package is loaded immediately, this happens +immediately after that, but if loading is done lazily (@pxref{Loading +Packages}), this is deferred until after the package has been loaded. + +In general, you should keep @code{:init} forms as simple and quick as +possible, and put as much as you can get away with into the +@code{:config} section. That way, deferred loading can help your +Emacs start as quickly as possible. + +@node Best practices +@subheading When to use @code{:preface}, @code{:config} and @code{:init}? + +Where possible, it is better to avoid @code{:preface}, @code{:config} +and @code{:init}. Instead, prefer autoloading keywords such as +@code{:bind}, @code{:hook}, and @code{:mode}, as they will take care +of setting up autoloads for you without any need for boilerplate code. +For example, consider the following declaration: @lisp -(use-package ace-jump-mode - :commands ace-jump-mode +(use-package foo :init - (bind-key "C-." 'ace-jump-mode)) + (add-hook 'some-hook 'foo-mode)) +@end lisp + +This has two problems. First, it will unconditionally load the +package @samp{foo} on startup, which will make things slower. You can +fix this by adding @code{:defer t}: + +@lisp +(use-package foo + :defer t + :init + (add-hook 'some-hook 'foo-mode)) +@end lisp + +This is better, as @samp{foo} is now only loaded when it is actually +needed (that is, when the hook @samp{some-hook} is run). + +The second problem is that there is a lot of boilerplate that you have +to write. In this case, it might not be so bad, but avoiding that was +what use-package was made to avoid. The better option in this case is +therefore to use @code{:hook} (@xref{Hooks}), which also implies +@w{@code{:defer t}}. The above is thereby reduced down to: + +@lisp +(use-package foo + :hook some-hook) +@end lisp + +use-package will set up autoloading for you, and your Emacs startup +time will not suffer one bit. + +@node Key bindings +@section Key bindings + +@cindex :bind +@cindex binding keys +@cindex key bindings +One common thing to do when loading a package is to bind a key to +commands within that module. Without use-package, this would be done +using a combination of @code{keymap-local-set}, +@code{keymap-global-set} and various autoloads. With use-package, you +can simplify this using the @code{:bind} keyword. + +@menu +* Global keybindings:: Bindings you can use anywhere. +* Binding in keymaps:: Bindings for particular modes. +* Binding to a keymap:: Binding a key to a keymap. +* Binding to repeat-maps:: Binding repeating keys. +* Displaying keybindings:: Displaying personal key bindings. +@end menu + +@node Global keybindings +@subsection Global keybindings + +To bind keys globally, the @code{:bind} keyword takes either a single +cons or a list of conses. Every cons has the form @code{(@var{key} +. @var{command}}, where @var{key} is a string indicating the key to +bind, and @var{command} is the name of a command (a symbol). The +syntax for the keys is similar to the syntax used by the @code{kbd} +function (@pxref{Init Rebinding,,, emacs, GNU Emacs Manual} for more +information). + +@subheading Using @code{:bind} with a single cons + +Here is an example of using a single cons: + +@lisp +(use-package ace-jump-mode + :bind ("C-." . ace-jump-mode)) @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 -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. +This does two things: first, it creates an autoload for the +@code{ace-jump-mode} command and defers loading of the +@code{ace-jump-mode} package until you actually use it. Second, it +binds the key @code{C-.} to that command globally. -The @code{:bind} keyword takes either a cons or a list of conses: +@subheading Using @code{:bind} with a list of conses + +Here is an example of using @code{:bind} with a list of conses: @lisp (use-package hi-lock @@ -399,11 +756,12 @@ The @code{:bind} keyword takes either a cons or a list of conses: ("M-o w" . highlight-phrase))) @end lisp -The @code{:commands} keyword likewise takes either a symbol or a list of symbols. +@subheading Using special keys -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 -the "kbd" syntax: see @uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html, the Emacs Manual} for more information. +Inside key strings, special keys like @kbd{TAB} or @kbd{F1}--@kbd{F12} +have to be written inside angle brackets, e.g. @code{"C-"}. +Standalone special keys (and some combinations) can be written in +square brackets, e.g.@ @code{[tab]} instead of @code{""}. Examples: @@ -415,16 +773,63 @@ Examples: ([S-f10] . helm-recentf))) @end lisp -@menu -* Binding to local keymaps:: -@end menu +@subheading Remapping commands + +Remapping commands with @code{:bind} and @code{bind-key} works as +expected, because when the binding is a vector, it is passed straight +to @code{define-key}. @xref{Remapping Commands,,, elisp, GNU Emacs +Lisp Reference Manual}) for more information about command remapping. +For example, the following declaration will rebind +@code{fill-paragraph} (bound to @kbd{M-q} by default) to +@code{unfill-toggle}: + +@lisp +(use-package unfill + :bind ([remap fill-paragraph] . unfill-toggle)) +@end lisp + +@subheading What @code{:bind} does behind the scenes + +To understand what @code{:bind} does behind the scenes, it might be +useful to consider an example: -@node Binding to local keymaps -@subsection Binding to local keymaps +@lisp +(use-package ace-jump-mode + :bind ("C-." . ace-jump-mode)) +@end lisp -Slightly different from binding a key to a keymap, is binding a key @strong{within} a -local keymap that only exists after the package is loaded. @code{use-package} -supports this with a @code{:map} modifier, taking the local keymap to bind to: +This could be expressed in a much more verbose way with the +@code{:commands} and @code{:init} keywords. + +@lisp +(use-package ace-jump-mode + :commands ace-jump-mode + :init + (bind-key "C-." 'ace-jump-mode)) +@end lisp + +Without using even the @code{:commands} keyword, we could also write +the above like so: + +@lisp +(use-package ace-jump-mode + :defer t + :init + (autoload 'ace-jump-mode "ace-jump-mode" nil t) + (bind-key "C-." 'ace-jump-mode)) +@end lisp + +Although these three forms are all equivalent, the first form is +usually the best, as it will save some typing. + +@node Binding in keymaps +@subsection Key bindings in local keymaps + +@findex :map, inside :bind +Slightly different from binding a key to a keymap, is binding a key +@emph{within} a local keymap that only exists after the package is +loaded. @code{use-package} supports this with a @code{:map} modifier, +taking the local keymap to bind to: @lisp (use-package helm @@ -432,12 +837,13 @@ supports this with a @code{:map} modifier, taking the local keymap to bind to: ("C-c h" . helm-execute-persistent-action))) @end lisp -The effect of this statement is to wait until @code{helm} has loaded, and then to -bind the key @code{C-c h} to @code{helm-execute-persistent-action} within Helm's local -keymap, @code{helm-mode-map}. +The effect of this statement is to wait until @code{helm} has loaded, +and then to bind the key @code{C-c h} to +@code{helm-execute-persistent-action} within Helm's local keymap, +@code{helm-command-map}. -Multiple uses of @code{:map} may be specified. Any binding occurring before the -first use of @code{:map} are applied to the global keymap: +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 (use-package term @@ -451,155 +857,337 @@ first use of @code{:map} are applied to the global keymap: ("M-n" . term-send-down))) @end lisp -@node @code{commands} -@section @code{:commands} +@node Binding to a keymap +@subsection Binding to keymaps -@node @code{preface} @code{init} @code{config} -@section @code{:preface}, @code{:init}, @code{:config} +@findex :bind-keymap, inside :bind +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 is actually a keymap, since keymaps are not functions, +and cannot be autoloaded using the built-in @code{autoload} function. -Here is the simplest @code{use-package} declaration: +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'' 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 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. + +For example: @lisp -;; This is only needed once, near the top of the file -(eval-when-compile - ;; Following line is not needed if use-package.el is in ~/.emacs.d - (add-to-list 'load-path "") - (require 'use-package)) +(use-package foo + :bind-keymap ("C-c p" . foo-command-map)) +@end lisp -(use-package foo) +@node Binding to repeat-maps +@subsection Binding to repeat-maps + +@findex :repeat-map, inside :bind +@cindex repeat-mode and use-package, using +A special case of binding within a local keymap is when that keymap is +used by @code{repeat-mode} @pxref{Repeating,,, emacs, GNU Emacs +Manual}. These keymaps are usually defined specifically for +this. Using the @code{:repeat-map} keyword, and passing it a name for +the map it defines, will bind all following keys inside that map, and +(by default) set the @code{repeat-map} property of each bound command +to that map. + +The following example creates a keymap called +@code{git-gutter+-repeat-map}, makes four bindings in it as above, +then sets the @code{repeat-map} property of each bound command +(@code{git-gutter+-next-hunk} @code{git-gutter+-previous-hunk}, +@code{git-gutter+-stage-hunks} and @code{git-gutter+-revert-hunk}) to +that keymap. + +@lisp +(use-package git-gutter+ + :bind + (:repeat-map git-gutter+-repeat-map + ("n" . git-gutter+-next-hunk) + ("p" . git-gutter+-previous-hunk) + ("s" . git-gutter+-stage-hunks) + ("r" . git-gutter+-revert-hunk))) @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 -succeeds, a message about @code{"Loading foo"} is logged, along with the time it -took to load, if it took over 0.1 seconds. +@findex :exit, inside :repeat-map and :bind +Specifying @code{:exit} inside the scope of @code{:repeat-map} will +prevent the @code{repeat-map} property being set, so that the command +can be used from within the repeat map, but after it using it the repeat +map will no longer be available. This is useful for commands often used +at the end of a series of repeated commands: + +@lisp +(use-package git-gutter+ + :bind + (:repeat-map my/git-gutter+-repeat-map + ("n" . git-gutter+-next-hunk) + ("p" . git-gutter+-previous-hunk) + ("s" . git-gutter+-stage-hunks) + ("r" . git-gutter+-revert-hunk) + :exit + ("c" . magit-commit-create) + ("C" . magit-commit) + ("b" . magit-blame))) +@end lisp -Use the @code{:init} keyword to execute code before a package is loaded. It -accepts one or more forms, up until the next keyword: +@findex :continue, inside :repeat-map and :bind +Specifying @code{:continue} @emph{forces} setting the +@code{repeat-map} property (just like @emph{not} specifying +@code{:exit}), so the above snippet is equivalent to: @lisp -(use-package foo - :init - (setq foo-variable t)) +(use-package git-gutter+ + :bind + (:repeat-map my/git-gutter+-repeat-map + :exit + ("c" . magit-commit-create) + ("C" . magit-commit) + ("b" . magit-blame) + :continue + ("n" . git-gutter+-next-hunk) + ("p" . git-gutter+-previous-hunk) + ("s" . git-gutter+-stage-hunks) + ("r" . git-gutter+-revert-hunk))) @end lisp -Similarly, @code{:config} can be used to execute code after a package is loaded. -In cases where loading is done lazily (see more about autoloading below), this -execution is deferred until after the autoload occurs: +@node Displaying keybindings +@subsection Displaying personal keybinding + +@findex describe-personal-keybindings +The @code{:bind} keyword uses the @code{bind-keys} macro from the +@samp{bind-key.el} library to set up keybindings. It keeps track of +all keybindings you make, so that you can display them separately from +the default keybindings. + +Use @w{@code{M-x describe-personal-keybindings}} to see all +keybindings you've set using either the @code{:bind} keyword or the +@code{bind-keys} macro. + +@node Hooks +@section Hooks + +@cindex hooks +The @code{:hook} keyword allows adding functions onto hooks. It takes +one argument of the form @var{hooks}, specifying one or more functions +to add to one or more hooks. For the purposes of @code{:hook}, the +name of hook variables should always exclude the @samp{-hook} suffix. +It is appended automatically for you, to save some typing. + +For example, consider the following @code{use-package} declaration +that sets up autoloads for @code{company-mode} from the @samp{company} +package, and adds @samp{company-mode} to @code{prog-mode-hook}: @lisp -(use-package foo +(use-package company + :commands company-mode :init - (setq foo-variable t) - :config - (foo-mode 1)) + (add-hook 'prog-mode-hook #'company-mode)) @end lisp -As you might expect, you can use @code{:init} and @code{:config} together: +Using @code{:hook}, this can be simplified to: @lisp -(use-package color-moccur - :commands (isearch-moccur isearch-all) - :bind (("M-s O" . moccur) - :map isearch-mode-map - ("M-o" . isearch-moccur) - ("M-O" . isearch-moccur-all)) +(use-package company + :hook (prog-mode . company-mode)) +@end lisp + +Here, @code{:hook} will automatically set up autoloads for the +@code{company-mode} command, so there is no need to use +@code{:commands}. + +The @code{:hook} keyword will also assume that the name of the +function you want to add is the same as the package name with +@samp{-mode} appended to it. Taking this into account, you can +simplify the above to the equivalent: + +@lisp +(use-package company + :hook prog-mode) +@end lisp + +@cindex multiple hooks +You can also provide a list of hooks. When multiple hooks should be +applied, the following examples are all equivalent: + +@lisp +(use-package company + :hook (prog-mode text-mode)) + +(use-package company + :hook ((prog-mode text-mode) . company-mode)) + +(use-package company + :hook ((prog-mode . company-mode) + (text-mode . company-mode))) + +(use-package company + :commands company-mode :init - (setq isearch-lazy-highlight t) + (add-hook 'prog-mode-hook #'company-mode) + (add-hook 'text-mode-hook #'company-mode)) +@end lisp + +One common mistake when using @code{:hook} is to forget to omit the +@samp{-hook} suffix, which, as already explained, is appended +automatically. Therefore, the following will not work, as it attempts +to add a function to non-existent @code{prog-mode-hook-hook}: + +@lisp +;; DOES NOT WORK +(use-package ace-jump-mode + :hook (prog-mode-hook . ace-jump-mode)) +@end lisp + +@vindex use-package-hook-name-suffix +If you do not like this behavior, you can customize the user option +@code{use-package-hook-name-suffix} to @code{nil}. The value of this +variable is @samp{"-hook"} by default. + +The use of @code{:hook}, as with @code{:bind}, @code{:mode}, +@code{:interpreter}, etc., causes the functions being hooked to +implicitly be read as @code{:commands}. This means that they will +establish interactive @code{autoload} definitions for that module, if +not already defined as functions), and so @code{:defer t} is also +implied by @code{:hook}. + +@node Modes and interpreters +@section Modes and interpreters + +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 +cells, or a string or regexp: + +@lisp +(use-package ruby-mode + :mode "\\.rb\\'" + :interpreter "ruby") + +;; The package is "python" but the mode is "python-mode": +(use-package python + :mode ("\\.py\\'" . python-mode) + :interpreter ("python" . python-mode)) +@end lisp + +@node Magic handlers +@section Magic handlers + +@findex :magic +@findex :magic-fallback +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 @code{:magic} and @code{:magic-fallback}, is +that the latter has a lower priority than @code{:mode}. + +Here is an example: + +@lisp +(use-package pdf-tools + :magic ("%PDF" . pdf-view-mode) :config - (use-package moccur-edit)) + (pdf-tools-install :no-query)) @end lisp -In this case, I want to autoload the commands @code{isearch-moccur} and -@code{isearch-all} from @code{color-moccur.el}, and bind keys both at the global level -and within the @code{isearch-mode-map} (see next section). When the package is -actually loaded (by using one of these commands), @code{moccur-edit} is also -loaded, to allow editing of the @code{moccur} buffer. +This registers an autoloaded command for @code{pdf-view-mode}, defers +loading of @code{pdf-tools}, and runs @code{pdf-view-mode} if the +beginning of a buffer matches the string @code{"%PDF"}. -@node @code{custom} -@section @code{:custom} +@node User options +@section User options -The @code{:custom} keyword allows customization of package custom variables. +@findex :custom +In Emacs, you normally set customizable variables (user options) using +the @code{M-x customize} interface (@pxref{Easy Customization,,, +emacs, GNU Emacs Manual}). We recommended this method for most users. +However, it is also possible to set them in your @code{use-package} +declarations by using the @code{:custom} keyword. @lisp (use-package comint + :defer t :custom (comint-buffer-maximum-size 20000 "Increase comint buffer size.") (comint-prompt-read-only t "Make the prompt read only.")) @end lisp -The documentation string is not mandatory. +This is better than using @code{setq} in a @code{:config} block, as +customizable variables might have some code associated with it that +Emacs will execute when you assign values to them. In Emacs 29, there +is also the new @code{setopt} macro that does this for you. -@node @code{custom-face} -@section @code{:custom-face} +Note that the values customized using this keyword are @emph{not} +saved in the standard Emacs @code{custom-file}. You should therefore +set each user option using either the @code{:custom} keyword @emph{or} +@w{@code{M-x customize-option}}, which will save customized values in +the Emacs @code{custom-file}. Do not use both for the same variable, +as this risk having conflicting values in your use-package declaration +and your @code{custom-file}. This can lead to problems that are both +tricky and tedious to debug. -The @code{:custom-face} keyword allows customization of package custom faces. +@node Faces +@section Faces + +The @code{:custom-face} keyword allows customization of package custom +faces. @lisp (use-package eruby-mode :custom-face (eruby-standard-face ((t (:slant italic))))) -@end lisp -@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 -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. +(use-package example + :custom-face + (example-1-face ((t (:foreground "LightPink")))) + (example-2-face ((t (:foreground "LightGreen"))) face-defspec-spec)) -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. +(use-package zenburn-theme + :preface + (setq my/zenburn-colors-alist + '((fg . "#DCDCCC") (bg . "#1C1C1C") (cyan . "#93E0E3"))) + :custom-face + (region ((t (:background ,(alist-get my/zenburn-colors-alist 'cyan))))) + :config + (load-theme 'zenburn t)) +@end lisp -@node @code{defines} @code{functions} -@section @code{:defines}, @code{:functions} +@node Hiding minor modes +@section Hiding minor modes with diminish and delight -Another feature of @code{use-package} is that it always loads every file that it -can when @code{.emacs} is being byte-compiled. This helps to silence spurious -warnings about unknown variables and functions. +@code{use-package} supports the diminish and delight packages, both of +which make it possible remove or change minor mode strings in your +mode-line. Which one to use is up to you, but you should normally +only use one or the other -- never both.@footnote{When in doubt, you +might as well use diminish.} To use either of them, you must first +install the corresponding package from @acronym{GNU ELPA}. -However, there are times when this is just not enough. For those times, use -the @code{:defines} and @code{:functions} keywords to introduce dummy variable and -function declarations solely for the sake of the byte-compiler: +@menu +* Diminish:: Hiding minor modes with Diminish. +* Delight:: Hiding minor modes with Delight. +@end menu -@lisp -(use-package texinfo - :defines texinfo-section-list - :commands texinfo-mode - :init - (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode))) -@end lisp +@node Diminish +@subsection Diminish -If you need to silence a missing function warning, you can use @code{:functions}: +@findex :diminish +When diminish@footnote{The diminish package is installable from +@acronym{GNU ELPA}.} is installed, you can use the @code{:diminish} +keyword. First, add the following declaration to the beginning of +your init file. The optional @w{@code{:ensure t}} makes sure the +package is installed if it isn't already (@pxref{Installing +packages}). @lisp -(use-package ruby-mode - :mode "\\.rb\\'" - :interpreter "ruby" - :functions inf-ruby-keys - :config - (defun my-ruby-mode-hook () - (require 'inf-ruby) - (inf-ruby-keys)) - - (add-hook 'ruby-mode-hook 'my-ruby-mode-hook)) +(use-package diminish :ensure t) @end lisp -@node @code{diminish} @code{delight} -@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 -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 -minor mode symbol, a cons of the symbol and its replacement string, or just a -replacement string, in which case the minor mode symbol is guessed to be the -package name with "-mode" appended at the end: +The @code{:diminish} keyword takes either a minor mode symbol, a cons +of the symbol and its replacement string, or just a replacement +string, in which case the minor mode symbol is guessed to be the +package name with @samp{-mode} appended at the end: @lisp (use-package abbrev @@ -609,11 +1197,26 @@ package name with "-mode" appended at the end: (quietly-read-abbrev-file))) @end lisp -@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, -the default mode name is hidden completely. +@node Delight +@subsection Delight + +@findex :delight +When delight@footnote{The @samp{delight} package is installable from +GNU ELPA.} is installed, you can use the @code{:delight} keyword. +First, add the following declaration to the beginning of your init +file. The optional @w{@code{:ensure t}} makes sure the package is +installed if it isn't already (@pxref{Installing packages}). + +@lisp +(use-package delight :ensure t) +@end lisp + +The @code{:delight} keyword takes a minor mode symbol, a replacement +string, or quoted mode line data (in which case the minor mode symbol +is guessed to be the package name with @samp{-mode} appended at the +end), both of these, or several lists of both. @xref{Mode Line +Data,,, elisp, GNU Emacs Lisp Reference Manual}. If no arguments are +provided, the default mode name is hidden completely. @lisp ;; Don't show anything for rainbow-mode. @@ -636,30 +1239,31 @@ the default mode name is hidden completely. (visual-line-mode)) @end lisp -@node @code{disabled} -@section @code{:disabled} +@c ---------------------------------------------------------------------------- +@node Installing packages +@chapter Installing packages automatically -The @code{:disabled} keyword can turn off a module you're having difficulties with, -or stop loading something you're not using at the present time: +The standard Emacs package manager is documented in the Emacs manual +(@pxref{Package Installation,,, emacs, GNU Emacs Manual}). The +@code{use-package} macro provides the @code{:ensure} and @code{:pin} +keywords, that interface with that package manager to automatically +install packages. This is particularly useful if you use your init +file on more than one system. -@lisp -(use-package ess-site - :disabled - :commands R) -@end lisp +@menu +* Install package:: +* Pinning packages:: +* Other package managers:: +@end menu -When byte-compiling your @code{.emacs} file, disabled declarations are omitted -from the output entirely, to accelerate startup times. +@node Install package +@section Installing package -@node @code{ensure} @code{pin} -@section @code{:ensure}, @code{:pin} +The @code{:ensure} keyword makes use-package ask the Emacs package +manager to install a package if it is not already present on your +system. -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 -not already present on your system (set @code{(setq use-package-always-ensure t)} -if you wish this behavior to be global for all packages): +For example: @lisp (use-package magit @@ -667,280 +1271,543 @@ if you wish this behavior to be global for all packages): @end lisp If you need to install a different package from the one named by -@code{use-package}, you can specify it like this: +@code{use-package}, you can use a symbol: @lisp (use-package tex :ensure auctex) @end lisp -Lastly, when running on Emacs 24.4 or later, use-package can pin a package to -a specific archive, allowing you to mix and match packages from different -archives. The primary use-case for this is preferring packages from the -@code{melpa-stable} and @code{gnu} archives, but using specific packages from @code{melpa} -when you need to track newer versions than what is available in the @code{stable} -archives is also a valid use-case. +You can customize the user option @code{use-package-always-ensure} to +non-@code{nil} if you want this behavior to be global for all +packages. -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 -set @code{use-package-always-pin} to set a default. +@lisp +(require 'use-package-ensure) +(setq use-package-always-ensure t) +@end lisp -If you want to manually keep a package updated and ignore upstream updates, -you can pin it to @code{manual}, which as long as there is no repository by that -name, will Just Work(tm). +@noindent +You can override the above setting for a single package by adding +@w{@code{:ensure nil}} to its declaration. -@code{use-package} throws an error if you try to pin a package to an archive that -has not been configured using @code{package-archives} (apart from the magic -@code{manual} archive mentioned above): +@node Pinning packages +@section Pinning packages using @code{:pin} -@example -Archive 'foo' requested for package 'bar' is not available. -@end example +@findex :pin +use-package can pin a package to a specific archive using the +@code{:pin} keyword.@footnote{The @code{:pin} keyword has no effect on +Emacs versions older than 24.4.} This allows you to mix and match +packages from different archives. The primary use-case for this is +preferring to install packages from @acronym{GNU ELPA} or +@acronym{NonGNU ELPA} (indicated by @code{gnu} and @code{nongnu}, +respectively), while installing specific packages from third-party +archives. -Example: +For example: @lisp (use-package company :ensure t - :pin melpa-stable) + :pin gnu) ; GNU ELPA +@end lisp -(use-package evil - :ensure t) - ;; no :pin needed, as package.el will choose the version in melpa +@vindex use-package-always-pin +Unfortunately, the third-party archive @acronym{MELPA} uses a +versioning scheme based on dates, which means that packages from that +archive are always preferred. If you are using that archive, we +strongly encourage you to customize @code{use-package-always-pin} to +@code{nongnu}. This guarantees that you are using a version of that +package that has been specifically marked for release by its +developer, and not a development snapshot. + +@c FIXME: This needs clarifying. AFAIK, :ensure does not update packages. +If you want to manually keep a package updated and ignore upstream +updates, you can pin it to @samp{manual}. This will work as long as +you have not customized a repository to use that name in the +@code{package-archives} variable. -(use-package adaptive-wrap - :ensure t - ;; as this package is available only in the gnu archive, this is - ;; technically not needed, but it helps to highlight where it - ;; comes from - :pin gnu) +Example: +@lisp (use-package org :ensure t ;; ignore org-mode from upstream and use a manually installed version :pin manual) @end lisp -@strong{NOTE}: the @code{:pin} argument has no effect on emacs versions < 24.4. +@code{use-package} signals an error if you try to pin a package to an +archive that is not configured using @code{package-archives} (except +from the special @samp{manual} archive). + +@node Other package managers +@section Non-standard package managers + +By default, use-package assumes that you are using the built-in +@code{package.el} package manager. We expect that most users will +find that it is more than capable enough, even for advanced use cases. + +@vindex use-package-ensure-function +However, some users might prefer to use a third-party package manager +for a specific circumstance or use case. By setting the user option +@code{use-package-ensure-function} to the name of a function, you can +direct @code{:ensure} to use a different package manager for +installing packages. + +For more details, please see the documentation of the package manager +you are using. If you run into any bugs, it is often best to report +them directly to the developers of that package manager. + +@c ---------------------------------------------------------------------------- +@node Byte-compiling +@chapter Byte-compiling your init file + +Some users might want to byte-compile their init file to make Emacs +startup even faster. This is not recommended in most cases, as the +speed-up is often too small to be worth it, and can lead to confusion +if the byte-compiled files are out-of-date. If you still want to do +it, read on. + +@code{use-package} always loads every library that it can while a file +is being byte-compiled. This helps silence spurious warnings about +unknown variables and functions. + +@findex :defines +@findex :functions +However, there are times when this is just not enough. For those +times, use the @code{:defines} and @code{:functions} keywords to +introduce dummy variable and function declarations solely for the sake +of silencing byte-compiler warnings. For example: -@node @code{hook} -@section @code{:hook} +@lisp +(use-package texinfo + :defines texinfo-section-list + :commands texinfo-mode + :init + (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode))) +@end lisp -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: +If you need to silence a missing function warning, you can use +@code{:functions}: @lisp -(use-package ace-jump-mode - :hook prog-mode) - -(use-package ace-jump-mode - :hook (prog-mode . ace-jump-mode)) +(use-package ruby-mode + :mode "\\.rb\\'" + :interpreter "ruby" + :functions inf-ruby-keys + :config + (defun my-ruby-mode-hook () + (require 'inf-ruby) + (inf-ruby-keys)) -(use-package ace-jump-mode - :commands ace-jump-mode - :init - (add-hook 'prog-mode-hook #'ace-jump-mode)) + (add-hook 'ruby-mode-hook 'my-ruby-mode-hook)) @end lisp -And likewise, when multiple hooks should be applied, the following are also -equivalent: +@findex :no-require +@cindex prevent a package from loading at compile-time +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 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 such cases, use +the @code{:no-require} keyword: @lisp -(use-package ace-jump-mode - :hook (prog-mode text-mode)) +(use-package foo + :no-require t + :config + (message "Evaluate this immediately after loading `foo'")) +@end lisp -(use-package ace-jump-mode - :hook ((prog-mode text-mode) . ace-jump-mode)) +@c ---------------------------------------------------------------------------- +@node Troubleshooting +@chapter Troubleshooting -(use-package ace-jump-mode - :hook ((prog-mode . ace-jump-mode) - (text-mode . ace-jump-mode))) +@cindex troubleshooting +@cindex debugging +If an error occurs while initializing or configuring a package, this +will not stop your Emacs from loading. Instead, @code{use-package} +captures the error and reports it in a special @code{*Warnings*} popup +buffer, so that you can debug the situation in an otherwise functional +Emacs. -(use-package ace-jump-mode - :commands ace-jump-mode - :init - (add-hook 'prog-mode-hook #'ace-jump-mode) - (add-hook 'text-mode-hook #'ace-jump-mode)) -@end lisp +If you are having trouble when starting Emacs, you can pass Emacs the +@samp{--debug-init} command line flag. @xref{Initial Options,,, +emacs, GNU Emacs Manual}. To get even more information when using +that flag, add the following to your init file (these options are +documented below): -The use of @code{:hook}, as with @code{:bind}, @code{:mode}, @code{:interpreter}, etc., causes the -functions being hooked to implicitly be read as @code{:commands} (meaning they will -establish interactive @code{autoload} definitions for that module, if not already -defined as functions), and so @code{:defer t} is also implied by @code{:hook}. +@lisp +(when init-file-debug + (setq use-package-verbose t + use-package-expand-minimally nil + use-package-compute-statistics t + debug-on-error t)) +@end lisp -@node @code{if} @code{when} @code{unless} -@section @code{:if}, @code{:when}, @code{:unless} +@cindex reporting bugs +@cindex expanding macro, for troubleshooting +Since @code{use-package} is a macro, the first step when you need to +dig deeper is usually to see what Emacs Lisp code your declaration +expands to. You can either use the command @w{@kbd{M-x +pp-macroexpand-last-sexp}}, or wrap the use-package declaration in +@code{macroexpand} and evaluate it. It is a good idea to include +their output in any bugs you file for use-package. -You can use the @code{:if} keyword to predicate the loading and initialization of -modules. +@menu +* Troubleshooting Options:: +* Gathering Statistics:: +* Disabling a package:: +@end menu -For example, I only want @code{edit-server} running for my main, graphical Emacs, -not for other Emacsen I may start at the command line: +@node Troubleshooting Options +@section Options that help when troubleshooting + +@vindex use-package-expand-minimally +By default, use-package will attempts to catch and report errors that +occur during expansion of use-package declarations in your init file. +Customize the user option @code{use-package-expand-minimally} to a +non-@code{nil} value to disable this checking. + +@findex :catch +This behavior may be overridden locally using the @code{:catch} +keyword. If @code{t} or @code{nil}, it enables or disables catching +errors at load time. It can also be a function taking two arguments: +the keyword being processed at the time the error was encountered, and +the error object (as generated by @code{condition-case}). For +example: @lisp -(use-package edit-server - :if window-system - :init - (add-hook 'after-init-hook 'server-start t) - (add-hook 'after-init-hook 'edit-server-start t)) +(use-package example + ;; Note that errors are never trapped in the preface, since doing so would + ;; hide definitions from the byte-compiler. + :preface (message "I'm here at byte-compile and load time") + :init (message "I'm always here at startup") + :config + (message "I'm always here after the package is loaded") + (error "oops") + ;; Don't try to (require 'example), this is just an example! + :no-require t + :catch (lambda (keyword err) + (message (error-message-string err)))) @end lisp -In another example, we can load things conditional on the operating system: +Evaluating the above form will print these messages: + +@verbatim +I’m here at byte-compile and load time +I’m always here at startup +Configuring package example... +I’m always here after the package is loaded +oops +@end verbatim + +@node Gathering Statistics +@section Gathering Statistics + +@vindex use-package-verbose +When a package is loaded, and if you have @code{use-package-verbose} +set to @code{t}, or if the package takes longer than 0.1 seconds to +load, you will see a message to indicate this loading activity in the +@code{*Messages*} buffer. The same will happen for configuration, or +@code{:config} blocks, that take longer than 0.1 seconds to execute. + +@vindex use-package-compute-statistics +If you'd like to see a summary how many packages you've loaded, what +stage of initialization they've reached, and how much aggregate time +they've spent (roughly), you can customize the user option +@code{use-package-compute-statistics} to a non-@code{nil} value. Then +reload your packages, normally by restarting Emacs, to make sure that +use-package can gather statistics for all your packages. + +@cindex use-package-report +Run the command @code{M-x use-package-report} to see the results. The +buffer displayed is a tabulated list. To sort rows based on a +particular column, move point to it and type @kbd{S}, or click the +column name at the top of the buffer on graphical displays. + +Note that, if you are setting @code{use-package-compute-statistics} +directly in your init file, and not with @code{customize}, you must do +this after loading @code{use-package} but before any +@code{use-package} forms. + +@node Disabling a package +@section Disabling a package + +@cindex disable package +@findex :disabled +The @code{:disabled} keyword inhibits loading a package, and all it's +customizations. It is equivalent to commenting out or deleting the +definition. + +You could use this, for example, to temporarily disable a package that +you're having difficulties with, or to avoid loading a package that +you're not currently using. + +This example disables the @samp{foo} package: @lisp -(use-package exec-path-from-shell - :if (memq window-system '(mac ns)) - :ensure t - :config - (exec-path-from-shell-initialize)) +(use-package foo + :disabled) @end lisp -Note that @code{:when} is provided as an alias for @code{:if}, and @code{:unless foo} means -the same thing as @code{:if (not foo)}. +When byte-compiling your init file, use-package omits disabled +declarations from the output entirely, in order to make Emacs startup +faster. + +@c ---------------------------------------------------------------------------- +@node Keyword extensions +@appendix Keyword extensions + +use-package is based on an extensible framework that makes it easy for +package authors to add new keywords, or modify the behavior of +existing keywords. + +Some keyword extensions are included with @code{use-package}, and can +be optionally enabled. + +@menu +* use-package-ensure-system-package:: +* use-package-chords:: +* Creating an extension:: +@end menu + +@node use-package-ensure-system-package +@section :use-package-ensure-system-package -@node @code{load-path} -@section @code{:load-path} +@findex :ensure-system-package +The @code{:ensure-system-package} keyword allows you to ensure certain +executables are available on your system alongside your package +declarations.@footnote{On macOS, you will want to make sure +@code{exec-path} is cognisant of all binary package names that you +would like to ensure are installed. The +@uref{https://github.com/purcell/exec-path-from-shell,@samp{exec-path-from-shell}} +package is often a good way to do this.} -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 -@code{user-emacs-directory}: +To use this extension, add this immediately after loading +@code{use-package}: @lisp -(use-package ess-site - :load-path "site-lisp/ess/lisp/" - :commands R) +(use-package use-package-ensure-system-package) @end 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 fixed at whatever was determined during compilation, to avoid looking -up the same information again on each startup: +Now you can use the @code{:ensure-system-package} keyword. +Here's an example usage: @lisp -(eval-and-compile - (defun ess-site-load-path () - (shell-command "find ~ -path ess/lisp"))) - -(use-package ess-site - :load-path (lambda () (list (ess-site-load-path))) - :commands R) +(use-package foo + :ensure-system-package foo) @end lisp -@node @code{mode} @code{interpreter} -@section @code{:mode}, @code{:interpreter} +This will expect a global binary package to exist called @code{foo}. +If it does not, it will use your system package manager to attempt an +install of a binary by the same name asynchronously. This requires +the GNU ELPA package +@uref{https://gitlab.com/jabranham/system-packages,@samp{system-packages}}, +so for this to work you must install that first. -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 -cells, or a string or regexp: +One way of making sure it is installed is with @code{use-package} +together with @code{:ensure}. @lisp -(use-package ruby-mode - :mode "\\.rb\\'" - :interpreter "ruby") - -;; The package is "python" but the mode is "python-mode": -(use-package python - :mode ("\\.py\\'" . python-mode) - :interpreter ("python" . python-mode)) +(use-package system-packages + :ensure t) @end lisp -If you aren't using @code{:commands}, @code{:bind}, @code{:bind*}, @code{:bind-keymap}, -@code{:bind-keymap*}, @code{:mode}, or @code{:interpreter} (all of which imply @code{:defer}; see -the docstring for @code{use-package} for a brief description of each), you can -still defer loading with the @code{:defer} keyword: +For example, on a @code{Debian GNU/Linux} system, this would call +@samp{apt-get install foo}. + +If the package is named differently than the binary, you can use a +cons in the form of @code{(binary . package-name)}. For example: @lisp -(use-package ace-jump-mode - :defer t - :init - (autoload 'ace-jump-mode "ace-jump-mode" nil t) - (bind-key "C-." 'ace-jump-mode)) +(use-package foo + :ensure-system-package + (foocmd . foo)) @end lisp -This does exactly the same thing as the following: +On a @code{Debian GNU/Linux} system, this would call @code{apt install +foo} if Emacs could not locate the executable +@code{foocmd}.@footnote{For manual testing, you could use the +@code{executable-find} function, which is what @samp{system-packages} +uses internally.} + +@code{:ensure-system-package} can also take a cons where its +@code{cdr} is a string that will get called by +@code{(async-shell-command)} to install if it isn't found. This does +not depend upon any external package. @lisp -(use-package ace-jump-mode - :bind ("C-." . ace-jump-mode)) +(use-package tern + :ensure-system-package (tern . "npm i -g tern")) @end lisp -@node @code{magic} @code{magic-fallback} -@section @code{:magic}, @code{:magic-fallback} +To install several packages, you can pass in a list of conses: + +@lisp +(use-package ruby-mode + :ensure-system-package + ((rubocop . "gem install rubocop") + (ruby-lint . "gem install ruby-lint") + (ripper-tags . "gem install ripper-tags") + (pry . "gem install pry"))) +@end 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: +Finally, in case the package dependency does not provide a global +executable, you can ensure packages exist by checking the presence of a +file path by providing a string like so: @lisp -(use-package pdf-tools - :load-path "site-lisp/pdf-tools/lisp" - :magic ("%PDF" . pdf-view-mode) - :config - (pdf-tools-install)) +(use-package dash-at-point + :if (eq system-type 'darwin) + :ensure-system-package + ("/Applications/Dash.app" . "brew cask install dash")) @end lisp -This registers an autoloaded command for @code{pdf-view-mode}, defers loading of -@code{pdf-tools}, and runs @code{pdf-view-mode} if the beginning of a buffer matches the -string @code{"%PDF"}. +@code{:ensure-system-package} will use @code{system-packages-install} +to install system packages, except where a custom command has been +specified, in which case it will be executed verbatim by +@code{async-shell-command}. + +The user options @code{system-packages-package-manager} and +@code{system-packages-use-sudo} are honored, but not for custom +commands. Custom commands should include the call to sudo in the +command if needed. -@node @code{no-require} -@section @code{:no-require} +@node use-package-chords +@section @code{(use-package-chords)} -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 -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 -such cases, use the @code{:no-require} keyword: +The @code{:chords} keyword allows you to define +@uref{https://www.emacswiki.org/emacs/key-chord.el,@code{key-chord}} +bindings for @code{use-package} declarations in the same manner as the +@code{:bind} keyword. + +To enable the extension: @lisp -(use-package foo - :no-require t - :config - (message "This is evaluated when `foo' is loaded")) +(use-package use-package-chords + :ensure t + :config (key-chord-mode 1)) @end lisp -@node @code{requires} -@section @code{:requires} - -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: +Then you can define your chord bindings in the same manner as +@code{:bind} using a cons or a list of conses: @lisp -(use-package abbrev - :requires foo) +(use-package ace-jump-mode + :chords (("jj" . ace-jump-char-mode) + ("jk" . ace-jump-word-mode) + ("jl" . ace-jump-line-mode))) @end lisp -This is the same as: +@node Creating an extension +@section How to create an extension keyword + +This section describes how to create a new keyword. + +@enumerate +@item +Add the keyword. + +The first step is to add your keyword at the right place in +@code{use-package-keywords}. This list determines the order in which +things will happen in the expanded code. You should never change this +order, but it gives you a framework within which to decide when your +keyword should fire. + +@item +Create a normalizer. + +The job of the normalizer is take a list of arguments (possibly +@code{nil}), and turn it into the single argument (which could still +be a list) that should appear in the final property list used by +@code{use-package}. + +Define a normalizer for your keyword by defining a function named +after the keyword, for example: @lisp -(use-package abbrev - :if (featurep 'foo)) +(defun use-package-normalize/:pin (name-symbol keyword args) + (use-package-only-one (symbol-name keyword) args + (lambda (label arg) + (cond + ((stringp arg) arg) + ((symbolp arg) (symbol-name arg)) + (t + (use-package-error + ":pin wants an archive name (a string)")))))) @end lisp -As a convenience, a list of such packages may be specified: +@item +Create a handler. + +Once you have a normalizer, you must create a handler for the keyword. + +Handlers can affect the handling of keywords in two ways. First, it +can modify the @code{state} plist before recursively processing the +remaining keywords, to influence keywords that pay attention to the +state (one example is the state keyword @code{:deferred}, not to be +confused with the @code{use-package} keyword @code{:defer}). Then, +once the remaining keywords have been handled and their resulting +forms returned, the handler may manipulate, extend, or just ignore +those forms. + +The task of each handler is to return a @emph{list of forms} +representing code to be inserted. It does not need to be a +@code{progn} list, as this is handled automatically in other places. +Thus it is common to see the idiom of using @code{use-package-concat} +to add new functionality before or after a code body, so that only the +minimum code necessary is emitted as the result of a +@code{use-package} expansion. + +This is an example handler: @lisp -(use-package abbrev - :requires (foo bar baz)) +(defun use-package-handler/:pin (name-symbol keyword archive-name rest state) + (let ((body (use-package-process-keywords name-symbol rest state))) + ;; This happens at macro expansion time, not when the expanded code is + ;; compiled or evaluated. + (if (null archive-name) + body + (use-package-pin-package name-symbol archive-name) + (use-package-concat + body + `((push '(,name-symbol . ,archive-name) + package-pinned-packages)))))) @end lisp -For more complex logic, such as that supported by @code{:after}, simply use @code{:if} -and the appropriate Lisp expression. +@item +Test it. + +After the keyword has been inserted into @code{use-package-keywords}, +and a normalizer and a handler defined, you can now test it by seeing +how usages of the keyword will expand. For this, use @code{M-x +pp-macroexpand-last-sexp} with the cursor set immediately after the +@code{(use-package ...)} expression. +@end enumerate + +@c ---------------------------------------------------------------------------- +@node History +@appendix History and acknowledgments + +use-package was written by John Wiegley. Its development started in +2012, and it got merged into Emacs in 2022, in preparation of the +release of Emacs 29.1. + +Dozens of people have contributed to use-package over the years with +bug reports, documentation and code. They are too many to list here, +but we thank them all for their contributions. + +This Texinfo manual was written by Stefan Kangas, as a significant +rewrite of the old use-package manual and @file{README}. -@node Debugging Tools -@chapter Debugging Tools +@node GNU Free Documentation License +@appendix GNU Free Documentation License +@include doclicense.texi -TODO +@node Index +@unnumbered Index +@printindex cp @bye -- 2.39.2