[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
feature/use-package 98e54f597e1: Add new use-package manual
|
From: |
Stefan Kangas |
|
Subject: |
feature/use-package 98e54f597e1: Add new use-package manual |
|
Date: |
Wed, 7 Dec 2022 18:47:18 -0500 (EST) |
branch: feature/use-package
commit 98e54f597e11fa760553bf7b12d8ebb388b5a488
Author: Stefan Kangas <stefankangas@gmail.com>
Commit: Stefan Kangas <stefankangas@gmail.com>
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-<up>"}.
+Standalone special keys (and some combinations) can be written in
+square brackets, e.g.@ @code{[tab]} instead of @code{"<tab>"}.
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 "<path where use-package is installed>")
- (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
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- feature/use-package 98e54f597e1: Add new use-package manual,
Stefan Kangas <=