From 34cadedc4bdbf6f2e4671ad4171f79a8192d81d3 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Wed, 3 Sep 2025 23:51:56 -0500 Subject: moving the use-package info file into it's proper place --- assets/info/use-package.info | 2386 ++++++++++++++++++++++++++++++++++++++++++ assets/use-package.info | 2386 ------------------------------------------ 2 files changed, 2386 insertions(+), 2386 deletions(-) create mode 100644 assets/info/use-package.info delete mode 100644 assets/use-package.info diff --git a/assets/info/use-package.info b/assets/info/use-package.info new file mode 100644 index 00000000..00197f3f --- /dev/null +++ b/assets/info/use-package.info @@ -0,0 +1,2386 @@ +This is use-package.info, produced by texi2any version 7.1 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-"’. Standalone special +keys (and some combinations) can be written in square brackets, +e.g. ‘[tab]’ instead of ‘""’. + + Examples: + + (use-package helm + :bind (("M-x" . helm-M-x) + ("M-" . 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. + + + 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 + . + + 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: Top933 +Node: Basic Concepts3113 +Node: Getting Started4537 +Node: Loading Packages7700 +Node: Loading basics9207 +Ref: Loading basics-Footnote-110760 +Node: Deferring loading10844 +Node: Forcing loading14061 +Node: Conditional loading14746 +Node: Loading sequentially16910 +Node: Load dependencies19491 +Node: Load path20468 +Node: Manual autoloads21705 +Node: Configuring Packages22361 +Node: Lisp Configuration23120 +Node: Preface keyword23984 +Node: Init keyword24890 +Node: Config keyword25508 +Node: Best practices26233 +Node: Key bindings27710 +Node: Global keybindings28480 +Node: Binding in keymaps32292 +Node: Binding to a keymap33501 +Node: Binding to repeat-maps34531 +Node: Displaying keybindings36918 +Node: Hooks37478 +Node: Modes and interpreters40246 +Node: Magic handlers41781 +Node: User options42610 +Node: Faces44025 +Node: Hiding minor modes44822 +Ref: Hiding minor modes-Footnote-145527 +Node: Diminish45582 +Ref: Diminish-Footnote-146519 +Node: Delight46578 +Ref: Delight-Footnote-148382 +Node: Installing packages48446 +Node: Install package49059 +Node: Pinning packages49889 +Ref: Pinning packages-Footnote-151583 +Node: Other package managers51663 +Node: Byte-compiling52535 +Node: Troubleshooting54527 +Node: Troubleshooting Options55878 +Node: Gathering Statistics57440 +Node: Disabling a package58999 +Node: Keyword extensions59709 +Node: use-package-ensure-system-package60197 +Ref: use-package-ensure-system-package-Footnote-163202 +Ref: use-package-ensure-system-package-Footnote-263470 +Node: Creating an extension63601 +Node: History67013 +Node: GNU Free Documentation License67686 +Node: Index92837 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/assets/use-package.info b/assets/use-package.info deleted file mode 100644 index 00197f3f..00000000 --- a/assets/use-package.info +++ /dev/null @@ -1,2386 +0,0 @@ -This is use-package.info, produced by texi2any version 7.1 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-"’. Standalone special -keys (and some combinations) can be written in square brackets, -e.g. ‘[tab]’ instead of ‘""’. - - Examples: - - (use-package helm - :bind (("M-x" . helm-M-x) - ("M-" . 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. - - - 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 - . - - 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: Top933 -Node: Basic Concepts3113 -Node: Getting Started4537 -Node: Loading Packages7700 -Node: Loading basics9207 -Ref: Loading basics-Footnote-110760 -Node: Deferring loading10844 -Node: Forcing loading14061 -Node: Conditional loading14746 -Node: Loading sequentially16910 -Node: Load dependencies19491 -Node: Load path20468 -Node: Manual autoloads21705 -Node: Configuring Packages22361 -Node: Lisp Configuration23120 -Node: Preface keyword23984 -Node: Init keyword24890 -Node: Config keyword25508 -Node: Best practices26233 -Node: Key bindings27710 -Node: Global keybindings28480 -Node: Binding in keymaps32292 -Node: Binding to a keymap33501 -Node: Binding to repeat-maps34531 -Node: Displaying keybindings36918 -Node: Hooks37478 -Node: Modes and interpreters40246 -Node: Magic handlers41781 -Node: User options42610 -Node: Faces44025 -Node: Hiding minor modes44822 -Ref: Hiding minor modes-Footnote-145527 -Node: Diminish45582 -Ref: Diminish-Footnote-146519 -Node: Delight46578 -Ref: Delight-Footnote-148382 -Node: Installing packages48446 -Node: Install package49059 -Node: Pinning packages49889 -Ref: Pinning packages-Footnote-151583 -Node: Other package managers51663 -Node: Byte-compiling52535 -Node: Troubleshooting54527 -Node: Troubleshooting Options55878 -Node: Gathering Statistics57440 -Node: Disabling a package58999 -Node: Keyword extensions59709 -Node: use-package-ensure-system-package60197 -Ref: use-package-ensure-system-package-Footnote-163202 -Ref: use-package-ensure-system-package-Footnote-263470 -Node: Creating an extension63601 -Node: History67013 -Node: GNU Free Documentation License67686 -Node: Index92837 - -End Tag Table - - -Local Variables: -coding: utf-8 -End: -- cgit v1.2.3