Ebuild - portage variable names

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Ebuild - portage variable names

Boris Vinogradov
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.

Thanks,
Boris Vinogradov
Reply | Threaded
Open this post in threaded view
|

Re: Ebuild - portage variable names

Duncan-42
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