Re: [gentoo-dev] [PATCH 0/1] [RFC] greadme.eclass

[Florian Schmaus <flow@gentoo.org>]

[-- Attachment #1.1.1: Type: text/plain, Size: 3618 bytes --]

On 09/01/2024 10.59, Michał Górny wrote:
> On Tue, 2024-01-09 at 09:30 +0100, Florian Schmaus wrote:
>> On 06/01/2024 18.21, Michał Górny wrote:
>>> On Sat, 2024-01-06 at 18:01 +0100, Florian Schmaus wrote:
>>>> I really like the functionality of readme.gentoo-r1.eclass, as it
>>>> allows to communicate Gentoo-specific information about a package to
>>>> the user. Especially as it improves the signal-to-noise ratio of
>>>> messages arriving to our users.
>>>>
>>>> However, readme.gentoo-r1.eclass will only show this information on
>>>> new installs, but not if the information changed. This is a major
>>>> drawback. Furthermore, readme.gentoo-r1.eclass does not provide an API
>>>> to assemble the information via heredoc.
>>>
>>> Are you implying that readme.gentoo-r1 is unfixable and you need to
>>> start over, and have a third generation of eclasses to install a readme
>>> file?
>>
>> Not at all. See the second item of the TODO list in the eclass' description.
>>
>> That said, both eclasses are rather small,
>>
> 
> Since when, 300 lines to install a README file is "small"?

The eclass becomes very small if you remove the _GREADME_COMPRESS code. 
As I wrote, adding compression support to the eclass makes the code very 
complex.


>>>> The main item is doc compression. Right now, greadme.eclass defaults
>>>> to add the readme doc to the compression exclusion list via
>>>> "docompress -x". A mode where the readme doc is compressed, just as
>>>> readme.gentoo-r1.eclass does, can be activated by setting
>>>> _GREADME_COMPRESS. However, I believe this mode is fragile as it can
>>>> not be guaranteed that a binary for the used compression algorithms is
>>>> installed on the host [1].
>>>
>>> Dangling reference here.  In any case, documentation compression is
>>> a standard feature of the package manager.  If it doesn't work for
>>> whatever reason, I'd rather see you focus on find a good solution rather
>>> than working it around via abusing `docompress -x`.
>>
>> The problem is the lack of a guarantee that the utilities required to
>> decompress the file are available at installation time.
> 
> It's user's responsibility to ensure that the tools set in their
> make.conf are available.

What if the user obtained a binpkg that was compressed with a different 
algorithm than the one set in their make.conf? Of course, the binhost 
could have set FEATURES=-binpkg-docompress, but what if not?

Even if we say it is the user's fault, then the problem of handling a 
decompressor failure would still exist. The eclass does not gracefully 
continue when decompressing the doc file, but instead it runs into a 
die(). To address this we would need to make unpacker.eclass and 
unpack() aware of nonfatal. The latter would require a PMS change.

Or, I could duplicate unpack logic --- which is probably a lot to 
account for the various compression options --- in the eclass. But I 
suspect be both do not want that.


>> It gets even worse if you consider binpkgs, as you have surely read the
>> comment while looking at the code of the greadme.eclass.
> 
> See FEATURES=-binpkg-docompress.  That's the correct way to distribute
> binary packages.

Is that documented somewhere that this is the right way to distribute 
binary packages?


With the information I have right now, I do not see a better alternative 
than excluding the doc file from compression.

Are you willing a sacrifice a very sensible feature just to be able to 
compress what is usually a file of a few hundred of bytes?



- Flow


[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 17273 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 614 bytes --]