# Changes ## 2.4.4 This release prepares for inclusion to GNU ELPA and includes no other changes ## 2.4.1 This is mostly a bug-fix release: - Update the documentation for :custom as per #850 - Fix broken test due to #850 - better tests - add test for #845 - Support keymap symbol in bind-key. Fix #845 - use-package-core.el: use the Emacs set-default function to avoid saving :custom vars twice - Fix Travis - typo, should be a vector, not a bytecode object Solves https://github.com/jwiegley/use-package/issues/842 - Add special value back again, in case needed for backwards compat I don't know why this special value exists, but perhaps old client code uses it. The additional `t' in the macro expansion is accidental but not harmful I guess. - Even when there's no :config, run any pre/post config hooks i.e., following the existing docs for use-package-inject-hooks, these hooks are run: use-package--foo--pre-config-hook use-package--foo--post-config-hook This should make config customisations more predictable (for example, spacemacs uses these hooks extensively to allow 'layers' to be customised). I got rid of the "special" default value for :config, because it doesn't seem to be treated any differently than nil. Fixes #785 - Clarify the documentation for :after - add table of contents to README - Fix typos Typos found with codespell. - Fix typos - Attempt to explain omit "-hook" better - Update tests - Switch from `require' to `load' + `featurep' - Use `require', not `load', when byte-compiling - Make custom-face evaluate elisp. Fix #696. - Add a line of documentation for (use-pacakage ... :hook). - Fix typo in README - Fix documentation for defer - Add no-query option for pdf-tools-install - Fix typo in README - Fix all notes in README - Mention use-package-ensure in README Without requiring `use-package-ensure`, setting `use-package-always-ensure` did not actually work for me. ## 2.4 ### Breaking changes - `use-package` no longer requires `diminish` as a dependency, allowing people to decide whether they want to use diminish or delight. This means that if you do use diminish, you'll now need to pull it into your configuration before any use of the `:diminish` kewyord. For example: ``` elisp (use-package diminish :ensure t) ``` - Emacs 24.3 or higher is now a requirement. - The `:defer-install` keyword has been removed. It may reappear as an add-on module for use-package in a future release. See issue #442 for more details. - There is no longer a `use-package-debug` option, since `use-package-verbose` already has the possible value of `debug`. - The ordering of several elements of `use-package-keywords` have changed; if you had previously customized this (or were an extension author adding to this list), you may need to rework your changes. - For extension authors, `:commands` should no longer be propagated down for autoloading. See more below. ### Other changes - Upgrade license to GPL 3. - If `use-package-verbose` is set to the symbol `debug`, any evaluation errors during package configuration will cause a complete report to be written to a `*use-package*` buffer, including: the text of the error, the `use-package` declaration that caused the error, the post-normalized form of this declaration, and the macro-expanded version (without verbosity-related code). Note that this still does not help if there are parsing errors, which cause Emacs to register a Lisp error at startup time. - New customization variable `use-package-deferring-keywords`, mainly intended for use by extension packages, indicates keywords that, if used without `:demand`, cause deferred loading (as if `:defer t` had been specified). - The `:ensure` keyword now accepts a specific pinning sub-keyword. For example: ``` elisp (use-package foo :pin "elpa") ``` This ensure the package `foo` is installed from `"elpa"`. ``` elisp (use-package foo :ensure bar :ensure (quux :pin "melpa")) ``` This says that `foo` ensures that `bar` is installed, as well as `quux` from `"melpa"`. It does *not* ensure that `foo` is installed, because explicit `:ensure` keywords were given. - New `:hook` keyword. - New `:catch` keyword. If `t` or `nil`, it enables (the default, see `use-package-defaults`) or disables catching errors at load time in use-package expansions. It can also be a function taking two arguments: the keyword being processed at the time the error was encountered, and the error object (as generated by `condition-case`). - New keywords `:custom (foo1 bar1) (foo2 bar2)` etc., and `:custom-face`. NOTE: These are only for people who wish to keep customizations with their accompanying use-package declarations. Functionally, the only benefit over using `setq` in a `:config` block is that customizations might execute code when values are assigned. If you currently use `M-x customize-option` and save to a settings file, you do not want to use this option. - New `:magic` and `:magic-fallback` keywords. - New `:defer-install` keyword. - New customization variable `use-package-enable-imenu-support`. - New customization variable `use-package-hook-name-suffix`. Any symbols named in `:hook`, or in the CAR of cons cells passed to `:hook`, have this text appended to them as a convenience. If you find yourself using this keyword to add to hooks of different names, or just don't want such appending done, you can change the text to an empty string. - New customization variable `use-package-compute-statistics`, and an accompanying command `M-x use-package-report`. See the README for more details. - Allow `:diminish` to take no arguments. - Support multiple symbols passed to `:after`, and a mini-DSL using `:all` and `:any`. - `:mode` and `:interpreter` can now accept `(rx ...)` forms. - Using `:load-path` without also using `:ensure` now implies `:ensure nil`. - `:bind (:map foo-map ...)` now defers binding in the map until the package has been loaded. - Print key bindings for keymaps in `describe-personal-keybindings`. - When `use-package-inject-hooks` is non-nil, always fire `:init` and `:config` hooks. - Documentation added for the `:after`, `:defer-install`, `:delight`, `:requires`, `:when` and `:unless` keywords. - `:requires SYM` is subtly different from `:if (featurep SYM)`, in that it happens before the `:preface`. This means that using `:requires` will cause definitions in the `:preface` to not be visible to the byte-compiler, leading to possible warnings about unknown functions, or functions that may not be available at run-time (which can generally be ignored, since `:requires` is intended as a check for basic system functionality; `:after` should be used to check for the presence of other modules). - New undocumented (and currently experimental) keyword `:load` may be used to change the name of the actual package loaded, rather than the package name, and may even add other names. For example: `(use-package auctex :load tex-site)`. This keyword is used internally to generate the `require` for a package, so that deferral is simply a matter of not generating this keyword. - The source code is now broken into several files, so that certain optional features (diminish, delight, ensure) may be maintained separately from the core functionality. - When using the `:after` keyword, now even autoloadeds keybinding are deferred until after that other package has loaded, in order to allow convenient `:bind` to maps only present in that other package. Consider the following: ``` elisp (use-package helm-descbinds :load-path "site-lisp/helm-descbinds" :after helm :bind ("C-h b" . helm-descbinds) :init (fset 'describe-bindings 'helm-descbinds)) ``` The binding of `C-h b` here will not occur until helm is loaded; and after it is loaded, `helm-descbinds` itself is not loaded until the user presses `C-h b`. - For extension authors, if you add a keyword to `use-package-keywords` whose presence should indicate deferred loading, please also add it to `use-package-deferring-keywords`. Note that this is a bit of a sledgehammer, in that the mere presence of these keywords implies deferred loading. For a more subtle approach, see the new `use-package-autoloads/` support mentioned in the next bullet. - For extension authors, if you wish deferred loading to possibly occur, create functions named `use-package-autoloads/` for each keyword that you define, returning an alist of the form `(SYMBOL . TYPE)` of symbols to be autoloaded. `SYMBOL` should be an interactive function, and `TYPE` the smybol `command`, but this functionality may be extended in future. These autoloads are established if deferred loading is to happen. - If you specify a lambda form rather than a function symbol in any of the constructs that *might* introduce autoloads: `:bind`, `:bind*`, `:interpreter`, `:mode`, `:magic`, `:magic-fallback`, and `:hook`: then deferred loading will no longer be implied, since there's nothing to associate an autoload with that could later load the module. In these cases, it will be as if you'd specified `:demand t`, in order to ensure the lambda form is able to execute in the context of the loaded package. - For extension authors, there is a new customization variable `use-package-merge-key-alist` that specifies how values passed to multiple occurrences of the same key should be merged into a single value, during normalization of the `use-package` declaration into a proper plist. The default behavior is to simply append the values together (since they are always normalized to lists). ### Bug fixes - Repeating a bind no longer causes duplicates in personal-keybindings. - When byte-compiling, correctly output declare-function directives. - Append to *use-package* when debugging, don't clear it. - Don't allow :commands, :bind, etc., to be given an empty list. - Explicit :defer t should override use-package-always-demand.