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

[Florian Schmaus]

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.



Starting over strikes me as sensible in this case.

That said, both eclasses are rather small, and "fixing" readme.gentoo-r1 would consist of copying most of greadme into readme.gentoo-r1, while still having the "legacy" readme.gentoo-r1 functionality in it.

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`.

> It's basically
> a case of "standard feature X doesn't work for me sometimes, so I now
> randomly disable X via my eclass, and hope nobody notices".







I'll send out v2 of greadme.eclass soon.



Surely you would be able to correct me if I am wrong.

The problem is the lack of a guarantee that the utilities required to decompress the file are available at installation time. It gets even worse if you consider binpkgs, as you have surely read the comment while looking at the code of the greadme.eclass. The primary motivation for posting this RFC was to find a solution and avoid the "docompress -x" approach. However, I don't think there is one that does not require adjusting PMS to provide the guarantee that the eclass can decompress the compressed doc file. Adjusting PMS seems overkill just for avoiding to exclude a single small file from compression. I also tried to make the greadme eclass handle unpacking errors gracefully. This turned out to be harder than I hoped because most (all?) functions of unpacker.eclass are not nonfatal compatible. The same is true for unpack() from PMS, which is used by unpacker.eclass. Looking at the conditional _GREADME_COMPRESS code, you will find that adding support for compressing the doc file introduces a lot of complexity to the eclass. That would still make me consider it, but I can not see any reliable approach to unpacking that does not involve adjusting PMS.

I believe it is reasonable to simply install the readme doc
uncompressed, since they are typically only a few lines long. However,
if anyone can point out a way to achieve the desired functionality with
a compressed readme doc, then please let me know.

The compression mechanism automatically detects when the file is too
small to be worth compressing.  See PORTAGE_DOCOMPRESS_SIZE_LIMIT.

How is this mechanism helpful here?

- Flow

OpenPGP_0x8CAC2A9678548E35.asc
Description: OpenPGP public key

OpenPGP_signature.asc
Description: OpenPGP digital signature