"Fossies" - the Fresh Open Source Software Archive

Member "emacs-26.1/doc/emacs/package.texi" (23 Apr 2018, 14945 Bytes) of package /linux/misc/emacs-26.1.tar.xz:

Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "package.texi": 25.3_vs_26.1.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Emacs Lisp Packages

Emacs includes a facility that lets you easily download and install packages that implement additional features. Each package is a separate Emacs Lisp program, sometimes including other components such as an Info manual.

M-x list-packages brings up a buffer named ‘*Packages*’ with a list of all packages. You can install or uninstall packages via this buffer. See section The Package Menu Buffer.

The command C-h P (describe-package) prompts for the name of a package, and displays a help buffer describing the attributes of the package and the features that it implements.

By default, Emacs downloads packages from a package archive maintained by the Emacs developers and hosted by the GNU project. Optionally, you can also download packages from archives maintained by third parties. See section Package Installation.

For information about turning an Emacs Lisp program into an installable package, See Packaging in The Emacs Lisp Reference Manual.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 The Package Menu Buffer

The command M-x list-packages brings up the package menu. This is a buffer listing all the packages that Emacs knows about, one on each line, with the following information:

The list-packages command accesses the network, to retrieve the list of available packages from package archive servers. If the network is unavailable, it falls back on the most recently retrieved list.

The following commands are available in the package menu:


Print a short message summarizing how to use the package menu (package-menu-quick-help).


Display a help buffer for the package on the current line (package-menu-describe-package), similar to the help window displayed by the C-h P command (see section Emacs Lisp Packages).


Mark the package on the current line for installation (package-menu-mark-install). If the package status is ‘available’, this adds an ‘I’ character to the start of the line; typing x (see below) will download and install the package.


Mark the package on the current line for deletion (package-menu-mark-delete). If the package status is ‘installed’, this adds a ‘D’ character to the start of the line; typing x (see below) will delete the package. See section Package Files and Directory Layout, for information about what package deletion entails.


Mark all obsolete packages for deletion (package-menu-mark-obsolete-for-deletion). This marks for deletion all the packages whose status is ‘obsolete’.


Remove any installation or deletion mark previously added to the current line by an i or d command.


Mark all package with a newer available version for upgrading (package-menu-mark-upgrades). This places an installation mark on the new available versions, and a deletion mark on the old installed versions.


Download and install all packages marked with i, and their dependencies; also, delete all packages marked with d (package-menu-execute). This also removes the marks.


Refresh the package list (package-menu-refresh). This fetches the list of available packages from the package archive again, and recomputes the package list.


Filter the package list (package-menu-filter). This prompts for a keyword (e.g., ‘games’), then shows only the packages that relate to that keyword. To restore the full package list, type q.


Permanently hide packages that match a regexp (package-menu-hide-package).


Toggle visibility of old versions of packages and also of versions from lower-priority archives (package-menu-toggle-hiding).

For example, you can install a package by typing i on the line listing that package, followed by x.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Package Installation

Packages are most conveniently installed using the package menu (see section The Package Menu Buffer), but you can also use the command M-x package-install. This prompts for the name of a package with the ‘available’ status, then downloads and installs it.

A package may require certain other packages to be installed, because it relies on functionality provided by them. When Emacs installs such a package, it also automatically downloads and installs any required package that is not already installed. (If a required package is somehow unavailable, Emacs signals an error and stops installation.) A package’s requirements list is shown in its help buffer.

By default, packages are downloaded from a single package archive maintained by the Emacs developers. This is controlled by the variable package-archives, whose value is a list of package archives known to Emacs. Each list element must have the form (id . location), where id is the name of a package archive and location is the HTTP address or name of the package archive directory. 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!

The maintainers of package archives can increase the trust that you can have in their packages by signing them. They generate a private/public pair of cryptographic keys, and use the private key to create a signature file for each package. With the public key, you can use the signature files to verify the package creator and make sure the package has not been tampered with. Signature verification uses the GnuPG package via the EasyPG interface (see EasyPG in Emacs EasyPG Assistant Manual). 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 https://pgp.mit.edu/. Use M-x package-import-keyring to import the key into Emacs. Emacs stores package keys in the directory specified by the variable package-gnupghome-dir, by default in the ‘gnupg’ subdirectory of package-user-dir, which causes Emacs to invoke GnuPG with the option ‘--homedir’ when verifying signatures. If package-gnupghome-dir is nil, GnuPG’s option ‘--homedir’ is omitted. The public key for the GNU package archive is distributed with Emacs, in the ‘etc/package-keyring.gpg’. Emacs uses it automatically.

If the user option package-check-signature is non-nil, Emacs attempts to verify signatures when you install packages. If the option has the value 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 package-unsigned-archives.

For more information on cryptographic keys and signing, see GnuPG in The GNU Privacy Guard Manual. Emacs comes with an interface to GNU Privacy Guard, see EasyPG in Emacs EasyPG Assistant Manual.

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 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.

Another option that is useful when you have several package archives enabled is 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 package-menu-hide-low-priority.)

Once a package is downloaded and installed, it is loaded into the current Emacs session. Loading a package is not quite the same as loading a Lisp library (@pxref{Lisp Libraries}); loading a package adds its directory to load-path and loads its autoloads. The effect of a package’s autoloads varies from package to package. Most packages just make some new commands available, while others have more wide-ranging effects on the Emacs session. For such information, consult the package’s help buffer.

By default, Emacs also automatically loads all installed packages in subsequent Emacs sessions. This happens at startup, after processing the init file (@pxref{Init File}). As an exception, Emacs does not load packages at startup if invoked with the ‘-q’ or ‘--no-init-file’ options (@pxref{Initial Options}).

To disable automatic package loading, change the variable package-enable-at-startup to nil.

The reason automatic package loading occurs after loading the init file is that user options only receive their customized values after loading the init file, including user options which affect the packaging system. In some circumstances, you may want to load packages explicitly in your init file (usually because some other code in your init file depends on a package). In that case, your init file should call the function package-initialize. It is up to you to ensure that relevant user options, such as package-load-list (see below), are set up prior to the package-initialize call. This will automatically set package-enable-at-startup to 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 M-x package-initialize to load your packages manually.

For finer control over package loading, you can use the variable package-load-list. Its value should be a list. A list element of the form (name version) tells Emacs to load version version of the package named name. Here, version should be a version string (corresponding to a specific version of the package), or t (which means to load any installed version), or nil (which means no version; this disables the package, preventing it from being loaded). A list element can also be the symbol all, which means to load the latest installed version of any package not named by the other list elements. The default value is just '(all).

For example, if you set package-load-list to '((muse "3.20") all), then Emacs only loads version 3.20 of the ‘muse’ package, plus any installed version of packages other than ‘muse’. Any other version of ‘muse’ that happens to be installed will be ignored. The ‘muse’ package will be listed in the package menu with the ‘held’ status.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Package Files and Directory Layout

Each package is downloaded from the package archive in the form of a single package file—either an Emacs Lisp source file, or a tar file containing multiple Emacs Lisp source and other files. Package files are automatically retrieved, processed, and disposed of by the Emacs commands that install packages. Normally, you will not need to deal directly with them, unless you are making a package (see Packaging in The Emacs Lisp Reference Manual). Should you ever need to install a package directly from a package file, use the command M-x package-install-file.

Once installed, the contents of a package are placed in a subdirectory of ‘~/.emacs.d/elpa/’ (you can change the name of that directory by changing the variable package-user-dir). The package subdirectory is named ‘name-version’, where name is the package name and version is its version string.

In addition to package-user-dir, Emacs looks for installed packages in the directories listed in package-directory-list. These directories are meant for system administrators to make Emacs packages available system-wide; Emacs itself never installs packages there. The package subdirectories for package-directory-list are laid out in the same way as in package-user-dir.

Deleting a package (see section The Package Menu Buffer) involves deleting the corresponding package subdirectory. This only works for packages installed in package-user-dir; if told to act on a package in a system-wide package directory, the deletion command signals an error.

[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on May 30, 2018 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated on May 30, 2018 using texi2html.