On checking portage-3.0.68 NEWS I see FEATURES=export-pms-vars mentioned with bug #721088. Upon install I checked the make.conf manpage and... it's not documented under FEATURES, nor is "export-pms" found in the page at all (so it's not that the info is there, just merged with another entry so hard for a human to find, as happened with another new feature a few releases ago). Indeed, checking the closing commit: https://gitweb.gentoo.org/proj/portage.git/commit/?id=c75b61b523457f8798c66afe4bcdc1708408ea00 ... I see no manpage changes at all. =:^( Given a local policy that the value of all available FEATURES should be explicitly set (with or without a prepended -), I need documentation to decide how I want to set it. I normally consider the make.conf manpage FEATURES section that documentation, and any deviation from the FEATURES and feature behavior it describes a bug in either the code or the documentation. (In the absence of that here I fell back to the mentioned bug and the commit log for its closing commit.) So this is that documentation bug, now filed. (FWIW:1 The also mentioned and apparently new FEATURES=selinux /does/ appear in the make.conf manpage FEATURES section, as expected.) (FWIW:2 Since I know about it now to turn it back on if needed, I decided I'd set -export-pms-vars and see what blows up. Haven't actually run anything with it yet...) (FWIW:3 I considered adding this to the above-mentioned bug #721088, but decided since there's now a release with the bug, this should be filed as a new bug against that release.)
I understand that the lack of description of the 'export-pms-vars' feature is frustrating if you have a local policy to explicitly set or unset all available FEATURES. However, FEATURES=export-pms-vars is meant as opt-in mechanism for potential new EAPI behavior to detect potential ebuild issues. It is nothing that end-users should consider, nor is it something that ebuild developers have to consider. It is mostly for those with interest in EAPI / PMS development. I would argue that documenting 'export-pms-vars' in a man page, which is primarily targeted to users, is maybe not the right thing to do. Portage's man pages are already loaded with a ton of knobs and documenting a knob that isn't meant for users does not strike me as sensible. That said, I should have maybe chosen a different mechanism than FEATURES to opt-in to potential new EAPI behavior. An environment variable comes to mind. > (FWIW:2 Since I know about it now to turn it back on if needed, I decided I'd > set -export-pms-vars and see what blows up. Haven't actually run anything > with it yet...) Yes, you want FEATURES=-export-pms-vars which is the default.
It must be documented if it exists, including the default value and its purpose.
To be explicit: I'll drop it from Portage if not documented. Documenting it should've been done anyway, but the rationale for not documenting (which I disagree with) should've been in the commit message nonetheless.
(In reply to Florian Schmaus from comment #1) > Yes, you want > FEATURES=-export-pms-vars > which is the default. I really hope that this is a typo and that the feature is enabled by default. PMS variables must be exported to the environment in EAPI 8 and earlier, and users should never ever disable this. The purpose of the feature is entirely meant for testing by Portage developers. Also, this should be documented, with a big warning that the feature is not PMS compliant and will likely break stuff in EAPI 8.
(In reply to Ulrich Müller from comment #4) > (In reply to Florian Schmaus from comment #1) > > Yes, you want > > FEATURES=-export-pms-vars > > which is the default. > > I really hope that this is a typo and that the feature is enabled by default. It is a typo. The feature was initially called do-not-export-pms-vars. Guess that threw me off. And yes, we did not change existing EAPI behavior.
ping!
I am sorry, but unfortunately, my Gentoo time is currently somewhat limited. I still believe I made a mistake when I added FEATURES="export-pms-vars." This feature tried to provide ebuild authors with an easy way to check their ebuild's behavior under potential future EAPI rules. However, being able to toggle whether or not PMS variables are exported, independent of the EAPI, is not something users should do (nor care about). Therefore, we should not complicate portage's documentation further, which is already difficult to comprehend. Instead, I have suggested in a previous comment that we drop FEATURES="export-pms-vars" and replace it with an environment variable. To clearly distinguish between settings exposed to users and more experimental settings for "experts." This argument is similar, but not identical, to https://github.com/gentoo/portage/pull/1427#discussion_r1947934008 I could try to allocate some time to work on this if we decide to go down this route. Otherwise, please feel free to proceed as you wish.
