procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

; Refine some 'package-vc' docstrings

Browse source 
* lisp/emacs-lisp/package-vc.el (package-vc-heuristic-alist)
(package-vc-install-dependencies, package-vc-upgrade)
(package-vc-install, package-vc-install-from-checkout)
(package-vc-prepare-patch, package-vc-upgrade-all)
(package-vc-allow-side-effects)
(package-vc-default-backend): Refine docstrings.  (Bug#65386)
This commit is contained in:
Eshel Yaron 2023-08-18 21:59:10 +02:00 • committed by Philip Kaludercic
parent 804a96af28
commit 82b13f0d1c
1 changed files with 100 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

163
lisp/emacs-lisp/package-vc.el
View file

@ -94,7 +94,14 @@
(+ (or alnum "-" "." "_")) (? "/")))
eos)
. Bzr))
"Heuristic mapping URL regular expressions to VC backends."
"Alist mapping repository URLs to VC backends.
`package-vc-install' consults this alist to determine the VC
backend from the repository URL when you call it without
specifying a backend. Each element of the alist has the form
\(URL-REGEXP . BACKEND). `package-vc-install' will use BACKEND of
the first association for which the URL of the repository matches
the URL-REGEXP of the association. If no match is found,
`package-vc-install' uses `package-vc-default-backend' instead."
:type `(alist :key-type (regexp :tag "Regular expression matching URLs")
:value-type (choice :tag "VC Backend"
,@(mapcar (lambda (b) `(const ,b))
@ -102,12 +109,13 @@
:version "29.1")
(defcustom package-vc-default-backend 'Git
"Default VC backend used when cloning a package repository.
If no repository type was specified or could be guessed by
`package-vc-heuristic-alist', this is the default VC backend
used as fallback. The value must be a member of
`vc-handled-backends' and the named backend must implement
the `clone' function."
"Default VC backend to use for cloning package repositories.
`package-vc-install' uses this backend when you specify neither
the backend nor a repository URL that's recognized via
`package-vc-heuristic-alist'.
The value must be a member of `vc-handled-backends' that supports
the `clone' VC function."
:type `(choice ,@(mapcar (lambda (b) (list 'const b))
vc-handled-backends))
:version "29.1")
@ -140,20 +148,21 @@ the `clone' function."
(package-desc-create :name name :kind 'vc))
spec)))))))
(defcustom package-vc-selected-packages '()
"List of packages that must be installed.
Each member of the list is of the form (NAME . SPEC), where NAME
is a symbol designating the package and SPEC is one of:
(defcustom package-vc-selected-packages nil
"List of packages to install from their VCS repositories.
Each element is of the form (NAME . SPEC), where NAME is a symbol
designating the package and SPEC is one of:
- nil, if any package version can be installed;
- a version string, if that specific revision is to be installed;
- a property list, describing a package specification. For more
details, please consult the subsection \"Specifying Package
Sources\" in the Info node `(emacs)Fetching Package Sources'.
- a property list, describing a package specification. For possible
values, see the subsection \"Specifying Package Sources\" in the
Info node `(emacs)Fetching Package Sources'.
This user option will be automatically updated to store package
specifications for packages that are not specified in any
archive."
The command `package-vc-install' updates the value of this user
option to store package specifications for packages that are not
specified in any archive."
:type '(alist :tag "List of packages you want to be installed"
:key-type (symbol :tag "Package")
:value-type
@ -345,19 +354,26 @@ asynchronously."
nil pkg-file nil 'silent))))
(defcustom package-vc-allow-side-effects nil
"Whether to process :make and :shell-command spec arguments.
"Whether to run extra build commands when installing VC packages.
Some packages specify \"make\" targets or other shell commands
that should run prior to building the package, by including the
:make or :shell-command keywords in their specification. By
default, Emacs ignores these keywords when installing and
upgrading VC packages, but if the value is a list of package
names (symbols), the build commands will be run for those
packages. If the value is t, always respect :make and
:shell-command keywords.
It may be necessary to run :make and :shell-command arguments in
order to initialize a package or build its documentation, but
please be careful when changing this option, as installing and
updating a package can run potentially harmful code.
When set to a list of symbols (packages), run commands for only
packages in the list. When nil, never run commands. Otherwise
when non-nil, run commands for any package with :make or
:shell-command specified.
Package specs are loaded from trusted package archives."
This applies to package specifications that come from your
configured package archives, as well as from entries in
`package-vc-selected-packages' and specifications that you give
to `package-vc-install' directly."
:type '(choice (const :tag "Run for all packages" t)
(repeat :tag "Run only for selected packages" (symbol :tag "Package name"))
(const :tag "Never run" nil))
@ -415,15 +431,15 @@ otherwise it's assumed to be an Info file."
(when clean-up
(delete-file file))))
(defun package-vc-install-dependencies (requirements)
"Install missing dependencies, and return missing ones.
The return value will be nil if everything was found, or a list
of (NAME VERSION) pairs of all packages that couldn't be found.
(defun package-vc-install-dependencies (deps)
"Install missing dependencies according to DEPS.
REQUIREMENTS should be a list of additional requirements; each
element in this list should have the form (PACKAGE VERSION-LIST),
where PACKAGE is a package name and VERSION-LIST is the required
version of that package."
DEPS is a list of elements (PACKAGE VERSION-LIST), where
PACKAGE is a package name and VERSION-LIST is the required
version of that package.
Return a list of dependencies that couldn't be met (or nil, when
this function successfully installs all given dependencies)."
(let ((to-install '()) (missing '()))
(cl-labels ((search (pkg)
"Attempt to find all dependencies for PKG."
@ -457,7 +473,7 @@ version of that package."
(let ((desc-a (package-desc-name a))
(desc-b (package-desc-name b)))
(depends-on-p desc-a desc-b))))
(mapc #'search requirements)
(mapc #'search deps)
(cl-callf sort to-install #'version-order)
(cl-callf seq-uniq to-install #'duplicate-p)
(cl-callf sort to-install #'dependent-order))
@ -718,7 +734,10 @@ installed package."
;;;###autoload
(defun package-vc-upgrade-all ()
"Attempt to upgrade all installed VC packages."
"Upgrade all installed VC packages.
This may fail if the local VCS state of one of the packages
conflicts with its remote repository state."
(interactive)
(dolist (package package-alist)
(dolist (pkg-desc (cdr package))
@ -728,7 +747,10 @@ installed package."
;;;###autoload
(defun package-vc-upgrade (pkg-desc)
"Attempt to upgrade the package PKG-DESC."
"Upgrade the package described by PKG-DESC from package's VC repository.
This may fail if the local VCS state of the package conflicts
with the remote repository state."
(interactive (list (package-vc--read-package-desc "Upgrade VC package: " t)))
;; HACK: To run `package-vc--unpack-1' after checking out the new
;; revision, we insert a hook into `vc-post-command-functions', and
@ -791,34 +813,45 @@ If no such revision can be found, return nil."
;;;###autoload
(defun package-vc-install (package &optional rev backend name)
"Fetch a PACKAGE and set it up for using with Emacs.
"Fetch a package described by PACKAGE and set it up for use with Emacs.
If PACKAGE is a string containing an URL, download the package
from the repository at that URL; the function will try to guess
the name of the package from the URL. This can be overridden by
passing the optional argument NAME. If PACKAGE is a cons-cell,
it should have the form (NAME . SPEC), where NAME is a symbol
indicating the package name and SPEC is a plist as described in
`package-vc-selected-packages'. Otherwise PACKAGE should be a
symbol whose name is the package name, and the URL for the
package will be taken from the package's metadata.
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 specifes 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 VC
backend. The special value `:last-release' (interactively, the
prefix argument), will 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.
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.
Optional argument BACKEND specifies the VC backend to use for cloning
the package's repository; this is only possible if NAME-OR-URL is a URL,
a string. If BACKEND is omitted or nil, the function
uses `package-vc-heuristic-alist' to guess the backend.
Note that by default, a VC package will be prioritized over a
regular package, but it will not remove a VC package.
\(fn PACKAGE &optional REV BACKEND)"
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
@ -894,7 +927,7 @@ for the last released version of the package."
;;;###autoload
(defun package-vc-install-from-checkout (dir name)
"Set up the package NAME in DIR by linking it into the ELPA directory.
"Install the package NAME from its source directory DIR.
Interactively, prompt the user for DIR, which should be a directory
under version control, typically one created by `package-vc-checkout'.
If invoked interactively with a prefix argument, prompt the user
@ -936,13 +969,17 @@ prompt for the name of the package to rebuild."
;;;###autoload
(defun package-vc-prepare-patch (pkg-desc subject revisions)
"Send patch for REVISIONS to maintainer of the package PKG using SUBJECT.
The function uses `vc-prepare-patch', passing SUBJECT and
REVISIONS directly. PKG-DESC must be a package description.
"Email patches for REVISIONS to maintainer of package PKG-DESC using SUBJECT.
PKG-DESC is a package descriptor and SUBJECT is the subject of
the message.
Interactively, prompt for PKG-DESC, SUBJECT, and REVISIONS. When
invoked with a numerical prefix argument, use the last N
revisions. When invoked interactively in a Log View buffer with
marked revisions, use those."
marked revisions, use those.
See also `vc-prepare-patch'."
(interactive
(list (package-vc--read-package-desc "Package to prepare a patch for: " t)
(and (not vc-prepare-patches-separately)