From 09d6070e56ea21a5e9720bc619c439c09e5b2680 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 12 May 2023 15:33:06 +0300 Subject: [PATCH] ; Improve and update documentation of built-in package upgrades * doc/emacs/package.texi (Package Statuses, Package Menu) (Package Installation): * etc/NEWS: Document the options and caveats of upgrading built-in packages. --- doc/emacs/package.texi | 50 +++++++++++++++++++++++++++++++++++++++--- etc/NEWS | 7 ++++++ 2 files changed, 54 insertions(+), 3 deletions(-) diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index d1766026db2..6722185cb20 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -160,7 +160,13 @@ current line by an @kbd{i} or @kbd{d} command Mark all package with a newer available version for upgrading (@code{package-menu-mark-upgrades}). This places an installation mark on the new available versions, and a deletion mark on the old -installed versions (marked with status @samp{obsolete}). +installed versions (marked with status @samp{obsolete}). By default, +this won't mark built-in packages for which a newer version is +available, but customizing @code{package-install-upgrade-built-in} can +change that. @xref{Package Installation}. If you customize +@code{package-install-upgrade-built-in} to a non-@code{nil} value, be +sure to review all the built-in packages the @kbd{U} command marks, to +avoid updating built-in packages you don't want to overwrite. @item x @kindex x @r{(Package Menu)} @@ -258,7 +264,11 @@ This shows only the packages that have been marked to be installed or deleted. @kindex / u @r{(Package Menu)} @findex package-menu-filter-upgradable Filter package list to show only packages for which there are -available upgrades (@code{package-menu-filter-upgradable}). +available upgrades (@code{package-menu-filter-upgradable}). By +default, this filter excludes the built-in packages for which a newer +version is available, but customizing +@code{package-install-upgrade-built-in} can change that. +@xref{Package Installation}. @item / / @kindex / / @r{(Package Menu)} @@ -286,9 +296,12 @@ the package archive. The package is available for installation, but a newer version is also available. Packages with this status are hidden by default. +@cindex built-in package @item built-in The package is included in Emacs by default. It cannot be deleted -through the package menu, and is not considered for upgrading. +through the package menu, and by default is not considered for +upgrading (but you can change that by customizing +@code{package-install-upgrade-built-in}, @pxref{Package Installation}). @item dependency The package was installed automatically to satisfy a dependency of @@ -339,6 +352,37 @@ if you want to upgrade a package, you can use the @kbd{M-x package-upgrade} command, and if you want to upgrade all the packages, you can use the @kbd{M-x package-upgrade-all} command. +@vindex package-install-upgrade-built-in + By default, @code{package-install} doesn't consider built-in +packages for which new versions are available from the archives. (A +package is built-in if it is included in the Emacs distribution.) In +particular, it will not show built-in packages in the list of +completion candidates when you type at its prompt. But if you invoke +@code{package-install} with a prefix argument, it will also consider +built-in packages that can be upgraded. You can make this behavior +the default by customizing the variable +@code{package-install-upgrade-built-in}: if its value is +non-@code{nil}, @code{package-install} will consider built-in packages +even when invoked without a prefix argument. Note that the +package-menu commands (@pxref{Package Menu}) are also affected by +@code{package-install-upgrade-built-in}. + + By contrast, @code{package-upgrade} and @code{package-upgrade-all} +never consider built-in packages. If you want to use these commands +for upgrading some built-in packages, you need to upgrade each of +those packages, once, either via @kbd{C-u M-x package-install +@key{RET}}, or by customizing @code{package-install-upgrade-built-in} +to a non-@code{nil} value, and then upgrading the package once via the +package menu or by @code{package-install}. + + If you customize @code{package-install-upgrade-built-in} to a +non-@code{nil} value, be very careful when using commands that update +many packages at once, like @code{package-upgrade-all} and @kbd{U} in +the package menu: those might overwrite built-in packages that you +didn't intent to replace with newer versions from the archives. Don't +use these bulk commands if you want to update only a small number of +built-in packages. + @cindex package requirements A package may @dfn{require} certain other packages to be installed, because it relies on functionality provided by them. When Emacs diff --git a/etc/NEWS b/etc/NEWS index 5f5ae1c75a1..a28e060dfdc 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1906,6 +1906,13 @@ default, this is disabled; however, if 'package-install' is invoked with a prefix argument, it will act as if this new option were enabled. +In addition, when this option is non-nil, built-in packages for which +a new version is available in archives can be upgraded via the package +menu produced by 'M-x list-packages'. If you do set this option +non-nil, we recommend not to use the 'U' command, but instead to use +'/ u' to show the packages which can be upgraded, and then unmark the +built-in packages which you don't need to overwrite from the archives. + If you customize this option, we recommend you place its non-default setting in your early-init file. -- 2.39.2