Function: package-vc-install

package-vc-install is an autoloaded, interactive and byte-compiled function defined in package-vc.el.gz.

Signature

(package-vc-install PACKAGE &optional REV BACKEND NAME)

Documentation

Fetch a package described by PACKAGE and set it up for use with Emacs.

PACKAGE specifies which package to install, where to find its source repository and how to build it.

If PACKAGE is a symbol, install the package with that name according to metadata that package archives provide for it. This is the simplest way to call this function, but it only works if the package you want to install is listed in a package archive you have configured.

If PACKAGE is a string, it specifies the URL of the package repository. In this case, optional argument BACKEND specifies the VC backend to use for cloning the repository; if it's nil, this function tries to infer which backend to use according to the value of package-vc-heuristic-alist and if that fails it uses package-vc-default-backend. Optional argument NAME specifies the package name in this case; if it's nil, this package uses file-name-base on the URL to obtain the package name, otherwise NAME is the package name as a symbol.

PACKAGE can also be a cons cell (PNAME . SPEC) where PNAME is the package name as a symbol, and SPEC is a plist that specifies how to fetch and build the package. For possible values, see the subsection "Specifying Package Sources" in the Info node (emacs)Fetching Package Sources.

By default, this function installs the last revision of the package available from its repository. If REV is a string, it describes the revision to install, as interpreted by the relevant VC backend. The special value :last-release (interactively, the prefix argument), says to use the commit of the latest release, if it exists. The last release is the latest revision which changed the "Version:" header of the package's main Lisp file.

If you use this function to install a package that you also have installed from a package archive, the version this function installs takes precedence.

View in manual

Probably introduced at or before Emacs version 29.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/package-vc.el.gz
;;;###autoload
(defun package-vc-install (package &optional rev backend name)
  "Fetch a package described by PACKAGE and set it up for use with Emacs.

PACKAGE specifies which package to install, where to find its
source repository and how to build it.

If PACKAGE is a symbol, install the package with that name
according to metadata that package archives provide for it.  This
is the simplest way to call this function, but it only works if
the package you want to install is listed in a package archive
you have configured.

If PACKAGE is a string, it specifies the URL of the package
repository.  In this case, optional argument BACKEND specifies
the VC backend to use for cloning the repository; if it's nil,
this function tries to infer which backend to use according to
the value of `package-vc-heuristic-alist' and if that fails it
uses `package-vc-default-backend'.  Optional argument NAME
specifies the package name in this case; if it's nil, this
package uses `file-name-base' on the URL to obtain the package
name, otherwise NAME is the package name as a symbol.

PACKAGE can also be a cons cell (PNAME . SPEC) where PNAME is the
package name as a symbol, and SPEC is a plist that specifies how
to fetch and build the package.  For possible values, see the
subsection \"Specifying Package Sources\" in the Info
node `(emacs)Fetching Package Sources'.

By default, this function installs the last revision of the
package available from its repository.  If REV is a string, it
describes the revision to install, as interpreted by the relevant
VC backend.  The special value `:last-release' (interactively,
the prefix argument), says to use the commit of the latest
release, if it exists.  The last release is the latest revision
which changed the \"Version:\" header of the package's main Lisp
file.

If you use this function to install a package that you also have
installed from a package archive, the version this function
installs takes precedence."
  (interactive
   (progn
     ;; Initialize the package system to get the list of package
     ;; symbols for completion.
     (package-vc--archives-initialize)
     (let* ((name-or-url (package-vc--read-package-name
                          "Fetch and install package: " t))
            (name (file-name-base (directory-file-name name-or-url))))
       (when (string-empty-p name)
         (user-error "Empty package name"))
       (list name-or-url
             (and current-prefix-arg :last-release)
             nil
             (intern (string-remove-prefix "emacs-" name))))))
  (package-vc--archives-initialize)
  (cond
   ((null package)
    (signal 'wrong-type-argument nil))
   ((consp package)
    (package-vc--unpack
     (package-desc-create :name (car package)
                          :kind 'vc)
     (cdr package)
     rev))
   ((and-let* (((stringp package))
               (backend (or backend (package-vc--guess-backend package))))
      (package-vc--unpack
       (package-desc-create
        :name (or name (intern (file-name-base package)))
        :kind 'vc)
       (list :vc-backend backend :url package)
       rev)))
   ((and-let* ((desc (assoc package package-archive-contents #'string=)))
      (package-vc--unpack
       (cadr desc)
       (or (package-vc--desc->spec (cadr desc))
           (and-let* ((extras (package-desc-extras (cadr desc)))
                      (url (alist-get :url extras))
                      (backend (package-vc--guess-backend url)))
             (list :vc-backend backend :url url))
           (user-error "Package `%s' has no VC data" package))
       rev)))
   ((user-error "Unknown package to fetch: %s" package))))