[gentoo-dev] Ebuild Readability Issues

[gentoo-dev] Ebuild Readability Issues

[Rafael Cordones Marcos]

Hi,

I am new in writting ebuilds and in the process of writting the first
one I found that the variables used have quite cryptic names: P, S, PV,
PVR, ...

Wouldn't it be better to have also a longer name like:

PACKAGE_SOURCEDIR == S
PACKAGE_ROOTDIR = D
PACKAGE_WORKINGDIR = WORKDIR
PACKAGE_FULL_NAME = P
PACKAGE_NAME = PN
PACKAGE_VERSION = PV
PACKAGE_VERSION_SUFFIX: I have not found an equivalent existing
variable!

PACKAGE_GENTOO_REVISION == PR

I have tracked down where in portage these variables are set and I think
is in /usr/lib/python2.2/site-packages/portage.py
We could add the above mentioned new variables to the "settings" array:

<python-code>
settings["PACKAGE_SOURCEDIR"] = settings["S"]
settings["PACKAGE_ROOTDIR"] = settings["D"]
settings["PACKAGE_FULL_NAME"] = settings["P"]
settings["PACKAGE_NAME"] = settings["PN"]
settings["PACKAGE_VERSION"] = settings["PV"]
settings["PACKAGE_VERSION_SUFFIX"] = ?
settings["PACKAGE_GENTOO_REVISION"] = settings["PR"]
</python-code>

I can take care of creating the patches for portage.py and the
documentation in http://www.gentoo.org/doc/en/gentoo-howto.xml

This changes are backwards compatible with existing ebuilds and will
improve the readability of newly created ones. We should agree on the
anmes though: PACKAGE_SOURCEDIR, PKG_SOURCEDIR, PKG_SOURCE_DIRECTORY?

/Rafa

-- 
Rafael Cordones Marcos
mailto:rcm@sasaska.net
http://sasaska.net

--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Ebuild Readability Issues

[Johannes Ballé]

Am Monday 02 December 2002 12:23 schrieb Rafael Cordones Marcos:
> I have tracked down where in portage these variables are set and I think
> is in /usr/lib/python2.2/site-packages/portage.py

I agree that the names are really annoying for someone who is new to portage 
(I say this out of my own experience). It would have been kind of acceptable 
if ALL OF THEM were mentioned in the developers howto ...

-- 
Johannes Ballé <joba123@arcor.de>


--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Ebuild Readability Issues

[Rafael Cordones Marcos]

On Mon, 2 Dec 2002 13:06:50 +0100
Johannes Ballé <joba123@arcor.de> wrote:

> Am Monday 02 December 2002 12:23 schrieb Rafael Cordones Marcos:
> > I have tracked down where in portage these variables are set and I
> > think is in /usr/lib/python2.2/site-packages/portage.py
> 
> I agree that the names are really annoying for someone who is new to
> portage (I say this out of my own experience). It would have been kind
> of acceptable if ALL OF THEM were mentioned in the developers howto
> ...

Yes, but, lets face it, documentation allways lags behind code. That's
why if I see an ebuild that conains a reference to ${PACKAGE_NAME} I do
not have to goo look for any documentation to understand what it means
(as compared to ${P}).

/Rafa

-- 
Rafael Cordones Marcos
mailto:rcm@sasaska.net
http://sasaska.net

--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Ebuild Readability Issues

[foser]

Rafael Cordones Marcos wrote:
> Yes, but, lets face it, documentation allways lags behind code. That's
> why if I see an ebuild that conains a reference to ${PACKAGE_NAME} I do
> not have to goo look for any documentation to understand what it means
> (as compared to ${P}).

Let's face it, using those longer names would make ebuilds bigger, 
uglier and probably faultier :the longer the varname, the higher the 
risk of mistakes. Given the amount of times these vars are used it would 
probably also increase the portage tree a few megs in size, i don't 
think that's acceptable.

The best way to learn about ebuilds and variables inside them is still 
looking at other ebuilds.

- foser


--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Ebuild Readability Issues

[Johannes Ballé]

Am Monday 02 December 2002 14:03 schrieb foser:
> Let's face it, using those longer names would make ebuilds bigger,
> uglier and probably faultier :the longer the varname, the higher the
> risk of mistakes. Given the amount of times these vars are used it would

That's not correct. The longer the varname, the greater the amount of 
redundancy. But redundancy in general does not CAUSE mistakes, redundancy 
allows for easier detection of mistakes. For instance, take a one-letter var 
name. A single typo can make it a totally different variable. When you take 5 
or 8 letters, a single typo would cause the variable to be undefined, and you 
could check for that. (I admit checking for unset variables may be difficult 
in shell scripts, but you get my point.)

> probably also increase the portage tree a few megs in size, i don't
> think that's acceptable.

That is an argument, although it shouldn't impact the traffic so much as rsync 
uses compression, anyway (unless it's turned off for some reason, correct me 
if I'm wrong). And regarding disk space, I wouldn't mind to have a few megs 
more reserved for the portage tree on my boxes.

> The best way to learn about ebuilds and variables inside them is still
> looking at other ebuilds.

Definitely not. You need a good reference, too. It's a major pain to have to 
search for one particular feature in the portage tree that you'd like to add 
to your ebuild. I tried this. In addition, if you use var names such as $P or 
$PN, looking at other ebuilds to find out what they mean can take you a long 
time.

Of course, if you write 2 or 3 ebuilds a day, long var names can become a 
pain, too. Therefore, I vote for short var names that are documented :-)

For that matter, "man 5 ebuild" looks fine. Maybe the dev howto should 
explicitly point to that manpage, since I, too, missed it.

Greetings.

-- 
Johannes Ballé <joba123@arcor.de>


--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Ebuild Readability Issues

[Mike Frysinger]

On Monday 02 December 2002 07:04, Rafael Cordones Marcos wrote:
> Yes, but, lets face it, documentation allways lags behind code. That's
> why if I see an ebuild that conains a reference to ${PACKAGE NAME} I do
> not have to goo look for any documentation to understand what it means
> (as compared to ${P}).

read `man 5 ebuild` ... its *very* up to date ... i update it on every release 
of portage :P ... this goes for all manpages that portage installs ...

as for using ${PACKAGE NAME} in an ebuild, thats just what someone chose to 
use as a variable, it has no 'official' value ...
-mike

--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Ebuild Readability Issues

[Rafael Cordones Marcos]

On Mon, 2 Dec 2002 11:03:08 -0500
Mike Frysinger <vapier@gentoo.org> wrote:

> read `man 5 ebuild` ... its *very* up to date ... i update it on every
> release of portage :P ... this goes for all manpages that portage
> installs ...

Ok. I get the point. Shouldn't have used the words "let's face it". And
yes, 'man 5 ebuild' has all the info I needed. I was referering to the
HTML doc at http://www.gentoo.org/doc/en/gentoo-howto.xml

/Rafa

-- 
Rafael Cordones Marcos
mailto:rcm@sasaska.net
http://sasaska.net

--
gentoo-dev@gentoo.org mailing list