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

Previous Next

Full log

View this message in rfc822 format

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: bug#78844: 30.1; feature request: public interface for querying builtin packages and versions
Date: Sat, 28 Jun 2025 10:10:03 +0300

> From: Xiyue Deng <manphiz <at> gmail.com>
> Cc: spwhitton <at> spwhitton.name, 78844 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
> Date: Fri, 27 Jun 2025 17:25:41 -0700
> 
> >> 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.
> >
> 
> Admittedly I tried to be lazy and want to just add the new functions to
> an existing section but didn't find any good fit.  I just bit the bullet
> and added a new section in package.texi for these functions.  Please
> help proofread.

Thanks, comments below.  However, packages.texi is not the right place
for this stuff, because it's for the user manual, not for the ELisp
reference manual.  Since these APIs are for Lisp programmers, they
should be documented in the ELisp manual, and the chapters I mentioned
are in that manual.

> >> +(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.
> 
> To be precise, package--builtin-versions doesn't have all the built-in
> packages (which I think is a subset of the list populated by
> package--builtins).  As here we are more interested in packages that do
> have a version associated, I have renamed the function to
> `package-versioned-builtin-packages' to hopefully better convey the
> intention.  Let me know if this is desirable.

The renaming could be fine if the intended users of this API will
indeed only want to know about versioned built-in packages, and won't
care about those who have no versions.  Is that in fact true?  If so,
why aren't unversioned packages important?

If we do want to return the built-in packages that have no versions,
then the name should remain as it was, and we should instead amend the
implementation to also return packages that have no versions.

> +@node Package Information
> +@section Get built-in packages and versions
> +@cindex package information
> +
> +Emacs ships a list of built-in packages which may also be packaged
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Emacs ships the packages themselves, not a list of packages.

Previous Next

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