File: package.el.html

The idea behind package.el is to be able to download packages and install them. Packages are versioned and have versioned dependencies. Furthermore, this supports built-in packages which may or may not be newer than user-specified packages. This makes it possible to upgrade Emacs and automatically disable packages which have moved from external to core. (Note though that we don't currently register any of these, so this feature does not actually work.)

A package is described by its name and version. The distribution format is either a tar file or a single .el file.

A tar file should be named "NAME-VERSION.tar". The tar file must unpack into a directory named after the package and version:
"NAME-VERSION". It must contain a file named "PACKAGE-pkg.el"
which consists of a call to define-package. It may also contain a
"dir" file and the info files it references.

A .el file is named "NAME-VERSION.el" in the remote archive, but is installed as simply "NAME.el" in a directory named "NAME-VERSION".

The downloader downloads all dependent packages. By default, packages come from the official GNU sources, but others may be added by customizing the package-archives alist. Packages get byte-compiled at install time.

At activation time we will set up the load-path and the info path, and we will load the package's autoloads. If a package's dependencies are not available, we will not activate that package.

Conceptually a package has multiple state transitions:

* Download. Fetching the package from ELPA.
* Install. Untar the package, or write the .el file, into
  ~/.emacs.d/elpa/ directory.
* Autoload generation.
* Byte compile. Currently this phase is done during install,
  but we may change this.
* Activate. Evaluate the autoloads for the package to make it
  available to the user.
* Load. Actually load the package and run some code from it.

Other external functions you may want to use:

M-x list-packages
   Enters a mode similar to buffer-menu which lets you manage
   packages. You can choose packages for install (mark with "i",
   then "x" to execute) or deletion, and you can see what packages
   are available. This will automatically fetch the latest list of
   packages from ELPA.

M-x package-install-from-buffer
   Install a package consisting of a single .el file that appears
   in the current buffer. This only works for packages which
   define a Version header properly; package.el also supports the
   extension headers Package-Version (in case Version is an RCS id
   or similar), and Package-Requires (if the package requires other
   packages).

M-x package-install-file
   Install a package from the indicated file. The package can be
   either a tar file or a .el file. A tar file must contain an
   appropriately-named "-pkg.el" file; a .el file must be properly
   formatted as with package-install-from-buffer.

Defined variables (52)

package--activatedNon-nil if ‘package-activate-all’ has been run.
package--builtinsAlist of built-in packages.
package--compatibility-tableHash table connecting package names to their compatibility.
package--downloads-in-progressList of in-progress asynchronous downloads.
package--emacs-version-listThe value of variable ‘emacs-version’ as a list.
package--initializedNon-nil if ‘package-initialize’ has been run.
package--old-archive-prioritiesStore currently used ‘package-archive-priorities’.
package--post-download-archives-hookHook run after the archive contents are downloaded.
package--quickstart-dirSet by ‘package-quickstart-file’ to the directory containing it.
package--quickstart-pkgsIf set to a list, we’re computing the set of pkgs to activate.
package-activated-listList of the names of currently activated packages.
package-alistAlist of all packages available for activation.
package-archive-column-widthColumn width for the Package archive in the package menu.
package-archive-contentsCache of the contents of all archives in ‘package-archives’.
package-archive-prioritiesAn alist of priorities for packages.
package-archive-versionVersion number of the package archive understood by package.el.
package-archivesAn alist of archives from which to fetch.
package-check-signatureNon-nil means to check package signatures when installing.
package-directory-listList of additional directories containing Emacs Lisp packages.
package-enable-at-startupWhether to make installed packages available when Emacs starts.
package-gnupghome-dirDirectory containing GnuPG keyring or nil.
package-hidden-regexpsList of regexps matching the name of packages to hide.
package-install-upgrade-built-inNon-nil means that built-in packages can be upgraded via a package archive.
package-list-unsignedIf non-nil, mention in the list which packages were installed without signature.
package-list-unversionedIf non-nil, include packages that don’t have a version in ‘list-packages’.
package-load-listList of packages for ‘package-activate-all’ to make available.
package-menu--hide-packagesWhether available obsolete packages should be hidden.
package-menu--mark-upgrades-pendingWhether mark-upgrades is waiting for a refresh to finish.
package-menu--new-package-listList of newly-available packages since ‘list-packages’ was last called.
package-menu--old-archive-contents‘package-archive-contents’ before the latest refresh.
package-menu--transaction-statusMode-line status of ongoing package transaction.
package-menu-asyncIf non-nil, package-menu will use async operations when possible.
package-menu-hide-low-priorityIf non-nil, hide low priority packages from the packages menu.
package-menu-mode-abbrev-tableAbbrev table for ‘package-menu-mode’.
package-menu-mode-hookHook run after entering ‘package-menu-mode’.
package-menu-mode-line-infoVariable which stores package-menu mode-line format.
package-menu-mode-mapLocal keymap for ‘package-menu-mode’ buffers.
package-menu-mode-menuMenu for ‘package-menu-mode’.
package-menu-mode-syntax-tableSyntax table for ‘package-menu-mode’.
package-menu-use-current-if-no-marksWhether x in package menu operates on current package if none are marked.
package-name-column-widthColumn width for the Package name in the package menu.
package-native-compileNon-nil means to natively compile packages as part of their installation.
package-pinned-packagesAn alist of packages that are pinned to specific archives.
package-quickstartPrecompute activation actions to speed up startup.
package-quickstart-fileLocation of the file used to speed up activation of packages at startup.
package-read-archive-hookList of functions to call to read the archive contents.
package-refresh-contents-hookList of functions to call to refresh the package archive.
package-selected-packagesStore here packages installed explicitly by user.
package-status-column-widthColumn width for the Package status in the package menu.
package-unsigned-archivesList of archives where we do not check for package signatures.
package-user-dirDirectory containing the user’s Emacs Lisp packages.
package-version-column-widthColumn width for the Package version in the package menu.

Defined functions (233)

copy-package--bi-desc(ARG)
copy-package-desc(ARG)
define-package(NAME-STRING VERSION-STRING &optional DOCSTRING REQUIREMENTS &rest EXTRA-PROPERTIES)
describe-package(PACKAGE)
describe-package-1(PKG)
list-packages(&optional NO-FETCH)
make-package--ac-desc
make-package--ac-desc--cmacro
make-package--bi-desc
make-package--bi-desc--cmacro
package--ac-desc-extras(package--ac-desc-extras X)
package--ac-desc-extras--inliner(INLINE--FORM X)
package--ac-desc-kind(package--ac-desc-kind X)
package--ac-desc-kind--inliner(INLINE--FORM X)
package--ac-desc-reqs(package--ac-desc-reqs X)
package--ac-desc-reqs--inliner(INLINE--FORM X)
package--ac-desc-summary(package--ac-desc-summary X)
package--ac-desc-summary--inliner(INLINE--FORM X)
package--ac-desc-version(package--ac-desc-version X)
package--ac-desc-version--inliner(INLINE--FORM X)
package--active-built-in-p(PACKAGE)
package--add-info-node(PKG-DIR)
package--add-to-archive-contents(PACKAGE ARCHIVE)
package--add-to-compatibility-table(PKG)
package--alist()
package--alist-to-plist-args(ALIST)
package--append-to-alist(PKG-DESC ALIST)
package--archive-file-exists-p(LOCATION FILE)
package--archives-initialize()
package--autoloads-file-name(PKG-DESC)
package--bi-desc-reqs(package--bi-desc-reqs X)
package--bi-desc-reqs--inliner(INLINE--FORM X)
package--bi-desc-summary(package--bi-desc-summary X)
package--bi-desc-summary--inliner(INLINE--FORM X)
package--bi-desc-version(package--bi-desc-version X)
package--bi-desc-version--inliner(INLINE--FORM X)
package--build-compatibility-table()
package--check-signature(LOCATION FILE &optional STRING ASYNC CALLBACK UNWIND)
package--check-signature-content(CONTENT STRING &optional SIG-FILE)
package--compile(PKG-DESC)
package--delete-directory(DIR)
package--dependencies(PKG)
package--describe-add-library-links()
package--display-verify-error(CONTEXT SIG-FILE)
package--download-and-read-archives(&optional ASYNC)
package--download-one-archive(ARCHIVE FILE &optional ASYNC)
package--ensure-package-menu-mode()
package--find-non-dependencies()
package--finder-goto-xref(BUTTON)
package--from-builtin(BI-DESC)
package--get-activatable-pkg(PKG-NAME)
package--get-deps(PKGS)
package--get-description(DESC)
package--has-keyword-p(DESC &optional KEYWORDS)
package--imenu-extract-index-name-function()
package--imenu-prev-index-position-function()
package--incompatible-p(PKG &optional SHALLOW)
package--library-stem(FILE)
package--make-autoloads-and-stuff(PKG-DESC PKG-DIR)
package--mapc(FUNCTION &optional PACKAGES)
package--native-compile-async(PKG-DESC)
package--newest-p(PKG)
package--parse-elpaignore(PKG-DESC)
package--prettify-quick-help-key(DESC)
package--print-email-button(RECIPIENT)
package--print-help-section(NAME &rest STRINGS)
package--push(PKG-DESC STATUS LISTNAME)
package--query-desc(&optional ALIST)
package--quickstart-rel(FILE)
package--read-archive-file(FILE)
package--read-pkg-desc(KIND)
package--reload-previously-loaded(PKG-DESC &optional WARN)
package--removable-packages()
package--remove-hidden(PKG-LIST)
package--save-selected-packages(&optional VALUE)
package--sort-by-dependence(PACKAGE-LIST)
package--sort-deps-in-alist(PACKAGE ONLY)
package--unless-error(BODY &rest BEFORE-BODY)
package--update-downloads-in-progress(ENTRY)
package--update-selected-packages(ADD REMOVE)
package--upgradeable-packages(&optional INCLUDE-BUILTINS)
package--used-elsewhere-p(PKG-DESC &optional PKG-LIST ALL)
package--user-installed-p(PACKAGE)
package--user-selected-p(PKG)
package--with-response-buffer
package--with-response-buffer-1
package--with-work-buffer(LOCATION FILE &rest BODY)
package--write-file-no-coding(FILE-NAME)
package-activate(PACKAGE &optional FORCE)
package-activate-1(PKG-DESC &optional RELOAD DEPS)
package-activate-all()
package-all-keywords()
package-archive-base(DESC)
package-archive-priority(ARCHIVE)
package-autoload-ensure-default-file(FILE)
package-autoremove(&optional NOCONFIRM)
package-browse-url(DESC &optional SECONDARY)
package-buffer-info()
package-built-in-p(PACKAGE &optional MIN-VERSION)
package-builtin-package-version(PACKAGE)
package-check-signature()
package-compute-transaction(PACKAGES REQUIREMENTS &optional SEEN)
package-delete(PKG-DESC &optional FORCE NOSAVE)
package-delete-button-action(BUTTON)
package-desc--keywords(PKG-DESC)
package-desc-archive(package-desc-archive X)
package-desc-archive--inliner(INLINE--FORM X)
package-desc-create
package-desc-create--cmacro
package-desc-dir(package-desc-dir X)
package-desc-dir--inliner(INLINE--FORM X)
package-desc-extras(package-desc-extras X)
package-desc-extras--inliner(INLINE--FORM X)
package-desc-from-define(NAME-STRING VERSION-STRING &optional SUMMARY REQUIREMENTS &rest REST-PLIST)
package-desc-full-name(PKG-DESC)
package-desc-kind(package-desc-kind X)
package-desc-kind--inliner(INLINE--FORM X)
package-desc-name(package-desc-name X)
package-desc-name--inliner(INLINE--FORM X)
package-desc-p(X)
package-desc-p--inliner(INLINE--FORM X)
package-desc-priority(PKG-DESC)
package-desc-priority-version(PKG-DESC)
package-desc-reqs(package-desc-reqs X)
package-desc-reqs--inliner(INLINE--FORM X)
package-desc-signed(package-desc-signed X)
package-desc-signed--inliner(INLINE--FORM X)
package-desc-status(PKG-DESC)
package-desc-suffix(PKG-DESC)
package-desc-summary(package-desc-summary X)
package-desc-summary--inliner(INLINE--FORM X)
package-desc-version(package-desc-version X)
package-desc-version--inliner(INLINE--FORM X)
package-dir-info()
package-disabled-p(PKG-NAME VERSION)
package-download-transaction(PACKAGES)
package-generate-autoloads(NAME PKG-DIR)
package-generate-description-file(PKG-DESC PKG-FILE)
package-get-descriptor(PKG-NAME)
package-get-version()
package-import-keyring(&optional FILE)
package-initialize(&optional NO-ACTIVATE)
package-install(PKG &optional DONT-SELECT)
package-install-button-action(BUTTON)
package-install-file(FILE)
package-install-from-archive(PKG-DESC)
package-install-from-buffer()
package-install-selected-packages(&optional NOCONFIRM)
package-installed-p(PACKAGE &optional MIN-VERSION)
package-isolate(PACKAGES &optional TEMP-INIT)
package-keyword-button-action(BUTTON)
package-list-packages(&optional NO-FETCH)
package-list-packages-no-fetch()
package-load-all-descriptors()
package-load-descriptor(PKG-DIR)
package-maintainers(PKG-DESC &optional NO-ERROR)
package-make-ac-desc(VERSION REQS SUMMARY KIND EXTRAS)
package-make-ac-desc--cmacro(CL-WHOLE-ARG VERSION REQS SUMMARY KIND EXTRAS)
package-make-builtin(VERSION SUMMARY)
package-make-builtin--cmacro(CL-WHOLE-ARG VERSION SUMMARY)
package-make-button(TEXT &rest PROPERTIES)
package-menu--archive-predicate(A B)
package-menu--description-predicate(A B)
package-menu--display(REMEMBER-POS SUFFIX)
package-menu--filter-by(PREDICATE SUFFIX)
package-menu--find-and-notify-upgrades()
package-menu--find-upgrades()
package-menu--generate(REMEMBER-POS &optional PACKAGES KEYWORDS)
package-menu--list-to-prompt(PACKAGES &optional INCLUDE-DEPENDENCIES)
package-menu--mark-or-notify-upgrades()
package-menu--mark-upgrades-1()
package-menu--name-predicate(A B)
package-menu--overlay-line(FACE)
package-menu--partition-transaction(INSTALL DELETE)
package-menu--perform-transaction(INSTALL-LIST DELETE-LIST)
package-menu--populate-new-package-list()
package-menu--post-refresh()
package-menu--print-info(PKG)
package-menu--print-info-simple(PKG)
package-menu--prompt-transaction-p(DELETE INSTALL UPGRADE)
package-menu--refresh(&optional PACKAGES KEYWORDS)
package-menu--refresh-contents(&optional ARG NOCONFIRM)
package-menu--remove-overlay()
package-menu--set-mode-line-format()
package-menu--status-predicate(A B)
package-menu--version-predicate(A B)
package-menu-backup-unmark()
package-menu-clear-filter()
package-menu-describe-package(&optional BUTTON)
package-menu-execute(&optional NOQUERY)
package-menu-filter(KEYWORD)
package-menu-filter-by-archive(ARCHIVE)
package-menu-filter-by-description(DESCRIPTION)
package-menu-filter-by-keyword(KEYWORD)
package-menu-filter-by-name(NAME)
package-menu-filter-by-name-or-description(NAME-OR-DESCRIPTION)
package-menu-filter-by-status(STATUS)
package-menu-filter-by-version(VERSION PREDICATE)
package-menu-filter-marked()
package-menu-filter-upgradable()
package-menu-get-status()
package-menu-hide-package()
package-menu-mark-delete(&optional NUM)
package-menu-mark-install(&optional NUM)
package-menu-mark-obsolete-for-deletion()
package-menu-mark-unmark(&optional NUM)
package-menu-mark-upgrades()
package-menu-mode()
package-menu-mode-menu(ARG1)
package-menu-quick-help()
package-menu-refresh(&optional IGNORE-AUTO NOCONFIRM PRESERVE-MODES)
package-menu-toggle-hiding()
package-process-define-package(EXP)
package-quickstart-refresh()
package-read-all-archive-contents()
package-read-archive-contents(ARCHIVE)
package-read-from-string(STR)
package-recompile(PKG)
package-recompile-all()
package-refresh-contents(&optional ASYNC)
package-reinstall(PKG)
package-report-bug(DESC)
package-show-package-list(&optional PACKAGES KEYWORDS)
package-strip-rcs-id(STR)
package-tar-file-info()
package-unpack(PKG-DESC)
package-untar-buffer(DIR)
package-upgrade(NAME)
package-upgrade-all(&optional QUERY)
package-vc-p(PKG-DESC)
package-vc-p--inliner(INLINE--FORM PKG-DESC)
package-version-join(VLIST)
package-versioned-builtin-packages()

Defined faces (21)

package-descriptionFace used on package description summaries in the package menu.
package-help-section-nameFace used on section names in package description buffers.
package-mark-delete-lineFace used for highlighting in package-menu packages marked to be deleted.
package-mark-install-lineFace used for highlighting in package-menu packages marked to be installed.
package-mode-line-installedFace for the number of installed packages displayed on the mode line.
package-mode-line-newFace for the number of new packages displayed on the mode line.
package-mode-line-to-upgradeFace for the number of packages to upgrade displayed on the mode line.
package-mode-line-totalFace for the total number of packages displayed on the mode line.
package-nameFace used on package names in the package menu.
package-status-avail-obsoFace used on the status and version of avail-obso packages.
package-status-availableFace used on the status and version of available packages.
package-status-built-inFace used on the status and version of built-in packages.
package-status-dependencyFace used on the status and version of dependency packages.
package-status-disabledFace used on the status and version of disabled packages.
package-status-externalFace used on the status and version of external packages.
package-status-from-sourceFace used on the status and version of installed packages.
package-status-heldFace used on the status and version of held packages.
package-status-incompatFace used on the status and version of incompat packages.
package-status-installedFace used on the status and version of installed packages.
package-status-newFace used on the status and version of new packages.
package-status-unsignedFace used on the status and version of unsigned packages.