You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
946 lines
30 KiB
946 lines
30 KiB
\input texinfo @c -*- texinfo -*-
|
|
@c %**start of header
|
|
@setfilename use-package.info
|
|
@settitle use-package User Manual
|
|
@documentencoding UTF-8
|
|
@documentlanguage en
|
|
@c %**end of header
|
|
|
|
@copying
|
|
@quotation
|
|
Copyright (C) 2012-2022 Free Software Foundation, Inc.
|
|
|
|
You can redistribute this document and/or modify it under the terms
|
|
of the GNU General Public License as published by the Free Software
|
|
Foundation, either version 3 of the License, or (at your option) any
|
|
later version.
|
|
|
|
This document is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU
|
|
General Public License for more details.
|
|
|
|
@end quotation
|
|
@end copying
|
|
|
|
@dircategory Emacs
|
|
@direntry
|
|
* use-package: (use-package). Declarative package configuration for Emacs.
|
|
@end direntry
|
|
|
|
@finalout
|
|
@titlepage
|
|
@title use-package User Manual
|
|
@subtitle for version 2.4.1-119-g0be480e+1
|
|
@author John Wiegley
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@contents
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top use-package User Manual
|
|
|
|
The @code{use-package} macro allows you to isolate package configuration in your
|
|
@code{.emacs} file in a way that is both performance-oriented and, well, tidy. I
|
|
created it because I have over 80 packages that I use in Emacs, and things
|
|
were getting difficult to manage. Yet with this utility my total load time is
|
|
around 2 seconds, with no loss of functionality!
|
|
|
|
@insertcopying
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* Introduction::
|
|
* Installation::
|
|
* Getting Started::
|
|
* Basic Concepts::
|
|
* Issues/Requests::
|
|
* Keywords::
|
|
* Debugging Tools::
|
|
|
|
@detailmenu
|
|
--- The Detailed Node Listing ---
|
|
|
|
Installation
|
|
|
|
* Installing from GNU ELPA::
|
|
* Installing from the Git Repository::
|
|
* Post-Installation Tasks::
|
|
|
|
Keywords
|
|
|
|
* @code{after}:: @code{:after}.
|
|
* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap}, @code{:bind-keymap*}.
|
|
* @code{bind} @code{bind*}:: @code{:bind}, @code{:bind*}.
|
|
* @code{commands}:: @code{:commands}.
|
|
* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init}, @code{:config}.
|
|
* @code{custom}:: @code{:custom}.
|
|
* @code{custom-face}:: @code{:custom-face}.
|
|
* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}.
|
|
* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}.
|
|
* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}.
|
|
* @code{disabled}:: @code{:disabled}.
|
|
* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}.
|
|
* @code{hook}:: @code{:hook}.
|
|
* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when}, @code{:unless}.
|
|
* @code{load-path}:: @code{:load-path}.
|
|
* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}.
|
|
* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}.
|
|
* @code{no-require}:: @code{:no-require}.
|
|
* @code{requires}:: @code{:requires}.
|
|
|
|
@code{bind}, @code{bind*}
|
|
|
|
* Binding to local keymaps::
|
|
|
|
|
|
@end detailmenu
|
|
@end menu
|
|
|
|
@node Introduction
|
|
@chapter Introduction
|
|
|
|
The @code{use-package} macro allows you to isolate package configuration in your
|
|
@code{.emacs} file in a way that is both performance-oriented and, well, tidy. I
|
|
created it because I have over 80 packages that I use in Emacs, and things
|
|
were getting difficult to manage. Yet with this utility my total load time is
|
|
around 2 seconds, with no loss of functionality!
|
|
|
|
More text to come@dots{}
|
|
|
|
@node Installation
|
|
@chapter Installation
|
|
|
|
use-package can be installed using Emacs' package manager or manually from
|
|
its development repository.
|
|
|
|
@menu
|
|
* Installing from GNU ELPA::
|
|
* Installing from the Git Repository::
|
|
* Post-Installation Tasks::
|
|
@end menu
|
|
|
|
@node Installing from GNU ELPA
|
|
@section Installing from GNU ELPA
|
|
|
|
use-package is available from GNU ELPA. If you haven't used
|
|
Emacs' package manager before, then it is high time you familiarize yourself
|
|
with it by reading the documentation in the Emacs manual, see
|
|
@ref{Packages,,,emacs,}. Then add one of the archives to @code{package-archives}:
|
|
|
|
First, you need to update the local package list using:
|
|
|
|
@example
|
|
M-x package-refresh-contents RET
|
|
@end example
|
|
|
|
Once you have done that, you can install use-package and its
|
|
dependencies using:
|
|
|
|
@example
|
|
M-x package-install RET use-package RET
|
|
@end example
|
|
|
|
Now see @ref{Post-Installation Tasks}.
|
|
|
|
@node Installing from the Git Repository
|
|
@section Installing from the Git Repository
|
|
|
|
First, use Git to clone the use-package repository:
|
|
|
|
@example
|
|
$ git clone https://github.com/jwiegley/use-package.git ~/.emacs.d/site-lisp/use-package
|
|
$ cd ~/.emacs.d/site-lisp/use-package
|
|
@end example
|
|
|
|
Then compile the libraries and generate the info manuals:
|
|
|
|
@example
|
|
$ make
|
|
@end example
|
|
|
|
You may need to create @code{/path/to/use-package/config.mk} with the following
|
|
content before running @code{make}:
|
|
|
|
@example
|
|
LOAD_PATH = -L /path/to/use-package
|
|
@end example
|
|
|
|
Finally add this to your init file:
|
|
|
|
@lisp
|
|
(add-to-list 'load-path "~/.emacs.d/site-lisp/use-package")
|
|
(require 'use-package)
|
|
|
|
(with-eval-after-load 'info
|
|
(info-initialize)
|
|
(add-to-list 'Info-directory-list
|
|
"~/.emacs.d/site-lisp/use-package/"))
|
|
@end lisp
|
|
|
|
Note that elements of @code{load-path} should not end with a slash, while those of
|
|
@code{Info-directory-list} should.
|
|
|
|
Instead of running use-package directly from the repository by adding it to
|
|
the @code{load-path}, you might want to instead install it in some other directory
|
|
using @code{sudo make install} and setting @code{load-path} accordingly.
|
|
|
|
To update use-package use:
|
|
|
|
@example
|
|
$ git pull
|
|
$ make
|
|
@end example
|
|
|
|
At times it might be necessary to run @code{make clean all} instead.
|
|
|
|
To view all available targets use @code{make help}.
|
|
|
|
Now see @ref{Post-Installation Tasks}.
|
|
|
|
@node Post-Installation Tasks
|
|
@section Post-Installation Tasks
|
|
|
|
After installing use-package you should verify that you are indeed using the
|
|
use-package release you think you are using. It's best to restart Emacs before
|
|
doing so, to make sure you are not using an outdated value for @code{load-path}.
|
|
|
|
@example
|
|
C-h v use-package-version RET
|
|
@end example
|
|
|
|
should display something like
|
|
|
|
@example
|
|
use-package-version’s value is "2.4.3"
|
|
@end example
|
|
|
|
If you are completely new to use-package then see @ref{Getting Started}.
|
|
|
|
If you run into problems, then please see the @ref{Debugging Tools}.
|
|
|
|
@node Getting Started
|
|
@chapter Getting Started
|
|
|
|
TODO@. For now, see @code{README.md}.
|
|
|
|
@node Basic Concepts
|
|
@chapter Basic Concepts
|
|
|
|
@code{use-package} was created for few basic reasons, each of which drove the
|
|
design in various ways. Understanding these reasons may help make some of
|
|
those decisions clearer:
|
|
|
|
@itemize
|
|
@item
|
|
To gather all configuration details of a package into one place,
|
|
making it easier to copy, disable, or move it elsewhere in the init
|
|
file.
|
|
|
|
@item
|
|
To reduce duplication and boilerplate, capturing several common
|
|
practices as mere keywords both easy and intuitive to use.
|
|
|
|
@item
|
|
To make startup time of Emacs as quick as possible, without
|
|
sacrificing the quantity of add-on packages used.
|
|
|
|
@item
|
|
To make it so errors encountered during startup disable only the
|
|
package raising the error, and as little else as possible, leaving a
|
|
close to a functional Emacs as possible.
|
|
|
|
@item
|
|
To allow byte-compilation of one's init file so that any warnings or
|
|
errors seen are meaningful. In this way, even if byte-compilation is not
|
|
used for speed (reason 3), it can still be used as a sanity check.
|
|
@end itemize
|
|
|
|
@node Issues/Requests
|
|
@chapter Issues/Requests
|
|
|
|
@node Keywords
|
|
@chapter Keywords
|
|
|
|
@menu
|
|
* @code{after}:: @code{after}.
|
|
* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap}, @code{:bind-keymap*}.
|
|
* @code{bind} @code{bind*}:: @code{bind} @code{:bind*}.
|
|
* @code{commands}:: @code{:commands}.
|
|
* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init}, @code{:config}.
|
|
* @code{custom}:: @code{:custom}.
|
|
* @code{custom-face}:: @code{:custom-face}.
|
|
* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}.
|
|
* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}.
|
|
* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}.
|
|
* @code{disabled}:: @code{:disabled}.
|
|
* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}.
|
|
* @code{hook}:: @code{:hook}.
|
|
* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when}, @code{:unless}.
|
|
* @code{load-path}:: @code{:load-path}.
|
|
* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}.
|
|
* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}.
|
|
* @code{no-require}:: @code{:no-require}.
|
|
* @code{requires}:: @code{:requires}.
|
|
@end menu
|
|
|
|
@node @code{after}
|
|
@section @code{:after}
|
|
|
|
Sometimes it only makes sense to configure a package after another has been
|
|
loaded, because certain variables or functions are not in scope until that
|
|
time. This can achieved using an @code{:after} keyword that allows a fairly rich
|
|
description of the exact conditions when loading should occur. Here is an
|
|
example:
|
|
|
|
@lisp
|
|
(use-package hydra
|
|
:load-path "site-lisp/hydra")
|
|
|
|
(use-package ivy
|
|
:load-path "site-lisp/swiper")
|
|
|
|
(use-package ivy-hydra
|
|
:after (ivy hydra))
|
|
@end lisp
|
|
|
|
In this case, because all of these packages are demand-loaded in the order
|
|
they occur, the use of @code{:after} is not strictly necessary. By using it,
|
|
however, the above code becomes order-independent, without an implicit
|
|
depedence on the nature of your init file.
|
|
|
|
By default, @code{:after (foo bar)} is the same as @code{:after (:all foo bar)}, meaning
|
|
that loading of the given package will not happen until both @code{foo} and @code{bar}
|
|
have been loaded. Here are some of the other possibilities:
|
|
|
|
@lisp
|
|
:after (foo bar)
|
|
:after (:all foo bar)
|
|
:after (:any foo bar)
|
|
:after (:all (:any foo bar) (:any baz quux))
|
|
:after (:any (:all foo bar) (:all baz quux))
|
|
@end lisp
|
|
|
|
When you nest selectors, such as @code{(:any (:all foo bar) (:all baz quux))}, it
|
|
means that the package will be loaded when either both @code{foo} and @code{bar} have
|
|
been loaded, or both @code{baz} and @code{quux} have been loaded.
|
|
|
|
@strong{NOTE}: Pay attention if you set @code{use-package-always-defer} to t, and also use
|
|
the @code{:after} keyword, as you will need to specify how the declared package is
|
|
to be loaded: e.g., by some @code{:bind}. If you're not using one of the mechanisms
|
|
that registers autoloads, such as @code{:bind} or @code{:hook}, and your package manager
|
|
does not provide autoloads, it's possible that without adding @code{:demand t} to
|
|
those declarations, your package will never be loaded.
|
|
|
|
@node @code{bind-keymap} @code{bind-keymap*}
|
|
@section @code{:bind-keymap}, @code{:bind-keymap*}
|
|
|
|
Normally @code{:bind} expects that commands are functions that will be autoloaded
|
|
from the given package. However, this does not work if one of those commands
|
|
is actually a keymap, since keymaps are not functions, and cannot be
|
|
autoloaded using Emacs' @code{autoload} mechanism.
|
|
|
|
To handle this case, @code{use-package} offers a special, limited variant of
|
|
@code{:bind} called @code{:bind-keymap}. The only difference is that the "commands"
|
|
bound to by @code{:bind-keymap} must be keymaps defined in the package, rather than
|
|
command functions. This is handled behind the scenes by generating custom code
|
|
that loads the package containing the keymap, and then re-executes your
|
|
keypress after the first load, to reinterpret that keypress as a prefix key.
|
|
|
|
For example:
|
|
|
|
@lisp
|
|
(use-package projectile
|
|
:bind-keymap
|
|
("C-c p" . projectile-command-map)
|
|
@end lisp
|
|
|
|
@node @code{bind} @code{bind*}
|
|
@section @code{:bind}, @code{:bind*}
|
|
|
|
Another common thing to do when loading a module is to bind a key to primary
|
|
commands within that module:
|
|
|
|
@lisp
|
|
(use-package ace-jump-mode
|
|
:bind ("C-." . ace-jump-mode))
|
|
@end lisp
|
|
|
|
This does two things: first, it creates an autoload for the @code{ace-jump-mode}
|
|
command and defers loading of @code{ace-jump-mode} until you actually use it.
|
|
Second, it binds the key @code{C-.} to that command. After loading, you can use
|
|
@code{M-x describe-personal-keybindings} to see all such keybindings you've set
|
|
throughout your @code{.emacs} file.
|
|
|
|
A more literal way to do the exact same thing is:
|
|
|
|
@lisp
|
|
(use-package ace-jump-mode
|
|
:commands ace-jump-mode
|
|
:init
|
|
(bind-key "C-." 'ace-jump-mode))
|
|
@end lisp
|
|
|
|
When you use the @code{:commands} keyword, it creates autoloads for those commands
|
|
and defers loading of the module until they are used. Since the @code{:init} form
|
|
is always run---even if @code{ace-jump-mode} might not be on your system---remember
|
|
to restrict @code{:init} code to only what would succeed either way.
|
|
|
|
The @code{:bind} keyword takes either a cons or a list of conses:
|
|
|
|
@lisp
|
|
(use-package hi-lock
|
|
:bind (("M-o l" . highlight-lines-matching-regexp)
|
|
("M-o r" . highlight-regexp)
|
|
("M-o w" . highlight-phrase)))
|
|
@end lisp
|
|
|
|
The @code{:commands} keyword likewise takes either a symbol or a list of symbols.
|
|
|
|
NOTE: Special keys like @code{tab} or @code{F1}-@code{Fn} can be written in square brackets,
|
|
i.e. @code{[tab]} instead of @code{"tab"}. The syntax for the keybindings is similar to
|
|
the "kbd" syntax: see @uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html, the Emacs Manual} for more information.
|
|
|
|
Examples:
|
|
|
|
@lisp
|
|
(use-package helm
|
|
:bind (("M-x" . helm-M-x)
|
|
("M-<f5>" . helm-find-files)
|
|
([f10] . helm-buffers-list)
|
|
([S-f10] . helm-recentf)))
|
|
@end lisp
|
|
|
|
@menu
|
|
* Binding to local keymaps::
|
|
@end menu
|
|
|
|
@node Binding to local keymaps
|
|
@subsection Binding to local keymaps
|
|
|
|
Slightly different from binding a key to a keymap, is binding a key @strong{within} a
|
|
local keymap that only exists after the package is loaded. @code{use-package}
|
|
supports this with a @code{:map} modifier, taking the local keymap to bind to:
|
|
|
|
@lisp
|
|
(use-package helm
|
|
:bind (:map helm-command-map
|
|
("C-c h" . helm-execute-persistent-action)))
|
|
@end lisp
|
|
|
|
The effect of this statement is to wait until @code{helm} has loaded, and then to
|
|
bind the key @code{C-c h} to @code{helm-execute-persistent-action} within Helm's local
|
|
keymap, @code{helm-mode-map}.
|
|
|
|
Multiple uses of @code{:map} may be specified. Any binding occurring before the
|
|
first use of @code{:map} are applied to the global keymap:
|
|
|
|
@lisp
|
|
(use-package term
|
|
: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)))
|
|
@end lisp
|
|
|
|
@node @code{commands}
|
|
@section @code{:commands}
|
|
|
|
@node @code{preface} @code{init} @code{config}
|
|
@section @code{:preface}, @code{:init}, @code{:config}
|
|
|
|
Here is the simplest @code{use-package} declaration:
|
|
|
|
@lisp
|
|
;; This is only needed once, near the top of the file
|
|
(eval-when-compile
|
|
;; Following line is not needed if use-package.el is in ~/.emacs.d
|
|
(add-to-list 'load-path "<path where use-package is installed>")
|
|
(require 'use-package))
|
|
|
|
(use-package foo)
|
|
@end lisp
|
|
|
|
This loads in the package @code{foo}, but only if @code{foo} is available on your
|
|
system. If not, a warning is logged to the @code{*Messages*} buffer. If it
|
|
succeeds, a message about @code{"Loading foo"} is logged, along with the time it
|
|
took to load, if it took over 0.1 seconds.
|
|
|
|
Use the @code{:init} keyword to execute code before a package is loaded. It
|
|
accepts one or more forms, up until the next keyword:
|
|
|
|
@lisp
|
|
(use-package foo
|
|
:init
|
|
(setq foo-variable t))
|
|
@end lisp
|
|
|
|
Similarly, @code{:config} can be used to execute code after a package is loaded.
|
|
In cases where loading is done lazily (see more about autoloading below), this
|
|
execution is deferred until after the autoload occurs:
|
|
|
|
@lisp
|
|
(use-package foo
|
|
:init
|
|
(setq foo-variable t)
|
|
:config
|
|
(foo-mode 1))
|
|
@end lisp
|
|
|
|
As you might expect, you can use @code{:init} and @code{:config} together:
|
|
|
|
@lisp
|
|
(use-package color-moccur
|
|
:commands (isearch-moccur isearch-all)
|
|
:bind (("M-s O" . moccur)
|
|
:map isearch-mode-map
|
|
("M-o" . isearch-moccur)
|
|
("M-O" . isearch-moccur-all))
|
|
:init
|
|
(setq isearch-lazy-highlight t)
|
|
:config
|
|
(use-package moccur-edit))
|
|
@end lisp
|
|
|
|
In this case, I want to autoload the commands @code{isearch-moccur} and
|
|
@code{isearch-all} from @code{color-moccur.el}, and bind keys both at the global level
|
|
and within the @code{isearch-mode-map} (see next section). When the package is
|
|
actually loaded (by using one of these commands), @code{moccur-edit} is also
|
|
loaded, to allow editing of the @code{moccur} buffer.
|
|
|
|
@node @code{custom}
|
|
@section @code{:custom}
|
|
|
|
The @code{:custom} keyword allows customization of package custom variables.
|
|
|
|
@lisp
|
|
(use-package comint
|
|
:custom
|
|
(comint-buffer-maximum-size 20000 "Increase comint buffer size.")
|
|
(comint-prompt-read-only t "Make the prompt read only."))
|
|
@end lisp
|
|
|
|
The documentation string is not mandatory.
|
|
|
|
@node @code{custom-face}
|
|
@section @code{:custom-face}
|
|
|
|
The @code{:custom-face} keyword allows customization of package custom faces.
|
|
|
|
@lisp
|
|
(use-package eruby-mode
|
|
:custom-face
|
|
(eruby-standard-face ((t (:slant italic)))))
|
|
@end lisp
|
|
|
|
@node @code{defer} @code{demand}
|
|
@section @code{:defer}, @code{:demand}
|
|
|
|
In almost all cases you don't need to manually specify @code{:defer t}. This is
|
|
implied whenever @code{:bind} or @code{:mode} or @code{:interpreter} is used. Typically, you
|
|
only need to specify @code{:defer} if you know for a fact that some other package
|
|
will do something to cause your package to load at the appropriate time, and
|
|
thus you would like to defer loading even though use-package isn't creating
|
|
any autoloads for you.
|
|
|
|
You can override package deferral with the @code{:demand} keyword. Thus, even if
|
|
you use @code{:bind}, using @code{:demand} will force loading to occur immediately and
|
|
not establish an autoload for the bound key.
|
|
|
|
@node @code{defines} @code{functions}
|
|
@section @code{:defines}, @code{:functions}
|
|
|
|
Another feature of @code{use-package} is that it always loads every file that it
|
|
can when @code{.emacs} is being byte-compiled. This helps to silence spurious
|
|
warnings about unknown variables and functions.
|
|
|
|
However, there are times when this is just not enough. For those times, use
|
|
the @code{:defines} and @code{:functions} keywords to introduce dummy variable and
|
|
function declarations solely for the sake of the byte-compiler:
|
|
|
|
@lisp
|
|
(use-package texinfo
|
|
:defines texinfo-section-list
|
|
:commands texinfo-mode
|
|
:init
|
|
(add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode)))
|
|
@end lisp
|
|
|
|
If you need to silence a missing function warning, you can use @code{:functions}:
|
|
|
|
@lisp
|
|
(use-package ruby-mode
|
|
:mode "\\.rb\\'"
|
|
:interpreter "ruby"
|
|
:functions inf-ruby-keys
|
|
:config
|
|
(defun my-ruby-mode-hook ()
|
|
(require 'inf-ruby)
|
|
(inf-ruby-keys))
|
|
|
|
(add-hook 'ruby-mode-hook 'my-ruby-mode-hook))
|
|
@end lisp
|
|
|
|
@node @code{diminish} @code{delight}
|
|
@section @code{:diminish}, @code{:delight}
|
|
|
|
@code{use-package} also provides built-in support for the diminish and delight
|
|
utilities---if you have them installed. Their purpose is to remove or change
|
|
minor mode strings in your mode-line.
|
|
|
|
@uref{https://github.com/myrjola/diminish.el, diminish} is invoked with the @code{:diminish} keyword, which is passed either a
|
|
minor mode symbol, a cons of the symbol and its replacement string, or just a
|
|
replacement string, in which case the minor mode symbol is guessed to be the
|
|
package name with "-mode" appended at the end:
|
|
|
|
@lisp
|
|
(use-package abbrev
|
|
:diminish abbrev-mode
|
|
:config
|
|
(if (file-exists-p abbrev-file-name)
|
|
(quietly-read-abbrev-file)))
|
|
@end lisp
|
|
|
|
@uref{https://elpa.gnu.org/packages/delight.html, delight} is invoked with the @code{:delight} keyword, which is passed a minor mode
|
|
symbol, a replacement string or quoted @uref{https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Data.html, mode-line data} (in which case the minor
|
|
mode symbol is guessed to be the package name with "-mode" appended at the
|
|
end), both of these, or several lists of both. If no arguments are provided,
|
|
the default mode name is hidden completely.
|
|
|
|
@lisp
|
|
;; Don't show anything for rainbow-mode.
|
|
(use-package rainbow-mode
|
|
:delight)
|
|
|
|
;; Don't show anything for auto-revert-mode, which doesn't match
|
|
;; its package name.
|
|
(use-package autorevert
|
|
:delight auto-revert-mode)
|
|
|
|
;; Remove the mode name for projectile-mode, but show the project name.
|
|
(use-package projectile
|
|
:delight '(:eval (concat " " (projectile-project-name))))
|
|
|
|
;; Completely hide visual-line-mode and change auto-fill-mode to " AF".
|
|
(use-package emacs
|
|
:delight
|
|
(auto-fill-function " AF")
|
|
(visual-line-mode))
|
|
@end lisp
|
|
|
|
@node @code{disabled}
|
|
@section @code{:disabled}
|
|
|
|
The @code{:disabled} keyword can turn off a module you're having difficulties with,
|
|
or stop loading something you're not using at the present time:
|
|
|
|
@lisp
|
|
(use-package ess-site
|
|
:disabled
|
|
:commands R)
|
|
@end lisp
|
|
|
|
When byte-compiling your @code{.emacs} file, disabled declarations are omitted
|
|
from the output entirely, to accelerate startup times.
|
|
|
|
@node @code{ensure} @code{pin}
|
|
@section @code{:ensure}, @code{:pin}
|
|
|
|
You can use @code{use-package} to load packages from ELPA with @code{package.el}. This
|
|
is particularly useful if you share your @code{.emacs} among several machines; the
|
|
relevant packages are downloaded automatically once declared in your @code{.emacs}.
|
|
The @code{:ensure} keyword causes the package(s) to be installed automatically if
|
|
not already present on your system (set @code{(setq use-package-always-ensure t)}
|
|
if you wish this behavior to be global for all packages):
|
|
|
|
@lisp
|
|
(use-package magit
|
|
:ensure t)
|
|
@end lisp
|
|
|
|
If you need to install a different package from the one named by
|
|
@code{use-package}, you can specify it like this:
|
|
|
|
@lisp
|
|
(use-package tex
|
|
:ensure auctex)
|
|
@end lisp
|
|
|
|
Lastly, when running on Emacs 24.4 or later, use-package can pin a package to
|
|
a specific archive, allowing you to mix and match packages from different
|
|
archives. The primary use-case for this is preferring packages from the
|
|
@code{melpa-stable} and @code{gnu} archives, but using specific packages from @code{melpa}
|
|
when you need to track newer versions than what is available in the @code{stable}
|
|
archives is also a valid use-case.
|
|
|
|
By default @code{package.el} prefers @code{melpa} over @code{melpa-stable} due to the
|
|
versioning @code{(> evil-20141208.623 evil-1.0.9)}, so even if you are tracking
|
|
only a single package from @code{melpa}, you will need to tag all the non-@code{melpa}
|
|
packages with the appropriate archive. If this really annoys you, then you can
|
|
set @code{use-package-always-pin} to set a default.
|
|
|
|
If you want to manually keep a package updated and ignore upstream updates,
|
|
you can pin it to @code{manual}, which as long as there is no repository by that
|
|
name, will Just Work(tm).
|
|
|
|
@code{use-package} throws an error if you try to pin a package to an archive that
|
|
has not been configured using @code{package-archives} (apart from the magic
|
|
@code{manual} archive mentioned above):
|
|
|
|
@example
|
|
Archive 'foo' requested for package 'bar' is not available.
|
|
@end example
|
|
|
|
Example:
|
|
|
|
@lisp
|
|
(use-package company
|
|
:ensure t
|
|
:pin melpa-stable)
|
|
|
|
(use-package evil
|
|
:ensure t)
|
|
;; no :pin needed, as package.el will choose the version in melpa
|
|
|
|
(use-package adaptive-wrap
|
|
:ensure t
|
|
;; as this package is available only in the gnu archive, this is
|
|
;; technically not needed, but it helps to highlight where it
|
|
;; comes from
|
|
:pin gnu)
|
|
|
|
(use-package org
|
|
:ensure t
|
|
;; ignore org-mode from upstream and use a manually installed version
|
|
:pin manual)
|
|
@end lisp
|
|
|
|
@strong{NOTE}: the @code{:pin} argument has no effect on emacs versions < 24.4.
|
|
|
|
@node @code{hook}
|
|
@section @code{:hook}
|
|
|
|
The @code{:hook} keyword allows adding functions onto hooks, here only the basename
|
|
of the hook is required. Thus, all of the following are equivalent:
|
|
|
|
@lisp
|
|
(use-package ace-jump-mode
|
|
:hook prog-mode)
|
|
|
|
(use-package ace-jump-mode
|
|
:hook (prog-mode . ace-jump-mode))
|
|
|
|
(use-package ace-jump-mode
|
|
:commands ace-jump-mode
|
|
:init
|
|
(add-hook 'prog-mode-hook #'ace-jump-mode))
|
|
@end lisp
|
|
|
|
And likewise, when multiple hooks should be applied, the following are also
|
|
equivalent:
|
|
|
|
@lisp
|
|
(use-package ace-jump-mode
|
|
:hook (prog-mode text-mode))
|
|
|
|
(use-package ace-jump-mode
|
|
:hook ((prog-mode text-mode) . ace-jump-mode))
|
|
|
|
(use-package ace-jump-mode
|
|
:hook ((prog-mode . ace-jump-mode)
|
|
(text-mode . ace-jump-mode)))
|
|
|
|
(use-package ace-jump-mode
|
|
:commands ace-jump-mode
|
|
:init
|
|
(add-hook 'prog-mode-hook #'ace-jump-mode)
|
|
(add-hook 'text-mode-hook #'ace-jump-mode))
|
|
@end lisp
|
|
|
|
The use of @code{:hook}, as with @code{:bind}, @code{:mode}, @code{:interpreter}, etc., causes the
|
|
functions being hooked to implicitly be read as @code{:commands} (meaning they will
|
|
establish interactive @code{autoload} definitions for that module, if not already
|
|
defined as functions), and so @code{:defer t} is also implied by @code{:hook}.
|
|
|
|
@node @code{if} @code{when} @code{unless}
|
|
@section @code{:if}, @code{:when}, @code{:unless}
|
|
|
|
You can use the @code{:if} keyword to predicate the loading and initialization of
|
|
modules.
|
|
|
|
For example, I only want @code{edit-server} running for my main, graphical Emacs,
|
|
not for other Emacsen I may start at the command line:
|
|
|
|
@lisp
|
|
(use-package edit-server
|
|
:if window-system
|
|
:init
|
|
(add-hook 'after-init-hook 'server-start t)
|
|
(add-hook 'after-init-hook 'edit-server-start t))
|
|
@end lisp
|
|
|
|
In another example, we can load things conditional on the operating system:
|
|
|
|
@lisp
|
|
(use-package exec-path-from-shell
|
|
:if (memq window-system '(mac ns))
|
|
:ensure t
|
|
:config
|
|
(exec-path-from-shell-initialize))
|
|
@end lisp
|
|
|
|
Note that @code{:when} is provided as an alias for @code{:if}, and @code{:unless foo} means
|
|
the same thing as @code{:if (not foo)}.
|
|
|
|
@node @code{load-path}
|
|
@section @code{:load-path}
|
|
|
|
If your package needs a directory added to the @code{load-path} in order to load,
|
|
use @code{:load-path}. This takes a symbol, a function, a string or a list of
|
|
strings. If the path is relative, it is expanded within
|
|
@code{user-emacs-directory}:
|
|
|
|
@lisp
|
|
(use-package ess-site
|
|
:load-path "site-lisp/ess/lisp/"
|
|
:commands R)
|
|
@end lisp
|
|
|
|
Note that when using a symbol or a function to provide a dynamically generated
|
|
list of paths, you must inform the byte-compiler of this definition so the
|
|
value is available at byte-compilation time. This is done by using the special
|
|
form @code{eval-and-compile} (as opposed to @code{eval-when-compile}). Further, this
|
|
value is fixed at whatever was determined during compilation, to avoid looking
|
|
up the same information again on each startup:
|
|
|
|
@lisp
|
|
(eval-and-compile
|
|
(defun ess-site-load-path ()
|
|
(shell-command "find ~ -path ess/lisp")))
|
|
|
|
(use-package ess-site
|
|
:load-path (lambda () (list (ess-site-load-path)))
|
|
:commands R)
|
|
@end lisp
|
|
|
|
@node @code{mode} @code{interpreter}
|
|
@section @code{:mode}, @code{:interpreter}
|
|
|
|
Similar to @code{:bind}, you can use @code{:mode} and @code{:interpreter} to establish a
|
|
deferred binding within the @code{auto-mode-alist} and @code{interpreter-mode-alist}
|
|
variables. The specifier to either keyword can be a cons cell, a list of cons
|
|
cells, or a string or regexp:
|
|
|
|
@lisp
|
|
(use-package ruby-mode
|
|
:mode "\\.rb\\'"
|
|
:interpreter "ruby")
|
|
|
|
;; The package is "python" but the mode is "python-mode":
|
|
(use-package python
|
|
:mode ("\\.py\\'" . python-mode)
|
|
:interpreter ("python" . python-mode))
|
|
@end lisp
|
|
|
|
If you aren't using @code{:commands}, @code{:bind}, @code{:bind*}, @code{:bind-keymap},
|
|
@code{:bind-keymap*}, @code{:mode}, or @code{:interpreter} (all of which imply @code{:defer}; see
|
|
the docstring for @code{use-package} for a brief description of each), you can
|
|
still defer loading with the @code{:defer} keyword:
|
|
|
|
@lisp
|
|
(use-package ace-jump-mode
|
|
:defer t
|
|
:init
|
|
(autoload 'ace-jump-mode "ace-jump-mode" nil t)
|
|
(bind-key "C-." 'ace-jump-mode))
|
|
@end lisp
|
|
|
|
This does exactly the same thing as the following:
|
|
|
|
@lisp
|
|
(use-package ace-jump-mode
|
|
:bind ("C-." . ace-jump-mode))
|
|
@end lisp
|
|
|
|
@node @code{magic} @code{magic-fallback}
|
|
@section @code{:magic}, @code{:magic-fallback}
|
|
|
|
Similar to @code{:mode} and @code{:interpreter}, you can also use @code{:magic} and
|
|
@code{:magic-fallback} to cause certain function to be run if the beginning of a
|
|
file matches a given regular expression. The difference between the two is
|
|
that @code{:magic-fallback} has a lower priority than @code{:mode}. For example:
|
|
|
|
@lisp
|
|
(use-package pdf-tools
|
|
:load-path "site-lisp/pdf-tools/lisp"
|
|
:magic ("%PDF" . pdf-view-mode)
|
|
:config
|
|
(pdf-tools-install))
|
|
@end lisp
|
|
|
|
This registers an autoloaded command for @code{pdf-view-mode}, defers loading of
|
|
@code{pdf-tools}, and runs @code{pdf-view-mode} if the beginning of a buffer matches the
|
|
string @code{"%PDF"}.
|
|
|
|
@node @code{no-require}
|
|
@section @code{:no-require}
|
|
|
|
Normally, @code{use-package} will load each package at compile time before
|
|
compiling the configuration, to ensure that any necessary symbols are in scope
|
|
to satisfy the byte-compiler. At times this can cause problems, since a
|
|
package may have special loading requirements, and all that you want to use
|
|
@code{use-package} for is to add a configuration to the @code{eval-after-load} hook. In
|
|
such cases, use the @code{:no-require} keyword:
|
|
|
|
@lisp
|
|
(use-package foo
|
|
:no-require t
|
|
:config
|
|
(message "This is evaluated when `foo' is loaded"))
|
|
@end lisp
|
|
|
|
@node @code{requires}
|
|
@section @code{:requires}
|
|
|
|
While the @code{:after} keyword delays loading until the dependencies are loaded,
|
|
the somewhat simpler @code{:requires} keyword simply never loads the package if the
|
|
dependencies are not available at the time the @code{use-package} declaration is
|
|
encountered. By "available" in this context it means that @code{foo} is available
|
|
of @code{(featurep 'foo)} evaluates to a non-nil value. For example:
|
|
|
|
@lisp
|
|
(use-package abbrev
|
|
:requires foo)
|
|
@end lisp
|
|
|
|
This is the same as:
|
|
|
|
@lisp
|
|
(use-package abbrev
|
|
:if (featurep 'foo))
|
|
@end lisp
|
|
|
|
As a convenience, a list of such packages may be specified:
|
|
|
|
@lisp
|
|
(use-package abbrev
|
|
:requires (foo bar baz))
|
|
@end lisp
|
|
|
|
For more complex logic, such as that supported by @code{:after}, simply use @code{:if}
|
|
and the appropriate Lisp expression.
|
|
|
|
@node Debugging Tools
|
|
@chapter Debugging Tools
|
|
|
|
TODO
|
|
|
|
@bye
|