2387 lines
98 KiB
Plaintext
2387 lines
98 KiB
Plaintext
This is use-package.info, produced by makeinfo version 6.7 from
|
||
use-package.texi.
|
||
|
||
This manual is for use-package, a configuration macro for simplifying
|
||
your init file.
|
||
|
||
Copyright © 2022 Free Software Foundation, Inc.
|
||
|
||
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.”
|
||
INFO-DIR-SECTION Emacs misc features
|
||
START-INFO-DIR-ENTRY
|
||
* use-package: (use-package). Declarative package configuration for Emacs.
|
||
END-INFO-DIR-ENTRY
|
||
|
||
|
||
File: use-package.info, Node: Top, Next: Basic Concepts, Up: (dir)
|
||
|
||
use-package User Manual
|
||
***********************
|
||
|
||
The ‘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.
|
||
|
||
This manual is for use-package, a configuration macro for simplifying
|
||
your init file.
|
||
|
||
Copyright © 2022 Free Software Foundation, Inc.
|
||
|
||
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.”
|
||
|
||
* Menu:
|
||
|
||
* 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::
|
||
|
||
|
||
File: use-package.info, Node: Basic Concepts, Next: Getting Started, Prev: Top, Up: Top
|
||
|
||
1 Basic Concepts
|
||
****************
|
||
|
||
use-package provides the ‘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:
|
||
|
||
1. 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.
|
||
|
||
2. To reduce duplication and boilerplate, capturing several common
|
||
practices as mere keywords both easy and intuitive to use.
|
||
|
||
3. To make startup time of Emacs as quick as possible, without
|
||
sacrificing the quantity of add-on packages used.
|
||
|
||
4. 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.
|
||
|
||
5. 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.
|
||
|
||
It is worth noting that use-package is not intended to replace the
|
||
standard ‘M-x customize’. On the contrary, it is designed to work
|
||
together with it, for things that customize cannot do.
|
||
|
||
|
||
File: use-package.info, Node: Getting Started, Next: Loading Packages, Prev: Basic Concepts, Up: Top
|
||
|
||
2 Getting Started
|
||
*****************
|
||
|
||
This chapter provides instructions and examples for quickly getting
|
||
started with use-package. The first thing you need to do is make sure
|
||
that ‘use-package’ itself is loaded. To do that, put this at the top of
|
||
your init file:
|
||
|
||
(require 'use-package)
|
||
|
||
The above makes the ‘use-macro’ for in the rest of your init file.
|
||
In this manual, we call each call to ‘use-macro’ a “declaration”, to
|
||
highlight the declarative nature of its semantic.
|
||
|
||
To unconditionally load a package named ‘foo’, add the following
|
||
declaration to your init file:
|
||
|
||
(use-package foo)
|
||
|
||
This declaration is equivalent to using ‘require’, with some use-package
|
||
specific error handling added in. Just like require, it needs the
|
||
package ‘foo’ to be installed and available in your ‘load-path’ (*note
|
||
Installing packages::).
|
||
|
||
To evaluate Lisp code _before_ the ‘foo’ package is loaded, use the
|
||
‘:init’ keyword:
|
||
|
||
(use-package foo
|
||
:init
|
||
(setq foo-variable t))
|
||
|
||
Similarly, ‘:config’ can be used to execute code _after_ a package is
|
||
loaded. In cases where loading is done lazily (*note Loading
|
||
Packages::), this execution is deferred until after the autoload occurs.
|
||
As you might expect, you can use ‘:init’ and ‘:config’ together:
|
||
|
||
(use-package foo
|
||
:init
|
||
(setq foo-variable t)
|
||
:config
|
||
(foo-mode 1))
|
||
|
||
The above declarations will all load the ‘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 GNU ELPA that provides it’s own
|
||
autoloads, it is often enough to say:
|
||
|
||
(use-package foo
|
||
:defer t)
|
||
|
||
This will avoid loading the package. Now, when you run any autoloaded
|
||
command, the package ‘foo’ is loaded automatically. Package authors
|
||
will make their own decisions about which commands are marked to
|
||
autoload by default.
|
||
|
||
In some cases, you might need or want to provide your own autoloads.
|
||
The below more complex example autoloads the commands ‘isearch-moccur’
|
||
and ‘isearch-all’ from ‘color-moccur.el’, and binds keys both globally
|
||
and in ‘isearch-mode-map’. When one of these commands are used, the
|
||
package is loaded. At that point, ‘moccur-edit’ is also loaded, to
|
||
allow editing of the ‘moccur’ buffer.
|
||
|
||
(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))
|
||
|
||
Some packages will suggest ready-made ‘use-package’ declarations that
|
||
you can use. Where possible, it is a good idea to copy them, and use
|
||
that as a starting point.
|
||
|
||
That should be enough to get you started!
|
||
|
||
|
||
File: use-package.info, Node: Loading Packages, Next: Configuring Packages, Prev: Getting Started, Up: Top
|
||
|
||
3 Loading Packages
|
||
******************
|
||
|
||
Before use-package can load an Emacs Lisp package, it must be available
|
||
in a directory on your ‘load-path’. When you install packages using the
|
||
built-in ‘install-package’ command, it will do this automatically for
|
||
you. Packages shipped with Emacs (built-in packages) are always
|
||
available.
|
||
|
||
If you install packages manually, you must make sure they are
|
||
available on your ‘load-path’. *Note (emacs)Lisp Libraries:: for
|
||
details.
|
||
|
||
Some packages have more than one library. In those cases, you might
|
||
need more than one ‘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.
|
||
|
||
use-package can interface with ‘package.el’ to install packages on
|
||
Emacs start. *Note Installing packages:: for details.
|
||
|
||
* 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 ‘load-path’.
|
||
* Manual autoloads:: Setting up autoloads manually.
|
||
|
||
|
||
File: use-package.info, Node: Loading basics, Next: Deferring loading, Up: Loading Packages
|
||
|
||
3.1 How and when use-package loads packages
|
||
===========================================
|
||
|
||
The ‘use-package’ macro either will either load a package immediately,
|
||
or when they are first used (autoloading). In the simplest case, a
|
||
‘use-package’ declaration loads a package when it is evaluated.(1) If
|
||
the declaration is in your init file, this happens automatically each
|
||
time Emacs is started.
|
||
|
||
For example, the below declaration immediately loads the library
|
||
‘foo’, just like ‘require’ would. If the library ‘foo’ is not available
|
||
in your ‘load-path’, it logs a warning to the ‘*Messages*’ buffer:
|
||
|
||
(use-package foo)
|
||
|
||
Note that a “package” is different from an Emacs Lisp “library”. The
|
||
above declaration tells use-package to load the _library_ ‘foo.el’,
|
||
which the overwhelming majority of cases also resides in a _package_
|
||
named ‘foo’. But the ‘foo’ package might also contain a library named
|
||
‘foo-extra.el’. If that library is not loaded automatically, you will
|
||
need a separate ‘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.
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) This happens both at run-time and at compile-time. *Note
|
||
Byte-compiling::.
|
||
|
||
|
||
File: use-package.info, Node: Deferring loading, Next: Forcing loading, Prev: Loading basics, Up: Loading Packages
|
||
|
||
3.2 Deferring package loading
|
||
=============================
|
||
|
||
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 ‘M-x’ or some key binding). This is based on
|
||
autoloading, a full description of which is outside the scope of this
|
||
manual. *Note (elisp)Autoload:: for the full story.
|
||
|
||
Some ‘use-package’ keywords provide autoload “triggers” that cause a
|
||
package to be loaded when certain events occur. For example, the
|
||
‘: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
|
||
‘:commands’, ‘:bind’, ‘:bind*’, ‘:bind-keymap’, ‘:bind-keymap*’,
|
||
‘:mode’, and ‘:interpreter’.
|
||
|
||
The ‘:defer’ keyword
|
||
--------------------
|
||
|
||
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 ‘:defer’ keyword. It
|
||
takes one boolean argument: a non-‘nil’ value means to stop this package
|
||
from being immediately loaded. Here is an example of using ‘:defer’ to
|
||
postpone loading the package ‘foo’:
|
||
|
||
(use-package foo
|
||
:defer t)
|
||
|
||
Using ‘:defer t’ by itself like this is rarely useful. Typically,
|
||
you would only use it together with a keyword like ‘:config’ (*note Lisp
|
||
Configuration::), or ‘:ensure’ (*note Installing packages::).
|
||
|
||
Defer loading until idle for N seconds
|
||
--------------------------------------
|
||
|
||
You can also give a numeric argument N to ‘:defer’ to specify that a
|
||
package should be loaded (if it hasn’t already) after Emacs has been
|
||
idle for N seconds. For example, use this to make use-package load
|
||
‘foo’ after 30 seconds of idle time:
|
||
|
||
(use-package foo
|
||
:defer 30)
|
||
|
||
When to use ‘:defer’
|
||
--------------------
|
||
|
||
When using autoloading keywords, there is no need to also use ‘:defer’.
|
||
It doesn’t hurt anything to add it in this case, perhaps for extra
|
||
clarity, but it is redundant.
|
||
|
||
You should use ‘: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 ‘package-install’, as packages
|
||
installed in this way normally always have their own autoloads already
|
||
set up.
|
||
|
||
Making ‘:defer t’ the default
|
||
-----------------------------
|
||
|
||
If you customize the user option ‘use-package-always-defer’ to
|
||
non-‘nil’, the ‘use-package’ macro will behave as if ‘:defer t’ is
|
||
always specified. This can be overridden for individual declarations
|
||
using either ‘:defer nil’ or ‘:demand t’ (*note Forcing loading::).
|
||
|
||
|
||
File: use-package.info, Node: Forcing loading, Next: Conditional loading, Prev: Deferring loading, Up: Loading Packages
|
||
|
||
3.3 Forcing package to load immediately
|
||
=======================================
|
||
|
||
The presence of autoloading trigger keywords can be overridden using
|
||
‘:demand t’, which forces the package to load immediately. Thus, even
|
||
if you use an autoloading keyword such as ‘:bind’ (*note Key
|
||
bindings::), adding ‘: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 ‘:demand t’ and ‘:defer t’, the ‘:defer’ keyword
|
||
will take precedence.
|
||
|
||
|
||
File: use-package.info, Node: Conditional loading, Next: Loading sequentially, Prev: Forcing loading, Up: Loading Packages
|
||
|
||
3.4 Loading packages conditionally
|
||
==================================
|
||
|
||
The ‘:if’, ‘:when’, and ‘: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 ‘:if’ keyword evaluates to non-‘nil’, the
|
||
package will be loaded and initialized. The ‘:when’ keyword is provided
|
||
as an alias for ‘:if’. Finally, the ‘:unless’ keyword is the inverse of
|
||
‘:if’, such that ‘:unless foo’ means the same thing as ‘:if (not foo)’.
|
||
|
||
For example, if you only want to load ‘foo’ in graphical Emacs
|
||
sessions, you could use the following:
|
||
|
||
(use-package foo
|
||
:if (display-graphic-p))
|
||
|
||
Some common use cases
|
||
---------------------
|
||
|
||
Here are some common cases for conditional loading, and how to achieve
|
||
them.
|
||
|
||
• Operating system
|
||
|
||
This example loads a package only on GNU/Linux. See the
|
||
‘system-type’ docstring for other valid values.
|
||
|
||
:if (eq system-type 'gnu/linux)
|
||
|
||
• Window system
|
||
|
||
This example loads a package only on macOS and X. See the
|
||
‘window-system’ docstring for valid values.
|
||
|
||
:if (memq window-system '(ns x))
|
||
|
||
• Installed package
|
||
|
||
This example loads a package only when the ‘foo’ package is
|
||
installed.
|
||
|
||
:if (package-installed-p 'foo)
|
||
|
||
• Libraries in ‘load-path’
|
||
|
||
This example loads a package only when ‘foo.el’ is available in
|
||
your ‘load-path’ (for example, if you installed that file
|
||
manually):
|
||
|
||
:if (locate-library "foo.el")
|
||
|
||
Making conditional loading affect ‘:preface’ and ‘:ensure’
|
||
----------------------------------------------------------
|
||
|
||
If you need to conditionalize a use-package form so that the condition
|
||
occurs before even ‘:ensure’ or ‘:preface’, use ‘when’ around the
|
||
use-package form itself. For example:
|
||
|
||
(when (memq window-system '(mac ns))
|
||
(use-package foo
|
||
:ensure t))
|
||
|
||
|
||
File: use-package.info, Node: Loading sequentially, Next: Load dependencies, Prev: Conditional loading, Up: Loading Packages
|
||
|
||
3.5 Loading packages in sequence
|
||
================================
|
||
|
||
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 ‘: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 GNU ELPA packages hydra, ivy, and
|
||
ivy-hydra. Note that ivy-hydra will always be loaded last:
|
||
|
||
(use-package hydra)
|
||
|
||
(use-package ivy)
|
||
|
||
(use-package ivy-hydra
|
||
:after (ivy hydra))
|
||
|
||
In this case, because the declarations are evaluated in the order
|
||
they occur, the use of ‘:after’ is not strictly necessary. However, if
|
||
‘hydra’ and ‘ivy’ were to be autoloaded, using ‘:after’ guarantees that
|
||
‘ivy-hydra’ is not loaded until it is actually needed. By using
|
||
‘: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.
|
||
|
||
Using ‘:after’ selectors
|
||
------------------------
|
||
|
||
The ‘:after’ keyword also accepts a list of selectors. By default,
|
||
‘:after (foo bar)’ is the same as ‘:after (:all foo bar)’, meaning that
|
||
loading of the given package will not happen until both ‘foo’ and ‘bar’
|
||
have been loaded. Here are some of the other possibilities:
|
||
|
||
: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))
|
||
|
||
When you nest selectors, such as ‘(:any (:all foo bar) (:all baz
|
||
quux))’, it means that the package will be loaded when either both ‘foo’
|
||
and ‘bar’ have been loaded, or when both ‘baz’ and ‘quux’ have been
|
||
loaded.
|
||
|
||
Pay attention when setting ‘use-package-always-defer’ to a non-‘nil’
|
||
value, and also using the ‘:after’ keyword. In this case, you will need
|
||
to specify how the declared package is to be loaded: for example, by
|
||
some ‘:bind’. If you are not using one of the keywords that registers
|
||
autoloads, such as ‘:bind’ or ‘:hook’, and your package manager does not
|
||
provide autoloads, it is possible that your package will never be loaded
|
||
if you do not add ‘:demand t’ to those declarations.
|
||
|
||
|
||
File: use-package.info, Node: Load dependencies, Next: Load path, Prev: Loading sequentially, Up: Loading Packages
|
||
|
||
3.6 Prevent loading if dependencies are missing
|
||
===============================================
|
||
|
||
While the ‘:after’ keyword delays loading until the dependencies are
|
||
loaded, the somewhat simpler ‘:requires’ keyword _never_ loads the
|
||
package if the dependencies are not available when the ‘use-package’
|
||
declaration is evaluated. In this context, “available” means that ‘foo’
|
||
is available if ‘(featurep 'foo)’ evaluates to a non-‘nil’ value. For
|
||
example:
|
||
|
||
(use-package abbrev
|
||
:requires foo)
|
||
|
||
This is the same as:
|
||
|
||
(use-package abbrev
|
||
:if (featurep 'foo))
|
||
|
||
As a convenience, a list of such packages may be specified:
|
||
|
||
(use-package abbrev
|
||
:requires (foo bar baz))
|
||
|
||
For more complex logic, such as that supported by ‘:after’, simply
|
||
use ‘:if’ and the appropriate Lisp expression.
|
||
|
||
|
||
File: use-package.info, Node: Load path, Next: Manual autoloads, Prev: Load dependencies, Up: Loading Packages
|
||
|
||
3.7 Setting a custom ‘load-path’
|
||
================================
|
||
|
||
If a package resides in some directory that is not in your ‘load-path’,
|
||
use the ‘: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 ‘user-emacs-directory’.
|
||
|
||
For example:
|
||
|
||
(use-package ess-site
|
||
:load-path "site-lisp/ess/lisp/"
|
||
:commands R)
|
||
|
||
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 ‘eval-and-compile’ (as opposed to
|
||
‘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:
|
||
|
||
(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)
|
||
|
||
|
||
File: use-package.info, Node: Manual autoloads, Prev: Load path, Up: Loading Packages
|
||
|
||
3.8 Setting up autoloads manually
|
||
=================================
|
||
|
||
To autoload an interactive command, use the ‘:commands’ keyword. When
|
||
you use the ‘:commands’ keyword, it creates autoloads for those commands
|
||
(which defers loading of the module until they are used). The
|
||
‘:commands’ keyword takes either a symbol or a list of symbols.
|
||
|
||
The ‘:autoload’ keyword works like ‘:commands’, but is used to
|
||
autoload non-interactive functions. Here is an example:
|
||
|
||
(use-package org-crypt
|
||
:autoload org-crypt-use-before-save-magic)
|
||
|
||
|
||
File: use-package.info, Node: Configuring Packages, Next: Installing packages, Prev: Loading Packages, Up: Top
|
||
|
||
4 Configuring Packages
|
||
**********************
|
||
|
||
This chapter describes the various keywords provided by ‘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.
|
||
|
||
|
||
File: use-package.info, Node: Lisp Configuration, Next: Key bindings, Up: Configuring Packages
|
||
|
||
4.1 Using Lisp code for configuring packages
|
||
============================================
|
||
|
||
The most general way to add customizations are the ‘:preface’, ‘:init’,
|
||
and ‘: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 ‘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 ‘:config’, ‘:init’, and ‘:preface’.
|
||
|
||
|
||
File: use-package.info, Node: Preface keyword, Next: Init keyword, Up: Lisp Configuration
|
||
|
||
4.1.1 ‘:preface’ is evaluated first
|
||
-----------------------------------
|
||
|
||
The ‘:preface’ section is evaluated before anything else, except
|
||
‘:disabled’ and ‘:ensure’. It can be used to establish function and
|
||
variable definitions that will:
|
||
|
||
1. Make the byte-compiler happy. It will not complain about functions
|
||
whose definitions are unknown because you have them within a guard
|
||
block.
|
||
|
||
2. Define code that can be used in an ‘:if’ test.
|
||
|
||
Note that whatever is specified within ‘: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.
|
||
|
||
|
||
File: use-package.info, Node: Init keyword, Next: Config keyword, Prev: Preface keyword, Up: Lisp Configuration
|
||
|
||
4.1.2 ‘:init’ is evaluated before loading package
|
||
-------------------------------------------------
|
||
|
||
The ‘:init’ section is evaluated just before the package is loaded.
|
||
Note that the ‘:init’ form is run unconditionally – even if the ‘foo’
|
||
package happens to not exist on your system. You must therefore
|
||
remember to restrict ‘:init’ code to only what would succeed either way.
|
||
‘:init’ also always happens before package load, whether ‘:config’ has
|
||
been deferred or not.
|
||
|
||
|
||
File: use-package.info, Node: Config keyword, Next: Best practices, Prev: Init keyword, Up: Lisp Configuration
|
||
|
||
4.1.3 ‘:config’ is evaluated after loading package
|
||
--------------------------------------------------
|
||
|
||
The ‘: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 (*note Loading Packages::), this is
|
||
deferred until after the package has been loaded.
|
||
|
||
In general, you should keep ‘:init’ forms as simple and quick as
|
||
possible, and put as much as you can get away with into the ‘:config’
|
||
section. That way, deferred loading can help your Emacs start as
|
||
quickly as possible.
|
||
|
||
|
||
File: use-package.info, Node: Best practices, Prev: Config keyword, Up: Lisp Configuration
|
||
|
||
When to use ‘:preface’, ‘:config’ and ‘:init’?
|
||
----------------------------------------------
|
||
|
||
Where possible, it is better to avoid ‘:preface’, ‘:config’ and ‘:init’.
|
||
Instead, prefer autoloading keywords such as ‘:bind’, ‘:hook’, and
|
||
‘:mode’, as they will take care of setting up autoloads for you without
|
||
any need for boilerplate code. For example, consider the following
|
||
declaration:
|
||
|
||
(use-package foo
|
||
:init
|
||
(add-hook 'some-hook 'foo-mode))
|
||
|
||
This has two problems. First, it will unconditionally load the
|
||
package ‘foo’ on startup, which will make things slower. You can fix
|
||
this by adding ‘:defer t’:
|
||
|
||
(use-package foo
|
||
:defer t
|
||
:init
|
||
(add-hook 'some-hook 'foo-mode))
|
||
|
||
This is better, as ‘foo’ is now only loaded when it is actually
|
||
needed (that is, when the hook ‘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 ‘:hook’ (*Note Hooks::), which also implies
|
||
‘:defer t’. The above is thereby reduced down to:
|
||
|
||
(use-package foo
|
||
:hook some-hook)
|
||
|
||
use-package will set up autoloading for you, and your Emacs startup
|
||
time will not suffer one bit.
|
||
|
||
|
||
File: use-package.info, Node: Key bindings, Next: Hooks, Prev: Lisp Configuration, Up: Configuring Packages
|
||
|
||
4.2 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 ‘keymap-local-set’, ‘keymap-global-set’ and
|
||
various autoloads. With use-package, you can simplify this using the
|
||
‘: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.
|
||
|
||
|
||
File: use-package.info, Node: Global keybindings, Next: Binding in keymaps, Up: Key bindings
|
||
|
||
4.2.1 Global keybindings
|
||
------------------------
|
||
|
||
To bind keys globally, the ‘:bind’ keyword takes as its argument either
|
||
a single cons or a list of conses. Each cons has the form
|
||
‘(KEY . DEFINITION)’, where KEY is a string indicating the key to bind,
|
||
and DEFINITION is the name of a command (a symbol). Alternatively,
|
||
DEFINITION may be a cons ‘(DESC . COMMAND)’, where DESC is a string
|
||
describing COMMAND, which is the name of a command to bind KEY to. The
|
||
syntax for the keys is similar to the syntax used by the ‘kbd’ function
|
||
(see *note (emacs)Init Rebinding::, for more information).
|
||
|
||
Using ‘:bind’ with a single cons
|
||
--------------------------------
|
||
|
||
Here is an example of using a single cons:
|
||
|
||
(use-package ace-jump-mode
|
||
:bind ("C-." . ace-jump-mode))
|
||
|
||
This does two things: first, it creates an autoload for the
|
||
‘ace-jump-mode’ command and defers loading of the ‘ace-jump-mode’
|
||
package until you actually use it. Second, it binds the key ‘C-.’ to
|
||
that command globally.
|
||
|
||
Using ‘:bind’ with a list of conses
|
||
-----------------------------------
|
||
|
||
Here is an example of using ‘:bind’ with a list of conses:
|
||
|
||
(use-package hi-lock
|
||
:bind (("M-o l" . highlight-lines-matching-regexp)
|
||
("M-o r" . highlight-regexp)
|
||
("M-o w" . highlight-phrase)))
|
||
|
||
Using special keys
|
||
------------------
|
||
|
||
Inside key strings, special keys like ‘TAB’ or ‘F1’–‘F12’ have to be
|
||
written inside angle brackets, e.g. ‘"C-<up>"’. Standalone special
|
||
keys (and some combinations) can be written in square brackets,
|
||
e.g. ‘[tab]’ instead of ‘"<tab>"’.
|
||
|
||
Examples:
|
||
|
||
(use-package helm
|
||
:bind (("M-x" . helm-M-x)
|
||
("M-<f5>" . helm-find-files)
|
||
([f10] . helm-buffers-list)
|
||
([S-f10] . helm-recentf)))
|
||
|
||
Providing custom descriptions of commands
|
||
-----------------------------------------
|
||
|
||
When binding keys to commands with ‘:bind’, custom descriptions of the
|
||
commands may optionally be provided.
|
||
|
||
Examples:
|
||
|
||
(use-package avy
|
||
:bind ("C-:" ("Jump to char" . avy-goto-char)
|
||
"M-g f" ("Jump to line" . avy-goto-line)))
|
||
|
||
These descriptions can be used by other code that deals with key
|
||
bindings. For example, the GNU ELPA package ‘which-key’ displays them
|
||
when showing key bindings, instead of the plain command names.
|
||
|
||
Remapping commands
|
||
------------------
|
||
|
||
Remapping commands with ‘:bind’ and ‘bind-key’ works as expected,
|
||
because when the binding is a vector, it is passed straight to
|
||
‘define-key’. *Note (elisp)Remapping Commands::) for more information
|
||
about command remapping. For example, the following declaration will
|
||
rebind ‘fill-paragraph’ (bound to ‘M-q’ by default) to ‘unfill-toggle’:
|
||
|
||
(use-package unfill
|
||
:bind ([remap fill-paragraph] . unfill-toggle))
|
||
|
||
What ‘:bind’ does behind the scenes
|
||
-----------------------------------
|
||
|
||
To understand what ‘:bind’ does behind the scenes, it might be useful to
|
||
consider an example:
|
||
|
||
(use-package ace-jump-mode
|
||
:bind ("C-." . ace-jump-mode))
|
||
|
||
This could be expressed in a much more verbose way with the
|
||
‘:commands’ and ‘:init’ keywords.
|
||
|
||
(use-package ace-jump-mode
|
||
:commands ace-jump-mode
|
||
:init
|
||
(bind-key "C-." 'ace-jump-mode))
|
||
|
||
Without using even the ‘:commands’ keyword, we could also write the
|
||
above like so:
|
||
|
||
(use-package ace-jump-mode
|
||
:defer t
|
||
:init
|
||
(autoload 'ace-jump-mode "ace-jump-mode" nil t)
|
||
(bind-key "C-." 'ace-jump-mode))
|
||
|
||
Although these three forms are all equivalent, the first form is
|
||
usually the best, as it will save some typing.
|
||
|
||
|
||
File: use-package.info, Node: Binding in keymaps, Next: Binding to a keymap, Prev: Global keybindings, Up: Key bindings
|
||
|
||
4.2.2 Key bindings in local keymaps
|
||
-----------------------------------
|
||
|
||
Slightly different from binding a key to a keymap, is binding a key
|
||
_within_ a local keymap that only exists after the package is loaded.
|
||
‘use-package’ supports this with a ‘:map’ modifier, taking the local
|
||
keymap to bind to:
|
||
|
||
(use-package helm
|
||
:bind (:map helm-command-map
|
||
("C-c h" . helm-execute-persistent-action)))
|
||
|
||
The effect of this statement is to wait until ‘helm’ has loaded, and
|
||
then to bind the key ‘C-c h’ to ‘helm-execute-persistent-action’ within
|
||
Helm’s local keymap, ‘helm-command-map’.
|
||
|
||
Multiple uses of ‘:map’ may be specified. Any binding occurring
|
||
before the first use of ‘:map’ are applied to the global keymap:
|
||
|
||
(use-package term
|
||
:bind (("C-c t" . term)
|
||
:map term-mode-map
|
||
("M-p" . term-send-up)
|
||
("M-n" . term-send-down)
|
||
:map term-raw-map
|
||
("M-o" . other-window)
|
||
("M-p" . term-send-up)
|
||
("M-n" . term-send-down)))
|
||
|
||
|
||
File: use-package.info, Node: Binding to a keymap, Next: Binding to repeat-maps, Prev: Binding in keymaps, Up: Key bindings
|
||
|
||
4.2.3 Binding to keymaps
|
||
------------------------
|
||
|
||
Normally ‘: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 ‘autoload’ function.
|
||
|
||
To handle this case, ‘use-package’ offers a special, limited variant
|
||
of ‘:bind’ called ‘:bind-keymap’. The only difference is that the
|
||
“commands” bound to by ‘: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:
|
||
|
||
(use-package foo
|
||
:bind-keymap ("C-c p" . foo-command-map))
|
||
|
||
|
||
File: use-package.info, Node: Binding to repeat-maps, Next: Displaying keybindings, Prev: Binding to a keymap, Up: Key bindings
|
||
|
||
4.2.4 Binding to repeat-maps
|
||
----------------------------
|
||
|
||
A special case of binding within a local keymap is when that keymap is
|
||
used by ‘repeat-mode’ *note (emacs)Repeating::. These keymaps are
|
||
usually defined specifically for this. Using the ‘: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 ‘repeat-map’ property of
|
||
each bound command to that map.
|
||
|
||
The following example creates a keymap called
|
||
‘git-gutter+-repeat-map’, makes four bindings in it as above, then sets
|
||
the ‘repeat-map’ property of each bound command (‘git-gutter+-next-hunk’
|
||
‘git-gutter+-previous-hunk’, ‘git-gutter+-stage-hunks’ and
|
||
‘git-gutter+-revert-hunk’) to that keymap.
|
||
|
||
(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)))
|
||
|
||
Specifying ‘:exit’ inside the scope of ‘:repeat-map’ will prevent the
|
||
‘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:
|
||
|
||
(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)))
|
||
|
||
Specifying ‘:continue’ _forces_ setting the ‘repeat-map’ property
|
||
(just like _not_ specifying ‘:exit’), so the above snippet is equivalent
|
||
to:
|
||
|
||
(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)))
|
||
|
||
|
||
File: use-package.info, Node: Displaying keybindings, Prev: Binding to repeat-maps, Up: Key bindings
|
||
|
||
4.2.5 Displaying personal keybinding
|
||
------------------------------------
|
||
|
||
The ‘:bind’ keyword uses the ‘bind-keys’ macro from the ‘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 ‘M-x describe-personal-keybindings’ to see all keybindings you’ve
|
||
set using either the ‘:bind’ keyword or the ‘bind-keys’ macro.
|
||
|
||
|
||
File: use-package.info, Node: Hooks, Next: Modes and interpreters, Prev: Key bindings, Up: Configuring Packages
|
||
|
||
4.3 Hooks
|
||
=========
|
||
|
||
The ‘:hook’ keyword allows adding functions onto hooks. It takes one
|
||
argument of the form HOOKS, specifying one or more functions to add to
|
||
one or more hooks. For the purposes of ‘:hook’, the name of hook
|
||
variables should always exclude the ‘-hook’ suffix. It is appended
|
||
automatically for you, to save some typing.
|
||
|
||
For example, consider the following ‘use-package’ declaration that
|
||
sets up autoloads for ‘company-mode’ from the ‘company’ package, and
|
||
adds ‘company-mode’ to ‘prog-mode-hook’:
|
||
|
||
(use-package company
|
||
:commands company-mode
|
||
:init
|
||
(add-hook 'prog-mode-hook #'company-mode))
|
||
|
||
Using ‘:hook’, this can be simplified to:
|
||
|
||
(use-package company
|
||
:hook (prog-mode . company-mode))
|
||
|
||
Here, ‘:hook’ will automatically set up autoloads for the
|
||
‘company-mode’ command, so there is no need to use ‘:commands’.
|
||
|
||
The ‘:hook’ keyword will also assume that the name of the function
|
||
you want to add is the same as the package name with ‘-mode’ appended to
|
||
it. Taking this into account, you can simplify the above to the
|
||
equivalent:
|
||
|
||
(use-package company
|
||
:hook prog-mode)
|
||
|
||
You can also provide a list of hooks. When multiple hooks should be
|
||
applied, the following examples are all equivalent:
|
||
|
||
(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
|
||
(add-hook 'prog-mode-hook #'company-mode)
|
||
(add-hook 'text-mode-hook #'company-mode))
|
||
|
||
One common mistake when using ‘:hook’ is to forget to omit the
|
||
‘-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 ‘prog-mode-hook-hook’:
|
||
|
||
;; DOES NOT WORK
|
||
(use-package ace-jump-mode
|
||
:hook (prog-mode-hook . ace-jump-mode))
|
||
|
||
If you do not like this behavior, you can customize the user option
|
||
‘use-package-hook-name-suffix’ to ‘nil’. The value of this variable is
|
||
‘"-hook"’ by default.
|
||
|
||
The use of ‘:hook’, as with ‘:bind’, ‘:mode’, ‘:interpreter’, etc.,
|
||
causes the functions being hooked to implicitly be read as ‘:commands’.
|
||
This means that they will establish interactive ‘autoload’ definitions
|
||
for that module, if not already defined as functions), and so ‘:defer t’
|
||
is also implied by ‘:hook’.
|
||
|
||
|
||
File: use-package.info, Node: Modes and interpreters, Next: Magic handlers, Prev: Hooks, Up: Configuring Packages
|
||
|
||
4.4 Modes and interpreters
|
||
==========================
|
||
|
||
Similar to ‘:bind’, you can use ‘:mode’ and ‘:interpreter’ to establish
|
||
a deferred binding within the ‘auto-mode-alist’ and
|
||
‘interpreter-mode-alist’ variables. The specifier to either keyword can
|
||
be a cons cell, a list of cons cells, or a string or regexp.
|
||
|
||
The following example reproduces the default ‘ruby-mode’
|
||
configuration, exactly as it is in Emacs out-of-the-box. That mode is
|
||
enabled automatically when a file whose name matches the regexp
|
||
‘"\\.rb\\'"’ (a file with the ‘.rb’ extension), or when the first line
|
||
of the file (known as the “shebang”) matches the string ‘"ruby"’:
|
||
|
||
(use-package ruby-mode
|
||
:mode "\\.rb\\'"
|
||
:interpreter "ruby")
|
||
|
||
The default ‘python-mode’ configuration can be reproduced using the
|
||
below declaration. Note that the package that should be loaded differs
|
||
from the mode name in this case, so we must use a cons:
|
||
|
||
;; The package is "python" but the mode is "python-mode":
|
||
(use-package python
|
||
:mode ("\\.py\\'" . python-mode)
|
||
:interpreter ("python" . python-mode))
|
||
|
||
Both the ‘:mode’ and ‘:interpreter’ keywords also accept a list of
|
||
regexps:
|
||
|
||
(use-package foo
|
||
;; Equivalent to "\\(ba[rz]\\)\\'":
|
||
:mode ("\\.bar\\'" "\\.baz\\'")
|
||
;; Equivalent to "\\(foo[ab]\\)":
|
||
:interpreter ("fooa" "foob"))
|
||
|
||
|
||
File: use-package.info, Node: Magic handlers, Next: User options, Prev: Modes and interpreters, Up: Configuring Packages
|
||
|
||
4.5 Magic handlers
|
||
==================
|
||
|
||
Similar to ‘:mode’ and ‘:interpreter’, you can also use ‘:magic’ and
|
||
‘:magic-fallback’ to cause certain function to be run if the beginning
|
||
of a file matches a given regular expression. The difference between
|
||
‘:magic’ and ‘:magic-fallback’, is that the latter has a lower priority
|
||
than ‘:mode’.
|
||
|
||
Here is an example:
|
||
|
||
(use-package pdf-tools
|
||
:magic ("%PDF" . pdf-view-mode)
|
||
:config
|
||
(pdf-tools-install :no-query))
|
||
|
||
This registers an autoloaded command for ‘pdf-view-mode’, defers
|
||
loading of ‘pdf-tools’, and runs ‘pdf-view-mode’ if the beginning of a
|
||
buffer matches the string ‘"%PDF"’.
|
||
|
||
|
||
File: use-package.info, Node: User options, Next: Faces, Prev: Magic handlers, Up: Configuring Packages
|
||
|
||
4.6 User options
|
||
================
|
||
|
||
In Emacs, you normally set customizable variables (user options) using
|
||
the ‘M-x customize’ interface (*note (emacs)Easy Customization::). We
|
||
recommended this method for most users. However, it is also possible to
|
||
set them in your ‘use-package’ declarations by using the ‘:custom’
|
||
keyword.
|
||
|
||
(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."))
|
||
|
||
This is better than using ‘setq’ in a ‘: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 ‘setopt’ macro that does this for you.
|
||
|
||
Note that the values customized using this keyword are _not_ saved in
|
||
the standard Emacs ‘custom-file’. You should therefore set each user
|
||
option using either the ‘:custom’ keyword _or_ ‘M-x customize-option’,
|
||
which will save customized values in the Emacs ‘custom-file’. Do not
|
||
use both for the same variable, as this risk having conflicting values
|
||
in your use-package declaration and your ‘custom-file’. This can lead
|
||
to problems that are both tricky and tedious to debug.
|
||
|
||
|
||
File: use-package.info, Node: Faces, Next: Hiding minor modes, Prev: User options, Up: Configuring Packages
|
||
|
||
4.7 Faces
|
||
=========
|
||
|
||
The ‘:custom-face’ keyword allows customization of package custom faces.
|
||
|
||
(use-package eruby-mode
|
||
:custom-face
|
||
(eruby-standard-face ((t (:slant italic)))))
|
||
|
||
(use-package example
|
||
:custom-face
|
||
(example-1-face ((t (:foreground "LightPink"))))
|
||
(example-2-face ((t (:foreground "LightGreen"))) face-defspec-spec))
|
||
|
||
(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))
|
||
|
||
|
||
File: use-package.info, Node: Hiding minor modes, Prev: Faces, Up: Configuring Packages
|
||
|
||
4.8 Hiding minor modes with diminish and delight
|
||
================================================
|
||
|
||
‘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.(1) To use either of them, you must first
|
||
install the corresponding package from GNU ELPA.
|
||
|
||
* Menu:
|
||
|
||
* Diminish:: Hiding minor modes with Diminish.
|
||
* Delight:: Hiding minor modes with Delight.
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) When in doubt, you might as well use diminish.
|
||
|
||
|
||
File: use-package.info, Node: Diminish, Next: Delight, Up: Hiding minor modes
|
||
|
||
4.8.1 Diminish
|
||
--------------
|
||
|
||
When diminish(1) is installed, you can use the ‘:diminish’ keyword. If
|
||
diminish is not installed, the ‘:diminish’ keyword does nothing.
|
||
|
||
First, add the following declaration to the beginning of your init
|
||
file. The optional ‘:ensure t’ makes sure the package is installed if
|
||
it isn’t already (*note Installing packages::).
|
||
|
||
(use-package diminish :ensure t)
|
||
|
||
The ‘: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
|
||
‘-mode’ appended at the end:
|
||
|
||
(use-package abbrev
|
||
:diminish abbrev-mode
|
||
:config
|
||
(if (file-exists-p abbrev-file-name)
|
||
(quietly-read-abbrev-file)))
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) The diminish package is installable from GNU ELPA.
|
||
|
||
|
||
File: use-package.info, Node: Delight, Prev: Diminish, Up: Hiding minor modes
|
||
|
||
4.8.2 Delight
|
||
-------------
|
||
|
||
When delight(1) is installed, you can use the ‘:delight’ keyword. If
|
||
delight is not installed, the ‘:delight’ keyword does nothing.
|
||
|
||
First, add the following declaration to the beginning of your init
|
||
file. The optional ‘:ensure t’ makes sure the package is installed if
|
||
it isn’t already (*note Installing packages::).
|
||
|
||
(use-package delight :ensure t)
|
||
|
||
The ‘:delight’ keyword takes a minor mode symbol, a replacement
|
||
string, or quoted mode line data (in which case the minor mode symbol is
|
||
assumed to be the package name with ‘-mode’ appended at the end), both
|
||
of these, or several lists of both. *Note (elisp)Mode Line Data::. If
|
||
no arguments are provided, the default mode name is hidden completely.
|
||
|
||
For example, the following hides everything for the ‘foo-mode’ minor
|
||
mode in the ‘foo’ package:
|
||
|
||
(use-package foo
|
||
:delight)
|
||
|
||
If the mode name doesn’t match the package name with ‘-mode’
|
||
appended, provide a symbol instead. For example, the following hides
|
||
‘auto-revert-mode’ from the mode line:
|
||
|
||
;; Don't show anything for auto-revert-mode, which doesn't match
|
||
;; its package name.
|
||
(use-package autorevert
|
||
:delight auto-revert-mode)
|
||
|
||
You can also run arbitrary Lisp code. For example, to replace
|
||
‘foo-mode’ with the value of the current buffer:
|
||
|
||
(use-package foo
|
||
:delight '(:eval buffer-file-name))
|
||
|
||
Here is an example of hiding several built-in minor modes:
|
||
|
||
;; Completely hide visual-line-mode and change auto-fill-mode to " AF".
|
||
(use-package emacs
|
||
:delight
|
||
(auto-fill-function " AF")
|
||
(visual-line-mode))
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) The ‘delight’ package is installable from GNU ELPA.
|
||
|
||
|
||
File: use-package.info, Node: Installing packages, Next: Byte-compiling, Prev: Configuring Packages, Up: Top
|
||
|
||
5 Installing packages automatically
|
||
***********************************
|
||
|
||
The standard Emacs package manager is documented in the Emacs manual
|
||
(*note (emacs)Package Installation::). The ‘use-package’ macro provides
|
||
the ‘:ensure’ and ‘: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.
|
||
|
||
* Menu:
|
||
|
||
* Install package::
|
||
* Pinning packages::
|
||
* Other package managers::
|
||
|
||
|
||
File: use-package.info, Node: Install package, Next: Pinning packages, Up: Installing packages
|
||
|
||
5.1 Installing package
|
||
======================
|
||
|
||
The ‘:ensure’ keyword makes use-package ask the Emacs package manager to
|
||
install a package if it is not already present on your system.
|
||
|
||
For example:
|
||
|
||
(use-package magit
|
||
:ensure t)
|
||
|
||
If you need to install a different package from the one named by
|
||
‘use-package’, you can use a symbol:
|
||
|
||
(use-package tex
|
||
:ensure auctex)
|
||
|
||
You can customize the user option ‘use-package-always-ensure’ to
|
||
non-‘nil’ if you want this behavior to be global for all packages.
|
||
|
||
(require 'use-package-ensure)
|
||
(setq use-package-always-ensure t)
|
||
|
||
You can override the above setting for a single package by adding
|
||
‘:ensure nil’ to its declaration.
|
||
|
||
|
||
File: use-package.info, Node: Pinning packages, Next: Other package managers, Prev: Install package, Up: Installing packages
|
||
|
||
5.2 Pinning packages using ‘:pin’
|
||
=================================
|
||
|
||
use-package can pin a package to a specific archive using the ‘:pin’
|
||
keyword.(1) This allows you to mix and match packages from different
|
||
archives. The primary use-case for this is preferring to install
|
||
packages from GNU ELPA or NonGNU ELPA (indicated by ‘gnu’ and ‘nongnu’,
|
||
respectively), while installing specific packages from third-party
|
||
archives.
|
||
|
||
For example:
|
||
|
||
(use-package company
|
||
:ensure t
|
||
:pin gnu) ; GNU ELPA
|
||
|
||
Unfortunately, the third-party archive 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 ‘use-package-always-pin’ to ‘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.
|
||
|
||
If you want to manually keep a package updated and ignore upstream
|
||
updates, you can pin it to ‘manual’. This will work as long as you have
|
||
not customized a repository to use that name in the ‘package-archives’
|
||
variable.
|
||
|
||
Example:
|
||
|
||
(use-package org
|
||
:ensure t
|
||
;; ignore org-mode from upstream and use a manually installed version
|
||
:pin manual)
|
||
|
||
‘use-package’ signals an error if you try to pin a package to an
|
||
archive that is not configured using ‘package-archives’ (except from the
|
||
special ‘manual’ archive).
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) The ‘:pin’ keyword has no effect on Emacs versions older than
|
||
24.4.
|
||
|
||
|
||
File: use-package.info, Node: Other package managers, Prev: Pinning packages, Up: Installing packages
|
||
|
||
5.3 Non-standard package managers
|
||
=================================
|
||
|
||
By default, use-package assumes that you are using the built-in
|
||
‘package.el’ package manager. We expect that most users will find that
|
||
it is more than capable enough, even for advanced use cases.
|
||
|
||
However, some users might prefer to use a third-party package manager
|
||
for a specific circumstance or use case. By setting the user option
|
||
‘use-package-ensure-function’ to the name of a function, you can direct
|
||
‘: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.
|
||
|
||
|
||
File: use-package.info, Node: Byte-compiling, Next: Troubleshooting, Prev: Installing packages, Up: Top
|
||
|
||
6 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.
|
||
|
||
‘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.
|
||
|
||
However, there are times when this is just not enough. For those
|
||
times, use the ‘:defines’ and ‘:functions’ keywords to introduce dummy
|
||
variable and function declarations solely for the sake of silencing
|
||
byte-compiler warnings. For example:
|
||
|
||
(use-package texinfo
|
||
:defines texinfo-section-list
|
||
:commands texinfo-mode
|
||
:init
|
||
(add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode)))
|
||
|
||
If you need to silence a missing function warning, you can use
|
||
‘:functions’:
|
||
|
||
(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))
|
||
|
||
Normally, ‘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 ‘use-package’ for is to add a configuration to the
|
||
‘eval-after-load’ hook. In such cases, use the ‘:no-require’ keyword:
|
||
|
||
(use-package foo
|
||
:no-require t
|
||
:config
|
||
(message "Evaluate this immediately after loading `foo'"))
|
||
|
||
|
||
File: use-package.info, Node: Troubleshooting, Next: Keyword extensions, Prev: Byte-compiling, Up: Top
|
||
|
||
7 Troubleshooting
|
||
*****************
|
||
|
||
If an error occurs while initializing or configuring a package, this
|
||
will not stop your Emacs from loading. Instead, ‘use-package’ captures
|
||
the error and reports it in a special ‘*Warnings*’ popup buffer, so that
|
||
you can debug the situation in an otherwise functional Emacs.
|
||
|
||
If you are having trouble when starting Emacs, you can pass Emacs the
|
||
‘--debug-init’ command line flag. *Note (emacs)Initial Options::. To
|
||
get even more information when using that flag, add the following to
|
||
your init file (these options are documented below):
|
||
|
||
(when init-file-debug
|
||
(setq use-package-verbose t
|
||
use-package-expand-minimally nil
|
||
use-package-compute-statistics t
|
||
debug-on-error t))
|
||
|
||
Since ‘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 ‘M-x pp-macroexpand-last-sexp’, or
|
||
wrap the use-package declaration in ‘macroexpand’ and evaluate it. It
|
||
is a good idea to include their output in any bugs you file for
|
||
use-package.
|
||
|
||
* Menu:
|
||
|
||
* Troubleshooting Options::
|
||
* Gathering Statistics::
|
||
* Disabling a package::
|
||
|
||
|
||
File: use-package.info, Node: Troubleshooting Options, Next: Gathering Statistics, Up: Troubleshooting
|
||
|
||
7.1 Options that help when troubleshooting
|
||
==========================================
|
||
|
||
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 ‘use-package-expand-minimally’ to a non-‘nil’
|
||
value to disable this checking.
|
||
|
||
This behavior may be overridden locally using the ‘:catch’ keyword.
|
||
If ‘t’ or ‘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 ‘condition-case’). For example:
|
||
|
||
(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))))
|
||
|
||
Evaluating the above form will print these messages:
|
||
|
||
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
|
||
|
||
|
||
File: use-package.info, Node: Gathering Statistics, Next: Disabling a package, Prev: Troubleshooting Options, Up: Troubleshooting
|
||
|
||
7.2 Gathering Statistics
|
||
========================
|
||
|
||
When a package is loaded, and if you have ‘use-package-verbose’ set to
|
||
‘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 ‘*Messages*’
|
||
buffer. The same will happen for configuration, or ‘:config’ blocks,
|
||
that take longer than 0.1 seconds to execute.
|
||
|
||
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
|
||
‘use-package-compute-statistics’ to a non-‘nil’ value. Then reload your
|
||
packages, normally by restarting Emacs, to make sure that use-package
|
||
can gather statistics for all your packages.
|
||
|
||
Run the command ‘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 ‘S’, or click the column
|
||
name at the top of the buffer on graphical displays.
|
||
|
||
To reset all statistics that use-package has gathered for the current
|
||
Emacs invocation, run the command ‘M-x use-package-reset-statistics’.
|
||
|
||
Note that, if you are setting ‘use-package-compute-statistics’
|
||
directly in your init file, and not with ‘customize’, you must do this
|
||
after loading ‘use-package’, but before any ‘use-package’ forms.
|
||
|
||
|
||
File: use-package.info, Node: Disabling a package, Prev: Gathering Statistics, Up: Troubleshooting
|
||
|
||
7.3 Disabling a package
|
||
=======================
|
||
|
||
The ‘: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 ‘foo’ package:
|
||
|
||
(use-package foo
|
||
:disabled)
|
||
|
||
When byte-compiling your init file, use-package omits disabled
|
||
declarations from the output entirely, in order to make Emacs startup
|
||
faster.
|
||
|
||
|
||
File: use-package.info, Node: Keyword extensions, Next: History, Prev: Troubleshooting, Up: Top
|
||
|
||
Appendix A 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 ‘use-package’, and can be
|
||
optionally enabled.
|
||
|
||
* Menu:
|
||
|
||
* use-package-ensure-system-package::
|
||
* Creating an extension::
|
||
|
||
|
||
File: use-package.info, Node: use-package-ensure-system-package, Next: Creating an extension, Up: Keyword extensions
|
||
|
||
A.1 :use-package-ensure-system-package
|
||
======================================
|
||
|
||
The ‘:ensure-system-package’ keyword allows you to ensure certain
|
||
executables are available on your system alongside your package
|
||
declarations.(1)
|
||
|
||
To use this extension, add this immediately after loading
|
||
‘use-package’:
|
||
|
||
(use-package use-package-ensure-system-package)
|
||
|
||
Now you can use the ‘:ensure-system-package’ keyword. Here’s an
|
||
example usage:
|
||
|
||
(use-package foo
|
||
:ensure-system-package foo)
|
||
|
||
This will expect a global binary package to exist called ‘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 ‘system-packages’
|
||
(https://gitlab.com/jabranham/system-packages), so for this to work you
|
||
must install that first.
|
||
|
||
One way of making sure it is installed is with ‘use-package’ together
|
||
with ‘:ensure’.
|
||
|
||
(use-package system-packages
|
||
:ensure t)
|
||
|
||
For example, on a ‘Debian GNU/Linux’ system, this would call ‘apt-get
|
||
install foo’.
|
||
|
||
If the package is named differently than the binary, you can use a
|
||
cons in the form of ‘(binary . package-name)’. For example:
|
||
|
||
(use-package foo
|
||
:ensure-system-package
|
||
(foocmd . foo))
|
||
|
||
On a ‘Debian GNU/Linux’ system, this would call ‘apt install foo’ if
|
||
Emacs could not locate the executable ‘foocmd’.(2)
|
||
|
||
‘:ensure-system-package’ can also take a cons where its ‘cdr’ is a
|
||
string that will get called by ‘(async-shell-command)’ to install if it
|
||
isn’t found. This does not depend upon any external package.
|
||
|
||
(use-package tern
|
||
:ensure-system-package (tern . "npm i -g tern"))
|
||
|
||
To install several packages, you can pass in a list of conses:
|
||
|
||
(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")))
|
||
|
||
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:
|
||
|
||
(use-package dash-at-point
|
||
:if (eq system-type 'darwin)
|
||
:ensure-system-package
|
||
("/Applications/Dash.app" . "brew cask install dash"))
|
||
|
||
‘:ensure-system-package’ will use ‘system-packages-install’ to
|
||
install system packages, except where a custom command has been
|
||
specified, in which case it will be executed verbatim by
|
||
‘async-shell-command’.
|
||
|
||
The user options ‘system-packages-package-manager’ and
|
||
‘system-packages-use-sudo’ are honored, but not for custom commands.
|
||
Custom commands should include the call to sudo in the command if
|
||
needed.
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) On macOS, you will want to make sure ‘exec-path’ is cognisant of
|
||
all binary package names that you would like to ensure are installed.
|
||
The ‘exec-path-from-shell’
|
||
(https://github.com/purcell/exec-path-from-shell) package is often a
|
||
good way to do this.
|
||
|
||
(2) For manual testing, you could use the ‘executable-find’ function,
|
||
which is what ‘system-packages’ uses internally.
|
||
|
||
|
||
File: use-package.info, Node: Creating an extension, Prev: use-package-ensure-system-package, Up: Keyword extensions
|
||
|
||
A.2 How to create an extension keyword
|
||
======================================
|
||
|
||
This section describes how to create a new keyword.
|
||
|
||
1. Add the keyword.
|
||
|
||
The first step is to add your keyword at the right place in
|
||
‘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.
|
||
|
||
2. Create a normalizer.
|
||
|
||
The job of the normalizer is take a list of arguments (possibly
|
||
‘nil’), and turn it into the single argument (which could still be
|
||
a list) that should appear in the final property list used by
|
||
‘use-package’.
|
||
|
||
Define a normalizer for your keyword by defining a function named
|
||
after the keyword, for example:
|
||
|
||
(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)"))))))
|
||
|
||
3. 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 ‘state’ plist before recursively processing the
|
||
remaining keywords, to influence keywords that pay attention to the
|
||
state (one example is the state keyword ‘:deferred’, not to be
|
||
confused with the ‘use-package’ keyword ‘: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 _list of forms_
|
||
representing code to be inserted. It does not need to be a ‘progn’
|
||
list, as this is handled automatically in other places. Thus it is
|
||
common to see the idiom of using ‘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 ‘use-package’
|
||
expansion.
|
||
|
||
This is an example handler:
|
||
|
||
(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))))))
|
||
|
||
4. Test it.
|
||
|
||
After the keyword has been inserted into ‘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 ‘M-x
|
||
pp-macroexpand-last-sexp’ with the cursor set immediately after the
|
||
‘(use-package ...)’ expression.
|
||
|
||
|
||
File: use-package.info, Node: History, Next: GNU Free Documentation License, Prev: Keyword extensions, Up: Top
|
||
|
||
Appendix B 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 ‘README’.
|
||
|
||
|
||
File: use-package.info, Node: GNU Free Documentation License, Next: Index, Prev: History, Up: Top
|
||
|
||
Appendix C GNU Free Documentation License
|
||
*****************************************
|
||
|
||
Version 1.3, 3 November 2008
|
||
|
||
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
|
||
<https://fsf.org/>
|
||
|
||
Everyone is permitted to copy and distribute verbatim copies
|
||
of this license document, but changing it is not allowed.
|
||
|
||
0. PREAMBLE
|
||
|
||
The purpose of this License is to make a manual, textbook, or other
|
||
functional and useful document “free” in the sense of freedom: to
|
||
assure everyone the effective freedom to copy and redistribute it,
|
||
with or without modifying it, either commercially or
|
||
noncommercially. Secondarily, this License preserves for the
|
||
author and publisher a way to get credit for their work, while not
|
||
being considered responsible for modifications made by others.
|
||
|
||
This License is a kind of “copyleft”, which means that derivative
|
||
works of the document must themselves be free in the same sense.
|
||
It complements the GNU General Public License, which is a copyleft
|
||
license designed for free software.
|
||
|
||
We have designed this License in order to use it for manuals for
|
||
free software, because free software needs free documentation: a
|
||
free program should come with manuals providing the same freedoms
|
||
that the software does. But this License is not limited to
|
||
software manuals; it can be used for any textual work, regardless
|
||
of subject matter or whether it is published as a printed book. We
|
||
recommend this License principally for works whose purpose is
|
||
instruction or reference.
|
||
|
||
1. APPLICABILITY AND DEFINITIONS
|
||
|
||
This License applies to any manual or other work, in any medium,
|
||
that contains a notice placed by the copyright holder saying it can
|
||
be distributed under the terms of this License. Such a notice
|
||
grants a world-wide, royalty-free license, unlimited in duration,
|
||
to use that work under the conditions stated herein. The
|
||
“Document”, below, refers to any such manual or work. Any member
|
||
of the public is a licensee, and is addressed as “you”. You accept
|
||
the license if you copy, modify or distribute the work in a way
|
||
requiring permission under copyright law.
|
||
|
||
A “Modified Version” of the Document means any work containing the
|
||
Document or a portion of it, either copied verbatim, or with
|
||
modifications and/or translated into another language.
|
||
|
||
A “Secondary Section” is a named appendix or a front-matter section
|
||
of the Document that deals exclusively with the relationship of the
|
||
publishers or authors of the Document to the Document’s overall
|
||
subject (or to related matters) and contains nothing that could
|
||
fall directly within that overall subject. (Thus, if the Document
|
||
is in part a textbook of mathematics, a Secondary Section may not
|
||
explain any mathematics.) The relationship could be a matter of
|
||
historical connection with the subject or with related matters, or
|
||
of legal, commercial, philosophical, ethical or political position
|
||
regarding them.
|
||
|
||
The “Invariant Sections” are certain Secondary Sections whose
|
||
titles are designated, as being those of Invariant Sections, in the
|
||
notice that says that the Document is released under this License.
|
||
If a section does not fit the above definition of Secondary then it
|
||
is not allowed to be designated as Invariant. The Document may
|
||
contain zero Invariant Sections. If the Document does not identify
|
||
any Invariant Sections then there are none.
|
||
|
||
The “Cover Texts” are certain short passages of text that are
|
||
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
|
||
that says that the Document is released under this License. A
|
||
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
|
||
be at most 25 words.
|
||
|
||
A “Transparent” copy of the Document means a machine-readable copy,
|
||
represented in a format whose specification is available to the
|
||
general public, that is suitable for revising the document
|
||
straightforwardly with generic text editors or (for images composed
|
||
of pixels) generic paint programs or (for drawings) some widely
|
||
available drawing editor, and that is suitable for input to text
|
||
formatters or for automatic translation to a variety of formats
|
||
suitable for input to text formatters. A copy made in an otherwise
|
||
Transparent file format whose markup, or absence of markup, has
|
||
been arranged to thwart or discourage subsequent modification by
|
||
readers is not Transparent. An image format is not Transparent if
|
||
used for any substantial amount of text. A copy that is not
|
||
“Transparent” is called “Opaque”.
|
||
|
||
Examples of suitable formats for Transparent copies include plain
|
||
ASCII without markup, Texinfo input format, LaTeX input format,
|
||
SGML or XML using a publicly available DTD, and standard-conforming
|
||
simple HTML, PostScript or PDF designed for human modification.
|
||
Examples of transparent image formats include PNG, XCF and JPG.
|
||
Opaque formats include proprietary formats that can be read and
|
||
edited only by proprietary word processors, SGML or XML for which
|
||
the DTD and/or processing tools are not generally available, and
|
||
the machine-generated HTML, PostScript or PDF produced by some word
|
||
processors for output purposes only.
|
||
|
||
The “Title Page” means, for a printed book, the title page itself,
|
||
plus such following pages as are needed to hold, legibly, the
|
||
material this License requires to appear in the title page. For
|
||
works in formats which do not have any title page as such, “Title
|
||
Page” means the text near the most prominent appearance of the
|
||
work’s title, preceding the beginning of the body of the text.
|
||
|
||
The “publisher” means any person or entity that distributes copies
|
||
of the Document to the public.
|
||
|
||
A section “Entitled XYZ” means a named subunit of the Document
|
||
whose title either is precisely XYZ or contains XYZ in parentheses
|
||
following text that translates XYZ in another language. (Here XYZ
|
||
stands for a specific section name mentioned below, such as
|
||
“Acknowledgements”, “Dedications”, “Endorsements”, or “History”.)
|
||
To “Preserve the Title” of such a section when you modify the
|
||
Document means that it remains a section “Entitled XYZ” according
|
||
to this definition.
|
||
|
||
The Document may include Warranty Disclaimers next to the notice
|
||
which states that this License applies to the Document. These
|
||
Warranty Disclaimers are considered to be included by reference in
|
||
this License, but only as regards disclaiming warranties: any other
|
||
implication that these Warranty Disclaimers may have is void and
|
||
has no effect on the meaning of this License.
|
||
|
||
2. VERBATIM COPYING
|
||
|
||
You may copy and distribute the Document in any medium, either
|
||
commercially or noncommercially, provided that this License, the
|
||
copyright notices, and the license notice saying this License
|
||
applies to the Document are reproduced in all copies, and that you
|
||
add no other conditions whatsoever to those of this License. You
|
||
may not use technical measures to obstruct or control the reading
|
||
or further copying of the copies you make or distribute. However,
|
||
you may accept compensation in exchange for copies. If you
|
||
distribute a large enough number of copies you must also follow the
|
||
conditions in section 3.
|
||
|
||
You may also lend copies, under the same conditions stated above,
|
||
and you may publicly display copies.
|
||
|
||
3. COPYING IN QUANTITY
|
||
|
||
If you publish printed copies (or copies in media that commonly
|
||
have printed covers) of the Document, numbering more than 100, and
|
||
the Document’s license notice requires Cover Texts, you must
|
||
enclose the copies in covers that carry, clearly and legibly, all
|
||
these Cover Texts: Front-Cover Texts on the front cover, and
|
||
Back-Cover Texts on the back cover. Both covers must also clearly
|
||
and legibly identify you as the publisher of these copies. The
|
||
front cover must present the full title with all words of the title
|
||
equally prominent and visible. You may add other material on the
|
||
covers in addition. Copying with changes limited to the covers, as
|
||
long as they preserve the title of the Document and satisfy these
|
||
conditions, can be treated as verbatim copying in other respects.
|
||
|
||
If the required texts for either cover are too voluminous to fit
|
||
legibly, you should put the first ones listed (as many as fit
|
||
reasonably) on the actual cover, and continue the rest onto
|
||
adjacent pages.
|
||
|
||
If you publish or distribute Opaque copies of the Document
|
||
numbering more than 100, you must either include a machine-readable
|
||
Transparent copy along with each Opaque copy, or state in or with
|
||
each Opaque copy a computer-network location from which the general
|
||
network-using public has access to download using public-standard
|
||
network protocols a complete Transparent copy of the Document, free
|
||
of added material. If you use the latter option, you must take
|
||
reasonably prudent steps, when you begin distribution of Opaque
|
||
copies in quantity, to ensure that this Transparent copy will
|
||
remain thus accessible at the stated location until at least one
|
||
year after the last time you distribute an Opaque copy (directly or
|
||
through your agents or retailers) of that edition to the public.
|
||
|
||
It is requested, but not required, that you contact the authors of
|
||
the Document well before redistributing any large number of copies,
|
||
to give them a chance to provide you with an updated version of the
|
||
Document.
|
||
|
||
4. MODIFICATIONS
|
||
|
||
You may copy and distribute a Modified Version of the Document
|
||
under the conditions of sections 2 and 3 above, provided that you
|
||
release the Modified Version under precisely this License, with the
|
||
Modified Version filling the role of the Document, thus licensing
|
||
distribution and modification of the Modified Version to whoever
|
||
possesses a copy of it. In addition, you must do these things in
|
||
the Modified Version:
|
||
|
||
A. Use in the Title Page (and on the covers, if any) a title
|
||
distinct from that of the Document, and from those of previous
|
||
versions (which should, if there were any, be listed in the
|
||
History section of the Document). You may use the same title
|
||
as a previous version if the original publisher of that
|
||
version gives permission.
|
||
|
||
B. List on the Title Page, as authors, one or more persons or
|
||
entities responsible for authorship of the modifications in
|
||
the Modified Version, together with at least five of the
|
||
principal authors of the Document (all of its principal
|
||
authors, if it has fewer than five), unless they release you
|
||
from this requirement.
|
||
|
||
C. State on the Title page the name of the publisher of the
|
||
Modified Version, as the publisher.
|
||
|
||
D. Preserve all the copyright notices of the Document.
|
||
|
||
E. Add an appropriate copyright notice for your modifications
|
||
adjacent to the other copyright notices.
|
||
|
||
F. Include, immediately after the copyright notices, a license
|
||
notice giving the public permission to use the Modified
|
||
Version under the terms of this License, in the form shown in
|
||
the Addendum below.
|
||
|
||
G. Preserve in that license notice the full lists of Invariant
|
||
Sections and required Cover Texts given in the Document’s
|
||
license notice.
|
||
|
||
H. Include an unaltered copy of this License.
|
||
|
||
I. Preserve the section Entitled “History”, Preserve its Title,
|
||
and add to it an item stating at least the title, year, new
|
||
authors, and publisher of the Modified Version as given on the
|
||
Title Page. If there is no section Entitled “History” in the
|
||
Document, create one stating the title, year, authors, and
|
||
publisher of the Document as given on its Title Page, then add
|
||
an item describing the Modified Version as stated in the
|
||
previous sentence.
|
||
|
||
J. Preserve the network location, if any, given in the Document
|
||
for public access to a Transparent copy of the Document, and
|
||
likewise the network locations given in the Document for
|
||
previous versions it was based on. These may be placed in the
|
||
“History” section. You may omit a network location for a work
|
||
that was published at least four years before the Document
|
||
itself, or if the original publisher of the version it refers
|
||
to gives permission.
|
||
|
||
K. For any section Entitled “Acknowledgements” or “Dedications”,
|
||
Preserve the Title of the section, and preserve in the section
|
||
all the substance and tone of each of the contributor
|
||
acknowledgements and/or dedications given therein.
|
||
|
||
L. Preserve all the Invariant Sections of the Document, unaltered
|
||
in their text and in their titles. Section numbers or the
|
||
equivalent are not considered part of the section titles.
|
||
|
||
M. Delete any section Entitled “Endorsements”. Such a section
|
||
may not be included in the Modified Version.
|
||
|
||
N. Do not retitle any existing section to be Entitled
|
||
“Endorsements” or to conflict in title with any Invariant
|
||
Section.
|
||
|
||
O. Preserve any Warranty Disclaimers.
|
||
|
||
If the Modified Version includes new front-matter sections or
|
||
appendices that qualify as Secondary Sections and contain no
|
||
material copied from the Document, you may at your option designate
|
||
some or all of these sections as invariant. To do this, add their
|
||
titles to the list of Invariant Sections in the Modified Version’s
|
||
license notice. These titles must be distinct from any other
|
||
section titles.
|
||
|
||
You may add a section Entitled “Endorsements”, provided it contains
|
||
nothing but endorsements of your Modified Version by various
|
||
parties—for example, statements of peer review or that the text has
|
||
been approved by an organization as the authoritative definition of
|
||
a standard.
|
||
|
||
You may add a passage of up to five words as a Front-Cover Text,
|
||
and a passage of up to 25 words as a Back-Cover Text, to the end of
|
||
the list of Cover Texts in the Modified Version. Only one passage
|
||
of Front-Cover Text and one of Back-Cover Text may be added by (or
|
||
through arrangements made by) any one entity. If the Document
|
||
already includes a cover text for the same cover, previously added
|
||
by you or by arrangement made by the same entity you are acting on
|
||
behalf of, you may not add another; but you may replace the old
|
||
one, on explicit permission from the previous publisher that added
|
||
the old one.
|
||
|
||
The author(s) and publisher(s) of the Document do not by this
|
||
License give permission to use their names for publicity for or to
|
||
assert or imply endorsement of any Modified Version.
|
||
|
||
5. COMBINING DOCUMENTS
|
||
|
||
You may combine the Document with other documents released under
|
||
this License, under the terms defined in section 4 above for
|
||
modified versions, provided that you include in the combination all
|
||
of the Invariant Sections of all of the original documents,
|
||
unmodified, and list them all as Invariant Sections of your
|
||
combined work in its license notice, and that you preserve all
|
||
their Warranty Disclaimers.
|
||
|
||
The combined work need only contain one copy of this License, and
|
||
multiple identical Invariant Sections may be replaced with a single
|
||
copy. If there are multiple Invariant Sections with the same name
|
||
but different contents, make the title of each such section unique
|
||
by adding at the end of it, in parentheses, the name of the
|
||
original author or publisher of that section if known, or else a
|
||
unique number. Make the same adjustment to the section titles in
|
||
the list of Invariant Sections in the license notice of the
|
||
combined work.
|
||
|
||
In the combination, you must combine any sections Entitled
|
||
“History” in the various original documents, forming one section
|
||
Entitled “History”; likewise combine any sections Entitled
|
||
“Acknowledgements”, and any sections Entitled “Dedications”. You
|
||
must delete all sections Entitled “Endorsements.”
|
||
|
||
6. COLLECTIONS OF DOCUMENTS
|
||
|
||
You may make a collection consisting of the Document and other
|
||
documents released under this License, and replace the individual
|
||
copies of this License in the various documents with a single copy
|
||
that is included in the collection, provided that you follow the
|
||
rules of this License for verbatim copying of each of the documents
|
||
in all other respects.
|
||
|
||
You may extract a single document from such a collection, and
|
||
distribute it individually under this License, provided you insert
|
||
a copy of this License into the extracted document, and follow this
|
||
License in all other respects regarding verbatim copying of that
|
||
document.
|
||
|
||
7. AGGREGATION WITH INDEPENDENT WORKS
|
||
|
||
A compilation of the Document or its derivatives with other
|
||
separate and independent documents or works, in or on a volume of a
|
||
storage or distribution medium, is called an “aggregate” if the
|
||
copyright resulting from the compilation is not used to limit the
|
||
legal rights of the compilation’s users beyond what the individual
|
||
works permit. When the Document is included in an aggregate, this
|
||
License does not apply to the other works in the aggregate which
|
||
are not themselves derivative works of the Document.
|
||
|
||
If the Cover Text requirement of section 3 is applicable to these
|
||
copies of the Document, then if the Document is less than one half
|
||
of the entire aggregate, the Document’s Cover Texts may be placed
|
||
on covers that bracket the Document within the aggregate, or the
|
||
electronic equivalent of covers if the Document is in electronic
|
||
form. Otherwise they must appear on printed covers that bracket
|
||
the whole aggregate.
|
||
|
||
8. TRANSLATION
|
||
|
||
Translation is considered a kind of modification, so you may
|
||
distribute translations of the Document under the terms of section
|
||
4. Replacing Invariant Sections with translations requires special
|
||
permission from their copyright holders, but you may include
|
||
translations of some or all Invariant Sections in addition to the
|
||
original versions of these Invariant Sections. You may include a
|
||
translation of this License, and all the license notices in the
|
||
Document, and any Warranty Disclaimers, provided that you also
|
||
include the original English version of this License and the
|
||
original versions of those notices and disclaimers. In case of a
|
||
disagreement between the translation and the original version of
|
||
this License or a notice or disclaimer, the original version will
|
||
prevail.
|
||
|
||
If a section in the Document is Entitled “Acknowledgements”,
|
||
“Dedications”, or “History”, the requirement (section 4) to
|
||
Preserve its Title (section 1) will typically require changing the
|
||
actual title.
|
||
|
||
9. TERMINATION
|
||
|
||
You may not copy, modify, sublicense, or distribute the Document
|
||
except as expressly provided under this License. Any attempt
|
||
otherwise to copy, modify, sublicense, or distribute it is void,
|
||
and will automatically terminate your rights under this License.
|
||
|
||
However, if you cease all violation of this License, then your
|
||
license from a particular copyright holder is reinstated (a)
|
||
provisionally, unless and until the copyright holder explicitly and
|
||
finally terminates your license, and (b) permanently, if the
|
||
copyright holder fails to notify you of the violation by some
|
||
reasonable means prior to 60 days after the cessation.
|
||
|
||
Moreover, your license from a particular copyright holder is
|
||
reinstated permanently if the copyright holder notifies you of the
|
||
violation by some reasonable means, this is the first time you have
|
||
received notice of violation of this License (for any work) from
|
||
that copyright holder, and you cure the violation prior to 30 days
|
||
after your receipt of the notice.
|
||
|
||
Termination of your rights under this section does not terminate
|
||
the licenses of parties who have received copies or rights from you
|
||
under this License. If your rights have been terminated and not
|
||
permanently reinstated, receipt of a copy of some or all of the
|
||
same material does not give you any rights to use it.
|
||
|
||
10. FUTURE REVISIONS OF THIS LICENSE
|
||
|
||
The Free Software Foundation may publish new, revised versions of
|
||
the GNU Free Documentation License from time to time. Such new
|
||
versions will be similar in spirit to the present version, but may
|
||
differ in detail to address new problems or concerns. See
|
||
<https://www.gnu.org/licenses/>.
|
||
|
||
Each version of the License is given a distinguishing version
|
||
number. If the Document specifies that a particular numbered
|
||
version of this License “or any later version” applies to it, you
|
||
have the option of following the terms and conditions either of
|
||
that specified version or of any later version that has been
|
||
published (not as a draft) by the Free Software Foundation. If the
|
||
Document does not specify a version number of this License, you may
|
||
choose any version ever published (not as a draft) by the Free
|
||
Software Foundation. If the Document specifies that a proxy can
|
||
decide which future versions of this License can be used, that
|
||
proxy’s public statement of acceptance of a version permanently
|
||
authorizes you to choose that version for the Document.
|
||
|
||
11. RELICENSING
|
||
|
||
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
|
||
World Wide Web server that publishes copyrightable works and also
|
||
provides prominent facilities for anybody to edit those works. A
|
||
public wiki that anybody can edit is an example of such a server.
|
||
A “Massive Multiauthor Collaboration” (or “MMC”) contained in the
|
||
site means any set of copyrightable works thus published on the MMC
|
||
site.
|
||
|
||
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
|
||
license published by Creative Commons Corporation, a not-for-profit
|
||
corporation with a principal place of business in San Francisco,
|
||
California, as well as future copyleft versions of that license
|
||
published by that same organization.
|
||
|
||
“Incorporate” means to publish or republish a Document, in whole or
|
||
in part, as part of another Document.
|
||
|
||
An MMC is “eligible for relicensing” if it is licensed under this
|
||
License, and if all works that were first published under this
|
||
License somewhere other than this MMC, and subsequently
|
||
incorporated in whole or in part into the MMC, (1) had no cover
|
||
texts or invariant sections, and (2) were thus incorporated prior
|
||
to November 1, 2008.
|
||
|
||
The operator of an MMC Site may republish an MMC contained in the
|
||
site under CC-BY-SA on the same site at any time before August 1,
|
||
2009, provided the MMC is eligible for relicensing.
|
||
|
||
ADDENDUM: How to use this License for your documents
|
||
====================================================
|
||
|
||
To use this License in a document you have written, include a copy of
|
||
the License in the document and put the following copyright and license
|
||
notices just after the title page:
|
||
|
||
Copyright (C) YEAR YOUR NAME.
|
||
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, no Front-Cover Texts, and no Back-Cover
|
||
Texts. A copy of the license is included in the section entitled ``GNU
|
||
Free Documentation License''.
|
||
|
||
If you have Invariant Sections, Front-Cover Texts and Back-Cover
|
||
Texts, replace the “with...Texts.” line with this:
|
||
|
||
with the Invariant Sections being LIST THEIR TITLES, with
|
||
the Front-Cover Texts being LIST, and with the Back-Cover Texts
|
||
being LIST.
|
||
|
||
If you have Invariant Sections without Cover Texts, or some other
|
||
combination of the three, merge those two alternatives to suit the
|
||
situation.
|
||
|
||
If your document contains nontrivial examples of program code, we
|
||
recommend releasing these examples in parallel under your choice of free
|
||
software license, such as the GNU General Public License, to permit
|
||
their use in free software.
|
||
|
||
|
||
File: use-package.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
|
||
|
||
Index
|
||
*****
|
||
|
||
[index ]
|
||
* Menu:
|
||
|
||
* :after: Loading sequentially. (line 6)
|
||
* :all (with :after): Loading sequentially. (line 34)
|
||
* :any (with :after): Loading sequentially. (line 34)
|
||
* :autoload: Manual autoloads. (line 6)
|
||
* :bind: Key bindings. (line 6)
|
||
* :bind <1>: Global keybindings. (line 6)
|
||
* :bind-keymap, inside :bind: Binding to a keymap. (line 6)
|
||
* :catch: Troubleshooting Options.
|
||
(line 11)
|
||
* :commands: Manual autoloads. (line 6)
|
||
* :config: Config keyword. (line 6)
|
||
* :continue, inside :repeat-map and :bind: Binding to repeat-maps.
|
||
(line 45)
|
||
* :custom: User options. (line 6)
|
||
* :custom-face: Faces. (line 6)
|
||
* :defer: Deferring loading. (line 25)
|
||
* :defines: Byte-compiling. (line 16)
|
||
* :delight: Delight. (line 6)
|
||
* :demand: Forcing loading. (line 6)
|
||
* :diminish: Diminish. (line 6)
|
||
* :disabled: Disabling a package. (line 6)
|
||
* :ensure: Install package. (line 6)
|
||
* :ensure-system-package: use-package-ensure-system-package.
|
||
(line 6)
|
||
* :exit, inside :repeat-map and :bind: Binding to repeat-maps.
|
||
(line 27)
|
||
* :functions: Byte-compiling. (line 16)
|
||
* :hook: Hooks. (line 6)
|
||
* :if: Conditional loading. (line 6)
|
||
* :init: Init keyword. (line 6)
|
||
* :interpreter: Modes and interpreters.
|
||
(line 6)
|
||
* :load-path: Load path. (line 6)
|
||
* :magic: Magic handlers. (line 6)
|
||
* :magic-fallback: Magic handlers. (line 6)
|
||
* :map, inside :bind: Binding in keymaps. (line 6)
|
||
* :mode: Modes and interpreters.
|
||
(line 6)
|
||
* :no-require: Byte-compiling. (line 41)
|
||
* :pin: Pinning packages. (line 6)
|
||
* :preface: Preface keyword. (line 6)
|
||
* :repeat-map, inside :bind: Binding to repeat-maps.
|
||
(line 6)
|
||
* :requires: Load dependencies. (line 6)
|
||
* :unless: Conditional loading. (line 6)
|
||
* :when: Conditional loading. (line 6)
|
||
* autoloading packages: Deferring loading. (line 6)
|
||
* binding keys: Key bindings. (line 6)
|
||
* conditional loading before :preface or :ensure: Conditional loading.
|
||
(line 59)
|
||
* debugging: Troubleshooting. (line 6)
|
||
* describe-personal-keybindings: Displaying keybindings.
|
||
(line 6)
|
||
* disable package: Disabling a package. (line 6)
|
||
* expanding macro, for troubleshooting: Troubleshooting. (line 22)
|
||
* hooks: Hooks. (line 6)
|
||
* key bindings: Key bindings. (line 6)
|
||
* loading lazily: Deferring loading. (line 6)
|
||
* loading packages: Loading Packages. (line 6)
|
||
* multiple hooks: Hooks. (line 37)
|
||
* prevent a package from loading at compile-time: Byte-compiling.
|
||
(line 41)
|
||
* repeat-mode and use-package, using: Binding to repeat-maps.
|
||
(line 6)
|
||
* reporting bugs: Troubleshooting. (line 22)
|
||
* triggers, for loading packages: Deferring loading. (line 14)
|
||
* troubleshooting: Troubleshooting. (line 6)
|
||
* use-package-always-defer: Deferring loading. (line 68)
|
||
* use-package-always-pin: Pinning packages. (line 19)
|
||
* use-package-compute-statistics: Gathering Statistics. (line 12)
|
||
* use-package-ensure-function: Other package managers.
|
||
(line 10)
|
||
* use-package-expand-minimally: Troubleshooting Options.
|
||
(line 6)
|
||
* use-package-hook-name-suffix: Hooks. (line 65)
|
||
* use-package-report: Gathering Statistics. (line 19)
|
||
* use-package-reset-statistics: Gathering Statistics. (line 24)
|
||
* use-package-verbose: Gathering Statistics. (line 6)
|
||
|
||
|
||
|
||
Tag Table:
|
||
Node: Top947
|
||
Node: Basic Concepts3143
|
||
Node: Getting Started4569
|
||
Node: Loading Packages7734
|
||
Node: Loading basics9243
|
||
Ref: Loading basics-Footnote-110804
|
||
Node: Deferring loading10888
|
||
Node: Forcing loading14111
|
||
Node: Conditional loading14796
|
||
Node: Loading sequentially16960
|
||
Node: Load dependencies19541
|
||
Node: Load path20522
|
||
Node: Manual autoloads21759
|
||
Node: Configuring Packages22415
|
||
Node: Lisp Configuration23174
|
||
Node: Preface keyword24038
|
||
Node: Init keyword24944
|
||
Node: Config keyword25564
|
||
Node: Best practices26289
|
||
Node: Key bindings27766
|
||
Node: Global keybindings28536
|
||
Node: Binding in keymaps32350
|
||
Node: Binding to a keymap33561
|
||
Node: Binding to repeat-maps34595
|
||
Node: Displaying keybindings36982
|
||
Node: Hooks37544
|
||
Node: Modes and interpreters40312
|
||
Node: Magic handlers41851
|
||
Node: User options42680
|
||
Node: Faces44095
|
||
Node: Hiding minor modes44892
|
||
Ref: Hiding minor modes-Footnote-145599
|
||
Node: Diminish45654
|
||
Ref: Diminish-Footnote-146593
|
||
Node: Delight46652
|
||
Ref: Delight-Footnote-148460
|
||
Node: Installing packages48524
|
||
Node: Install package49137
|
||
Node: Pinning packages49967
|
||
Ref: Pinning packages-Footnote-151661
|
||
Node: Other package managers51741
|
||
Node: Byte-compiling52613
|
||
Node: Troubleshooting54605
|
||
Node: Troubleshooting Options55956
|
||
Node: Gathering Statistics57518
|
||
Node: Disabling a package59085
|
||
Node: Keyword extensions59801
|
||
Node: use-package-ensure-system-package60289
|
||
Ref: use-package-ensure-system-package-Footnote-163298
|
||
Ref: use-package-ensure-system-package-Footnote-263566
|
||
Node: Creating an extension63697
|
||
Node: History67109
|
||
Node: GNU Free Documentation License67782
|
||
Node: Index93134
|
||
|
||
End Tag Table
|
||
|
||
|
||
Local Variables:
|
||
coding: utf-8
|
||
End:
|