;; work.)
;; A package is described by its name and version. The distribution
-;; format is either a tar file or a single .el file.
+;; 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:
\f
;;; Customization options
+
;;;###autoload
(defcustom package-enable-at-startup t
"Whether to make installed packages available when Emacs starts.
t: both criteria are used.
This variable has no effect if `package-menu--hide-packages' is
-nil, so it can be toggled with \\<package-menu-mode-map> \\[package-menu-toggle-hiding]."
+nil, so it can be toggled with \\<package-menu-mode-map>\\[package-menu-toggle-hiding]."
:type '(choice (const :tag "Don't hide anything" nil)
(const :tag "Hide per package-archive-priorities"
archive)
the package will be unavailable."
:type '(alist :key-type (symbol :tag "Package")
:value-type (string :tag "Archive name"))
- ;; I don't really see why this is risky...
- ;; I suppose it could prevent you receiving updates for a package,
+ ;; This could prevent you from receiving updates for a package,
;; via an entry (PACKAGE . NON-EXISTING). Which could be an issue
;; if PACKAGE has a known vulnerability that is fixed in newer versions.
:risky t
package-check-signature))
(defcustom package-unsigned-archives nil
- "List of archives where we do not check for package signatures."
+ "List of archives where we do not check for package signatures.
+This should be a list of strings matching the names of package
+archives in the variable `package-archives'."
:type '(repeat (string :tag "Archive name"))
:risky t
:version "24.4")
;; user) it makes sense to take the package name as a symbol instead,
;; but keep in mind there could be multiple `package-desc's with the
;; same name.
+
(defvar package--default-summary "No description available.")
(cl-defstruct (package-desc
(nth 1 keywords)
keywords)))
-(defun package-desc-priority (p)
- "Return the priority of the archive of package-desc object P."
- (package-archive-priority (package-desc-archive p)))
+(defun package-desc-priority (pkg-desc)
+ "Return the priority of the archive of package-desc object PKG-DESC."
+ (package-archive-priority (package-desc-archive pkg-desc)))
(cl-defstruct (package--bi-desc
(:constructor package-make-builtin (version summary))
;; command `package-initialize' is also closely related to this
;; section, but it is left for a later section because it also affects
;; other stuff.
+
(defvar package--builtins nil
"Alist of built-in packages.
The actual value is initialized by loading the library
(put 'package-activated-list 'risky-local-variable t)
;;;; Populating `package-alist'.
+
;; The following functions are called on each installed package by
;; `package-load-all-descriptors', which ultimately populates the
;; `package-alist' variable.
new-pkg-desc)))
(defun package-load-descriptor (pkg-dir)
- "Load the description file in directory PKG-DIR."
+ "Load the package description file in directory PKG-DIR.
+Create a new `package-desc' object, add it to `package-alist' and
+return it."
(let ((pkg-file (expand-file-name (package--description-file pkg-dir)
pkg-dir))
(signed-file (concat pkg-dir ".signed")))
\f
;;; Package activation
;; Section for functions used by `package-activate', which see.
+
(defun package-disabled-p (pkg-name version)
"Return whether PKG-NAME at VERSION can be activated.
The decision is made according to `package-load-list'.
;;; Communicating with Archives
;; Set of low-level functions for communicating with archives and
;; signature checking.
+
(defun package--write-file-no-coding (file-name)
(let ((buffer-file-coding-system 'no-conversion))
(write-region (point-min) (point-max) file-name nil 'silent)))
(declare-function epg-signature-to-string "epg" (signature))
(defun package--display-verify-error (context sig-file)
+ "Show error details with CONTEXT for failed verification of SIG-FILE.
+The details are shown in a new buffer called \"*Error\"."
(unless (equal (epg-context-error-output context) "")
(with-output-to-temp-buffer "*Error*"
(with-current-buffer standard-output
;; function `package-read-all-archive-contents' from a cache on disk.
;; The `package-initialize' command is also closely related to this
;; section, but it has its own section.
+
(defconst package-archive-version 1
- "Version number of the package archive understood by this file.
+ "Version number of the package archive understood by package.el.
Lower version numbers than this will probably be understood as well.")
;; We don't prime the cache since it tends to get out of date.
(defvar package-archive-contents nil
- "Cache of the contents of the Emacs Lisp Package Archive.
+ "Cache of the contents of all archives in `package-archives'.
This is an alist mapping package names (symbols) to
non-empty lists of `package-desc' structures.")
(put 'package-archive-contents 'risky-local-variable t)
(package--append-to-alist pkg-desc package-archive-contents)))))
(defun package--read-archive-file (file)
- "Re-read archive file FILE, if it exists.
-Will return the data from the file, or nil if the file does not exist.
-Will throw an error if the archive version is too new."
+ "Read cached archive FILE data, if it exists.
+Return the data from the file, or nil if the file does not exist.
+If the archive version is too new, signal an error."
(let ((filename (expand-file-name file package-user-dir)))
(when (file-exists-p filename)
(with-temp-buffer
(cdr contents))))))
(defun package-read-archive-contents (archive)
- "Re-read archive contents for ARCHIVE.
-If successful, set the variable `package-archive-contents'.
+ "Read cached archive file for ARCHIVE.
+If successful, set or update the variable `package-archive-contents'.
+ARCHIVE should be a string matching the name of a package archive
+in the variable `package-archives'.
If the archive version is too new, signal an error."
;; Version 1 of 'archive-contents' is identical to our internal
;; representation.
it again.")
(defun package-read-all-archive-contents ()
- "Re-read `archive-contents', if it exists.
-If successful, set `package-archive-contents'."
+ "Read cached archive file for all archives in `package-archives'.
+If successful, set or update `package-archive-contents'."
(setq package-archive-contents nil)
(setq package--old-archive-priorities package-archive-priorities)
(dolist (archive package-archives)
;;;; Populating `package-archive-contents' from archives
;; This subsection populates the variables listed above from the
;; actual archives, instead of from a local cache.
+
(defvar package--downloads-in-progress nil
"List of in-progress asynchronous downloads.")
(defun package--download-and-read-archives (&optional async)
"Download descriptions of all `package-archives' and read them.
-This populates `package-archive-contents'. If ASYNC is non-nil,
-perform the downloads asynchronously."
+Populate `package-archive-contents' with the result.
+
+If optional argument ASYNC is non-nil, perform the downloads
+asynchronously."
;; The downloaded archive contents will be read as part of
;; `package--update-downloads-in-progress'.
(dolist (archive package-archives)
;; keeping track of which packages were installed strictly as
;; dependencies, and determining which packages cannot be removed
;; because they are dependencies.
+
(defun package-compute-transaction (packages requirements &optional seen)
"Return a list of packages to be installed, including PACKAGES.
PACKAGES should be a list of `package-desc'.
;;;###autoload
(defun package-install (pkg &optional dont-select)
"Install the package PKG.
-PKG can be a `package-desc' or a symbol naming one of the available packages
-in an archive in `package-archives'. Interactively, prompt for its name.
+PKG can be a `package-desc' or a symbol naming one of the
+available packages in an archive in `package-archives'. When
+called interactively, prompt for the package name.
-If called interactively or if DONT-SELECT nil, add PKG to
+Mark the installed package as selected by adding it to
`package-selected-packages'.
+When called from Lisp and optional argument DONT-SELECT is
+non-nil, install the package but do not add it to
+`package-select-packages'.
+
If PKG is a `package-desc' and it is already installed, don't try
to install it but still mark it as selected."
(interactive
\f
;;; Package Deletion
+
(defun package--newest-p (pkg)
"Return non-nil if PKG is the newest package with its name."
(equal (cadr (assq (package-desc-name pkg) package-alist))
\f
;;; Package menu faces
+
(defface package-name
'((t :inherit link))
"Face used on package names in the package menu."
\f
;;; Package menu printing
+
(defun package-menu--print-info-simple (pkg)
"Return a package entry suitable for `tabulated-list-entries'.
PKG is a `package-desc' object.
projects / emacs.git / commitdiff