GNU bug report logs - #78844
30.1; feature request: public interface for querying builtin packages and versions

Previous Next

Full log

Message #50 received at 78844 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Xiyue Deng <manphiz <at> gmail.com>
Cc: 78844 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca, spwhitton <at> spwhitton.name
Subject: Re: bug#78844: 30.1;
 feature request: public interface for querying builtin packages and
 versions
Date: Fri, 27 Jun 2025 16:01:54 +0300

> Cc: 78844 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
> From: Xiyue Deng <manphiz <at> gmail.com>
> Date: Fri, 27 Jun 2025 03:34:25 -0700
> 
> > and see if these packages need documentation in the Elisp manual (they
> > may or may not).
> >
> 
> I don't seem to find any Elisp manual for package.el (there is one in
> the Emacs manual but only has documents for user facing interfaces for
> the package buffer).  But do let me know if there is.

There's the "Packaging" chapter in the ELisp manual.  Whether it is a
suitable place to add these interfaces depends on who is the intended
audience of the interfaces.  If that chapter is not suitable, maybe
the "Loading" chapter is a better place.

> +(defun package-builtin-packages ()
> +  "Return a list of builtin package symbols.
> +The returned list is not guaranteed to be sorted."

This doc string is too biased towards implementation, IMO.  I would
rephrase it as follows:

    Return a list of all the built-in packages.
  The return value is a list of names of built-in packages represented
  as symbols.

I don't see a need to mention that the list is not sorted, because not
saying it's sorted should be enough for users not to rely on that.
(As a matter of fact, I think the list will be sorted, because
package--builtin-versions is sorted.)

> +(defun package-builtin-package-version (package)
> +  "Return the version-list of PACKAGE (symbol).

This uses "version-list", which is not accepted terminology in Emacs.
I suggest

    Return the version of a built-in PACKAGE given by its symbol.
  Value is a list of integers representing the version of PACKAGE,
  in the format returned by `version-to-list', or nil if PACKAGE
  has no version or is not a built-in package.

> diff --git a/etc/NEWS b/etc/NEWS
> index eb85baae341..e940b5fce17 100644
> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -2607,6 +2607,13 @@ sleep state.
>  and set the top-level buffer-local value of a variable.  A top-level
>  value is the one that variable has outside of any let-bindings.
>  
> ++++
> +** New functions to query builtin package information.
> +'package-builtin-packages' returns a list of symbols of built-in
> +packages; 'package-builtin-package-version' returns the version-list of
> +a given package symbol.  These functions provide stable interfaces for
> +external tools to query built-in package information.

This should go under the "Package" section in NEWS.

Thanks.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.