emacs/doc/misc/use-package.texi

\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