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
[Message part 1 (text/plain, inline)]
Hi Eli,
Eli Zaretskii <eliz <at> gnu.org> writes:
>> 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.
>
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.
>> +(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 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.
Indeed, this seems to be an unnecessary detail to call out.
> (As a matter of fact, I think the list will be sorted, because
> package--builtin-versions is sorted.)
>
In fact, in 30.1 (which I'm using) it's almost sorted in descending
alphabetic order except that the last item is "emacs" and the second to
last is "all-out". Anyway, as you mentioned, not mentioning the
ordering in the docstring should indicate that a caller should not make
any assumptions.
>> +(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.
>
Adapted.
>> 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.
>
Moved there.
> Thanks.
PTAL.
--
Regards,
Xiyue Deng
[0001-Add-public-interfaces-for-accessing-builtin-package-.patch (text/x-diff, attachment)]
[signature.asc (application/pgp-signature, inline)]
This bug report was last modified 27 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.