diff --git a/emacs.d/use-package/NEWS.md b/emacs.d/use-package/NEWS.md index bf49b99..c499820 100644 --- a/emacs.d/use-package/NEWS.md +++ b/emacs.d/use-package/NEWS.md @@ -1,14 +1,5 @@ # Changes -## 2.4.5 - -This is mostly a bug-fix release: - -- When `:hook` is using in the form `(use-package foo :hook bar)`, - this is once again equivalent to - `(use-package foo :hook (bar . foo))` and no longer the same as - `(use-package foo :hook (bar . foo-mode))`. - ## 2.4.4 This release prepares for inclusion to GNU ELPA and includes no other changes diff --git a/emacs.d/use-package/README.md b/emacs.d/use-package/README.md index bfd34cd..7c3308f 100644 --- a/emacs.d/use-package/README.md +++ b/emacs.d/use-package/README.md @@ -166,21 +166,7 @@ The `:bind` keyword takes either a cons or a list of conses: ("M-o w" . highlight-phrase))) ``` -Alternatively, the command name may be replaced with a cons `(desc . command)`, -where `desc` is a string describing `command`, which is the name of a command -to bind to: - -```elisp -(use-package avy - :bind ("C-:" ("Jump to char" . avy-goto-char) - "M-g f" ("Jump to line" . avy-goto-line))) -``` - -These descriptions can be used by other code that deals with key bindings. -For example, the GNU ELPA package which-key displays them when showing key -bindings, instead of the plain command names. - -The `:commands` keyword takes either a symbol or a list of symbols. +The `:commands` keyword likewise takes either a symbol or a list of symbols. **NOTE**: inside strings, special keys like `tab` or `F1`-`Fn` have to be written inside angle brackets, e.g. `"C-"`. Standalone special keys (and some combinations) can be written in square brackets, e.g. `[tab]` instead of `""`. The syntax for the keybindings is similar to @@ -401,10 +387,13 @@ string `"%PDF"`. ## Hooks -The `:hook` keyword allows adding functions onto package hooks. The -following are equivalent: +The `:hook` keyword allows adding functions onto package hooks. Thus, +all of the following are equivalent: ``` elisp +(use-package company + :hook prog-mode) + (use-package company :hook (prog-mode . company-mode)) @@ -414,10 +403,13 @@ following are equivalent: (add-hook 'prog-mode-hook #'company-mode)) ``` -And likewise, when multiple hooks should be applied, all of the -following are also equivalent: +And likewise, when multiple hooks should be applied, the following are also +equivalent: ``` elisp +(use-package company + :hook (prog-mode text-mode)) + (use-package company :hook ((prog-mode text-mode) . company-mode)) @@ -425,15 +417,6 @@ following are also equivalent: :hook ((prog-mode . company-mode) (text-mode . company-mode))) -(use-package company - :hook (prog-mode . company-mode) - :hook (text-mode . company-mode)) - -(use-package company - :hook - (prog-mode . company-mode) - (text-mode . company-mode)) - (use-package company :commands company-mode :init @@ -441,8 +424,8 @@ following are also equivalent: (add-hook 'text-mode-hook #'company-mode)) ``` -When using `:hook`, omit the "-hook" suffix if you specify the hook -explicitly, as this is appended by default. For example, the following +When using `:hook` omit the "-hook" suffix if you specify the hook +explicitly, as this is appended by default. For example the following code will not work as it attempts to add to the `prog-mode-hook-hook` which does not exist: diff --git a/emacs.d/use-package/bind-key.el b/emacs.d/use-package/bind-key.el index fcef1ab..3168f68 100644 --- a/emacs.d/use-package/bind-key.el +++ b/emacs.d/use-package/bind-key.el @@ -10,29 +10,29 @@ ;; Keywords: keys keybinding config dotemacs extensions ;; URL: https://github.com/jwiegley/use-package -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify +;; This program 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. -;; GNU Emacs is distributed in the hope that it will be useful, +;; This program 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 GNU Emacs. If not, see . +;; along with this program. If not, see . ;;; Commentary: -;; 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. +;; 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: ;; -;; Bind keys as follows in your init file: +;; (require 'bind-key) ;; ;; (bind-key "C-c x" 'my-ctrl-c-x-command) ;; @@ -95,8 +95,6 @@ ;; 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: @@ -105,10 +103,7 @@ (defgroup bind-key nil "A simple way to manage personal keybindings." - :group 'keyboard - :group 'convenience - :link '(emacs-commentary-link :tag "Commentary" "bind-key.el") - :version "29.1") + :group 'emacs) (defcustom bind-key-column-widths '(18 . 40) "Width of columns in `describe-personal-keybindings'." @@ -117,7 +112,8 @@ (defcustom bind-key-segregation-regexp "\\`\\(\\(C-[chx] \\|M-[gso] \\)\\([CM]-\\)?\\|.+-\\)" - "Regexp used by \\[describe-personal-keybindings] to divide key sets." + "Regular expression used to divide key sets in the output from +\\[describe-personal-keybindings]." :type 'regexp :group 'bind-key) @@ -132,18 +128,7 @@ "Keymap for `override-global-mode'.") (define-minor-mode override-global-mode - "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." + "A minor mode so that keymap settings override other modes." :init-value t :lighter "") @@ -162,12 +147,11 @@ 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 the 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 documentation of +`edmacro-mode' for details. -COMMAND must be an interactive function, lambda form, or a cons -`(STRING . DEFN)'. +COMMAND must be an interactive function or lambda form. KEYMAP, if present, should be a keymap variable or symbol. For example: @@ -441,11 +425,6 @@ 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/emacs.d/use-package/doclicense.texi b/emacs.d/use-package/doclicense.texi deleted file mode 100644 index eaf3da0..0000000 --- a/emacs.d/use-package/doclicense.texi +++ /dev/null @@ -1,505 +0,0 @@ -@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/emacs.d/use-package/docstyle.texi b/emacs.d/use-package/docstyle.texi deleted file mode 100644 index e740439..0000000 --- a/emacs.d/use-package/docstyle.texi +++ /dev/null @@ -1,19 +0,0 @@ -@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/emacs.d/use-package/use-package-bind-key.el b/emacs.d/use-package/use-package-bind-key.el index 9cc5529..75def7f 100644 --- a/emacs.d/use-package/use-package-bind-key.el +++ b/emacs.d/use-package/use-package-bind-key.el @@ -5,20 +5,18 @@ ;; Author: John Wiegley ;; Maintainer: John Wiegley -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify +;; This program 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. -;; GNU Emacs is distributed in the hope that it will be useful, +;; This program 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 GNU Emacs. If not, see . +;; along with this program. If not, see . ;;; Commentary: @@ -26,10 +24,6 @@ ;; 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: @@ -38,14 +32,15 @@ ;;;###autoload (defun use-package-autoload-keymap (keymap-symbol package override) - "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. + "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. -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)) @@ -69,17 +64,8 @@ deferred until the prefix key sequence is pressed." (let ((arg args) args*) (while arg - (let ((x (car arg)) - (y (cadr arg))) + (let ((x (car arg))) (cond - ;; (KEY DESC . COMMAND), i.e. (KEY . (DESC . COMMAND)) - ((and (or (stringp x) - (vectorp x)) - (consp y) - (stringp (car y)) - (or (use-package-recognize-function (cdr y) t #'stringp))) - (setq args* (nconc args* (list (cons x y)))) - (setq arg (cddr arg))) ;; (KEY . COMMAND) ((and (consp x) (or (stringp (car x)) diff --git a/emacs.d/use-package/use-package-core.el b/emacs.d/use-package/use-package-core.el index bb523f6..1190f14 100644 --- a/emacs.d/use-package/use-package-core.el +++ b/emacs.d/use-package/use-package-core.el @@ -5,27 +5,29 @@ ;; Author: John Wiegley ;; Maintainer: John Wiegley -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify +;; This program 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. -;; GNU Emacs is distributed in the hope that it will be useful, +;; This program 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 GNU Emacs. If not, see . +;; along with this program. If not, see . ;;; Commentary: -;; This file contains the core implementation of the `use-package' -;; macro. +;; 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! ;; -;; See the `use-package' info manual for more information. +;; Please see README.md from the same repository for documentation. ;;; Code: @@ -61,9 +63,7 @@ (defgroup use-package nil "A `use-package' declaration for simplifying your `.emacs'." - :group 'initialization - :link '(custom-manual "(use-package) Top") - :version "29.1") + :group 'startup) (defconst use-package-version "2.4.4" "This version of `use-package'.") @@ -100,7 +100,8 @@ :load ;; This must occur almost last; the only forms which should appear after ;; are those that must happen directly after the config forms. - :config) + :config + :local) "The set of valid keywords, in the order they are processed in. The order of this list is *very important*, so it is only advisable to insert new keywords, never to delete or reorder @@ -963,18 +964,10 @@ If RECURSED is non-nil, recurse into sublists." (defun use-package-autoloads-mode (_name _keyword args) (mapcar - #'(lambda (x) - (cond - ((consp (cdr x)) - (cons (cddr x) 'command)) - ((consp x) - (cons (cdr x) 'command)))) + #'(lambda (x) (cons (cdr x) 'command)) (cl-remove-if-not #'(lambda (x) - (or (and (consp x) - (use-package-non-nil-symbolp (cdr x))) - (and (consp x) - (consp (cdr x)) - (use-package-non-nil-symbolp (cddr x))))) + (and (consp x) + (use-package-non-nil-symbolp (cdr x)))) args))) (defun use-package-handle-mode (name alist args rest state) @@ -1305,7 +1298,10 @@ meaning: (setq every nil))) every)))) #'use-package-recognize-function - name label arg)))) + (if (string-suffix-p "-mode" (symbol-name name)) + name + (intern (concat (symbol-name name) "-mode"))) + label arg)))) (defalias 'use-package-autoloads/:hook 'use-package-autoloads-mode) @@ -1584,6 +1580,31 @@ no keyword implies `:all'." (when use-package-compute-statistics `((use-package-statistics-gather :config ',name t)))))) +;;;; :local + +(defun use-package-normalize/:local (name keyword args) + (let ((first-arg-name (symbol-name (caar args)))) + (if (not (string-suffix-p "-hook" first-arg-name)) + (let* ((sym-name (symbol-name name)) + (addition (if (string-suffix-p "-mode" sym-name) + "-hook" + "-mode-hook")) + (hook (intern (concat sym-name addition)))) + `((,hook . ,(use-package-normalize-forms name keyword args)))) + (cl-loop for (hook . code) in args + collect `(,hook . ,(use-package-normalize-forms name keyword code)))))) + +(defun use-package-handler/:local (name _keyword arg rest state) + (let* ((body (use-package-process-keywords name rest state))) + (use-package-concat + body + (cl-loop for (hook . code) in arg + for func-name = (intern (concat "use-package-func/" (symbol-name hook))) + collect (progn + (push 'progn code) + `(defun ,func-name () ,code)) + collect `(add-hook ',hook ',func-name))))) + ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;;; The main macro @@ -1614,8 +1635,8 @@ no keyword implies `:all'." (defmacro use-package (name &rest args) "Declare an Emacs package by specifying a group of configuration options. -For the full documentation, see Info node `(use-package) top'. -Usage: +For full documentation, please see the README file that came with +this file. Usage: (use-package package-name [:keyword [option]]...) @@ -1652,15 +1673,12 @@ 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/emacs.d/use-package/use-package-delight.el b/emacs.d/use-package/use-package-delight.el index 41978b9..c6abac9 100644 --- a/emacs.d/use-package/use-package-delight.el +++ b/emacs.d/use-package/use-package-delight.el @@ -5,28 +5,23 @@ ;; Author: John Wiegley ;; Maintainer: John Wiegley -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify +;; This program 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. -;; GNU Emacs is distributed in the hope that it will be useful, +;; This program 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 GNU Emacs. If not, see . +;; along with this program. If not, see . ;;; Commentary: -;; 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. +;; Provides support for the :delight keyword, which is made available by +;; default by requiring `use-package'. ;;; Code: diff --git a/emacs.d/use-package/use-package-diminish.el b/emacs.d/use-package/use-package-diminish.el index 7fff93b..9b8a09a 100644 --- a/emacs.d/use-package/use-package-diminish.el +++ b/emacs.d/use-package/use-package-diminish.el @@ -5,28 +5,23 @@ ;; Author: John Wiegley ;; Maintainer: John Wiegley -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify +;; This program 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. -;; GNU Emacs is distributed in the hope that it will be useful, +;; This program 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 GNU Emacs. If not, see . +;; along with this program. If not, see . ;;; Commentary: -;; 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. +;; Provides support for the :diminish keyword, which is made available by +;; default by requiring `use-package'. ;;; Code: diff --git a/emacs.d/use-package/use-package-ensure-system-package.el b/emacs.d/use-package/use-package-ensure-system-package.el index 6681e5a..9c9f079 100644 --- a/emacs.d/use-package/use-package-ensure-system-package.el +++ b/emacs.d/use-package/use-package-ensure-system-package.el @@ -9,29 +9,24 @@ ;; Package-Requires: ((use-package "2.1") (system-packages "1.0.4")) ;; Filename: use-package-ensure-system-package.el -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify +;; This program 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. -;; GNU Emacs is distributed in the hope that it will be useful, +;; This program 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 GNU Emacs. If not, see . +;; along with this program. If not, see . ;;; Commentary: - +;; ;; The `:ensure-system-package` keyword allows you to ensure system -;; binaries exist alongside your `use-package` declarations. Using it -;; requires the `system-packages' package to be installed (available -;; on GNU ELPA). +;; binaries exist alongside your `use-package` declarations. ;; -;; See the `use-package' info manual for more information. ;;; Code: @@ -42,10 +37,10 @@ (declare-function system-packages-get-command "system-packages")) (defvar use-package-ensure-system-package--custom-packages '() - "List of commands used to install custom packages.") + "List of custom packages installed.") (defun use-package-ensure-system-package-consify (arg) - "Turn ARG into a cons of the form (PACKAGE-NAME . INSTALL-COMMAND')." + "Turn ARG into a cons of (`package-name' . `install-command')." (cond ((stringp arg) (cons arg `(system-packages-install ,arg))) @@ -64,15 +59,13 @@ `(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 the form (PACKAGE-NAME . INSTALL-COMMAND)." + "Turn ARGS into a list of conses of (`package-name' . `install-command')." (use-package-as-one (symbol-name keyword) args (lambda (_label arg) (cond @@ -82,7 +75,7 @@ Run the same commands used for installing them." (list (use-package-ensure-system-package-consify arg))))))) (defun use-package-ensure-system-package-exists? (file-or-exe) - "If FILE-OR-EXE is a string, ensure the file path exists. + "If variable 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/emacs.d/use-package/use-package-ensure.el b/emacs.d/use-package/use-package-ensure.el index dae0312..c9cc6e7 100644 --- a/emacs.d/use-package/use-package-ensure.el +++ b/emacs.d/use-package/use-package-ensure.el @@ -5,27 +5,23 @@ ;; Author: John Wiegley ;; Maintainer: John Wiegley -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify +;; This program 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. -;; GNU Emacs is distributed in the hope that it will be useful, +;; This program 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 GNU Emacs. If not, see . +;; along with this program. If not, see . ;;; Commentary: -;; 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. +;; Provides support for the :ensure and :pin keywords, which is made available +;; by default by requiring `use-package'. ;;; Code: @@ -34,9 +30,7 @@ (defgroup use-package-ensure nil "Support for :ensure and :pin keywords in `use-package' declarations." - :group 'use-package - :link '(custom-manual "(use-package) Installing packages") - :version "29.1") + :group 'use-package) (eval-when-compile (declare-function package-installed-p "package") diff --git a/emacs.d/use-package/use-package-jump.el b/emacs.d/use-package/use-package-jump.el index 6fc52af..0c4cd20 100644 --- a/emacs.d/use-package/use-package-jump.el +++ b/emacs.d/use-package/use-package-jump.el @@ -5,29 +5,25 @@ ;; Author: John Wiegley ;; Maintainer: John Wiegley -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify +;; This program 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. -;; GNU Emacs is distributed in the hope that it will be useful, +;; This program 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 GNU Emacs. If not, see . +;; along with this program. If not, see . ;;; 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 autoloaded, it will not work. +;; initialization. If it was delay-loaded, it will not work. ;; Improvements are needed. -;; -;; See the `use-package' info manual for more information. ;;; Code: diff --git a/emacs.d/use-package/use-package-lint.el b/emacs.d/use-package/use-package-lint.el index 498213a..2092c0d 100644 --- a/emacs.d/use-package/use-package-lint.el +++ b/emacs.d/use-package/use-package-lint.el @@ -5,26 +5,22 @@ ;; Author: John Wiegley ;; Maintainer: John Wiegley -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify +;; This program 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. -;; GNU Emacs is distributed in the hope that it will be useful, +;; This program 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 GNU Emacs. If not, see . +;; along with this program. If not, see . ;;; Commentary: ;; Provides the command `M-x use-package-lint'. -;; -;; See the `use-package' info manual for more information. ;;; Code: diff --git a/emacs.d/use-package/use-package-tests.el b/emacs.d/use-package/use-package-tests.el index c5fc9fb..ac3dce2 100644 --- a/emacs.d/use-package/use-package-tests.el +++ b/emacs.d/use-package/use-package-tests.el @@ -1,21 +1,19 @@ ;;; use-package-tests.el --- Tests for use-package.el -*- lexical-binding: t; -*- -;; 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 +;; This program 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. -;; GNU Emacs is distributed in the hope that it will be useful, +;; This program 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 GNU Emacs. If not, see . +;; along with this program. If not, see . + +;;; Commentary: ;;; Code: @@ -575,7 +573,7 @@ (ert-deftest use-package-test/:bind-1 () (match-expansion - (use-package foo :bind ("C-k" . key1) ("C-u" ("Key 2" . key2))) + (use-package foo :bind ("C-k" . key1) ("C-u" . key2)) `(progn (unless (fboundp 'key1) @@ -585,11 +583,11 @@ (autoload #'key2 "foo" nil t)) (bind-keys :package foo ("C-k" . key1) - ("C-u" "Key 2" . key2))))) + ("C-u" . key2))))) (ert-deftest use-package-test/:bind-2 () (match-expansion - (use-package foo :bind (("C-k" . key1) ("C-u" ("Key 2" . key2)))) + (use-package foo :bind (("C-k" . key1) ("C-u" . key2))) `(progn (unless (fboundp 'key1) (autoload #'key1 "foo" nil t)) @@ -597,7 +595,7 @@ (autoload #'key2 "foo" nil t)) (bind-keys :package foo ("C-k" . key1) - ("C-u" "Key 2" . key2))))) + ("C-u" . key2))))) (ert-deftest use-package-test/:bind-3 () (match-expansion @@ -987,7 +985,7 @@ 'foopkg :hook args))) (should-error (norm nil)) (should (equal (norm '(bar)) - '((bar . foopkg)))) + '((bar . foopkg-mode)))) (should (equal (norm '((bar . foopkg))) '((bar . foopkg)))) (should (equal (norm '((bar . baz))) @@ -995,9 +993,9 @@ (should (equal (norm '(((bar baz) . quux))) '(((bar baz) . quux)))) (should (equal (norm '(bar baz)) - '(((bar baz) . foopkg)))) + '(((bar baz) . foopkg-mode)))) (should (equal (norm '((bar baz) (quux bow))) - '(((bar baz) . foopkg) ((quux bow) . foopkg)))) + '(((bar baz) . foopkg-mode) ((quux bow) . foopkg-mode)))) (should (equal (norm '((bar . baz) (quux . bow))) '((bar . baz) (quux . bow)))) (should (equal (norm '(((bar1 bar2) . baz) ((quux1 quux2) . bow))) @@ -1507,6 +1505,37 @@ (config) t)))))) +(ert-deftest use-package-test/pre-post-hooks-with-:config () + (let ((use-package-inject-hooks t)) + (match-expansion + (use-package foo :config (config)) + `(progn + (when + (run-hook-with-args-until-failure 'use-package--foo--pre-init-hook) + (run-hooks 'use-package--foo--post-init-hook)) + (require 'foo nil nil) + (when + (run-hook-with-args-until-failure 'use-package--foo--pre-config-hook) + (config) + (run-hooks 'use-package--foo--post-config-hook)) + t)))) + +(ert-deftest use-package-test/pre-post-hooks-without-:config () + ;; https://github.com/jwiegley/use-package/issues/785 + (let ((use-package-inject-hooks t)) + (match-expansion + (use-package foo) + `(progn + (when + (run-hook-with-args-until-failure 'use-package--foo--pre-init-hook) + (run-hooks 'use-package--foo--post-init-hook)) + (require 'foo nil nil) + (when + (run-hook-with-args-until-failure 'use-package--foo--pre-config-hook) + t + (run-hooks 'use-package--foo--post-config-hook)) + t)))) + (ert-deftest use-package-test-normalize/:diminish () (should (equal (use-package-normalize-diminish 'foopkg :diminish nil) '(foopkg-mode))) @@ -1926,9 +1955,9 @@ (use-package nonexistent :hook lisp-mode) `(when (locate-library nonexistent) - (unless (fboundp 'nonexistent) - (autoload #'nonexistent "nonexistent" nil t)) - (add-hook 'lisp-mode-hook #'nonexistent))))) + (unless (fboundp 'nonexistent-mode) + (autoload #'nonexistent-mode "nonexistent" nil t)) + (add-hook 'lisp-mode-hook #'nonexistent-mode))))) (ert-deftest bind-key/:prefix-map () (match-expansion diff --git a/emacs.d/use-package/use-package.el b/emacs.d/use-package/use-package.el index 0929696..bafa093 100644 --- a/emacs.d/use-package/use-package.el +++ b/emacs.d/use-package/use-package.el @@ -10,31 +10,29 @@ ;; Keywords: dotemacs startup speed config package extensions ;; URL: https://github.com/jwiegley/use-package -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify +;; This program 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. -;; GNU Emacs is distributed in the hope that it will be useful, +;; This program 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 GNU Emacs. If not, see . +;; along with this program. If not, see . ;;; Commentary: ;; The `use-package' declaration macro allows you to isolate package -;; 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! +;; 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! ;; -;; See the `use-package' info manual for more information. +;; Please see README.md from the same repository for documentation. ;;; Code: diff --git a/emacs.d/use-package/use-package.texi b/emacs.d/use-package/use-package.texi index b1d7b10..573baac 100644 --- a/emacs.d/use-package/use-package.texi +++ b/emacs.d/use-package/use-package.texi @@ -1,32 +1,29 @@ \input texinfo @c -*- texinfo -*- @c %**start of header -@setfilename ../../use-package.info +@setfilename use-package.info @settitle use-package User Manual -@include docstyle.texi -@syncodeindex vr cp -@syncodeindex fn cp +@documentencoding UTF-8 +@documentlanguage en @c %**end of header @copying -This manual is for use-package, a configuration macro for simplifying -your init file. +@quotation +Copyright (C) 2012-2022 Free Software Foundation, Inc. -Copyright @copyright{} 2022 Free Software Foundation, Inc. +You can redistribute this document and/or modify it under the terms +of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any +later version. + +This document is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU +General Public License for more details. -@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 misc features +@dircategory Emacs @direntry * use-package: (use-package). Declarative package configuration for Emacs. @end direntry @@ -34,8 +31,8 @@ modify this GNU manual.'' @finalout @titlepage @title use-package User Manual -@subtitle for version 2.4.5 -@author John Wiegley & Stefan Kangas +@subtitle for version 2.4.1-119-g0be480e+1 +@author John Wiegley @page @vskip 0pt plus 1filll @insertcopying @@ -47,750 +44,353 @@ modify this GNU manual.'' @node Top @top use-package User Manual -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. +The @code{use-package} macro allows you to isolate package configuration in your +@code{.emacs} file in a way that is both performance-oriented and, well, tidy. I +created it because I have over 80 packages that I use in Emacs, and things +were getting difficult to manage. Yet with this utility my total load time is +around 2 seconds, with no loss of functionality! @insertcopying +@end ifnottex @menu -* 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:: +* Introduction:: +* Installation:: +* Getting Started:: +* Basic Concepts:: +* Issues/Requests:: +* Keywords:: +* Debugging Tools:: + +@detailmenu +--- The Detailed Node Listing --- + +Installation + +* Installing from GNU ELPA:: +* Installing from the Git Repository:: +* Post-Installation Tasks:: + +Keywords + +* @code{after}:: @code{:after}. +* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap}, @code{:bind-keymap*}. +* @code{bind} @code{bind*}:: @code{:bind}, @code{:bind*}. +* @code{commands}:: @code{:commands}. +* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init}, @code{:config}. +* @code{custom}:: @code{:custom}. +* @code{custom-face}:: @code{:custom-face}. +* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}. +* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}. +* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}. +* @code{disabled}:: @code{:disabled}. +* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}. +* @code{hook}:: @code{:hook}. +* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when}, @code{:unless}. +* @code{load-path}:: @code{:load-path}. +* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}. +* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}. +* @code{no-require}:: @code{:no-require}. +* @code{requires}:: @code{:requires}. + +@code{bind}, @code{bind*} + +* Binding to local keymaps:: + + +@end detailmenu @end menu -@end ifnottex - -@c ---------------------------------------------------------------------------- -@node Basic Concepts -@chapter Basic Concepts - -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: -@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. +@node Introduction +@chapter Introduction -@item -To reduce duplication and boilerplate, capturing several common -practices as mere keywords both easy and intuitive to use. +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! -@item -To make startup time of Emacs as quick as possible, without -sacrificing the quantity of add-on packages used. +More text to come@dots{} -@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. +@node Installation +@chapter Installation -@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 +use-package can be installed using Emacs' package manager or manually from +its development repository. -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. +@menu +* Installing from GNU ELPA:: +* Installing from the Git Repository:: +* Post-Installation Tasks:: +@end menu -@c ---------------------------------------------------------------------------- -@node Getting Started -@chapter Getting Started +@node Installing from GNU ELPA +@section Installing from GNU ELPA -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: +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}: -@lisp -(require 'use-package) -@end lisp +First, you need to update the local package list using: -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. +@example +M-x package-refresh-contents RET +@end example -To unconditionally load a package named @samp{foo}, add the following -declaration to your init file: +Once you have done that, you can install use-package and its +dependencies using: -@lisp -(use-package foo) -@end lisp +@example +M-x package-install RET use-package RET +@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}). +Now see @ref{Post-Installation Tasks}. -To evaluate Lisp code @emph{before} the @samp{foo} package is loaded, -use the @code{:init} keyword: +@node Installing from the Git Repository +@section Installing from the Git Repository -@lisp -(use-package foo - :init - (setq foo-variable t)) -@end lisp +First, use Git to clone the use-package repository: -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 +$ git clone https://github.com/jwiegley/use-package.git ~/.emacs.d/site-lisp/use-package +$ cd ~/.emacs.d/site-lisp/use-package +@end example -@lisp -(use-package foo - :init - (setq foo-variable t) - :config - (foo-mode 1)) -@end lisp +Then compile the libraries and generate the info manuals: -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: +@example +$ make +@end example -@lisp -(use-package foo - :defer t) -@end lisp +You may need to create @code{/path/to/use-package/config.mk} with the following +content before running @code{make}: -@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. +@example +LOAD_PATH = -L /path/to/use-package +@end example -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. +Finally add this to your init file: @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 - -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. - -That should be enough to get you started! - -@c ---------------------------------------------------------------------------- -@node Loading Packages -@chapter Loading Packages - -@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. - -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. - -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. - -use-package can interface with @samp{package.el} to install packages -on Emacs start. @xref{Installing packages} for details. - -@menu -* Loading basics:: How and when packages are loaded. -* Deferring loading:: Loading packages later. -* Forcing loading:: Loading packages immediately. -* Conditional loading:: Loading packages conditionally. -* Loading sequentially:: Loading packages in sequence. -* Load dependencies:: Don't load without dependencies. -* Load path:: Using a custom @code{load-path}. -* Manual autoloads:: Setting up autoloads manually. -@end menu - -@node Loading basics -@section How and when use-package loads packages - -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. - -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: +(add-to-list 'load-path "~/.emacs.d/site-lisp/use-package") +(require 'use-package) -@lisp -(use-package foo) +(with-eval-after-load 'info + (info-initialize) + (add-to-list 'Info-directory-list + "~/.emacs.d/site-lisp/use-package/")) @end lisp -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}: +Note that elements of @code{load-path} should not end with a slash, while those of +@code{Info-directory-list} should. -@lisp -(use-package foo - :defer t) -@end lisp +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. -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}). +To update use-package use: -@subheading Defer loading until idle for N seconds +@example +$ git pull +$ make +@end example -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: +At times it might be necessary to run @code{make clean all} instead. -@lisp -(use-package foo - :defer 30) -@end lisp +To view all available targets use @code{make help}. -@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: +Now see @ref{Post-Installation Tasks}. -@lisp -(use-package foo - :if (display-graphic-p)) -@end lisp +@node Post-Installation Tasks +@section Post-Installation Tasks -@subheading Some common use cases +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}. -Here are some common cases for conditional loading, and how to achieve -them. +@example +C-h v use-package-version RET +@end example -@itemize +should display something like -@item Operating system +@example +use-package-version’s value is "2.4.3" +@end example -This example loads a package only on GNU/Linux. See the -@code{system-type} docstring for other valid values. +If you are completely new to use-package then see @ref{Getting Started}. -@lisp -:if (eq system-type 'gnu/linux) -@end lisp +If you run into problems, then please see the @ref{Debugging Tools}. -@item Window system +@node Getting Started +@chapter Getting Started -This example loads a package only on macOS and X. See the -@code{window-system} docstring for valid values. +TODO@. For now, see @code{README.md}. -@lisp -:if (memq window-system '(ns x)) -@end lisp +@node Basic Concepts +@chapter Basic Concepts -@item Installed package +@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: -This example loads a package only when the @samp{foo} package is -installed. +@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. -@lisp -:if (package-installed-p 'foo) -@end lisp +@item +To reduce duplication and boilerplate, capturing several common +practices as mere keywords both easy and intuitive to use. -@item Libraries in @code{load-path} +@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 when @file{foo.el} is available in -your @code{load-path} (for example, if you installed that file -manually): +@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 (locate-library "foo.el") -@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 -@subheading Making conditional loading affect @code{:preface} and @code{:ensure} - -@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: +@node Issues/Requests +@chapter Issues/Requests -@lisp -(when (memq window-system '(mac ns)) - (use-package foo - :ensure t)) -@end lisp +@node Keywords +@chapter Keywords -@node Loading sequentially -@section Loading packages in sequence +@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 -@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). +@node @code{after} +@section @code{:after} -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: +Sometimes it only makes sense to configure a package after another has been +loaded, because certain variables or functions are not in scope until that +time. This can achieved using an @code{:after} keyword that allows a fairly rich +description of the exact conditions when loading should occur. Here is an +example: @lisp -(use-package hydra) +(use-package hydra + :load-path "site-lisp/hydra") -(use-package ivy) +(use-package ivy + :load-path "site-lisp/swiper") (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 +In this case, because all of these packages are demand-loaded in the order +they occur, the use of @code{:after} is not strictly necessary. By using it, +however, the above code becomes order-independent, without an implicit +depedence on the nature of your init file. + +By default, @code{:after (foo bar)} is the same as @code{:after (:all foo bar)}, meaning +that loading of the given package will not happen until both @code{foo} and @code{bar} +have been loaded. Here are some of the other possibilities: + +@lisp :after (foo bar) :after (:all foo bar) :after (:any foo bar) :after (:all (:any foo bar) (:any baz quux)) :after (:any (:all foo bar) (:all baz quux)) -@end 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 -As a convenience, a list of such packages may be specified: +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. -@lisp -(use-package abbrev - :requires (foo bar baz)) -@end lisp +@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. -For more complex logic, such as that supported by @code{:after}, -simply use @code{:if} and the appropriate Lisp expression. +@node @code{bind-keymap} @code{bind-keymap*} +@section @code{:bind-keymap}, @code{:bind-keymap*} -@node Load path -@section Setting a custom @code{load-path} +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. -@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}. +To handle this case, @code{use-package} offers a special, limited variant of +@code{:bind} called @code{:bind-keymap}. The only difference is that the "commands" +bound to by @code{:bind-keymap} must be keymaps defined in the package, rather than +command functions. This is handled behind the scenes by generating custom code +that loads the package containing the keymap, and then re-executes your +keypress after the first load, to reinterpret that keypress as a prefix key. For example: @lisp -(use-package 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 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. - -The @code{:autoload} keyword works like @code{:commands}, but is used -to autoload non-interactive functions. Here is an example: - -@lisp -(use-package org-crypt - :autoload org-crypt-use-before-save-magic) -@end lisp - -@c ---------------------------------------------------------------------------- -@node Configuring Packages -@chapter Configuring Packages - -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 foo - :init - (add-hook 'some-hook 'foo-mode)) -@end lisp - -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}: - -@lisp -(use-package foo - :defer t - :init - (add-hook 'some-hook 'foo-mode)) +(use-package projectile + :bind-keymap + ("C-c p" . projectile-command-map) @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). +@node @code{bind} @code{bind*} +@section @code{:bind}, @code{:bind*} -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: +Another common thing to do when loading a module is to bind a key to primary +commands within that module: @lisp -(use-package foo - :hook some-hook) +(use-package ace-jump-mode + :bind ("C-." . ace-jump-mode)) @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 as its argument -either a single cons or a list of conses. Each cons has the form -@w{@code{(@var{key} . @var{definition})}}, where @var{key} is a string -indicating the key to bind, and @var{definition} is the name of a -command (a symbol). Alternatively, @var{definition} may be a cons -@w{@code{(@var{desc} . @var{command})}}, where @var{desc} is a string -describing @var{command}, which is the name of a command to bind -@var{key} to. The syntax for the keys is similar to the syntax used -by the @code{kbd} function (see @ref{Init Rebinding,,, emacs, GNU -Emacs Manual}, for more information). +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. -@subheading Using @code{:bind} with a single cons - -Here is an example of using a single cons: +A more literal way to do the exact same thing is: @lisp (use-package ace-jump-mode - :bind ("C-." . ace-jump-mode)) + :commands ace-jump-mode + :init + (bind-key "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 +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. -Here is an example of using @code{:bind} with a list of conses: +The @code{:bind} keyword takes either a cons or a list of conses: @lisp (use-package hi-lock @@ -799,12 +399,11 @@ Here is an example of using @code{:bind} with a list of conses: ("M-o w" . highlight-phrase))) @end lisp -@subheading Using special keys +The @code{:commands} keyword likewise takes either a symbol or a list of symbols. -Inside key strings, special keys like @kbd{TAB} or @kbd{F1}--@kbd{F12} -have to be written inside angle brackets, e.g. @code{"C-"}. -Standalone special keys (and some combinations) can be written in -square brackets, e.g.@ @code{[tab]} instead of @code{""}. +NOTE: Special keys like @code{tab} or @code{F1}-@code{Fn} can be written in square brackets, +i.e. @code{[tab]} instead of @code{"tab"}. The syntax for the keybindings is similar to +the "kbd" syntax: see @uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html, the Emacs Manual} for more information. Examples: @@ -816,84 +415,16 @@ Examples: ([S-f10] . helm-recentf))) @end lisp -@subheading Providing custom descriptions of commands - -When binding keys to commands with @code{:bind}, custom descriptions -of the commands may optionally be provided. - -Examples: - -@lisp -@group -(use-package avy - :bind ("C-:" ("Jump to char" . avy-goto-char) - "M-g f" ("Jump to line" . avy-goto-line))) -@end group -@end lisp - -@noindent -These descriptions can be used by other code that deals with key -bindings. For example, the @acronym{GNU} @acronym{ELPA} package -@file{which-key} displays them when showing key bindings, instead of -the plain command names. - -@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. - -@lisp -(use-package ace-jump-mode - :commands ace-jump-mode - :init - (bind-key "C-." 'ace-jump-mode)) -@end lisp - -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. +@menu +* Binding to local keymaps:: +@end menu -@node Binding in keymaps -@subsection Key bindings in local keymaps +@node Binding to local keymaps +@subsection Binding to 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: +Slightly different from binding a key to a keymap, is binding a key @strong{within} a +local keymap that only exists after the package is loaded. @code{use-package} +supports this with a @code{:map} modifier, taking the local keymap to bind to: @lisp (use-package helm @@ -901,13 +432,12 @@ 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-command-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-mode-map}. -Multiple uses of @code{:map} may be specified. Any binding occurring -before the first use of @code{:map} are applied to the global keymap: +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 @@ -921,429 +451,184 @@ before the first use of @code{:map} are applied to the global keymap: ("M-n" . term-send-down))) @end lisp -@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{commands} +@section @code{:commands} -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. +@node @code{preface} @code{init} @code{config} +@section @code{:preface}, @code{:init}, @code{:config} -For example: +Here is the simplest @code{use-package} declaration: @lisp -(use-package foo - :bind-keymap ("C-c p" . foo-command-map)) -@end lisp - -@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. +;; 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 "") + (require 'use-package)) -@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 - -@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: - -@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 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 - -@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 company - :commands company-mode - :init - (add-hook 'prog-mode-hook #'company-mode)) -@end lisp - -Using @code{:hook}, this can be simplified to: - -@lisp -(use-package company - :hook (prog-mode . company-mode)) +(use-package foo) @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 +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. -@cindex multiple hooks -You can also provide a list of hooks. When multiple hooks should be -applied, the following examples are all equivalent: +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 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 +(use-package foo :init - (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)) + (setq foo-variable t)) @end lisp -Both the @code{:mode} and @code{:interpreter} keywords also accept a -list of regexps: +Similarly, @code{:config} can be used to execute code after a package is loaded. +In cases where loading is done lazily (see more about autoloading below), this +execution is deferred until after the autoload occurs: @lisp (use-package foo - ;; Equivalent to "\\(ba[rz]\\)\\'": - :mode ("\\.bar\\'" "\\.baz\\'") - ;; Equivalent to "\\(foo[ab]\\)": - :interpreter ("fooa" "foob")) + :init + (setq foo-variable t) + :config + (foo-mode 1)) @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: +As you might expect, you can use @code{:init} and @code{:config} together: @lisp -(use-package pdf-tools - :magic ("%PDF" . pdf-view-mode) +(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 - (pdf-tools-install :no-query)) + (use-package moccur-edit)) @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"}. +In this case, I want to autoload the commands @code{isearch-moccur} and +@code{isearch-all} from @code{color-moccur.el}, and bind keys both at the global level +and within the @code{isearch-mode-map} (see next section). When the package is +actually loaded (by using one of these commands), @code{moccur-edit} is also +loaded, to allow editing of the @code{moccur} buffer. -@node User options -@section User options +@node @code{custom} +@section @code{:custom} -@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. +The @code{:custom} keyword allows customization of package custom variables. @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 -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. - -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 documentation string is not mandatory. -@node Faces -@section Faces +@node @code{custom-face} +@section @code{:custom-face} -@findex :custom-face -The @code{:custom-face} keyword allows customization of package custom -faces. +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 Hiding minor modes -@section Hiding minor modes with diminish and delight +@node @code{defer} @code{demand} +@section @code{:defer}, @code{:demand} -@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}. +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. -@menu -* Diminish:: Hiding minor modes with Diminish. -* Delight:: Hiding minor modes with Delight. -@end menu +You can override package deferral with the @code{:demand} keyword. Thus, even if +you use @code{:bind}, using @code{:demand} will force loading to occur immediately and +not establish an autoload for the bound key. -@node Diminish -@subsection Diminish +@node @code{defines} @code{functions} +@section @code{:defines}, @code{: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. +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. -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}). +However, there are times when this is just not enough. For those times, use +the @code{:defines} and @code{:functions} keywords to introduce dummy variable and +function declarations solely for the sake of the byte-compiler: @lisp -(use-package diminish :ensure t) +(use-package texinfo + :defines texinfo-section-list + :commands texinfo-mode + :init + (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode))) @end lisp -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: +If you need to silence a missing function warning, you can use @code{:functions}: @lisp -(use-package abbrev - :diminish abbrev-mode +(use-package ruby-mode + :mode "\\.rb\\'" + :interpreter "ruby" + :functions inf-ruby-keys :config - (if (file-exists-p abbrev-file-name) - (quietly-read-abbrev-file))) + (defun my-ruby-mode-hook () + (require 'inf-ruby) + (inf-ruby-keys)) + + (add-hook 'ruby-mode-hook 'my-ruby-mode-hook)) @end lisp -@node Delight -@subsection Delight +@node @code{diminish} @code{delight} +@section @code{:diminish}, @code{:delight} -@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. +@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. -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}). +@uref{https://github.com/myrjola/diminish.el, diminish} is invoked with the @code{:diminish} keyword, which is passed either a +minor mode symbol, a cons of the symbol and its replacement string, or just a +replacement string, in which case the minor mode symbol is guessed to be the +package name with "-mode" appended at the end: @lisp -(use-package delight :ensure t) +(use-package abbrev + :diminish abbrev-mode + :config + (if (file-exists-p abbrev-file-name) + (quietly-read-abbrev-file))) @end lisp -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: +@uref{https://elpa.gnu.org/packages/delight.html, delight} is invoked with the @code{:delight} keyword, which is passed a minor mode +symbol, a replacement string or quoted @uref{https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Data.html, mode-line data} (in which case the minor +mode symbol is guessed to be the package name with "-mode" appended at the +end), both of these, or several lists of both. If no arguments are provided, +the default mode name is hidden completely. @lisp -(use-package foo +;; Don't show anything for rainbow-mode. +(use-package rainbow-mode :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 -You can also run arbitrary Lisp code. For example, to replace -@samp{foo-mode} with the value of the current buffer: +;; Remove the mode name for projectile-mode, but show the project name. +(use-package projectile + :delight '(:eval (concat " " (projectile-project-name)))) -@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 @@ -1351,32 +636,30 @@ Here is an example of hiding several built-in minor modes: (visual-line-mode)) @end lisp -@c ---------------------------------------------------------------------------- -@node Installing packages -@chapter Installing packages automatically +@node @code{disabled} +@section @code{:disabled} -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. +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: -@menu -* Install package:: -* Pinning packages:: -* Other package managers:: -@end menu +@lisp +(use-package ess-site + :disabled + :commands R) +@end lisp -@node Install package -@section Installing package +When byte-compiling your @code{.emacs} file, disabled declarations are omitted +from the output entirely, to accelerate startup times. -@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. +@node @code{ensure} @code{pin} +@section @code{:ensure}, @code{:pin} -For example: +You can use @code{use-package} to load packages from ELPA with @code{package.el}. This +is particularly useful if you share your @code{.emacs} among several machines; the +relevant packages are downloaded automatically once declared in your @code{.emacs}. +The @code{:ensure} keyword causes the package(s) to be installed automatically if +not already present on your system (set @code{(setq use-package-always-ensure t)} +if you wish this behavior to be global for all packages): @lisp (use-package magit @@ -1384,520 +667,280 @@ For example: @end lisp If you need to install a different package from the one named by -@code{use-package}, you can use a symbol: +@code{use-package}, you can specify it like this: @lisp (use-package tex :ensure auctex) @end lisp -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. +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. -@lisp -(require 'use-package-ensure) -(setq use-package-always-ensure t) -@end lisp +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. -@noindent -You can override the above setting for a single package by adding -@w{@code{:ensure nil}} to its declaration. +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). -@node Pinning packages -@section Pinning packages using @code{:pin} +@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): -@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 +Archive 'foo' requested for package 'bar' is not available. +@end example -For example: +Example: @lisp (use-package company :ensure t - :pin gnu) ; GNU ELPA -@end lisp + :pin melpa-stable) -@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 evil + :ensure t) + ;; no :pin needed, as package.el will choose the version in melpa -Example: +(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) -@lisp (use-package org :ensure t ;; ignore org-mode from upstream and use a manually installed version :pin manual) @end lisp -@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: +@strong{NOTE}: the @code{:pin} argument has no effect on emacs versions < 24.4. -@lisp -(use-package texinfo - :defines texinfo-section-list - :commands texinfo-mode - :init - (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode))) -@end lisp +@node @code{hook} +@section @code{:hook} -If you need to silence a missing function warning, you can use -@code{:functions}: +The @code{:hook} keyword allows adding functions onto hooks, here only the basename +of the hook is required. Thus, all of the following are equivalent: @lisp -(use-package 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 + :hook prog-mode) - (add-hook 'ruby-mode-hook 'my-ruby-mode-hook)) +(use-package ace-jump-mode + :hook (prog-mode . ace-jump-mode)) + +(use-package ace-jump-mode + :commands ace-jump-mode + :init + (add-hook 'prog-mode-hook #'ace-jump-mode)) @end lisp -@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: +And likewise, when multiple hooks should be applied, the following are also +equivalent: @lisp -(use-package foo - :no-require t - :config - (message "Evaluate this immediately after loading `foo'")) -@end lisp - -@c ---------------------------------------------------------------------------- -@node Troubleshooting -@chapter Troubleshooting +(use-package ace-jump-mode + :hook (prog-mode text-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 + :hook ((prog-mode text-mode) . ace-jump-mode)) -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): +(use-package ace-jump-mode + :hook ((prog-mode . ace-jump-mode) + (text-mode . ace-jump-mode))) -@lisp -(when init-file-debug - (setq use-package-verbose t - use-package-expand-minimally nil - use-package-compute-statistics t - debug-on-error t)) +(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 -@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. +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}. -@menu -* Troubleshooting Options:: -* Gathering Statistics:: -* Disabling a package:: -@end menu +@node @code{if} @code{when} @code{unless} +@section @code{:if}, @code{:when}, @code{:unless} -@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: +You can use the @code{:if} keyword to predicate the loading and initialization of +modules. + +For example, I only want @code{edit-server} running for my main, graphical Emacs, +not for other Emacsen I may start at the command line: @lisp -(use-package 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)))) +(use-package edit-server + :if window-system + :init + (add-hook 'after-init-hook 'server-start t) + (add-hook 'after-init-hook 'edit-server-start t)) @end lisp -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: +In another example, we can load things conditional on the operating system: @lisp -(use-package foo - :disabled) +(use-package exec-path-from-shell + :if (memq window-system '(mac ns)) + :ensure t + :config + (exec-path-from-shell-initialize)) @end lisp -When byte-compiling your init file, use-package omits disabled -declarations from the output entirely, in order to make Emacs startup -faster. - -@c ---------------------------------------------------------------------------- -@node Keyword extensions -@appendix Keyword extensions +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)}. -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. +@node @code{load-path} +@section @code{:load-path} -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}: +If your package needs a directory added to the @code{load-path} in order to load, +use @code{:load-path}. This takes a symbol, a function, a string or a list of +strings. If the path is relative, it is expanded within +@code{user-emacs-directory}: @lisp -(use-package use-package-ensure-system-package) +(use-package ess-site + :load-path "site-lisp/ess/lisp/" + :commands R) @end lisp -Now you can use the @code{:ensure-system-package} keyword. -Here's an example usage: +Note that when using a symbol or a function to provide a dynamically generated +list of paths, you must inform the byte-compiler of this definition so the +value is available at byte-compilation time. This is done by using the special +form @code{eval-and-compile} (as opposed to @code{eval-when-compile}). Further, this +value is fixed at whatever was determined during compilation, to avoid looking +up the same information again on each startup: @lisp -(use-package foo - :ensure-system-package foo) -@end lisp - -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. - -One way of making sure it is installed is with @code{use-package} -together with @code{:ensure}. +(eval-and-compile + (defun ess-site-load-path () + (shell-command "find ~ -path ess/lisp"))) -@lisp -(use-package system-packages - :ensure t) +(use-package ess-site + :load-path (lambda () (list (ess-site-load-path))) + :commands R) @end lisp -For example, on a @code{Debian GNU/Linux} system, this would call -@samp{apt-get install foo}. +@node @code{mode} @code{interpreter} +@section @code{:mode}, @code{:interpreter} -If the package is named differently than the binary, you can use a -cons in the form of @code{(binary . package-name)}. For example: +Similar to @code{:bind}, you can use @code{:mode} and @code{:interpreter} to establish a +deferred binding within the @code{auto-mode-alist} and @code{interpreter-mode-alist} +variables. The specifier to either keyword can be a cons cell, a list of cons +cells, or a string or regexp: @lisp -(use-package foo - :ensure-system-package - (foocmd . foo)) -@end lisp - -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. +(use-package ruby-mode + :mode "\\.rb\\'" + :interpreter "ruby") -@lisp -(use-package tern - :ensure-system-package (tern . "npm i -g tern")) +;; The package is "python" but the mode is "python-mode": +(use-package python + :mode ("\\.py\\'" . python-mode) + :interpreter ("python" . python-mode)) @end lisp -To install several packages, you can pass in a list of conses: +If you aren't using @code{:commands}, @code{:bind}, @code{:bind*}, @code{:bind-keymap}, +@code{:bind-keymap*}, @code{:mode}, or @code{:interpreter} (all of which imply @code{:defer}; see +the docstring for @code{use-package} for a brief description of each), you can +still defer loading with the @code{:defer} keyword: @lisp -(use-package 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"))) +(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 -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: +This does exactly the same thing as the following: @lisp -(use-package dash-at-point - :if (eq system-type 'darwin) - :ensure-system-package - ("/Applications/Dash.app" . "brew cask install dash")) +(use-package ace-jump-mode + :bind ("C-." . ace-jump-mode)) @end lisp -@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{magic} @code{magic-fallback} +@section @code{:magic}, @code{:magic-fallback} -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. +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: -@node Creating an extension -@section How to create an extension keyword - -This section describes how to create a new keyword. - -@enumerate -@item -Add the keyword. - -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. +@lisp +(use-package pdf-tools + :load-path "site-lisp/pdf-tools/lisp" + :magic ("%PDF" . pdf-view-mode) + :config + (pdf-tools-install)) +@end lisp -@item -Create a normalizer. +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"}. -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}. +@node @code{no-require} +@section @code{:no-require} -Define a normalizer for your keyword by defining a function named -after the keyword, for example: +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 -(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)")))))) +(use-package foo + :no-require t + :config + (message "This is evaluated when `foo' is loaded")) @end lisp -@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. +@node @code{requires} +@section @code{:requires} -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: +While the @code{:after} keyword delays loading until the dependencies are loaded, +the somewhat simpler @code{:requires} keyword simply never loads the package if the +dependencies are not available at the time the @code{use-package} declaration is +encountered. By "available" in this context it means that @code{foo} is available +of @code{(featurep 'foo)} evaluates to a non-nil value. For example: @lisp -(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)))))) +(use-package abbrev + :requires foo) @end lisp -@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 +This is the same as: -@c ---------------------------------------------------------------------------- -@node History -@appendix History and acknowledgments +@lisp +(use-package abbrev + :if (featurep 'foo)) +@end lisp -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. +As a convenience, a list of such packages may be specified: -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. +@lisp +(use-package abbrev + :requires (foo bar baz)) +@end lisp -This Texinfo manual was written by Stefan Kangas, as a significant -rewrite of the old use-package manual and @file{README}. +For more complex logic, such as that supported by @code{:after}, simply use @code{:if} +and the appropriate Lisp expression. -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi +@node Debugging Tools +@chapter Debugging Tools -@node Index -@unnumbered Index -@printindex cp +TODO @bye