[gentoo-portage-dev] Re: Ebuild - portage variable names

[Duncan]

Boris Vinogradov posted on Tue, 27 Nov 2018 21:13:35 +0300 as excerpted:

> I use gentoo about 8 year. I already try to write ebuild for my package
> but I think it's difficult to everyone who do it in the first time.
>
> Because ebuild have strange short name for common portage variable such
> as {P}, {PV}, {PN} etc. Another developers use these modified variables
> with name and preffix MY, for example {MY_P}, {MY_PV}. I think it isn't
> readable because everyone who read and write ebuilds sometime may be
> foget their means.
>
> I propouse to use human readble variable names for portage variables,
> such as {PATH} instead {P}, {PACKAGE_N}/{PACKAGE_NAME} instead {PN},
> etc... Human isn't a computer who knowns evething point of
> https://devmanual.gentoo.org/ebuild-writing/variables/index.html and
> other portage internals.
>
> I think it's major for everyone gentoo developer because ebuild is face
> of portage system and main component of gentoo unique feature.

It's worth noting that ebuilds conform to a gentoo common standard called 
Package Management Specification (PMS), which defines ebuild-critical 
variable names such as {P}, {PV}, etc, and that there are package 
managers other than portage which along with portage depend on ebuilds 
conforming to this standard or they will fail to function correctly.

Updates to this standard are usually done via defining new EAPIs, with 
EAPI=7 being the current latest (tho note that while all officially 
approved APIs have been sequential numeric, EAPIs are specifically not 
required to be numeric, a historic experimental EAPI was named 5-hdepend, 
for instance).  Ideas for a new EAPI are proposed and discussed, 
generally with a preliminary approval by the Gentoo council before 
implementation in portage (as the defined PM reference implementation), 
after which a final council approval is required before the new EAPI is 
allowed to be used in the Gentoo tree.

So to propose human-readable standard var names you'd need to propose the 
change as part of a new EAPI and get it approved as such, but of course 
the existing EAPIs would remain in use for some time, so developers would 
continue to need to know the existing EAPI vars until they are fully 
deprecated and all ebuilds containing them are removed from the tree.

And honestly I must say I'm a bit skeptical, in part because in the 
decade and a half I've been a gentooer (user not dev) myself, I've not 
seen this sort of proposal before, so I suspect most devs must get 
comfortable with the existing short vars pretty quickly, and would resent 
the "churn for no good reason" and consequent relearning a wholesale 
switch to "human readable" would mean for them.  So I doubt its chances 
at approval... tho I wouldn't really mind being proven wrong on this 
point if you're up for the longer term drive to approval it'd take, 
because...

As for me personally, as another user, when I'm working on modifying 
ebuilds and don't remember the specifics of a standard var or function, I 
open the ebuild (5) manpage in another VT or terminal window, and use it 
for reference.

Another alternative is the app-doc/pms "Gentoo Package Manager 
Specification" package, which contains the specific standards definitions 
along with a nicely printable quick-reference card listing which EAPIs 
define what.  I have that installed too, as I suspect most devs and 
advanced users doing ebuild work do, tho as I mentioned I personally tend 
to find the ebuild (5) manpage easier for a quick lookup, and only tend 
to use PMS when I'm checking details not in the ebuild (5) manpage or I 
need the specific wording of the agreed PMS standard.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman