X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/699c782b7668c44d0fa4446331b0590a6d5dac82..5ab083034ca221a7b4f00156a0efece84da999d8:/doc/emacs/package.texi diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index 91b25cfa00..3c09983805 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -1,6 +1,6 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 -@c Free Software Foundation, Inc. +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2016 Free Software +@c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Packages @chapter Emacs Lisp Packages @@ -14,7 +14,7 @@ Emacs includes a facility that lets you easily download and install separate Emacs Lisp program, sometimes including other components such as an Info manual. - @kbd{M-x list-packages} brings up a buffer named @samp{*Packages*} + @kbd{M-x list-packages} brings up a buffer named @file{*Packages*} with a list of all packages. You can install or uninstall packages via this buffer. @xref{Package Menu}. @@ -30,9 +30,7 @@ third parties. @xref{Package Installation}. For information about turning an Emacs Lisp program into an installable package, @xref{Packaging,,,elisp, The Emacs Lisp Reference -Manual}. For information about finding third-party packages and other -Emacs Lisp extensions, @xref{Packages that do not come with -Emacs,,,efaq, GNU Emacs FAQ}. +Manual}. @menu * Package Menu:: Buffer for viewing and managing packages. @@ -52,18 +50,28 @@ on each line, with the following information: @itemize @bullet @item -The package name (e.g. @samp{auctex}). +The package name (e.g., @samp{auctex}). @item -The package's version number (e.g. @samp{11.86}). +The package's version number (e.g., @samp{11.86}). @item The package's status---normally one of @samp{available} (can be -downloaded from the package archive), @samp{installed}, or -@samp{built-in} (included in Emacs by default). - -In some instances, the status can be @samp{held}, @samp{disabled}, or -@samp{obsolete}. @xref{Package Installation}. +downloaded from the package archive), @samp{installed}, +@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}), +or @samp{built-in} (included in Emacs by default). The status +@samp{external} means the package is not built-in and not from the +directory specified by @code{package-user-dir} (@pxref{Package +Files}). External packages are treated much like built-in: they +cannot be deleted through the package menu, and are not considered for +upgrading. + +The status can also be @samp{new}. This is equivalent to +@samp{available}, except that it means the package became newly +available on the package archive after your last invocation of +@kbd{M-x list-packages}. In other instances, a package may have the +status @samp{held}, @samp{disabled}, or @samp{obsolete}. +@xref{Package Installation}. @item A short description of the package. @@ -103,17 +111,24 @@ line; typing @kbd{x} (see below) will delete the package. @xref{Package Files}, for information about what package deletion entails. +@item ~ +Mark all obsolete packages for deletion +(@code{package-menu-mark-obsolete-for-deletion}). This marks for +deletion all the packages whose status is @samp{obsolete}. + @item u +@itemx @key{DEL} Remove any installation or deletion mark previously added to the current line by an @kbd{i} or @kbd{d} command. @item U -Mark all package with a newer available version for ``upgrading'' +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. @item x +@vindex package-menu-async Download and install all packages marked with @kbd{i}, and their dependencies; also, delete all packages marked with @kbd{d} (@code{package-menu-execute}). This also removes the marks. @@ -122,6 +137,20 @@ dependencies; also, delete all packages marked with @kbd{d} Refresh the package list (@code{package-menu-refresh}). This fetches the list of available packages from the package archive again, and recomputes the package list. + +@item f +Filter the package list (@code{package-menu-filter}). This prompts +for a keyword (e.g., @samp{games}), then shows only the packages +that relate to that keyword. To restore the full package list, +type @kbd{q}. + +@item H +Permanently hide packages that match a regexp +(@code{package-menu-hide-package}). + +@item ( +Toggle visibility of old versions of packages and also of versions +from lower-priority archives (@code{package-menu-toggle-hiding}). @end table @noindent @@ -157,6 +186,56 @@ directory name of the package archive. You can alter this list if you wish to use third party package archives---but do so at your own risk, and use only third parties that you think you can trust! +@anchor{Package Signing} +@cindex package security +@cindex package signing + The maintainers of package archives can increase the trust that you +can have in their packages by @dfn{signing} them. They generate a +private/public pair of cryptographic keys, and use the private key to +create a @dfn{signature file} for each package. With the public key, you +can use the signature files to verify who created the package, and +that it has not been modified. A valid signature is not a cast-iron +guarantee that a package is not malicious, so you should still +exercise caution. Package archives should provide instructions +on how you can obtain their public key. One way is to download the +key from a server such as @url{http://pgp.mit.edu/}. +Use @kbd{M-x package-import-keyring} to import the key into Emacs. +Emacs stores package keys in the @file{gnupg} subdirectory +of @code{package-user-dir}. +The public key for the GNU package archive is distributed with Emacs, +in the @file{etc/package-keyring.gpg}. Emacs uses it automatically. + +@vindex package-check-signature +@vindex package-unsigned-archives + If the user option @code{package-check-signature} is non-@code{nil}, +Emacs attempts to verify signatures when you install packages. If the +option has the value @code{allow-unsigned}, you can still install a +package that is not signed. If you use some archives that do not sign +their packages, you can add them to the list @code{package-unsigned-archives}. + + For more information on cryptographic keys and signing, +@pxref{Top,, Top, gnupg, The GNU Privacy Guard Manual}. +Emacs comes with an interface to GNU Privacy Guard, +@pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}. + +@vindex package-pinned-packages + If you have more than one package archive enabled, and some of them +offer different versions of the same package, you may find the option +@code{package-pinned-packages} useful. You can add package/archive +pairs to this list, to ensure that the specified package is only ever +downloaded from the specified archive. + +@vindex package-archive-priorities +@vindex package-menu-hide-low-priority + Another option that is useful when you have several package archives +enabled is @code{package-archive-priorities}. It specifies the +priority of each archive (higher numbers specify higher priority +archives). By default, archives have the priority of zero, unless +specified otherwise by this option's value. Packages from +lower-priority archives will not be shown in the menu, if the same +package is available from a higher-priority archive. (This is +controlled by the value of @code{package-menu-hide-low-priority}.) + Once a package is downloaded and installed, it is @dfn{loaded} into the current Emacs session. Loading a package is not quite the same as loading a Lisp library (@pxref{Lisp Libraries}); its effect varies @@ -184,7 +263,7 @@ in your init file depends on a package). In that case, your init file should call the function @code{package-initialize}. It is up to you to ensure that relevant user options, such as @code{package-load-list} (see below), are set up prior to the @code{package-initialize} call. -You should also set @code{package-enable-at-startup} to @code{nil}, to +This will automatically set @code{package-enable-at-startup} to @code{nil}, to avoid loading the packages again after processing the init file. Alternatively, you may choose to completely inhibit package loading at startup, and invoke the command @kbd{M-x package-initialize} to load @@ -198,7 +277,7 @@ version @var{version} of the package named @var{name}. Here, @var{version} should be a version string (corresponding to a specific version of the package), or @code{t} (which means to load any installed version), or @code{nil} (which means no version; this -``disables'' the package, preventing it from being loaded). A list +disables the package, preventing it from being loaded). A list element can also be the symbol @code{all}, which means to load the latest installed version of any package not named by the other list elements. The default value is just @code{'(all)}.