Re: [gentoo-dev] per-package USE documentation (from gentoo-doc)

[Jason Rhinelander]

Joel Konkle-Parker wrote:
 >
 >> My suggestion is that the USE flags be overhauled to put some order
 >> into it. Ideally, this would be done along the lines of Luke-Jr's
 >> post. Hence, the above should be split into mysql-dev and mysql-user
 >> or some such. The same could be done with the java USE flag.

This reminds me of the Redhat/Mandrake/etc. way of doing things, where 
you have mysql-dev.rpm, mysql-client.rpm, mysql-server.rpm, 
mysql-docs.rpm, etc.  Does anyone else think exploding the use flags 
into 5 times as many use flags is going to be a hassle?  Sure, it'd be 
nice when looking at individual cases, as mentioned, but when it comes 
right down to it my USE "line" in make.conf is already 4 lines long.

 > I whole-heartedly agree with the premise of "putting some order into
 > it". I still think part of that needs to be some sort of clear
 > documentation. 'mozilla +java' is pretty clear, but 'xfree +xml2' just
 > says to me "why does xfree need xml2, what does it do for it, and what
 > would happen if I didn't include it?". There needs to be some sort of
 > clear descriptions (optimally per-package) that allow people to make
 > informed decisions about which flags to include and which they can
 > safely discard.

It seems to me that a far better approach is the idea of per-package use 
flags, with some documentation in the package - so that something like 
``emerge -pvv packagename'' would show me not only which use flags are 
in effect, but what they do to the package.

So, yes to better (i.e. per-package) documentation, but no to exploding 
use flags 5 or 6 ways each.

For documentation, I suggest something like the following:

Inside abc-xyz/packagename-1.2.3-r4.ebuild:
...
IUSE="aaa bbb ccc"

WHYIUSE="aaa - gives you aaa client support
bbb - gives you bbb server support
ccc - makes <package> do strange and unusual things with ccc"
...

Then, when I, Gentoo User, run:

# emerge -pv packagename otherpackage

I'll see (nothing new):

These are the packages that I would merge, in order:

Calculating dependencies ...done!
[ebuild  N    ] abc-xyz/packagename-1.2.3-r4  +aaa -bbb -ccc
[ebuild  N    ] abc-xyz/otherpackage-4.3.2-r1  +gnome -curses +cgi

"Ah, that's interesting," I think to myself "I wonder what the cgi use 
flag does for 'otherpackage'?"  So I run:

# emerge -pvv packagename otherpackage

and I see:

These are the packages that I would merge, in order:

Calculating dependencies ...done!
[ebuild  N    ] abc-xyz/packagename-1.2.3-r4  +aaa -bbb -ccc
     aaa - gives you aaa client support
     bbb - gives you bbb server support
     ccc - makes packagename do strange and unusual things with ccc"
[ebuild  N    ] abc-xyz/otherpackage-4.3.2-r1  +gnome -curses +cgi
     gnome - adds gnome control center support
     curses - adds curses management support
     cgi - gives you management support via an installed CGI script


I think the above would be a VERY useful thing, at least once use flags 
are sorted out - but the sorting out that needs to happen is making use 
flags per-package, not to go in the direction of giving every package 
its own set of use flags.

--

-- Jason Rhinelander
-- Gossamer Threads, Inc.

--
gentoo-dev@g.o mailing list