[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/bind-key bcf0984cf5 3/3: Merge pull request #1030 from
|
From: |
ELPA Syncer |
|
Subject: |
[elpa] externals/bind-key bcf0984cf5 3/3: Merge pull request #1030 from skangas/merge-emacs |
|
Date: |
Fri, 9 Dec 2022 15:57:18 -0500 (EST) |
branch: externals/bind-key
commit bcf0984cf55b70fe6896c6a15f61df92b24f8ffd
Merge: 90787092a0 ff8c57268a
Author: John Wiegley <johnw@newartisans.com>
Commit: GitHub <noreply@github.com>
Merge pull request #1030 from skangas/merge-emacs
---
bind-key.el | 54 +-
doclicense.texi | 505 ++++++++
docstyle.texi | 19 +
use-package-bind-key.el | 25 +-
use-package-core.el | 35 +-
use-package-delight.el | 15 +-
use-package-diminish.el | 15 +-
use-package-ensure-system-package.el | 25 +-
use-package-ensure.el | 18 +-
use-package-jump.el | 14 +-
use-package-lint.el | 10 +-
use-package-tests.el | 12 +-
use-package.el | 20 +-
use-package.texi | 2117 ++++++++++++++++++++++++----------
14 files changed, 2202 insertions(+), 682 deletions(-)
diff --git a/bind-key.el b/bind-key.el
index 3168f686a0..9a1d65ba5e 100644
--- a/bind-key.el
+++ b/bind-key.el
@@ -10,29 +10,29 @@
;; Keywords: keys keybinding config dotemacs extensions
;; URL: https://github.com/jwiegley/use-package
-;; This program is free software; you can redistribute it and/or modify
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
-;; This program is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
-;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
-;; If you have lots of keybindings set in your .emacs file, it can be hard to
-;; know which ones you haven't set yet, and which may now be overriding some
-;; new default in a new Emacs version. This module aims to solve that
-;; problem.
-;;
-;; Bind keys as follows in your .emacs:
+;; If you have lots of keybindings set in your init file, it can be
+;; hard to know which ones you haven't set yet, and which may now be
+;; overriding some new default in a new Emacs version. This module
+;; aims to solve that problem.
;;
-;; (require 'bind-key)
+;; Bind keys as follows in your init file:
;;
;; (bind-key "C-c x" 'my-ctrl-c-x-command)
;;
@@ -95,6 +95,8 @@
;; This display will tell you if you've overridden a default keybinding, and
;; what the default was. Also, it will tell you if the key was rebound after
;; your binding it with `bind-key', and what it was rebound it to.
+;;
+;; See the `use-package' info manual for more information.
;;; Code:
@@ -103,7 +105,10 @@
(defgroup bind-key nil
"A simple way to manage personal keybindings."
- :group 'emacs)
+ :group 'keyboard
+ :group 'convenience
+ :link '(emacs-commentary-link :tag "Commentary" "bind-key.el")
+ :version "29.1")
(defcustom bind-key-column-widths '(18 . 40)
"Width of columns in `describe-personal-keybindings'."
@@ -112,8 +117,7 @@
(defcustom bind-key-segregation-regexp
"\\`\\(\\(C-[chx] \\|M-[gso] \\)\\([CM]-\\)?\\|.+-\\)"
- "Regular expression used to divide key sets in the output from
-\\[describe-personal-keybindings]."
+ "Regexp used by \\[describe-personal-keybindings] to divide key sets."
:type 'regexp
:group 'bind-key)
@@ -128,7 +132,18 @@
"Keymap for `override-global-mode'.")
(define-minor-mode override-global-mode
- "A minor mode so that keymap settings override other modes."
+ "A minor mode for allowing keybindings to override other modes.
+The main purpose of this mode is to simplify bindings keys in
+such a way that they take precedence over other modes.
+
+To achieve this, the keymap `override-global-map' is added to
+`emulation-mode-map-alists', which makes it take precedence over
+keymaps in `minor-mode-map-alist'. Thereby, key bindings get an
+even higher precedence than global key bindings defined with
+`keymap-global-set' (or, in Emacs 28 or older, `global-set-key').
+
+The macro `bind-key*' (which see) provides a convenient way to
+add keys to that keymap."
:init-value t
:lighter "")
@@ -147,9 +162,9 @@ Elements have the form ((KEY . [MAP]) CMD ORIGINAL-CMD)")
"Bind KEY-NAME to COMMAND in KEYMAP (`global-map' if not passed).
KEY-NAME may be a vector, in which case it is passed straight to
-`define-key'. Or it may be a string to be interpreted as
-spelled-out keystrokes, e.g., `C-c C-z'. See documentation of
-`edmacro-mode' for details.
+`define-key'. Or it may be a string to be interpreted as
+spelled-out keystrokes, e.g., \"C-c C-z\". See the documentation
+of `edmacro-mode' for details.
COMMAND must be an interactive function or lambda form.
@@ -425,6 +440,11 @@ function symbol (unquoted)."
;;;###autoload
(defmacro bind-keys* (&rest args)
+ "Bind multiple keys at once, in `override-global-map'.
+Accepts the same keyword arguments as `bind-keys' (which see).
+
+This binds keys in such a way that bindings are not overridden by
+other modes. See `override-global-mode'."
(macroexp-progn (bind-keys-form args 'override-global-map)))
(defun get-binding-description (elem)
diff --git a/doclicense.texi b/doclicense.texi
new file mode 100644
index 0000000000..eaf3da0e92
--- /dev/null
+++ b/doclicense.texi
@@ -0,0 +1,505 @@
+@c The GNU Free Documentation License.
+@center Version 1.3, 3 November 2008
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation,
Inc.
+@uref{https://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{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.
+
+@item
+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, La@TeX{} 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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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:
+
+@enumerate A
+@item
+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.
+
+@item
+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.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+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.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+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.
+
+@item
+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.''
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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
+@uref{https://www.gnu.org/licenses/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+@item
+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.
+
+@end enumerate
+
+@page
+@heading 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:
+
+@smallexample
+@group
+ Copyright (C) @var{year} @var{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''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}Texts.''@: line with this:
+
+@smallexample
+@group
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
+@end group
+@end smallexample
+
+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.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
diff --git a/docstyle.texi b/docstyle.texi
new file mode 100644
index 0000000000..e7404398d2
--- /dev/null
+++ b/docstyle.texi
@@ -0,0 +1,19 @@
+@c Emacs documentation style settings
+@documentencoding UTF-8
+@c These two require Texinfo 5.0 or later, so we use the older
+@c equivalent @set variables supported in 4.11 and hence
+@ignore
+@codequotebacktick on
+@codequoteundirected on
+@end ignore
+@set txicodequoteundirected
+@set txicodequotebacktick
+@iftex
+@c It turns out TeX sometimes fails to hyphenate, so we help it here
+@hyphenation{au-to-mat-i-cal-ly}
+@hyphenation{spec-i-fied}
+@hyphenation{work-a-round}
+@hyphenation{work-a-rounds}
+@hyphenation{un-marked}
+@hyphenation{dic-tion-ary}
+@end iftex
diff --git a/use-package-bind-key.el b/use-package-bind-key.el
index 75def7febd..4ebf54825c 100644
--- a/use-package-bind-key.el
+++ b/use-package-bind-key.el
@@ -5,18 +5,20 @@
;; Author: John Wiegley <johnw@newartisans.com>
;; Maintainer: John Wiegley <johnw@newartisans.com>
-;; This program is free software; you can redistribute it and/or modify
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
-;; This program is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
-;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
@@ -24,6 +26,10 @@
;; keywords. Note that these are currently still baked into
;; `use-package-keywords' and `use-package-deferring-keywords', although this
;; is harmless if they are never used.
+;;
+;; These keywords are made available by default by requiring `use-package'.
+;;
+;; See the `use-package' info manual for more information.
;;; Code:
@@ -32,15 +38,14 @@
;;;###autoload
(defun use-package-autoload-keymap (keymap-symbol package override)
- "Loads PACKAGE and then binds the key sequence used to invoke
-this function to KEYMAP-SYMBOL. It then simulates pressing the
-same key sequence a again, so that the next key pressed is routed
-to the newly loaded keymap.
+ "Load PACKAGE and bind key sequence invoking this function to KEYMAP-SYMBOL.
+Then simulate pressing the same key sequence a again, so that the
+next key pressed is routed to the newly loaded keymap.
-This function supports use-package's :bind-keymap keyword. It
+This function supports use-package's :bind-keymap keyword. It
works by binding the given key sequence to an invocation of this
-function for a particular keymap. The keymap is expected to be
-defined by the package. In this way, loading the package is
+function for a particular keymap. The keymap is expected to be
+defined by the package. In this way, loading the package is
deferred until the prefix key sequence is pressed."
(if (not (require package nil t))
(use-package-error (format "Cannot load package.el: %s" package))
diff --git a/use-package-core.el b/use-package-core.el
index 6606681f2e..ed6a65494f 100644
--- a/use-package-core.el
+++ b/use-package-core.el
@@ -5,29 +5,27 @@
;; Author: John Wiegley <johnw@newartisans.com>
;; Maintainer: John Wiegley <johnw@newartisans.com>
-;; This program is free software; you can redistribute it and/or modify
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
-;; This program is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
-;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
-;; The `use-package' declaration macro allows you to isolate package
-;; configuration in your ".emacs" in a way that is performance-oriented and,
-;; well, just tidy. I created it because I have over 80 packages that I use
-;; in Emacs, and things were getting difficult to manage. Yet with this
-;; utility my total load time is just under 1 second, with no loss of
-;; functionality!
+;; This file contains the core implementation of the `use-package'
+;; macro.
;;
-;; Please see README.md from the same repository for documentation.
+;; See the `use-package' info manual for more information.
;;; Code:
@@ -63,7 +61,9 @@
(defgroup use-package nil
"A `use-package' declaration for simplifying your `.emacs'."
- :group 'startup)
+ :group 'initialization
+ :link '(custom-manual "(use-package) Top")
+ :version "29.1")
(defconst use-package-version "2.4.4"
"This version of `use-package'.")
@@ -1609,8 +1609,8 @@ no keyword implies `:all'."
(defmacro use-package (name &rest args)
"Declare an Emacs package by specifying a group of configuration options.
-For full documentation, please see the README file that came with
-this file. Usage:
+For the full documentation, see Info node `(use-package) top'.
+Usage:
(use-package package-name
[:keyword [option]]...)
@@ -1647,12 +1647,15 @@ this file. Usage:
`:magic-fallback', or `:interpreter'. This can be an integer,
to force loading after N seconds of idle time, if the package
has not already been loaded.
-:after Delay the use-package declaration until after the named
modules
- have loaded. Once load, it will be as though the use-package
- declaration (without `:after') had been seen at that moment.
:demand Prevent the automatic deferred loading introduced by
constructs
such as `:bind' (see `:defer' for the complete list).
+:after Delay the effect of the use-package declaration
+ until after the named libraries have loaded.
+ Before they have been loaded, no other keyword
+ has any effect at all, and once they have been
+ loaded it is as if `:after' was not specified.
+
:if EXPR Initialize and load only if EXPR evaluates to a non-nil value.
:disabled The package is ignored completely if this keyword is present.
:defines Declare certain variables to silence the byte-compiler.
diff --git a/use-package-delight.el b/use-package-delight.el
index c6abac9a64..41978b94f4 100644
--- a/use-package-delight.el
+++ b/use-package-delight.el
@@ -5,23 +5,28 @@
;; Author: John Wiegley <johnw@newartisans.com>
;; Maintainer: John Wiegley <johnw@newartisans.com>
-;; This program is free software; you can redistribute it and/or modify
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
-;; This program is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
-;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
-;; Provides support for the :delight keyword, which is made available by
-;; default by requiring `use-package'.
+;; Provides support for the :delight keyword, which is made available
+;; by default by requiring `use-package'. Using it requires the
+;; `delight' package to be installed (available on GNU ELPA).
+;;
+;; See the `use-package' info manual for more information.
;;; Code:
diff --git a/use-package-diminish.el b/use-package-diminish.el
index 9b8a09a297..7fff93b0e9 100644
--- a/use-package-diminish.el
+++ b/use-package-diminish.el
@@ -5,23 +5,28 @@
;; Author: John Wiegley <johnw@newartisans.com>
;; Maintainer: John Wiegley <johnw@newartisans.com>
-;; This program is free software; you can redistribute it and/or modify
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
-;; This program is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
-;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
-;; Provides support for the :diminish keyword, which is made available by
-;; default by requiring `use-package'.
+;; Provides support for the :diminish keyword, which is made available
+;; by default by requiring `use-package'. Using it requires the
+;; `diminish' package to be installed (available on GNU ELPA).
+;;
+;; See the `use-package' info manual for more information.
;;; Code:
diff --git a/use-package-ensure-system-package.el
b/use-package-ensure-system-package.el
index 9c9f0797a0..6681e5afb7 100644
--- a/use-package-ensure-system-package.el
+++ b/use-package-ensure-system-package.el
@@ -9,24 +9,29 @@
;; Package-Requires: ((use-package "2.1") (system-packages "1.0.4"))
;; Filename: use-package-ensure-system-package.el
-;; This program is free software; you can redistribute it and/or modify
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
-;; This program is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
-;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
-;;
+
;; The `:ensure-system-package` keyword allows you to ensure system
-;; binaries exist alongside your `use-package` declarations.
+;; binaries exist alongside your `use-package` declarations. Using it
+;; requires the `system-packages' package to be installed (available
+;; on GNU ELPA).
;;
+;; See the `use-package' info manual for more information.
;;; Code:
@@ -37,10 +42,10 @@
(declare-function system-packages-get-command "system-packages"))
(defvar use-package-ensure-system-package--custom-packages '()
- "List of custom packages installed.")
+ "List of commands used to install custom packages.")
(defun use-package-ensure-system-package-consify (arg)
- "Turn ARG into a cons of (`package-name' . `install-command')."
+ "Turn ARG into a cons of the form (PACKAGE-NAME . INSTALL-COMMAND')."
(cond
((stringp arg)
(cons arg `(system-packages-install ,arg)))
@@ -59,13 +64,15 @@
`(system-packages-install ,(symbol-name (cdr arg)))))))))
(defun use-package-ensure-system-package-update-custom-packages ()
+ "Update custom packages (not installed by system package manager).
+Run the same commands used for installing them."
(interactive)
(dolist (cmd use-package-ensure-system-package--custom-packages)
(async-shell-command cmd)))
;;;###autoload
(defun use-package-normalize/:ensure-system-package (_name-symbol keyword args)
- "Turn ARGS into a list of conses of (`package-name' . `install-command')."
+ "Turn ARGS into a list of conses of the form (PACKAGE-NAME .
INSTALL-COMMAND)."
(use-package-as-one (symbol-name keyword) args
(lambda (_label arg)
(cond
@@ -75,7 +82,7 @@
(list (use-package-ensure-system-package-consify arg)))))))
(defun use-package-ensure-system-package-exists? (file-or-exe)
- "If variable is a string, ensure the file path exists.
+ "If FILE-OR-EXE is a string, ensure the file path exists.
If it is a symbol, ensure the binary exist."
(if (stringp file-or-exe)
(file-exists-p file-or-exe)
diff --git a/use-package-ensure.el b/use-package-ensure.el
index c9cc6e70c5..dae0312dba 100644
--- a/use-package-ensure.el
+++ b/use-package-ensure.el
@@ -5,23 +5,27 @@
;; Author: John Wiegley <johnw@newartisans.com>
;; Maintainer: John Wiegley <johnw@newartisans.com>
-;; This program is free software; you can redistribute it and/or modify
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
-;; This program is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
-;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
-;; Provides support for the :ensure and :pin keywords, which is made available
-;; by default by requiring `use-package'.
+;; Provides support for the :ensure and :pin keywords, which are made
+;; available by default by requiring `use-package'.
+;;
+;; See the `use-package' info manual for more information.
;;; Code:
@@ -30,7 +34,9 @@
(defgroup use-package-ensure nil
"Support for :ensure and :pin keywords in `use-package' declarations."
- :group 'use-package)
+ :group 'use-package
+ :link '(custom-manual "(use-package) Installing packages")
+ :version "29.1")
(eval-when-compile
(declare-function package-installed-p "package")
diff --git a/use-package-jump.el b/use-package-jump.el
index 0c4cd20d05..6fc52afd28 100644
--- a/use-package-jump.el
+++ b/use-package-jump.el
@@ -5,25 +5,29 @@
;; Author: John Wiegley <johnw@newartisans.com>
;; Maintainer: John Wiegley <johnw@newartisans.com>
-;; This program is free software; you can redistribute it and/or modify
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
-;; This program is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
-;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
-;; Provides the command `M-x use-package-jump-to-package-form', however it
+;; Provides the command `M-x use-package-jump-to-package-form'. However, it
;; only works if the package being jumped to was required during
-;; initialization. If it was delay-loaded, it will not work.
+;; initialization. If it was autoloaded, it will not work.
;; Improvements are needed.
+;;
+;; See the `use-package' info manual for more information.
;;; Code:
diff --git a/use-package-lint.el b/use-package-lint.el
index 2092c0d269..498213a76b 100644
--- a/use-package-lint.el
+++ b/use-package-lint.el
@@ -5,22 +5,26 @@
;; Author: John Wiegley <johnw@newartisans.com>
;; Maintainer: John Wiegley <johnw@newartisans.com>
-;; This program is free software; you can redistribute it and/or modify
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
-;; This program is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
-;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; Provides the command `M-x use-package-lint'.
+;;
+;; See the `use-package' info manual for more information.
;;; Code:
diff --git a/use-package-tests.el b/use-package-tests.el
index b66b08ec11..e4586b04f2 100644
--- a/use-package-tests.el
+++ b/use-package-tests.el
@@ -1,19 +1,21 @@
;;; use-package-tests.el --- Tests for use-package.el -*- lexical-binding: t;
-*-
-;; This program is free software; you can redistribute it and/or modify
+;; Copyright (C) 2014-2022 Free Software Foundation, Inc.
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
-;; This program is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
-;; along with this program. If not, see <https://www.gnu.org/licenses/>.
-
-;;; Commentary:
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Code:
diff --git a/use-package.el b/use-package.el
index bafa0934a6..0929696466 100644
--- a/use-package.el
+++ b/use-package.el
@@ -10,29 +10,31 @@
;; Keywords: dotemacs startup speed config package extensions
;; URL: https://github.com/jwiegley/use-package
-;; This program is free software; you can redistribute it and/or modify
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
-;; This program is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
-;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; The `use-package' declaration macro allows you to isolate package
-;; configuration in your ".emacs" in a way that is performance-oriented and,
-;; well, just tidy. I created it because I have over 80 packages that I use
-;; in Emacs, and things were getting difficult to manage. Yet with this
-;; utility my total load time is just under 1 second, with no loss of
-;; functionality!
+;; configuration in your init file in a way that is
+;; performance-oriented and, well, just tidy. I created it because I
+;; have over 80 packages that I use in Emacs, and things were getting
+;; difficult to manage. Yet with this utility my total load time is
+;; just under 1 second, with no loss of functionality!
;;
-;; Please see README.md from the same repository for documentation.
+;; See the `use-package' info manual for more information.
;;; Code:
diff --git a/use-package.texi b/use-package.texi
index 573baac89a..4f0f8a2677 100644
--- a/use-package.texi
+++ b/use-package.texi
@@ -1,29 +1,32 @@
\input texinfo @c -*- texinfo -*-
@c %**start of header
-@setfilename use-package.info
+@setfilename ../../use-package.info
@settitle use-package User Manual
-@documentencoding UTF-8
-@documentlanguage en
+@include docstyle.texi
+@syncodeindex vr cp
+@syncodeindex fn cp
@c %**end of header
@copying
-@quotation
-Copyright (C) 2012-2022 Free Software Foundation, Inc.
-
-You can redistribute this document and/or modify it under the terms
-of the GNU General Public License as published by the Free Software
-Foundation, either version 3 of the License, or (at your option) any
-later version.
+This manual is for use-package, a configuration macro for simplifying
+your init file.
-This document is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU
-General Public License for more details.
+Copyright @copyright{} 2022 Free Software Foundation, Inc.
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
+and with the Back-Cover Texts as in (a) below. A copy of the license
+is included in the section entitled ``GNU Free Documentation License''.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual.''
@end quotation
@end copying
-@dircategory Emacs
+@dircategory Emacs misc features
@direntry
* use-package: (use-package). Declarative package configuration for Emacs.
@end direntry
@@ -31,8 +34,8 @@ General Public License for more details.
@finalout
@titlepage
@title use-package User Manual
-@subtitle for version 2.4.1-119-g0be480e+1
-@author John Wiegley
+@subtitle for version 2.4.5
+@author John Wiegley & Stefan Kangas
@page
@vskip 0pt plus 1filll
@insertcopying
@@ -44,353 +47,747 @@ General Public License for more details.
@node Top
@top use-package User Manual
-The @code{use-package} macro allows you to isolate package configuration in
your
-@code{.emacs} file in a way that is both performance-oriented and, well, tidy.
I
-created it because I have over 80 packages that I use in Emacs, and things
-were getting difficult to manage. Yet with this utility my total load time is
-around 2 seconds, with no loss of functionality!
+The @code{use-package} macro allows you to isolate package
+customization in your init file in a declarative way. It takes care
+of a lot of things for you that would otherwise require a lot of
+repetitive boilerplate code. It can help with common customization,
+such as binding keys, setting up hooks, customizing user options and
+faces, autoloading, and more. It also helps you keep Emacs startup
+fast, even when you use many (even hundreds) of packages.
+
+Note that use-package is not a package manager. Although use-package
+does have the useful capability to interface with the Emacs package
+manager, its primary purpose is for the configuration and loading of
+packages.
@insertcopying
-@end ifnottex
@menu
-* Introduction::
-* Installation::
-* Getting Started::
-* Basic Concepts::
-* Issues/Requests::
-* Keywords::
-* Debugging Tools::
-
-@detailmenu
---- The Detailed Node Listing ---
-
-Installation
-
-* Installing from GNU ELPA::
-* Installing from the Git Repository::
-* Post-Installation Tasks::
-
-Keywords
-
-* @code{after}:: @code{:after}.
-* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap},
@code{:bind-keymap*}.
-* @code{bind} @code{bind*}:: @code{:bind}, @code{:bind*}.
-* @code{commands}:: @code{:commands}.
-* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init},
@code{:config}.
-* @code{custom}:: @code{:custom}.
-* @code{custom-face}:: @code{:custom-face}.
-* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}.
-* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}.
-* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}.
-* @code{disabled}:: @code{:disabled}.
-* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}.
-* @code{hook}:: @code{:hook}.
-* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when},
@code{:unless}.
-* @code{load-path}:: @code{:load-path}.
-* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}.
-* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}.
-* @code{no-require}:: @code{:no-require}.
-* @code{requires}:: @code{:requires}.
-
-@code{bind}, @code{bind*}
-
-* Binding to local keymaps::
-
-
-@end detailmenu
+* Basic Concepts:: Basic concepts of use-package.
+* Getting Started:: A gentle introduction to use-package.
+* Loading Packages:: How and when packages are loaded.
+* Configuring Packages:: Package configuration keywords.
+* Installing packages:: Ensuring packages are available.
+* Byte-compiling:: Byte-compiling your init file.
+* Troubleshooting:: What to do when there's trouble.
+
+Appendices
+* Keyword extensions:: Adding new use-package keywords.
+* History:: History and acknowledgments.
+* GNU Free Documentation License:: The license for this manual.
+* Index::
@end menu
+@end ifnottex
-@node Introduction
-@chapter Introduction
-
-The @code{use-package} macro allows you to isolate package configuration in
your
-@code{.emacs} file in a way that is both performance-oriented and, well, tidy.
I
-created it because I have over 80 packages that I use in Emacs, and things
-were getting difficult to manage. Yet with this utility my total load time is
-around 2 seconds, with no loss of functionality!
+@c ----------------------------------------------------------------------------
+@node Basic Concepts
+@chapter Basic Concepts
-More text to come@dots{}
+use-package provides the @code{use-package} macro, that simplifies the
+customization and use of packages in Emacs. It was created for a few
+basic reasons, each of which drove the design. Understanding these
+reasons may help make some of those decisions clearer:
-@node Installation
-@chapter Installation
+@enumerate
+@item
+To gather all configuration details of a package into one place,
+making it easier to copy, disable, or move it elsewhere in the init
+file.
-use-package can be installed using Emacs' package manager or manually from
-its development repository.
+@item
+To reduce duplication and boilerplate, capturing several common
+practices as mere keywords both easy and intuitive to use.
-@menu
-* Installing from GNU ELPA::
-* Installing from the Git Repository::
-* Post-Installation Tasks::
-@end menu
+@item
+To make startup time of Emacs as quick as possible, without
+sacrificing the quantity of add-on packages used.
-@node Installing from GNU ELPA
-@section Installing from GNU ELPA
+@item
+To make it so errors encountered during startup disable only the
+package raising the error, and as little else as possible, leaving as
+close to a functional Emacs as possible.
-use-package is available from GNU ELPA. If you haven't used
-Emacs' package manager before, then it is high time you familiarize yourself
-with it by reading the documentation in the Emacs manual, see
-@ref{Packages,,,emacs,}. Then add one of the archives to
@code{package-archives}:
+@item
+To allow byte-compilation of one's init file so that any warnings or
+errors seen are meaningful. In this way, even if byte-compilation is
+not used for speed (reason 3), it can still be used as a sanity check.
+@end enumerate
-First, you need to update the local package list using:
+It is worth noting that use-package is not intended to replace the
+standard @w{@code{M-x customize}}. On the contrary, it is designed to
+work together with it, for things that customize cannot do.
-@example
-M-x package-refresh-contents RET
-@end example
+@c ----------------------------------------------------------------------------
+@node Getting Started
+@chapter Getting Started
-Once you have done that, you can install use-package and its
-dependencies using:
+This chapter provides instructions and examples for quickly getting
+started with use-package. The first thing you need to do is make sure
+that @samp{use-package} itself is loaded. To do that, put this at the
+top of your init file:
-@example
-M-x package-install RET use-package RET
-@end example
+@lisp
+(require 'use-package)
+@end lisp
-Now see @ref{Post-Installation Tasks}.
+The above makes the @code{use-macro} for in the rest of your init
+file. In this manual, we call each call to @code{use-macro} a
+@dfn{declaration}, to highlight the declarative nature of its
+semantic.
-@node Installing from the Git Repository
-@section Installing from the Git Repository
+To unconditionally load a package named @samp{foo}, add the following
+declaration to your init file:
-First, use Git to clone the use-package repository:
+@lisp
+(use-package foo)
+@end lisp
-@example
-$ git clone https://github.com/jwiegley/use-package.git
~/.emacs.d/site-lisp/use-package
-$ cd ~/.emacs.d/site-lisp/use-package
-@end example
+@noindent
+This declaration is equivalent to using @code{require}, with some
+use-package specific error handling added in. Just like require, it
+needs the package @samp{foo} to be installed and available in your
+@code{load-path} (@pxref{Installing packages}).
-Then compile the libraries and generate the info manuals:
+To evaluate Lisp code @emph{before} the @samp{foo} package is loaded,
+use the @code{:init} keyword:
-@example
-$ make
-@end example
+@lisp
+(use-package foo
+ :init
+ (setq foo-variable t))
+@end lisp
-You may need to create @code{/path/to/use-package/config.mk} with the following
-content before running @code{make}:
+Similarly, @code{:config} can be used to execute code @emph{after} a
+package is loaded. In cases where loading is done lazily
+(@pxref{Loading Packages}), this execution is deferred until after the
+autoload occurs. As you might expect, you can use @code{:init} and
+@code{:config} together:
-@example
-LOAD_PATH = -L /path/to/use-package
-@end example
+@lisp
+(use-package foo
+ :init
+ (setq foo-variable t)
+ :config
+ (foo-mode 1))
+@end lisp
-Finally add this to your init file:
+The above declarations will all load the @samp{foo} package
+immediately. In most cases, this is not necessary or desirable, as
+that will slow down Emacs startup. Instead, you should try to set
+things up so that packages are only loaded when they are actually
+needed (autoloading). If you have installed a package from
+@acronym{GNU ELPA} that provides it's own autoloads, it is often
+enough to say:
@lisp
-(add-to-list 'load-path "~/.emacs.d/site-lisp/use-package")
-(require 'use-package)
+(use-package foo
+ :defer t)
+@end lisp
+
+@noindent
+This will avoid loading the package. Now, when you run any autoloaded
+command, the package @samp{foo} is loaded automatically. Package
+authors will make their own decisions about which commands are marked
+to autoload by default.
-(with-eval-after-load 'info
- (info-initialize)
- (add-to-list 'Info-directory-list
- "~/.emacs.d/site-lisp/use-package/"))
+In some cases, you might need or want to provide your own autoloads.
+The below more complex example autoloads the commands
+@code{isearch-moccur} and @code{isearch-all} from
+@file{color-moccur.el}, and binds keys both globally and in
+@code{isearch-mode-map}. When one of these commands are used, the
+package is loaded. At that point, @code{moccur-edit} is also loaded,
+to allow editing of the @code{moccur} buffer.
+
+@lisp
+(use-package color-moccur
+ :commands (isearch-moccur isearch-all)
+ :bind (("M-s O" . moccur)
+ :map isearch-mode-map
+ ("M-o" . isearch-moccur)
+ ("M-O" . isearch-moccur-all))
+ :init
+ (setq isearch-lazy-highlight t)
+ :config
+ (use-package moccur-edit))
@end lisp
-Note that elements of @code{load-path} should not end with a slash, while
those of
-@code{Info-directory-list} should.
+Some packages will suggest ready-made @code{use-package} declarations
+that you can use. Where possible, it is a good idea to copy them, and
+use that as a starting point.
-Instead of running use-package directly from the repository by adding it to
-the @code{load-path}, you might want to instead install it in some other
directory
-using @code{sudo make install} and setting @code{load-path} accordingly.
+That should be enough to get you started!
-To update use-package use:
+@c ----------------------------------------------------------------------------
+@node Loading Packages
+@chapter Loading Packages
-@example
-$ git pull
-$ make
-@end example
+@cindex loading packages
+Before use-package can load an Emacs Lisp package, it must be
+available in a directory on your @code{load-path}. When you install
+packages using the built-in @code{install-package} command, it will do
+this automatically for you. Packages shipped with Emacs (built-in
+packages) are always available.
-At times it might be necessary to run @code{make clean all} instead.
+If you install packages manually, you must make sure they are
+available on your @code{load-path}. @xref{Lisp Libraries,,, emacs,
+GNU Emacs Manual} for details.
-To view all available targets use @code{make help}.
+Some packages have more than one library. In those cases, you might
+need more than one @code{use-package} declaration to make sure it is
+properly loaded. For complex configurations, you might also need more
+than one declaration for a package with the same name.
-Now see @ref{Post-Installation Tasks}.
+use-package can interface with @samp{package.el} to install packages
+on Emacs start. @xref{Installing packages} for details.
-@node Post-Installation Tasks
-@section Post-Installation Tasks
+@menu
+* Loading basics:: How and when packages are loaded.
+* Deferring loading:: Loading packages later.
+* Forcing loading:: Loading packages immediately.
+* Conditional loading:: Loading packages conditionally.
+* Loading sequentially:: Loading packages in sequence.
+* Load dependencies:: Don't load without dependencies.
+* Load path:: Using a custom @code{load-path}.
+* Manual autoloads:: Setting up autoloads manually.
+@end menu
-After installing use-package you should verify that you are indeed using the
-use-package release you think you are using. It's best to restart Emacs before
-doing so, to make sure you are not using an outdated value for
@code{load-path}.
+@node Loading basics
+@section How and when use-package loads packages
-@example
-C-h v use-package-version RET
-@end example
+The @code{use-package} macro either will either load a package
+immediately, or when they are first used (autoloading). In the
+simplest case, a @code{use-package} declaration loads a package when
+it is evaluated.@footnote{This happens both at run-time and at
+compile-time. @xref{Byte-compiling}.} If the declaration is in your
+init file, this happens automatically each time Emacs is started.
-should display something like
+For example, the below declaration immediately loads the library
+@code{foo}, just like @code{require} would. If the library @samp{foo}
+is not available in your @code{load-path}, it logs a warning to the
+@samp{*Messages*} buffer:
-@example
-use-package-version’s value is "2.4.3"
-@end example
+@lisp
+(use-package foo)
+@end lisp
-If you are completely new to use-package then see @ref{Getting Started}.
+Note that a ``package'' is different from an Emacs Lisp ``library''.
+The above declaration tells use-package to load the @emph{library}
+@file{foo.el}, which the overwhelming majority of cases also resides
+in a @emph{package} named @code{foo}. But the @code{foo} package
+might also contain a library named @file{foo-extra.el}. If that
+library is not loaded automatically, you will need a separate
+@code{use-package} declaration to make sure that it is. This manual
+will often use these terms interchangeably, as this distinction does
+not usually matter, but you should keep it in mind for the cases when
+it does.
+
+The details of how and when you should load a package might differ
+from one package to another. When in doubt, refer to the package
+documentation for details.
+
+@node Deferring loading
+@section Deferring package loading
+
+@cindex autoloading packages
+@cindex loading lazily
+In the examples we have seen so far, use-package loads packages every
+time you start Emacs, even if that package is never used. That will
+make starting Emacs slower. use-package therefore tries to set things
+up in such a way that it only loads packages when a command is first
+used (either with @kbd{M-x} or some key binding). This is based on
+autoloading, a full description of which is outside the scope of this
+manual. @xref{Autoload,,, elisp, GNU Emacs Lisp Reference Manual} for
+the full story.
+
+@cindex triggers, for loading packages
+Some @code{use-package} keywords provide autoload @dfn{triggers} that
+cause a package to be loaded when certain events occur. For example,
+the @code{:hook} keyword sets up a trigger that fires when the
+specified hook is run, and then loads the package automatically. The
+other trigger keywords, all of which are described later in this
+manual, are @code{:commands}, @code{:bind}, @code{:bind*},
+@code{:bind-keymap}, @code{:bind-keymap*}, @code{:mode}, and
+@code{:interpreter}.
+
+@subheading The @code{:defer} keyword
+
+@findex :defer
+If you did not specify any autoloading keyword, use-package will fall
+back to loading the package immediately (typically when Emacs is
+starting up). This can be overridden using the @code{:defer} keyword.
+It takes one boolean argument: a non-@code{nil} value means to stop
+this package from being immediately loaded. Here is an example of
+using @code{:defer} to postpone loading the package @samp{foo}:
-If you run into problems, then please see the @ref{Debugging Tools}.
+@lisp
+(use-package foo
+ :defer t)
+@end lisp
-@node Getting Started
-@chapter Getting Started
+Using @code{:defer t} by itself like this is rarely useful.
+Typically, you would only use it together with a keyword like
+@code{:config} (@pxref{Lisp Configuration}), or @code{:ensure}
+(@pxref{Installing packages}).
-TODO@. For now, see @code{README.md}.
+@subheading Defer loading until idle for N seconds
-@node Basic Concepts
-@chapter Basic Concepts
+You can also give a numeric argument @var{N} to @w{@code{:defer}} to
+specify that a package should be loaded (if it hasn't already) after
+Emacs has been idle for @var{N} seconds. For example, use this to
+make use-package load @samp{foo} after 30 seconds of idle time:
+
+@lisp
+(use-package foo
+ :defer 30)
+@end lisp
-@code{use-package} was created for few basic reasons, each of which drove the
-design in various ways. Understanding these reasons may help make some of
-those decisions clearer:
+@subheading When to use @code{:defer}
+
+When using autoloading keywords, there is no need to also use
+@code{:defer}. It doesn't hurt anything to add it in this case,
+perhaps for extra clarity, but it is redundant.
+
+You should use @code{:defer} to force deferred loading, in cases when
+use-package isn't creating any autoloads for you. For example, you
+might know that some other package will already do something to cause
+your package to load at the appropriate time. This is usually the
+case when you install a package using @code{package-install}, as
+packages installed in this way normally always have their own
+autoloads already set up.
+
+@subheading Making @w{@code{:defer t}} the default
+
+@vindex use-package-always-defer
+If you customize the user option @code{use-package-always-defer} to
+non-@code{nil}, the @code{use-package} macro will behave as if
+@w{@code{:defer t}} is always specified. This can be overridden for
+individual declarations using either @w{@code{:defer nil}} or
+@w{@code{:demand t}} (@pxref{Forcing loading}).
+
+@node Forcing loading
+@section Forcing package to load immediately
+
+@findex :demand
+The presence of autoloading trigger keywords can be overridden using
+@code{:demand t}, which forces the package to load immediately. Thus,
+even if you use an autoloading keyword such as @code{:bind}
+(@pxref{Key bindings}), adding @code{:demand} will force loading to
+occur immediately. It will also avoid creating an autoload for the
+bound key, as it would be redundant.
+
+If you specify both @w{@code{:demand t}} and @w{@code{:defer t}}, the
+@code{:defer} keyword will take precedence.
+
+@node Conditional loading
+@section Loading packages conditionally
+
+@findex :if
+@findex :when
+@findex :unless
+The @code{:if}, @code{:when}, and @code{:unless} keywords predicates
+the loading and initialization of packages. They all accept one
+argument, an Emacs Lisp form that is evaluated at run-time.
+
+If the argument of the @code{:if} keyword evaluates to non-@code{nil},
+the package will be loaded and initialized. The @code{:when} keyword
+is provided as an alias for @code{:if}. Finally, the @code{:unless}
+keyword is the inverse of @code{:if}, such that @w{@code{:unless foo}}
+means the same thing as @w{@code{:if (not foo)}}.
+
+For example, if you only want to load @samp{foo} in graphical Emacs
+sessions, you could use the following:
+
+@lisp
+(use-package foo
+ :if (display-graphic-p))
+@end lisp
+
+@subheading Some common use cases
+
+Here are some common cases for conditional loading, and how to achieve
+them.
@itemize
-@item
-To gather all configuration details of a package into one place,
-making it easier to copy, disable, or move it elsewhere in the init
-file.
-@item
-To reduce duplication and boilerplate, capturing several common
-practices as mere keywords both easy and intuitive to use.
+@item Operating system
-@item
-To make startup time of Emacs as quick as possible, without
-sacrificing the quantity of add-on packages used.
+This example loads a package only on GNU/Linux. See the
+@code{system-type} docstring for other valid values.
-@item
-To make it so errors encountered during startup disable only the
-package raising the error, and as little else as possible, leaving a
-close to a functional Emacs as possible.
+@lisp
+:if (eq system-type 'gnu/linux)
+@end lisp
-@item
-To allow byte-compilation of one's init file so that any warnings or
-errors seen are meaningful. In this way, even if byte-compilation is not
-used for speed (reason 3), it can still be used as a sanity check.
-@end itemize
+@item Window system
-@node Issues/Requests
-@chapter Issues/Requests
+This example loads a package only on macOS and X. See the
+@code{window-system} docstring for valid values.
-@node Keywords
-@chapter Keywords
+@lisp
+:if (memq window-system '(ns x))
+@end lisp
-@menu
-* @code{after}:: @code{after}.
-* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap},
@code{:bind-keymap*}.
-* @code{bind} @code{bind*}:: @code{bind} @code{:bind*}.
-* @code{commands}:: @code{:commands}.
-* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init},
@code{:config}.
-* @code{custom}:: @code{:custom}.
-* @code{custom-face}:: @code{:custom-face}.
-* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}.
-* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}.
-* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}.
-* @code{disabled}:: @code{:disabled}.
-* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}.
-* @code{hook}:: @code{:hook}.
-* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when},
@code{:unless}.
-* @code{load-path}:: @code{:load-path}.
-* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}.
-* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}.
-* @code{no-require}:: @code{:no-require}.
-* @code{requires}:: @code{:requires}.
-@end menu
+@item Installed package
-@node @code{after}
-@section @code{:after}
+This example loads a package only when the @samp{foo} package is
+installed.
-Sometimes it only makes sense to configure a package after another has been
-loaded, because certain variables or functions are not in scope until that
-time. This can achieved using an @code{:after} keyword that allows a fairly
rich
-description of the exact conditions when loading should occur. Here is an
-example:
+@lisp
+:if (package-installed-p 'foo)
+@end lisp
+
+@item Libraries in @code{load-path}
+
+This example loads a package only when @file{foo.el} is available in
+your @code{load-path} (for example, if you installed that file
+manually):
@lisp
-(use-package hydra
- :load-path "site-lisp/hydra")
+:if (locate-library "foo.el")
+@end lisp
+@end itemize
-(use-package ivy
- :load-path "site-lisp/swiper")
+@subheading Making conditional loading affect @code{:preface} and
@code{:ensure}
-(use-package ivy-hydra
- :after (ivy hydra))
+@cindex conditional loading before @code{:preface} or @code{:ensure}
+If you need to conditionalize a use-package form so that the condition
+occurs before even @code{:ensure} or @code{:preface}, use @code{when}
+around the use-package form itself. For example:
+
+@lisp
+(when (memq window-system '(mac ns))
+ (use-package foo
+ :ensure t))
@end lisp
-In this case, because all of these packages are demand-loaded in the order
-they occur, the use of @code{:after} is not strictly necessary. By using it,
-however, the above code becomes order-independent, without an implicit
-depedence on the nature of your init file.
+@node Loading sequentially
+@section Loading packages in sequence
+
+@findex :after
+Sometimes it only makes sense to configure a package after another one
+has been loaded, because certain variables or functions are not in
+scope until that time. This can achieved with the @code{:after}
+keyword, which allows a fairly rich description of the exact
+conditions when loading should occur. It takes either a symbol
+indicating the package name, a list of such symbols, or a list of
+selectors (see below).
-By default, @code{:after (foo bar)} is the same as @code{:after (:all foo
bar)}, meaning
-that loading of the given package will not happen until both @code{foo} and
@code{bar}
-have been loaded. Here are some of the other possibilities:
+Here is an example of using the @acronym{GNU ELPA} packages hydra,
+ivy, and ivy-hydra. Note that ivy-hydra will always be loaded last:
@lisp
+(use-package hydra)
+
+(use-package ivy)
+
+(use-package ivy-hydra
+ :after (ivy hydra))
+@end lisp
+
+In this case, because the declarations are evaluated in the order they
+occur, the use of @code{:after} is not strictly necessary. However,
+if @samp{hydra} and @samp{ivy} were to be autoloaded, using
+@code{:after} guarantees that @samp{ivy-hydra} is not loaded until it
+is actually needed. By using @code{:after}, the above code will also
+work even if the order of the declaration changes. This means that
+moving things around in your init file is less likely to break things.
+
+@subheading Using @code{:after} selectors
+
+@findex :all (with :after)
+@findex :any (with :after)
+The @code{:after} keyword also accepts a list of selectors. By
+default, @code{:after (foo bar)} is the same as @w{@code{:after (:all
+foo bar)}}, meaning that loading of the given package will not happen
+until both @code{foo} and @code{bar} have been loaded. Here are some
+of the other possibilities:
+
+@verbatim
:after (foo bar)
:after (:all foo bar)
:after (:any foo bar)
:after (:all (:any foo bar) (:any baz quux))
:after (:any (:all foo bar) (:all baz quux))
+@end verbatim
+
+When you nest selectors, such as @code{(:any (:all foo bar) (:all baz
+quux))}, it means that the package will be loaded when either both
+@code{foo} and @code{bar} have been loaded, or when both @code{baz}
+and @code{quux} have been loaded.
+
+Pay attention when setting @code{use-package-always-defer} to a
+non-@code{nil} value, and also using the @code{:after} keyword. In
+this case, you will need to specify how the declared package is to be
+loaded: for example, by some @code{:bind}. If you are not using one
+of the keywords that registers autoloads, such as @code{:bind} or
+@code{:hook}, and your package manager does not provide autoloads, it
+is possible that your package will never be loaded if you do not add
+@code{:demand t} to those declarations.
+
+@node Load dependencies
+@section Prevent loading if dependencies are missing
+
+@findex :requires
+While the @code{:after} keyword delays loading until the dependencies
+are loaded, the somewhat simpler @code{:requires} keyword @emph{never}
+loads the package if the dependencies are not available when the
+@code{use-package} declaration is evaluated. In this context,
+``available'' means that @code{foo} is available if @w{@code{(featurep
+'foo)}} evaluates to a non-@code{nil} value. For example:
+
+@lisp
+(use-package abbrev
+ :requires foo)
+@end lisp
+
+This is the same as:
+
+@lisp
+(use-package abbrev
+ :if (featurep 'foo))
@end lisp
-When you nest selectors, such as @code{(:any (:all foo bar) (:all baz quux))},
it
-means that the package will be loaded when either both @code{foo} and
@code{bar} have
-been loaded, or both @code{baz} and @code{quux} have been loaded.
+As a convenience, a list of such packages may be specified:
-@strong{NOTE}: Pay attention if you set @code{use-package-always-defer} to t,
and also use
-the @code{:after} keyword, as you will need to specify how the declared
package is
-to be loaded: e.g., by some @code{:bind}. If you're not using one of the
mechanisms
-that registers autoloads, such as @code{:bind} or @code{:hook}, and your
package manager
-does not provide autoloads, it's possible that without adding @code{:demand t}
to
-those declarations, your package will never be loaded.
+@lisp
+(use-package abbrev
+ :requires (foo bar baz))
+@end lisp
-@node @code{bind-keymap} @code{bind-keymap*}
-@section @code{:bind-keymap}, @code{:bind-keymap*}
+For more complex logic, such as that supported by @code{:after},
+simply use @code{:if} and the appropriate Lisp expression.
-Normally @code{:bind} expects that commands are functions that will be
autoloaded
-from the given package. However, this does not work if one of those commands
-is actually a keymap, since keymaps are not functions, and cannot be
-autoloaded using Emacs' @code{autoload} mechanism.
+@node Load path
+@section Setting a custom @code{load-path}
-To handle this case, @code{use-package} offers a special, limited variant of
-@code{:bind} called @code{:bind-keymap}. The only difference is that the
"commands"
-bound to by @code{:bind-keymap} must be keymaps defined in the package, rather
than
-command functions. This is handled behind the scenes by generating custom code
-that loads the package containing the keymap, and then re-executes your
-keypress after the first load, to reinterpret that keypress as a prefix key.
+@findex :load-path
+If a package resides in some directory that is not in your
+@code{load-path}, use the @code{:load-path} keyword to add it. It
+takes a symbol, a function, a string or a list of strings. If the
+path is relative, it is expanded within @code{user-emacs-directory}.
For example:
@lisp
-(use-package projectile
- :bind-keymap
- ("C-c p" . projectile-command-map)
+(use-package ess-site
+ :load-path "site-lisp/ess/lisp/"
+ :commands R)
+@end lisp
+
+Note that when using a symbol or a function to provide a dynamically
+generated list of paths, you must inform the byte-compiler of this
+definition so that the value is available at byte-compilation time.
+This is done by using the special form @code{eval-and-compile} (as
+opposed to @code{eval-when-compile}). Further, this value is fixed at
+whatever was determined during compilation, to avoid looking up the
+same information again on each startup. For example:
+
+@lisp
+(eval-and-compile
+ (defun ess-site-load-path ()
+ (shell-command "find ~ -path ess/lisp")))
+
+(use-package ess-site
+ :load-path (lambda () (list (ess-site-load-path)))
+ :commands R)
@end lisp
-@node @code{bind} @code{bind*}
-@section @code{:bind}, @code{:bind*}
+@node Manual autoloads
+@section Setting up autoloads manually
+
+@findex :commands
+@findex :autoload
+To autoload an interactive command, use the @code{:commands} keyword.
+When you use the @code{:commands} keyword, it creates autoloads for
+those commands (which defers loading of the module until they are
+used). The @code{:commands} keyword takes either a symbol or a list
+of symbols.
-Another common thing to do when loading a module is to bind a key to primary
-commands within that module:
+The @code{:autoload} keyword works like @code{:commands}, but is used
+to autoload non-interactive functions. Here is an example:
@lisp
-(use-package ace-jump-mode
- :bind ("C-." . ace-jump-mode))
+(use-package org-crypt
+ :autoload org-crypt-use-before-save-magic)
@end lisp
-This does two things: first, it creates an autoload for the
@code{ace-jump-mode}
-command and defers loading of @code{ace-jump-mode} until you actually use it.
-Second, it binds the key @code{C-.} to that command. After loading, you can
use
-@code{M-x describe-personal-keybindings} to see all such keybindings you've set
-throughout your @code{.emacs} file.
+@c ----------------------------------------------------------------------------
+@node Configuring Packages
+@chapter Configuring Packages
-A more literal way to do the exact same thing is:
+This chapter describes the various keywords provided by
+@code{use-package} that helps you configure packages.
+
+@menu
+* Lisp Configuration:: Using Lisp to configure packages.
+* Key bindings:: Making your own keybindings.
+* Hooks:: Adding functions to hooks.
+* Modes and interpreters:: Enabling modes automatically.
+* Magic handlers:: Using regexps to enable modes.
+* User options:: Setting user options.
+* Faces:: Customizing faces.
+* Hiding minor modes:: Tidying up the mode line.
+@end menu
+
+@node Lisp Configuration
+@section Using Lisp code for configuring packages
+
+The most general way to add customizations are the @code{:preface},
+@code{:init}, and @code{:config} keywords. They all accept one or
+more Emacs Lisp forms, up to the next keyword, that are evaluated in
+order. This lets you add arbitrary Lisp code to your
+@code{use-package} declarations.
+
+The only difference between these keywords is when they are evaluated.
+
+@menu
+* Preface keyword:: Evaluate code before anything else.
+* Init keyword:: Evaluate code before loading package.
+* Config keyword:: Evaluate code after loading package.
+* Best practices:: When to use @code{:config}, @code{:init}, and
@code{:preface}.
+@end menu
+
+@node Preface keyword
+@subsection @code{:preface} is evaluated first
+
+@findex :preface
+The @code{:preface} section is evaluated before anything else, except
+@code{:disabled} and @code{:ensure}. It can be used to establish
+function and variable definitions that will:
+
+@enumerate
+@item
+Make the byte-compiler happy. It will not complain about functions
+whose definitions are unknown because you have them within a guard
+block.
+
+@item
+Define code that can be used in an @code{:if} test.
+@end enumerate
+
+Note that whatever is specified within @code{:preface} is evaluated
+both at load time and at byte-compilation time, in order to ensure
+that definitions are seen by both the Lisp evaluator and the
+byte-compiler. Therefore, you should avoid having any side-effects in
+your preface, and restrict it to symbol declarations and definitions.
+
+@node Init keyword
+@subsection @code{:init} is evaluated before loading package
+
+@findex :init
+The @code{:init} section is evaluated just before the package is
+loaded. Note that the @code{:init} form is run unconditionally --
+even if the @code{foo} package happens to not exist on your system.
+You must therefore remember to restrict @code{:init} code to only what
+would succeed either way. @code{:init} also always happens before
+package load, whether @code{:config} has been deferred or not.
+
+@node Config keyword
+@subsection @code{:config} is evaluated after loading package
+
+@findex :config
+The @code{:config} section is evaluated after the package has been
+loaded. If the package is loaded immediately, this happens
+immediately after that, but if loading is done lazily (@pxref{Loading
+Packages}), this is deferred until after the package has been loaded.
+
+In general, you should keep @code{:init} forms as simple and quick as
+possible, and put as much as you can get away with into the
+@code{:config} section. That way, deferred loading can help your
+Emacs start as quickly as possible.
+
+@node Best practices
+@subheading When to use @code{:preface}, @code{:config} and @code{:init}?
+
+Where possible, it is better to avoid @code{:preface}, @code{:config}
+and @code{:init}. Instead, prefer autoloading keywords such as
+@code{:bind}, @code{:hook}, and @code{:mode}, as they will take care
+of setting up autoloads for you without any need for boilerplate code.
+For example, consider the following declaration:
@lisp
-(use-package ace-jump-mode
- :commands ace-jump-mode
+(use-package foo
:init
- (bind-key "C-." 'ace-jump-mode))
+ (add-hook 'some-hook 'foo-mode))
@end lisp
-When you use the @code{:commands} keyword, it creates autoloads for those
commands
-and defers loading of the module until they are used. Since the @code{:init}
form
-is always run---even if @code{ace-jump-mode} might not be on your
system---remember
-to restrict @code{:init} code to only what would succeed either way.
+This has two problems. First, it will unconditionally load the
+package @samp{foo} on startup, which will make things slower. You can
+fix this by adding @code{:defer t}:
-The @code{:bind} keyword takes either a cons or a list of conses:
+@lisp
+(use-package foo
+ :defer t
+ :init
+ (add-hook 'some-hook 'foo-mode))
+@end lisp
+
+This is better, as @samp{foo} is now only loaded when it is actually
+needed (that is, when the hook @samp{some-hook} is run).
+
+The second problem is that there is a lot of boilerplate that you have
+to write. In this case, it might not be so bad, but avoiding that was
+what use-package was made to avoid. The better option in this case is
+therefore to use @code{:hook} (@xref{Hooks}), which also implies
+@w{@code{:defer t}}. The above is thereby reduced down to:
+
+@lisp
+(use-package foo
+ :hook some-hook)
+@end lisp
+
+use-package will set up autoloading for you, and your Emacs startup
+time will not suffer one bit.
+
+@node Key bindings
+@section Key bindings
+
+@cindex :bind
+@cindex binding keys
+@cindex key bindings
+One common thing to do when loading a package is to bind a key to
+commands within that module. Without use-package, this would be done
+using a combination of @code{keymap-local-set},
+@code{keymap-global-set} and various autoloads. With use-package, you
+can simplify this using the @code{:bind} keyword.
+
+@menu
+* Global keybindings:: Bindings you can use anywhere.
+* Binding in keymaps:: Bindings for particular modes.
+* Binding to a keymap:: Binding a key to a keymap.
+* Binding to repeat-maps:: Binding repeating keys.
+* Displaying keybindings:: Displaying personal key bindings.
+@end menu
+
+@node Global keybindings
+@subsection Global keybindings
+
+@findex :bind
+To bind keys globally, the @code{:bind} keyword takes either a single
+cons or a list of conses. Every cons has the form @code{(@var{key}
+. @var{command}}, where @var{key} is a string indicating the key to
+bind, and @var{command} is the name of a command (a symbol). The
+syntax for the keys is similar to the syntax used by the @code{kbd}
+function (@pxref{Init Rebinding,,, emacs, GNU Emacs Manual} for more
+information).
+
+@subheading Using @code{:bind} with a single cons
+
+Here is an example of using a single cons:
+
+@lisp
+(use-package ace-jump-mode
+ :bind ("C-." . ace-jump-mode))
+@end lisp
+
+This does two things: first, it creates an autoload for the
+@code{ace-jump-mode} command and defers loading of the
+@code{ace-jump-mode} package until you actually use it. Second, it
+binds the key @code{C-.} to that command globally.
+
+@subheading Using @code{:bind} with a list of conses
+
+Here is an example of using @code{:bind} with a list of conses:
@lisp
(use-package hi-lock
@@ -399,11 +796,12 @@ The @code{:bind} keyword takes either a cons or a list of
conses:
("M-o w" . highlight-phrase)))
@end lisp
-The @code{:commands} keyword likewise takes either a symbol or a list of
symbols.
+@subheading Using special keys
-NOTE: Special keys like @code{tab} or @code{F1}-@code{Fn} can be written in
square brackets,
-i.e. @code{[tab]} instead of @code{"tab"}. The syntax for the keybindings is
similar to
-the "kbd" syntax: see
@uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html,
the Emacs Manual} for more information.
+Inside key strings, special keys like @kbd{TAB} or @kbd{F1}--@kbd{F12}
+have to be written inside angle brackets, e.g. @code{"C-<up>"}.
+Standalone special keys (and some combinations) can be written in
+square brackets, e.g.@ @code{[tab]} instead of @code{"<tab>"}.
Examples:
@@ -415,16 +813,63 @@ Examples:
([S-f10] . helm-recentf)))
@end lisp
-@menu
-* Binding to local keymaps::
-@end menu
+@subheading Remapping commands
+
+Remapping commands with @code{:bind} and @code{bind-key} works as
+expected, because when the binding is a vector, it is passed straight
+to @code{define-key}. @xref{Remapping Commands,,, elisp, GNU Emacs
+Lisp Reference Manual}) for more information about command remapping.
+For example, the following declaration will rebind
+@code{fill-paragraph} (bound to @kbd{M-q} by default) to
+@code{unfill-toggle}:
+
+@lisp
+(use-package unfill
+ :bind ([remap fill-paragraph] . unfill-toggle))
+@end lisp
+
+@subheading What @code{:bind} does behind the scenes
+
+To understand what @code{:bind} does behind the scenes, it might be
+useful to consider an example:
+
+@lisp
+(use-package ace-jump-mode
+ :bind ("C-." . ace-jump-mode))
+@end lisp
+
+This could be expressed in a much more verbose way with the
+@code{:commands} and @code{:init} keywords.
-@node Binding to local keymaps
-@subsection Binding to local keymaps
+@lisp
+(use-package ace-jump-mode
+ :commands ace-jump-mode
+ :init
+ (bind-key "C-." 'ace-jump-mode))
+@end lisp
-Slightly different from binding a key to a keymap, is binding a key
@strong{within} a
-local keymap that only exists after the package is loaded. @code{use-package}
-supports this with a @code{:map} modifier, taking the local keymap to bind to:
+Without using even the @code{:commands} keyword, we could also write
+the above like so:
+
+@lisp
+(use-package ace-jump-mode
+ :defer t
+ :init
+ (autoload 'ace-jump-mode "ace-jump-mode" nil t)
+ (bind-key "C-." 'ace-jump-mode))
+@end lisp
+
+Although these three forms are all equivalent, the first form is
+usually the best, as it will save some typing.
+
+@node Binding in keymaps
+@subsection Key bindings in local keymaps
+
+@findex :map, inside :bind
+Slightly different from binding a key to a keymap, is binding a key
+@emph{within} a local keymap that only exists after the package is
+loaded. @code{use-package} supports this with a @code{:map} modifier,
+taking the local keymap to bind to:
@lisp
(use-package helm
@@ -432,12 +877,13 @@ supports this with a @code{:map} modifier, taking the
local keymap to bind to:
("C-c h" . helm-execute-persistent-action)))
@end lisp
-The effect of this statement is to wait until @code{helm} has loaded, and then
to
-bind the key @code{C-c h} to @code{helm-execute-persistent-action} within
Helm's local
-keymap, @code{helm-mode-map}.
+The effect of this statement is to wait until @code{helm} has loaded,
+and then to bind the key @code{C-c h} to
+@code{helm-execute-persistent-action} within Helm's local keymap,
+@code{helm-command-map}.
-Multiple uses of @code{:map} may be specified. Any binding occurring before
the
-first use of @code{:map} are applied to the global keymap:
+Multiple uses of @code{:map} may be specified. Any binding occurring
+before the first use of @code{:map} are applied to the global keymap:
@lisp
(use-package term
@@ -451,184 +897,429 @@ first use of @code{:map} are applied to the global
keymap:
("M-n" . term-send-down)))
@end lisp
-@node @code{commands}
-@section @code{:commands}
+@node Binding to a keymap
+@subsection Binding to keymaps
+
+@findex :bind-keymap, inside :bind
+Normally @code{:bind} expects that commands are functions that will be
+autoloaded from the given package. However, this does not work if one of
+those commands is actually a keymap, since keymaps are not functions,
+and cannot be autoloaded using the built-in @code{autoload} function.
-@node @code{preface} @code{init} @code{config}
-@section @code{:preface}, @code{:init}, @code{:config}
+To handle this case, @code{use-package} offers a special, limited
+variant of @code{:bind} called @code{:bind-keymap}. The only difference
+is that the ``commands'' bound to by @code{:bind-keymap} must be keymaps
+defined in the package, rather than command functions. This is handled
+behind the scenes by generating custom code that loads the package
+containing the keymap, and then re-executes your keypress after the
+first load, to reinterpret that keypress as a prefix key.
-Here is the simplest @code{use-package} declaration:
+For example:
@lisp
-;; This is only needed once, near the top of the file
-(eval-when-compile
- ;; Following line is not needed if use-package.el is in ~/.emacs.d
- (add-to-list 'load-path "<path where use-package is installed>")
- (require 'use-package))
+(use-package foo
+ :bind-keymap ("C-c p" . foo-command-map))
+@end lisp
-(use-package foo)
+@node Binding to repeat-maps
+@subsection Binding to repeat-maps
+
+@findex :repeat-map, inside :bind
+@cindex repeat-mode and use-package, using
+A special case of binding within a local keymap is when that keymap is
+used by @code{repeat-mode} @pxref{Repeating,,, emacs, GNU Emacs
+Manual}. These keymaps are usually defined specifically for
+this. Using the @code{:repeat-map} keyword, and passing it a name for
+the map it defines, will bind all following keys inside that map, and
+(by default) set the @code{repeat-map} property of each bound command
+to that map.
+
+The following example creates a keymap called
+@code{git-gutter+-repeat-map}, makes four bindings in it as above,
+then sets the @code{repeat-map} property of each bound command
+(@code{git-gutter+-next-hunk} @code{git-gutter+-previous-hunk},
+@code{git-gutter+-stage-hunks} and @code{git-gutter+-revert-hunk}) to
+that keymap.
+
+@lisp
+(use-package git-gutter+
+ :bind
+ (:repeat-map git-gutter+-repeat-map
+ ("n" . git-gutter+-next-hunk)
+ ("p" . git-gutter+-previous-hunk)
+ ("s" . git-gutter+-stage-hunks)
+ ("r" . git-gutter+-revert-hunk)))
@end lisp
-This loads in the package @code{foo}, but only if @code{foo} is available on
your
-system. If not, a warning is logged to the @code{*Messages*} buffer. If it
-succeeds, a message about @code{"Loading foo"} is logged, along with the time
it
-took to load, if it took over 0.1 seconds.
+@findex :exit, inside :repeat-map and :bind
+Specifying @code{:exit} inside the scope of @code{:repeat-map} will
+prevent the @code{repeat-map} property being set, so that the command
+can be used from within the repeat map, but after it using it the repeat
+map will no longer be available. This is useful for commands often used
+at the end of a series of repeated commands:
-Use the @code{:init} keyword to execute code before a package is loaded. It
-accepts one or more forms, up until the next keyword:
+@lisp
+(use-package git-gutter+
+ :bind
+ (:repeat-map my/git-gutter+-repeat-map
+ ("n" . git-gutter+-next-hunk)
+ ("p" . git-gutter+-previous-hunk)
+ ("s" . git-gutter+-stage-hunks)
+ ("r" . git-gutter+-revert-hunk)
+ :exit
+ ("c" . magit-commit-create)
+ ("C" . magit-commit)
+ ("b" . magit-blame)))
+@end lisp
+
+@findex :continue, inside :repeat-map and :bind
+Specifying @code{:continue} @emph{forces} setting the
+@code{repeat-map} property (just like @emph{not} specifying
+@code{:exit}), so the above snippet is equivalent to:
@lisp
-(use-package foo
- :init
- (setq foo-variable t))
+(use-package git-gutter+
+ :bind
+ (:repeat-map my/git-gutter+-repeat-map
+ :exit
+ ("c" . magit-commit-create)
+ ("C" . magit-commit)
+ ("b" . magit-blame)
+ :continue
+ ("n" . git-gutter+-next-hunk)
+ ("p" . git-gutter+-previous-hunk)
+ ("s" . git-gutter+-stage-hunks)
+ ("r" . git-gutter+-revert-hunk)))
@end lisp
-Similarly, @code{:config} can be used to execute code after a package is
loaded.
-In cases where loading is done lazily (see more about autoloading below), this
-execution is deferred until after the autoload occurs:
+@node Displaying keybindings
+@subsection Displaying personal keybinding
+
+@findex describe-personal-keybindings
+The @code{:bind} keyword uses the @code{bind-keys} macro from the
+@samp{bind-key.el} library to set up keybindings. It keeps track of
+all keybindings you make, so that you can display them separately from
+the default keybindings.
+
+Use @w{@code{M-x describe-personal-keybindings}} to see all
+keybindings you've set using either the @code{:bind} keyword or the
+@code{bind-keys} macro.
+
+@node Hooks
+@section Hooks
+
+@cindex hooks
+@findex :hook
+The @code{:hook} keyword allows adding functions onto hooks. It takes
+one argument of the form @var{hooks}, specifying one or more functions
+to add to one or more hooks. For the purposes of @code{:hook}, the
+name of hook variables should always exclude the @samp{-hook} suffix.
+It is appended automatically for you, to save some typing.
+
+For example, consider the following @code{use-package} declaration
+that sets up autoloads for @code{company-mode} from the @samp{company}
+package, and adds @samp{company-mode} to @code{prog-mode-hook}:
@lisp
-(use-package foo
+(use-package company
+ :commands company-mode
:init
- (setq foo-variable t)
- :config
- (foo-mode 1))
+ (add-hook 'prog-mode-hook #'company-mode))
@end lisp
-As you might expect, you can use @code{:init} and @code{:config} together:
+Using @code{:hook}, this can be simplified to:
@lisp
-(use-package color-moccur
- :commands (isearch-moccur isearch-all)
- :bind (("M-s O" . moccur)
- :map isearch-mode-map
- ("M-o" . isearch-moccur)
- ("M-O" . isearch-moccur-all))
+(use-package company
+ :hook (prog-mode . company-mode))
+@end lisp
+
+Here, @code{:hook} will automatically set up autoloads for the
+@code{company-mode} command, so there is no need to use
+@code{:commands}.
+
+The @code{:hook} keyword will also assume that the name of the
+function you want to add is the same as the package name with
+@samp{-mode} appended to it. Taking this into account, you can
+simplify the above to the equivalent:
+
+@lisp
+(use-package company
+ :hook prog-mode)
+@end lisp
+
+@cindex multiple hooks
+You can also provide a list of hooks. When multiple hooks should be
+applied, the following examples are all equivalent:
+
+@lisp
+(use-package company
+ :hook (prog-mode text-mode))
+
+(use-package company
+ :hook ((prog-mode text-mode) . company-mode))
+
+(use-package company
+ :hook ((prog-mode . company-mode)
+ (text-mode . company-mode)))
+
+(use-package company
+ :commands company-mode
:init
- (setq isearch-lazy-highlight t)
+ (add-hook 'prog-mode-hook #'company-mode)
+ (add-hook 'text-mode-hook #'company-mode))
+@end lisp
+
+One common mistake when using @code{:hook} is to forget to omit the
+@samp{-hook} suffix, which, as already explained, is appended
+automatically. Therefore, the following will not work, as it attempts
+to add a function to non-existent @code{prog-mode-hook-hook}:
+
+@lisp
+;; DOES NOT WORK
+(use-package ace-jump-mode
+ :hook (prog-mode-hook . ace-jump-mode))
+@end lisp
+
+@vindex use-package-hook-name-suffix
+If you do not like this behavior, you can customize the user option
+@code{use-package-hook-name-suffix} to @code{nil}. The value of this
+variable is @samp{"-hook"} by default.
+
+The use of @code{:hook}, as with @code{:bind}, @code{:mode},
+@code{:interpreter}, etc., causes the functions being hooked to
+implicitly be read as @code{:commands}. This means that they will
+establish interactive @code{autoload} definitions for that module, if
+not already defined as functions), and so @code{:defer t} is also
+implied by @code{:hook}.
+
+@node Modes and interpreters
+@section Modes and interpreters
+
+@findex :mode
+@findex :interpreter
+Similar to @code{:bind}, you can use @code{:mode} and
+@code{:interpreter} to establish a deferred binding within the
+@code{auto-mode-alist} and @code{interpreter-mode-alist} variables.
+The specifier to either keyword can be a cons cell, a list of cons
+cells, or a string or regexp.
+
+The following example reproduces the default @code{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
+@code{"\\.rb\\'"} (a file with the @samp{.rb} extension), or when the
+first line of the file (known as the ``shebang'') matches the string
+@code{"ruby"}:
+
+@lisp
+(use-package ruby-mode
+ :mode "\\.rb\\'"
+ :interpreter "ruby")
+@end lisp
+
+The default @code{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:
+
+@lisp
+;; The package is "python" but the mode is "python-mode":
+(use-package python
+ :mode ("\\.py\\'" . python-mode)
+ :interpreter ("python" . python-mode))
+@end lisp
+
+Both the @code{:mode} and @code{:interpreter} keywords also accept a
+list of regexps:
+
+@lisp
+(use-package foo
+ ;; Equivalent to "\\(ba[rz]\\)\\'":
+ :mode ("\\.bar\\'" "\\.baz\\'")
+ ;; Equivalent to "\\(foo[ab]\\)":
+ :interpreter ("fooa" "foob"))
+@end lisp
+
+@node Magic handlers
+@section Magic handlers
+
+@findex :magic
+@findex :magic-fallback
+Similar to @code{:mode} and @code{:interpreter}, you can also use
+@code{:magic} and @code{:magic-fallback} to cause certain function to
+be run if the beginning of a file matches a given regular expression.
+The difference between @code{:magic} and @code{:magic-fallback}, is
+that the latter has a lower priority than @code{:mode}.
+
+Here is an example:
+
+@lisp
+(use-package pdf-tools
+ :magic ("%PDF" . pdf-view-mode)
:config
- (use-package moccur-edit))
+ (pdf-tools-install :no-query))
@end lisp
-In this case, I want to autoload the commands @code{isearch-moccur} and
-@code{isearch-all} from @code{color-moccur.el}, and bind keys both at the
global level
-and within the @code{isearch-mode-map} (see next section). When the package is
-actually loaded (by using one of these commands), @code{moccur-edit} is also
-loaded, to allow editing of the @code{moccur} buffer.
+This registers an autoloaded command for @code{pdf-view-mode}, defers
+loading of @code{pdf-tools}, and runs @code{pdf-view-mode} if the
+beginning of a buffer matches the string @code{"%PDF"}.
-@node @code{custom}
-@section @code{:custom}
+@node User options
+@section User options
-The @code{:custom} keyword allows customization of package custom variables.
+@findex :custom
+In Emacs, you normally set customizable variables (user options) using
+the @code{M-x customize} interface (@pxref{Easy Customization,,,
+emacs, GNU Emacs Manual}). We recommended this method for most users.
+However, it is also possible to set them in your @code{use-package}
+declarations by using the @code{:custom} keyword.
@lisp
(use-package comint
+ :defer t
:custom
(comint-buffer-maximum-size 20000 "Increase comint buffer size.")
(comint-prompt-read-only t "Make the prompt read only."))
@end lisp
-The documentation string is not mandatory.
+This is better than using @code{setq} in a @code{:config} block, as
+customizable variables might have some code associated with it that
+Emacs will execute when you assign values to them. In Emacs 29, there
+is also the new @code{setopt} macro that does this for you.
-@node @code{custom-face}
-@section @code{:custom-face}
+Note that the values customized using this keyword are @emph{not}
+saved in the standard Emacs @code{custom-file}. You should therefore
+set each user option using either the @code{:custom} keyword @emph{or}
+@w{@code{M-x customize-option}}, which will save customized values in
+the Emacs @code{custom-file}. Do not use both for the same variable,
+as this risk having conflicting values in your use-package declaration
+and your @code{custom-file}. This can lead to problems that are both
+tricky and tedious to debug.
-The @code{:custom-face} keyword allows customization of package custom faces.
+@node Faces
+@section Faces
+
+@findex :custom-face
+The @code{:custom-face} keyword allows customization of package custom
+faces.
@lisp
(use-package eruby-mode
:custom-face
(eruby-standard-face ((t (:slant italic)))))
+
+(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))
@end lisp
-@node @code{defer} @code{demand}
-@section @code{:defer}, @code{:demand}
+@node Hiding minor modes
+@section Hiding minor modes with diminish and delight
-In almost all cases you don't need to manually specify @code{:defer t}. This
is
-implied whenever @code{:bind} or @code{:mode} or @code{:interpreter} is used.
Typically, you
-only need to specify @code{:defer} if you know for a fact that some other
package
-will do something to cause your package to load at the appropriate time, and
-thus you would like to defer loading even though use-package isn't creating
-any autoloads for you.
+@code{use-package} supports the diminish and delight packages, both of
+which make it possible remove or change minor mode strings in your
+mode-line. Which one to use is up to you, but you should normally
+only use one or the other -- never both.@footnote{When in doubt, you
+might as well use diminish.} To use either of them, you must first
+install the corresponding package from @acronym{GNU ELPA}.
-You can override package deferral with the @code{:demand} keyword. Thus, even
if
-you use @code{:bind}, using @code{:demand} will force loading to occur
immediately and
-not establish an autoload for the bound key.
+@menu
+* Diminish:: Hiding minor modes with Diminish.
+* Delight:: Hiding minor modes with Delight.
+@end menu
-@node @code{defines} @code{functions}
-@section @code{:defines}, @code{:functions}
+@node Diminish
+@subsection Diminish
-Another feature of @code{use-package} is that it always loads every file that
it
-can when @code{.emacs} is being byte-compiled. This helps to silence spurious
-warnings about unknown variables and functions.
+@findex :diminish
+When diminish@footnote{The diminish package is installable from
+@acronym{GNU ELPA}.} is installed, you can use the @code{:diminish}
+keyword. If diminish is not installed, the @code{:diminish} keyword
+does nothing.
-However, there are times when this is just not enough. For those times, use
-the @code{:defines} and @code{:functions} keywords to introduce dummy variable
and
-function declarations solely for the sake of the byte-compiler:
+First, add the following declaration to the beginning of your init
+file. The optional @w{@code{:ensure t}} makes sure the package is
+installed if it isn't already (@pxref{Installing packages}).
@lisp
-(use-package texinfo
- :defines texinfo-section-list
- :commands texinfo-mode
- :init
- (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode)))
+(use-package diminish :ensure t)
@end lisp
-If you need to silence a missing function warning, you can use
@code{:functions}:
+The @code{:diminish} keyword takes either a minor mode symbol, a cons
+of the symbol and its replacement string, or just a replacement
+string, in which case the minor mode symbol is guessed to be the
+package name with @samp{-mode} appended at the end:
@lisp
-(use-package ruby-mode
- :mode "\\.rb\\'"
- :interpreter "ruby"
- :functions inf-ruby-keys
+(use-package abbrev
+ :diminish abbrev-mode
:config
- (defun my-ruby-mode-hook ()
- (require 'inf-ruby)
- (inf-ruby-keys))
-
- (add-hook 'ruby-mode-hook 'my-ruby-mode-hook))
+ (if (file-exists-p abbrev-file-name)
+ (quietly-read-abbrev-file)))
@end lisp
-@node @code{diminish} @code{delight}
-@section @code{:diminish}, @code{:delight}
+@node Delight
+@subsection Delight
-@code{use-package} also provides built-in support for the diminish and delight
-utilities---if you have them installed. Their purpose is to remove or change
-minor mode strings in your mode-line.
+@findex :delight
+When delight@footnote{The @samp{delight} package is installable from
+GNU ELPA.} is installed, you can use the @code{:delight} keyword. If
+delight is not installed, the @code{:delight} keyword does nothing.
-@uref{https://github.com/myrjola/diminish.el, diminish} is invoked with the
@code{:diminish} keyword, which is passed either a
-minor mode symbol, a cons of the symbol and its replacement string, or just a
-replacement string, in which case the minor mode symbol is guessed to be the
-package name with "-mode" appended at the end:
+First, add the following declaration to the beginning of your init
+file. The optional @w{@code{:ensure t}} makes sure the package is
+installed if it isn't already (@pxref{Installing packages}).
@lisp
-(use-package abbrev
- :diminish abbrev-mode
- :config
- (if (file-exists-p abbrev-file-name)
- (quietly-read-abbrev-file)))
+(use-package delight :ensure t)
@end lisp
-@uref{https://elpa.gnu.org/packages/delight.html, delight} is invoked with the
@code{:delight} keyword, which is passed a minor mode
-symbol, a replacement string or quoted
@uref{https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Data.html,
mode-line data} (in which case the minor
-mode symbol is guessed to be the package name with "-mode" appended at the
-end), both of these, or several lists of both. If no arguments are provided,
-the default mode name is hidden completely.
+The @code{:delight} keyword takes a minor mode symbol, a replacement
+string, or quoted mode line data (in which case the minor mode symbol
+is assumed to be the package name with @samp{-mode} appended at the
+end), both of these, or several lists of both. @xref{Mode Line
+Data,,, elisp, GNU Emacs Lisp Reference Manual}. If no arguments are
+provided, the default mode name is hidden completely.
+
+For example, the following hides everything for the @samp{foo-mode}
+minor mode in the @samp{foo} package:
@lisp
-;; Don't show anything for rainbow-mode.
-(use-package rainbow-mode
+(use-package foo
:delight)
+@end lisp
+
+If the mode name doesn't match the package name with @samp{-mode}
+appended, provide a symbol instead. For example, the following hides
+@code{auto-revert-mode} from the mode line:
+@lisp
;; Don't show anything for auto-revert-mode, which doesn't match
;; its package name.
(use-package autorevert
:delight auto-revert-mode)
+@end lisp
-;; Remove the mode name for projectile-mode, but show the project name.
-(use-package projectile
- :delight '(:eval (concat " " (projectile-project-name))))
+You can also run arbitrary Lisp code. For example, to replace
+@samp{foo-mode} with the value of the current buffer:
+@lisp
+(use-package foo
+ :delight '(:eval buffer-file-name))
+@end lisp
+
+Here is an example of hiding several built-in minor modes:
+
+@lisp
;; Completely hide visual-line-mode and change auto-fill-mode to " AF".
(use-package emacs
:delight
@@ -636,30 +1327,32 @@ the default mode name is hidden completely.
(visual-line-mode))
@end lisp
-@node @code{disabled}
-@section @code{:disabled}
+@c ----------------------------------------------------------------------------
+@node Installing packages
+@chapter Installing packages automatically
-The @code{:disabled} keyword can turn off a module you're having difficulties
with,
-or stop loading something you're not using at the present time:
+The standard Emacs package manager is documented in the Emacs manual
+(@pxref{Package Installation,,, emacs, GNU Emacs Manual}). The
+@code{use-package} macro provides the @code{:ensure} and @code{:pin}
+keywords, that interface with that package manager to automatically
+install packages. This is particularly useful if you use your init
+file on more than one system.
-@lisp
-(use-package ess-site
- :disabled
- :commands R)
-@end lisp
+@menu
+* Install package::
+* Pinning packages::
+* Other package managers::
+@end menu
-When byte-compiling your @code{.emacs} file, disabled declarations are omitted
-from the output entirely, to accelerate startup times.
+@node Install package
+@section Installing package
-@node @code{ensure} @code{pin}
-@section @code{:ensure}, @code{:pin}
+@findex :ensure
+The @code{:ensure} keyword makes use-package ask the Emacs package
+manager to install a package if it is not already present on your
+system.
-You can use @code{use-package} to load packages from ELPA with
@code{package.el}. This
-is particularly useful if you share your @code{.emacs} among several machines;
the
-relevant packages are downloaded automatically once declared in your
@code{.emacs}.
-The @code{:ensure} keyword causes the package(s) to be installed automatically
if
-not already present on your system (set @code{(setq use-package-always-ensure
t)}
-if you wish this behavior to be global for all packages):
+For example:
@lisp
(use-package magit
@@ -667,280 +1360,520 @@ if you wish this behavior to be global for all
packages):
@end lisp
If you need to install a different package from the one named by
-@code{use-package}, you can specify it like this:
+@code{use-package}, you can use a symbol:
@lisp
(use-package tex
:ensure auctex)
@end lisp
-Lastly, when running on Emacs 24.4 or later, use-package can pin a package to
-a specific archive, allowing you to mix and match packages from different
-archives. The primary use-case for this is preferring packages from the
-@code{melpa-stable} and @code{gnu} archives, but using specific packages from
@code{melpa}
-when you need to track newer versions than what is available in the
@code{stable}
-archives is also a valid use-case.
+You can customize the user option @code{use-package-always-ensure} to
+non-@code{nil} if you want this behavior to be global for all
+packages.
-By default @code{package.el} prefers @code{melpa} over @code{melpa-stable} due
to the
-versioning @code{(> evil-20141208.623 evil-1.0.9)}, so even if you are tracking
-only a single package from @code{melpa}, you will need to tag all the
non-@code{melpa}
-packages with the appropriate archive. If this really annoys you, then you can
-set @code{use-package-always-pin} to set a default.
+@lisp
+(require 'use-package-ensure)
+(setq use-package-always-ensure t)
+@end lisp
-If you want to manually keep a package updated and ignore upstream updates,
-you can pin it to @code{manual}, which as long as there is no repository by
that
-name, will Just Work(tm).
+@noindent
+You can override the above setting for a single package by adding
+@w{@code{:ensure nil}} to its declaration.
-@code{use-package} throws an error if you try to pin a package to an archive
that
-has not been configured using @code{package-archives} (apart from the magic
-@code{manual} archive mentioned above):
+@node Pinning packages
+@section Pinning packages using @code{:pin}
-@example
-Archive 'foo' requested for package 'bar' is not available.
-@end example
+@findex :pin
+use-package can pin a package to a specific archive using the
+@code{:pin} keyword.@footnote{The @code{:pin} keyword has no effect on
+Emacs versions older than 24.4.} This allows you to mix and match
+packages from different archives. The primary use-case for this is
+preferring to install packages from @acronym{GNU ELPA} or
+@acronym{NonGNU ELPA} (indicated by @code{gnu} and @code{nongnu},
+respectively), while installing specific packages from third-party
+archives.
-Example:
+For example:
@lisp
(use-package company
:ensure t
- :pin melpa-stable)
+ :pin gnu) ; GNU ELPA
+@end lisp
-(use-package evil
- :ensure t)
- ;; no :pin needed, as package.el will choose the version in melpa
+@vindex use-package-always-pin
+Unfortunately, the third-party archive @acronym{MELPA} uses a
+versioning scheme based on dates, which means that packages from that
+archive are always preferred. If you are using that archive, we
+strongly encourage you to customize @code{use-package-always-pin} to
+@code{nongnu}. This guarantees that you are using a version of that
+package that has been specifically marked for release by its
+developer, and not a development snapshot.
+
+@c FIXME: This needs clarifying. AFAIK, :ensure does not update packages.
+If you want to manually keep a package updated and ignore upstream
+updates, you can pin it to @samp{manual}. This will work as long as
+you have not customized a repository to use that name in the
+@code{package-archives} variable.
-(use-package adaptive-wrap
- :ensure t
- ;; as this package is available only in the gnu archive, this is
- ;; technically not needed, but it helps to highlight where it
- ;; comes from
- :pin gnu)
+Example:
+@lisp
(use-package org
:ensure t
;; ignore org-mode from upstream and use a manually installed version
:pin manual)
@end lisp
-@strong{NOTE}: the @code{:pin} argument has no effect on emacs versions < 24.4.
+@code{use-package} signals an error if you try to pin a package to an
+archive that is not configured using @code{package-archives} (except
+from the special @samp{manual} archive).
+
+@node Other package managers
+@section Non-standard package managers
+
+By default, use-package assumes that you are using the built-in
+@code{package.el} package manager. We expect that most users will
+find that it is more than capable enough, even for advanced use cases.
+
+@vindex use-package-ensure-function
+However, some users might prefer to use a third-party package manager
+for a specific circumstance or use case. By setting the user option
+@code{use-package-ensure-function} to the name of a function, you can
+direct @code{:ensure} to use a different package manager for
+installing packages.
+
+For more details, please see the documentation of the package manager
+you are using. If you run into any bugs, it is often best to report
+them directly to the developers of that package manager.
+
+@c ----------------------------------------------------------------------------
+@node Byte-compiling
+@chapter Byte-compiling your init file
+
+Some users might want to byte-compile their init file to make Emacs
+startup even faster. This is not recommended in most cases, as the
+speed-up is often too small to be worth it, and can lead to confusion
+if the byte-compiled files are out-of-date. If you still want to do
+it, read on.
+
+@code{use-package} always loads every library that it can while a file
+is being byte-compiled. This helps silence spurious warnings about
+unknown variables and functions.
+
+@findex :defines
+@findex :functions
+However, there are times when this is just not enough. For those
+times, use the @code{:defines} and @code{:functions} keywords to
+introduce dummy variable and function declarations solely for the sake
+of silencing byte-compiler warnings. For example:
-@node @code{hook}
-@section @code{:hook}
+@lisp
+(use-package texinfo
+ :defines texinfo-section-list
+ :commands texinfo-mode
+ :init
+ (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode)))
+@end lisp
-The @code{:hook} keyword allows adding functions onto hooks, here only the
basename
-of the hook is required. Thus, all of the following are equivalent:
+If you need to silence a missing function warning, you can use
+@code{:functions}:
@lisp
-(use-package ace-jump-mode
- :hook prog-mode)
-
-(use-package ace-jump-mode
- :hook (prog-mode . ace-jump-mode))
+(use-package ruby-mode
+ :mode "\\.rb\\'"
+ :interpreter "ruby"
+ :functions inf-ruby-keys
+ :config
+ (defun my-ruby-mode-hook ()
+ (require 'inf-ruby)
+ (inf-ruby-keys))
-(use-package ace-jump-mode
- :commands ace-jump-mode
- :init
- (add-hook 'prog-mode-hook #'ace-jump-mode))
+ (add-hook 'ruby-mode-hook 'my-ruby-mode-hook))
@end lisp
-And likewise, when multiple hooks should be applied, the following are also
-equivalent:
+@findex :no-require
+@cindex prevent a package from loading at compile-time
+Normally, @code{use-package} will load each package at compile time
+before compiling the configuration, to ensure that any necessary
+symbols are in scope to satisfy the byte-compiler. At times this can
+cause problems, since a package may have special loading requirements,
+and all that you want to use @code{use-package} for is to add a
+configuration to the @code{eval-after-load} hook. In such cases, use
+the @code{:no-require} keyword:
@lisp
-(use-package ace-jump-mode
- :hook (prog-mode text-mode))
+(use-package foo
+ :no-require t
+ :config
+ (message "Evaluate this immediately after loading `foo'"))
+@end lisp
-(use-package ace-jump-mode
- :hook ((prog-mode text-mode) . ace-jump-mode))
+@c ----------------------------------------------------------------------------
+@node Troubleshooting
+@chapter Troubleshooting
-(use-package ace-jump-mode
- :hook ((prog-mode . ace-jump-mode)
- (text-mode . ace-jump-mode)))
+@cindex troubleshooting
+@cindex debugging
+If an error occurs while initializing or configuring a package, this
+will not stop your Emacs from loading. Instead, @code{use-package}
+captures the error and reports it in a special @code{*Warnings*} popup
+buffer, so that you can debug the situation in an otherwise functional
+Emacs.
-(use-package ace-jump-mode
- :commands ace-jump-mode
- :init
- (add-hook 'prog-mode-hook #'ace-jump-mode)
- (add-hook 'text-mode-hook #'ace-jump-mode))
-@end lisp
+If you are having trouble when starting Emacs, you can pass Emacs the
+@samp{--debug-init} command line flag. @xref{Initial Options,,,
+emacs, GNU Emacs Manual}. To get even more information when using
+that flag, add the following to your init file (these options are
+documented below):
-The use of @code{:hook}, as with @code{:bind}, @code{:mode},
@code{:interpreter}, etc., causes the
-functions being hooked to implicitly be read as @code{:commands} (meaning they
will
-establish interactive @code{autoload} definitions for that module, if not
already
-defined as functions), and so @code{:defer t} is also implied by @code{:hook}.
+@lisp
+(when init-file-debug
+ (setq use-package-verbose t
+ use-package-expand-minimally nil
+ use-package-compute-statistics t
+ debug-on-error t))
+@end lisp
-@node @code{if} @code{when} @code{unless}
-@section @code{:if}, @code{:when}, @code{:unless}
+@cindex reporting bugs
+@cindex expanding macro, for troubleshooting
+Since @code{use-package} is a macro, the first step when you need to
+dig deeper is usually to see what Emacs Lisp code your declaration
+expands to. You can either use the command @w{@kbd{M-x
+pp-macroexpand-last-sexp}}, or wrap the use-package declaration in
+@code{macroexpand} and evaluate it. It is a good idea to include
+their output in any bugs you file for use-package.
-You can use the @code{:if} keyword to predicate the loading and initialization
of
-modules.
+@menu
+* Troubleshooting Options::
+* Gathering Statistics::
+* Disabling a package::
+@end menu
-For example, I only want @code{edit-server} running for my main, graphical
Emacs,
-not for other Emacsen I may start at the command line:
+@node Troubleshooting Options
+@section Options that help when troubleshooting
+
+@vindex use-package-expand-minimally
+By default, use-package will attempts to catch and report errors that
+occur during expansion of use-package declarations in your init file.
+Customize the user option @code{use-package-expand-minimally} to a
+non-@code{nil} value to disable this checking.
+
+@findex :catch
+This behavior may be overridden locally using the @code{:catch}
+keyword. If @code{t} or @code{nil}, it enables or disables catching
+errors at load time. It can also be a function taking two arguments:
+the keyword being processed at the time the error was encountered, and
+the error object (as generated by @code{condition-case}). For
+example:
@lisp
-(use-package edit-server
- :if window-system
- :init
- (add-hook 'after-init-hook 'server-start t)
- (add-hook 'after-init-hook 'edit-server-start t))
+(use-package example
+ ;; Note that errors are never trapped in the preface, since doing so would
+ ;; hide definitions from the byte-compiler.
+ :preface (message "I'm here at byte-compile and load time")
+ :init (message "I'm always here at startup")
+ :config
+ (message "I'm always here after the package is loaded")
+ (error "oops")
+ ;; Don't try to (require 'example), this is just an example!
+ :no-require t
+ :catch (lambda (keyword err)
+ (message (error-message-string err))))
@end lisp
-In another example, we can load things conditional on the operating system:
+Evaluating the above form will print these messages:
+
+@verbatim
+I’m here at byte-compile and load time
+I’m always here at startup
+Configuring package example...
+I’m always here after the package is loaded
+oops
+@end verbatim
+
+@node Gathering Statistics
+@section Gathering Statistics
+
+@vindex use-package-verbose
+When a package is loaded, and if you have @code{use-package-verbose}
+set to @code{t}, or if the package takes longer than 0.1 seconds to
+load, you will see a message to indicate this loading activity in the
+@code{*Messages*} buffer. The same will happen for configuration, or
+@code{:config} blocks, that take longer than 0.1 seconds to execute.
+
+@vindex use-package-compute-statistics
+If you'd like to see a summary how many packages you've loaded, what
+stage of initialization they've reached, and how much aggregate time
+they've spent (roughly), you can customize the user option
+@code{use-package-compute-statistics} to a non-@code{nil} value. Then
+reload your packages, normally by restarting Emacs, to make sure that
+use-package can gather statistics for all your packages.
+
+@cindex use-package-report
+Run the command @kbd{M-x use-package-report} to see the results. The
+buffer displayed is a tabulated list. To sort rows based on a
+particular column, move point to it and type @kbd{S}, or click the
+column name at the top of the buffer on graphical displays.
+
+@cindex use-package-reset-statistics
+To reset all statistics that use-package has gathered for the current
+Emacs invocation, run the command @kbd{M-x use-package-reset-statistics}.
+
+Note that, if you are setting @code{use-package-compute-statistics}
+directly in your init file, and not with @code{customize}, you must do
+this after loading @code{use-package}, but before any
+@code{use-package} forms.
+
+@node Disabling a package
+@section Disabling a package
+
+@cindex disable package
+@findex :disabled
+The @code{:disabled} keyword inhibits loading a package, and all it's
+customizations. It is equivalent to commenting out or deleting the
+definition.
+
+You could use this, for example, to temporarily disable a package that
+you're having difficulties with, or to avoid loading a package that
+you're not currently using.
+
+This example disables the @samp{foo} package:
@lisp
-(use-package exec-path-from-shell
- :if (memq window-system '(mac ns))
- :ensure t
- :config
- (exec-path-from-shell-initialize))
+(use-package foo
+ :disabled)
@end lisp
-Note that @code{:when} is provided as an alias for @code{:if}, and
@code{:unless foo} means
-the same thing as @code{:if (not foo)}.
+When byte-compiling your init file, use-package omits disabled
+declarations from the output entirely, in order to make Emacs startup
+faster.
-@node @code{load-path}
-@section @code{:load-path}
+@c ----------------------------------------------------------------------------
+@node Keyword extensions
+@appendix Keyword extensions
-If your package needs a directory added to the @code{load-path} in order to
load,
-use @code{:load-path}. This takes a symbol, a function, a string or a list of
-strings. If the path is relative, it is expanded within
-@code{user-emacs-directory}:
+use-package is based on an extensible framework that makes it easy for
+package authors to add new keywords, or modify the behavior of
+existing keywords.
+
+Some keyword extensions are included with @code{use-package}, and can
+be optionally enabled.
+
+@menu
+* use-package-ensure-system-package::
+* Creating an extension::
+@end menu
+
+@node use-package-ensure-system-package
+@section :use-package-ensure-system-package
+
+@findex :ensure-system-package
+The @code{:ensure-system-package} keyword allows you to ensure certain
+executables are available on your system alongside your package
+declarations.@footnote{On macOS, you will want to make sure
+@code{exec-path} is cognisant of all binary package names that you
+would like to ensure are installed. The
+@uref{https://github.com/purcell/exec-path-from-shell,@samp{exec-path-from-shell}}
+package is often a good way to do this.}
+
+To use this extension, add this immediately after loading
+@code{use-package}:
@lisp
-(use-package ess-site
- :load-path "site-lisp/ess/lisp/"
- :commands R)
+(use-package use-package-ensure-system-package)
@end lisp
-Note that when using a symbol or a function to provide a dynamically generated
-list of paths, you must inform the byte-compiler of this definition so the
-value is available at byte-compilation time. This is done by using the special
-form @code{eval-and-compile} (as opposed to @code{eval-when-compile}).
Further, this
-value is fixed at whatever was determined during compilation, to avoid looking
-up the same information again on each startup:
+Now you can use the @code{:ensure-system-package} keyword.
+Here's an example usage:
@lisp
-(eval-and-compile
- (defun ess-site-load-path ()
- (shell-command "find ~ -path ess/lisp")))
-
-(use-package ess-site
- :load-path (lambda () (list (ess-site-load-path)))
- :commands R)
+(use-package foo
+ :ensure-system-package foo)
@end lisp
-@node @code{mode} @code{interpreter}
-@section @code{:mode}, @code{:interpreter}
+This will expect a global binary package to exist called @code{foo}.
+If it does not, it will use your system package manager to attempt an
+install of a binary by the same name asynchronously. This requires
+the GNU ELPA package
+@uref{https://gitlab.com/jabranham/system-packages,@samp{system-packages}},
+so for this to work you must install that first.
-Similar to @code{:bind}, you can use @code{:mode} and @code{:interpreter} to
establish a
-deferred binding within the @code{auto-mode-alist} and
@code{interpreter-mode-alist}
-variables. The specifier to either keyword can be a cons cell, a list of cons
-cells, or a string or regexp:
+One way of making sure it is installed is with @code{use-package}
+together with @code{:ensure}.
@lisp
-(use-package ruby-mode
- :mode "\\.rb\\'"
- :interpreter "ruby")
-
-;; The package is "python" but the mode is "python-mode":
-(use-package python
- :mode ("\\.py\\'" . python-mode)
- :interpreter ("python" . python-mode))
+(use-package system-packages
+ :ensure t)
@end lisp
-If you aren't using @code{:commands}, @code{:bind}, @code{:bind*},
@code{:bind-keymap},
-@code{:bind-keymap*}, @code{:mode}, or @code{:interpreter} (all of which imply
@code{:defer}; see
-the docstring for @code{use-package} for a brief description of each), you can
-still defer loading with the @code{:defer} keyword:
+For example, on a @code{Debian GNU/Linux} system, this would call
+@samp{apt-get install foo}.
+
+If the package is named differently than the binary, you can use a
+cons in the form of @code{(binary . package-name)}. For example:
@lisp
-(use-package ace-jump-mode
- :defer t
- :init
- (autoload 'ace-jump-mode "ace-jump-mode" nil t)
- (bind-key "C-." 'ace-jump-mode))
+(use-package foo
+ :ensure-system-package
+ (foocmd . foo))
@end lisp
-This does exactly the same thing as the following:
+On a @code{Debian GNU/Linux} system, this would call @code{apt install
+foo} if Emacs could not locate the executable
+@code{foocmd}.@footnote{For manual testing, you could use the
+@code{executable-find} function, which is what @samp{system-packages}
+uses internally.}
+
+@code{:ensure-system-package} can also take a cons where its
+@code{cdr} is a string that will get called by
+@code{(async-shell-command)} to install if it isn't found. This does
+not depend upon any external package.
@lisp
-(use-package ace-jump-mode
- :bind ("C-." . ace-jump-mode))
+(use-package tern
+ :ensure-system-package (tern . "npm i -g tern"))
@end lisp
-@node @code{magic} @code{magic-fallback}
-@section @code{:magic}, @code{:magic-fallback}
+To install several packages, you can pass in a list of conses:
-Similar to @code{:mode} and @code{:interpreter}, you can also use
@code{:magic} and
-@code{:magic-fallback} to cause certain function to be run if the beginning of
a
-file matches a given regular expression. The difference between the two is
-that @code{:magic-fallback} has a lower priority than @code{:mode}. For
example:
+@lisp
+(use-package ruby-mode
+ :ensure-system-package
+ ((rubocop . "gem install rubocop")
+ (ruby-lint . "gem install ruby-lint")
+ (ripper-tags . "gem install ripper-tags")
+ (pry . "gem install pry")))
+@end lisp
+
+Finally, in case the package dependency does not provide a global
+executable, you can ensure packages exist by checking the presence of a
+file path by providing a string like so:
@lisp
-(use-package pdf-tools
- :load-path "site-lisp/pdf-tools/lisp"
- :magic ("%PDF" . pdf-view-mode)
- :config
- (pdf-tools-install))
+(use-package dash-at-point
+ :if (eq system-type 'darwin)
+ :ensure-system-package
+ ("/Applications/Dash.app" . "brew cask install dash"))
@end lisp
-This registers an autoloaded command for @code{pdf-view-mode}, defers loading
of
-@code{pdf-tools}, and runs @code{pdf-view-mode} if the beginning of a buffer
matches the
-string @code{"%PDF"}.
+@code{:ensure-system-package} will use @code{system-packages-install}
+to install system packages, except where a custom command has been
+specified, in which case it will be executed verbatim by
+@code{async-shell-command}.
-@node @code{no-require}
-@section @code{:no-require}
+The user options @code{system-packages-package-manager} and
+@code{system-packages-use-sudo} are honored, but not for custom
+commands. Custom commands should include the call to sudo in the
+command if needed.
-Normally, @code{use-package} will load each package at compile time before
-compiling the configuration, to ensure that any necessary symbols are in scope
-to satisfy the byte-compiler. At times this can cause problems, since a
-package may have special loading requirements, and all that you want to use
-@code{use-package} for is to add a configuration to the @code{eval-after-load}
hook. In
-such cases, use the @code{:no-require} keyword:
+@node Creating an extension
+@section How to create an extension keyword
-@lisp
-(use-package foo
- :no-require t
- :config
- (message "This is evaluated when `foo' is loaded"))
-@end lisp
+This section describes how to create a new keyword.
+
+@enumerate
+@item
+Add the keyword.
-@node @code{requires}
-@section @code{:requires}
+The first step is to add your keyword at the right place in
+@code{use-package-keywords}. This list determines the order in which
+things will happen in the expanded code. You should never change this
+order, but it gives you a framework within which to decide when your
+keyword should fire.
-While the @code{:after} keyword delays loading until the dependencies are
loaded,
-the somewhat simpler @code{:requires} keyword simply never loads the package
if the
-dependencies are not available at the time the @code{use-package} declaration
is
-encountered. By "available" in this context it means that @code{foo} is
available
-of @code{(featurep 'foo)} evaluates to a non-nil value. For example:
+@item
+Create a normalizer.
-@lisp
-(use-package abbrev
- :requires foo)
-@end lisp
+The job of the normalizer is take a list of arguments (possibly
+@code{nil}), and turn it into the single argument (which could still
+be a list) that should appear in the final property list used by
+@code{use-package}.
-This is the same as:
+Define a normalizer for your keyword by defining a function named
+after the keyword, for example:
@lisp
-(use-package abbrev
- :if (featurep 'foo))
+(defun use-package-normalize/:pin (name-symbol keyword args)
+ (use-package-only-one (symbol-name keyword) args
+ (lambda (label arg)
+ (cond
+ ((stringp arg) arg)
+ ((symbolp arg) (symbol-name arg))
+ (t
+ (use-package-error
+ ":pin wants an archive name (a string)"))))))
@end lisp
-As a convenience, a list of such packages may be specified:
+@item
+Create a handler.
+
+Once you have a normalizer, you must create a handler for the keyword.
+
+Handlers can affect the handling of keywords in two ways. First, it
+can modify the @code{state} plist before recursively processing the
+remaining keywords, to influence keywords that pay attention to the
+state (one example is the state keyword @code{:deferred}, not to be
+confused with the @code{use-package} keyword @code{:defer}). Then,
+once the remaining keywords have been handled and their resulting
+forms returned, the handler may manipulate, extend, or just ignore
+those forms.
+
+The task of each handler is to return a @emph{list of forms}
+representing code to be inserted. It does not need to be a
+@code{progn} list, as this is handled automatically in other places.
+Thus it is common to see the idiom of using @code{use-package-concat}
+to add new functionality before or after a code body, so that only the
+minimum code necessary is emitted as the result of a
+@code{use-package} expansion.
+
+This is an example handler:
@lisp
-(use-package abbrev
- :requires (foo bar baz))
+(defun use-package-handler/:pin (name-symbol keyword archive-name rest state)
+ (let ((body (use-package-process-keywords name-symbol rest state)))
+ ;; This happens at macro expansion time, not when the expanded code is
+ ;; compiled or evaluated.
+ (if (null archive-name)
+ body
+ (use-package-pin-package name-symbol archive-name)
+ (use-package-concat
+ body
+ `((push '(,name-symbol . ,archive-name)
+ package-pinned-packages))))))
@end lisp
-For more complex logic, such as that supported by @code{:after}, simply use
@code{:if}
-and the appropriate Lisp expression.
+@item
+Test it.
+
+After the keyword has been inserted into @code{use-package-keywords},
+and a normalizer and a handler defined, you can now test it by seeing
+how usages of the keyword will expand. For this, use @code{M-x
+pp-macroexpand-last-sexp} with the cursor set immediately after the
+@code{(use-package ...)} expression.
+@end enumerate
+
+@c ----------------------------------------------------------------------------
+@node History
+@appendix History and acknowledgments
+
+use-package was written by John Wiegley. Its development started in
+2012, and it got merged into Emacs in 2022, in preparation of the
+release of Emacs 29.1.
+
+Dozens of people have contributed to use-package over the years with
+bug reports, documentation and code. They are too many to list here,
+but we thank them all for their contributions.
+
+This Texinfo manual was written by Stefan Kangas, as a significant
+rewrite of the old use-package manual and @file{README}.
-@node Debugging Tools
-@chapter Debugging Tools
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
-TODO
+@node Index
+@unnumbered Index
+@printindex cp
@bye