[gentoo-dev] Re: USE flag documentation

[gentoo-dev] Re: USE flag documentation

[Duncan]

Marius Mauch <genone@gentoo.org> posted
20080101060928.2a500186.genone@gentoo.org, excerpted below, on  Tue, 01
Jan 2008 06:09:28 +0100:

> Most of the time when I see complaints about the description of USE
> flags (I'm fully aware of those) the issue isn't the format, just that
> noone else has come up with a better description.

There are, I believe, two complaints, but one you don't see often as many 
don't think it's currently possible with a global USE flag (and possible 
but seldom done with local flags).

The first complaint is poor descriptions in general.  "foo - Adds foo 
support" just doesn't cut it.  (See USE=glw, for instance.  USE=gif's 
"Adds GIF image support" is at least somewhat better, saying GIF is an 
image format, at least.  I haven't a clue what libGlw does, except that 
it says requires mesa, which I know is 3D, so I suppose it's related to 
that, but what if someone doesn't know what mesa is?)  This seems to be 
the one you are addressing.

The second complaint, a frustration I often find myself experiencing, is 
that particularly with global flags, it's difficult to see exactly what 
they do in a particular package without actually seeing what the ebuild 
does.  Does it add the dependency and link against it?  Does it install 
example code and/or documentation for it?  Does it install bindings for 
it?  Is it build (static) against the included version vs using the 
system copy?  Does it not change what's supported at all, only the 
library/codec implementation used to handle it (the case with mp3/lame/
whatever sometimes)?  Etc.

It'd sure be nice to be able to run an euse -i flag and get the details 
of what flag actually does for various packages, or euse -i flag package, 
and get the info for just that package.  It'd be /real/ nice if emerge 
had a -vv or -vvv mode, that spit out what all the use flags actually did 
for those packages, at the detail level of the questions above.  If 
whatever proposal makes that easier, I say go for it. =8^)

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

-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] USE flag documentation

[Mark Loeser]

[-- Attachment #1: Type: text/plain, Size: 727 bytes --]

Here is a newer revision of the GLEP.  I still have multiple methods of
solving this problem (mostly because I want and *need* input from people
as to what they would prefer).  Please tell me what you would want to
use so I can come up with a more precise specification.  What exactly do
we need this system to do that we can't do now?  Is overriding the USE
flag with use.local.desc sufficient and we just need to document the
current solution properly?

Please...let me know how you feel about this.

http://dev.gentoo.org/~halcy0n/gleps/glep-0054.html

Thanks,

-- 
Mark Loeser
email         -   halcy0n AT gentoo DOT org
email         -   mark AT halcy0n DOT com
web           -   http://www.halcy0n.com

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] USE flag documentation

[Yuri Vasilevski]

Hello,

On Sun, 13 Jan 2008 20:24:53 -0500
Mark Loeser <halcy0n@gentoo.org> wrote:

> What exactly do we need this system to do that we can't do now?

The only interesting thing I can think of, is to expose some of the USE
flags logic found in some ebuilds in a parseable fashion.

I'm talking about things like (from mplayer-1.0_rc2_p24929-r2.ebuild):

- Two flags are mutually exclusive:
  ( cdio implies !cdparanoia ) and (cdparanoia implies !cdio)
- A flag makes sense only if another flag is on:
  !encode implies !aac

This way portage will be able to inform/warn the user automatically
that the set of USE flags the user has chosen really means some other
thing. Something like:

[ebuild   R   ] media-video/mplayer-1.0_rc2_p24929-r2  USE="X cdio -aac#1 -cdparanoia#2 -encode ..."

#1 aac needs encode
#2 cdio conflicts with cdparanoia

But this logic will have to be exposed on a .ebuild level.

> Is overriding the USE flag with use.local.desc sufficient and we just
> need to document the current solution properly?

I would say yes.

Also, what would we gain switching to xml?
The format as it is now is trivially parseable and human friendly.
While if the data is in xml format it will be less human friendly, as
well as, it will be harder to extract the information from shell
scripts.

Kindest regards,
Yuri.
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] USE flag documentation

[Santiago M. Mola]

On 1/14/08, Yuri Vasilevski <yvasilev@gentoo.org> wrote:
>
> [ebuild   R   ] media-video/mplayer-1.0_rc2_p24929-r2  USE="X cdio -aac#1 -cdparanoia#2 -encode ..."
>
> #1 aac needs encode
> #2 cdio conflicts with cdparanoia

This can be implemented with use.desc/use.local.desc. Paludis already
does that by default.

> But this logic will have to be exposed on a .ebuild level.
>

I don't think this is worth an EAPI change, or adding new variables to
ebuilds. metada.xml USE flag documentation could be extended to cover
such cases if it's really needed... but is it?

-- 
Santiago M. Mola
Jabber ID: cooldwind@gmail.com
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] USE flag documentation

[Santiago M. Mola]

On 1/14/08, Santiago M. Mola <coldwind@gentoo.org> wrote:
> On 1/14/08, Yuri Vasilevski <yvasilev@gentoo.org> wrote:
> >
> > [ebuild   R   ] media-video/mplayer-1.0_rc2_p24929-r2  USE="X cdio -aac#1 -cdparanoia#2 -encode ..."
> >
> > #1 aac needs encode
> > #2 cdio conflicts with cdparanoia
>
> This can be implemented with use.desc/use.local.desc. Paludis already
> does that by default.
>

Sorry. Paludis shows USE flags, and overrides definitions with use.local.desc.
But stuff like "aac needs encode"  and "cdio conflicts with
cdparanoia" should be something separate from USE flag documentation.
As you said, it should be handled at ebuild level.

-- 
Santiago M. Mola
Jabber ID: cooldwind@gmail.com
-- 
gentoo-dev@lists.gentoo.org mailing list

[gentoo-dev] Re: USE flag documentation

[Ryan Hill]

Mark Loeser wrote:
> Here is a newer revision of the GLEP.  I still have multiple methods of
> solving this problem (mostly because I want and *need* input from people
> as to what they would prefer).  Please tell me what you would want to
> use so I can come up with a more precise specification.  What exactly do
> we need this system to do that we can't do now?  Is overriding the USE
> flag with use.local.desc sufficient and we just need to document the
> current solution properly?
> 
> Please...let me know how you feel about this.
> 
> http://dev.gentoo.org/~halcy0n/gleps/glep-0054.html
> 
> Thanks,

What do people think of this?

a) Keep use.desc as it is:  a list of common flags and a short general 
description of their meaning.

b) Keep use.local.desc as it is: a list of per-package flags that are specific 
to one to a few ebuilds (i think 5 is the number though i think 10 is more 
appropriate, but that's not relevant to this discussion).  Again, each has a 
short description.

c) Allow flags from use.desc to also exist in use.local.desc.  In the case that 
a flag for a package exists in both, the use.local.desc description overrides 
the use.desc one.  This allows a more specific per-package description of global 
flags.

d) Allow long descriptions in a package's metadata.xml, as some have begun to do 
already, for cases where more info is needed.  For example I'd like to explain 
exactly what the bindist flag on freetype does and what legal implications 
disabling it can have.

The reason I suggest we do it this way is it's very close to what we're already 
doing now.  The only thing we'd need to do is decide it's okay to do (c) and 
adapt our various utils to use the use.local.desc description when both exist. 
I actually planned on proposing something like this about a year ago but never 
got around to it.  But at the time I did some poking and found that several of 
our utils already did the right thing while the others needed minor adjustments 
(I think I had a one-line patch for equery).  We also needn't worry about 
breaking 3rd party tools.  The worst that would happen is they'd display the 
use.desc description, which is what they do now.

On the other hand, if there are any far-reaching changes we need made to the USE 
flag system - any features we wish we had or misfeatures we wish we didn't - now 
would be a good time to address them.


-- 
fonts,                                            by design, by neglect
gcc-porting,                              for a fact or just for effect
wxwindows @ gentoo     EFFD 380E 047A 4B51 D2BD C64F 8AA8 8346 F9A4 0662

-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] USE flag documentation

[Vlastimil Babka]

Santiago M. Mola wrote:
> But stuff like "aac needs encode"  and "cdio conflicts with
> cdparanoia" should be something separate from USE flag documentation.

Well, at least until it's handled at ebuild level, local USE flag 
documentation can be used to explain the implications to the user 
beforehand (ewarns work too, but only after user tries to actually 
install the package).

VB
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] Re: USE flag documentation

[Vlastimil Babka]

Ryan Hill wrote:
> What do people think of this?
> 
> a) Keep use.desc as it is:  a list of common flags and a short general 
> description of their meaning.

Good.

> b) Keep use.local.desc as it is: a list of per-package flags that are 
> specific to one to a few ebuilds (i think 5 is the number though i think 
> 10 is more appropriate, but that's not relevant to this discussion).  
> Again, each has a short description.
> 
> c) Allow flags from use.desc to also exist in use.local.desc.  In the 
> case that a flag for a package exists in both, the use.local.desc 
> description overrides the use.desc one.  This allows a more specific 
> per-package description of global flags.

Good.

> d) Allow long descriptions in a package's metadata.xml, as some have 
> begun to do already, for cases where more info is needed.  For example 
> I'd like to explain exactly what the bindist flag on freetype does and 
> what legal implications disabling it can have.

Right. Also why not also add short descriptions there, and deprecate 
use.local.desc when tools are converted? Placing package-local info to 
global files (when not needed to distinguish profiles as with 
package.use.mask etc) is icky.
Note that the metadata.xml should be able to record per-version 
differences somehow.

> On the other hand, if there are any far-reaching changes we need made to 
> the USE flag system - any features we wish we had or misfeatures we wish 
> we didn't - now would be a good time to address them.

I wish for use deps :P
Well, addressing conflicts and implications between flags at ebuild/PM 
level would be also nice, but really shouldn't affect the way 
documentation is handled, IMHO.

VB
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] USE flag documentation

[Piotr Jaroszyński]

On Monday 14 of January 2008 02:24:53 Mark Loeser wrote:
> Here is a newer revision of the GLEP.  I still have multiple methods of
> solving this problem (mostly because I want and *need* input from people
> as to what they would prefer).  Please tell me what you would want to
> use so I can come up with a more precise specification.  What exactly do
> we need this system to do that we can't do now?  Is overriding the USE
> flag with use.local.desc sufficient and we just need to document the
> current solution properly?
>
> Please...let me know how you feel about this.

Tbh, I don't have any issues with the current solution, but I may be missing 
something. "Rationale" doesn't seem to help though, afaics it is just saying 
that the current behaviour  needs to be documented and fwiw PMS draft covers 
this already:
http://dev.gentoo.org/~spb/pms.pdf - section 3.4.3

> http://dev.gentoo.org/~halcy0n/gleps/glep-0054.html

Please, don't use an already assigned GLEP number, it's a bit confusing. Note 
that 55 is taken as well.

-- 
Best Regards,
Piotr Jaroszyński
--
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] USE flag documentation

[Mark Loeser]

[-- Attachment #1: Type: text/plain, Size: 1190 bytes --]

Piotr Jaroszyński <peper@gentoo.org> said:
> Tbh, I don't have any issues with the current solution, but I may be missing 
> something. "Rationale" doesn't seem to help though, afaics it is just saying 
> that the current behaviour  needs to be documented and fwiw PMS draft covers 
> this already:
> http://dev.gentoo.org/~spb/pms.pdf - section 3.4.3

Which is fine, but PMS is just a draft.  I'm trying to see if everyone
can accept one solution, instead of throwing things into metadata.xml
and into use.local.desc without the process being documented in one place.
This is more of a proposal to see if we should even change how we do things
today.  Maybe we shouldn't, and that's what I'm trying to figure out...

> > http://dev.gentoo.org/~halcy0n/gleps/glep-0054.html
> 
> Please, don't use an already assigned GLEP number, it's a bit confusing. Note 
> that 55 is taken as well.

It wasn't taken when I first sent it (as far as I know).  I forgot to
change before resending.  Thanks for reminding me.

Thanks,

-- 
Mark Loeser
email         -   halcy0n AT gentoo DOT org
email         -   mark AT halcy0n DOT com
web           -   http://www.halcy0n.com

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: USE flag documentation

[Mark Loeser]

[-- Attachment #1: Type: text/plain, Size: 1204 bytes --]

Ryan Hill <dirtyepic@gentoo.org> said:
> a) Keep use.desc as it is:  a list of common flags and a short general 
> description of their meaning.

Sounds good.

> b) Keep use.local.desc as it is: a list of per-package flags that are 
> specific to one to a few ebuilds (i think 5 is the number though i think 10 
> is more appropriate, but that's not relevant to this discussion).  Again, 
> each has a short description.

Also fine.

> c) Allow flags from use.desc to also exist in use.local.desc.  In the case 
> that a flag for a package exists in both, the use.local.desc description 
> overrides the use.desc one.  This allows a more specific per-package 
> description of global flags.

Still doing alright :)

> d) Allow long descriptions in a package's metadata.xml, as some have begun 
> to do already, for cases where more info is needed.  For example I'd like 
> to explain exactly what the bindist flag on freetype does and what legal 
> implications disabling it can have.

Why can't this be done in use.local.desc?

-- 
Mark Loeser
email         -   halcy0n AT gentoo DOT org
email         -   mark AT halcy0n DOT com
web           -   http://www.halcy0n.com

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

[gentoo-dev] Re: USE flag documentation

[Ryan Hill]

Mark Loeser wrote:
> Ryan Hill <dirtyepic@gentoo.org> said:
>> a) Keep use.desc as it is:  a list of common flags and a short general 
>> description of their meaning.
> 
> Sounds good.
> 
>> b) Keep use.local.desc as it is: a list of per-package flags that are 
>> specific to one to a few ebuilds (i think 5 is the number though i think 10 
>> is more appropriate, but that's not relevant to this discussion).  Again, 
>> each has a short description.
> 
> Also fine.
> 
>> c) Allow flags from use.desc to also exist in use.local.desc.  In the case 
>> that a flag for a package exists in both, the use.local.desc description 
>> overrides the use.desc one.  This allows a more specific per-package 
>> description of global flags.
> 
> Still doing alright :)
> 
>> d) Allow long descriptions in a package's metadata.xml, as some have begun 
>> to do already, for cases where more info is needed.  For example I'd like 
>> to explain exactly what the bindist flag on freetype does and what legal 
>> implications disabling it can have.
> 
> Why can't this be done in use.local.desc?

My expectation is that `grep "flag" use.local.desc` will give me a list of 
packages using that flag (or having it in the description), one per line. 
Putting paragraphs in there doesn't seem right.

-- 
fonts,                                            by design, by neglect
gcc-porting,                              for a fact or just for effect
wxwindows @ gentoo     EFFD 380E 047A 4B51 D2BD C64F 8AA8 8346 F9A4 0662

-- 
gentoo-dev@lists.gentoo.org mailing list

[gentoo-dev] Re: USE flag documentation

[Ryan Hill]

Vlastimil Babka wrote:
> Ryan Hill wrote:
>> What do people think of this?
>>
>> a) Keep use.desc as it is:  a list of common flags and a short general 
>> description of their meaning.
> 
> Good.
> 
>> b) Keep use.local.desc as it is: a list of per-package flags that are 
>> specific to one to a few ebuilds (i think 5 is the number though i 
>> think 10 is more appropriate, but that's not relevant to this 
>> discussion).  Again, each has a short description.
>>
>> c) Allow flags from use.desc to also exist in use.local.desc.  In the 
>> case that a flag for a package exists in both, the use.local.desc 
>> description overrides the use.desc one.  This allows a more specific 
>> per-package description of global flags.
> 
> Good.
> 
>> d) Allow long descriptions in a package's metadata.xml, as some have 
>> begun to do already, for cases where more info is needed.  For example 
>> I'd like to explain exactly what the bindist flag on freetype does and 
>> what legal implications disabling it can have.
> 
> Right. Also why not also add short descriptions there, and deprecate 
> use.local.desc when tools are converted? Placing package-local info to 
> global files (when not needed to distinguish profiles as with 
> package.use.mask etc) is icky.
> Note that the metadata.xml should be able to record per-version 
> differences somehow.

Then instead of grepping a file I would need to read XML.  Also icky.  Utils 
would help, but then utils would need to implement an XML parser.


-- 
fonts,                                            by design, by neglect
gcc-porting,                              for a fact or just for effect
wxwindows @ gentoo     EFFD 380E 047A 4B51 D2BD C64F 8AA8 8346 F9A4 0662

-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] Re: USE flag documentation

[Chris Gianelloni]

[-- Attachment #1: Type: text/plain, Size: 695 bytes --]

On Tue, 2008-01-15 at 17:00 -0600, Ryan Hill wrote:
> My expectation is that `grep "flag" use.local.desc` will give me a
> list of packages using that flag (or having it in the description),
> one per line. Putting paragraphs in there doesn't seem right.

A single long line still fills this "requirement" for us.  However, it
does bring up the point.  Why even have use.local.desc (or
metadata.xml's <use> tag) at all?  Is there really a need for a *global*
list of flags that are ebuild-specific?  (I don't care or have much
opinion, either way, I'm merely presenting some topic for discussion on
this.)

-- 
Chris Gianelloni
Release Engineering Strategic Lead
Games Developer

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: [gentoo-dev] Re: USE flag documentation

[Alec Warner]

On 1/15/08, Chris Gianelloni <wolf31o2@gentoo.org> wrote:
> On Tue, 2008-01-15 at 17:00 -0600, Ryan Hill wrote:
> > My expectation is that `grep "flag" use.local.desc` will give me a
> > list of packages using that flag (or having it in the description),
> > one per line. Putting paragraphs in there doesn't seem right.
>
> A single long line still fills this "requirement" for us.  However, it
> does bring up the point.  Why even have use.local.desc (or
> metadata.xml's <use> tag) at all?  Is there really a need for a *global*
> list of flags that are ebuild-specific?  (I don't care or have much
> opinion, either way, I'm merely presenting some topic for discussion on
> this.)

The global use.* files are convenient because it means we don't need
to generate or push a cache for the data (like for metadata).  If it
was per package or per-ebuild we would need to generate a cache to
answer queries like 'what does the "foo" flag do'.

>
> --
> Chris Gianelloni
> Release Engineering Strategic Lead
> Games Developer
>
>
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] Re: USE flag documentation

[Mark Loeser]

[-- Attachment #1: Type: text/plain, Size: 1588 bytes --]

Ryan Hill <dirtyepic@gentoo.org> said:
> Mark Loeser wrote:
>> Ryan Hill <dirtyepic@gentoo.org> said:
>>> c) Allow flags from use.desc to also exist in use.local.desc.  In the 
>>> case that a flag for a package exists in both, the use.local.desc 
>>> description overrides the use.desc one.  This allows a more specific 
>>> per-package description of global flags.
>> Still doing alright :)
>>> d) Allow long descriptions in a package's metadata.xml, as some have 
>>> begun to do already, for cases where more info is needed.  For example 
>>> I'd like to explain exactly what the bindist flag on freetype does and 
>>> what legal implications disabling it can have.
>> Why can't this be done in use.local.desc?
>
> My expectation is that `grep "flag" use.local.desc` will give me a list of 
> packages using that flag (or having it in the description), one per line. 
> Putting paragraphs in there doesn't seem right.

One could argue that you can't do that currently for DEPEND strings and
such, so that seems like a possibly weak argument to me.  Just because
you can do something right now doesn't mean it was meant to be that way,
or shouldn't be changed to make things better :)

Either way, I would prefer (and I'm sure others will as well since it
will cut down on confusion) if we pick either use.local.desc or to move
them into metadata.xml.  Having it possibly be in both places just seems
silly.

-- 
Mark Loeser
email         -   halcy0n AT gentoo DOT org
email         -   mark AT halcy0n DOT com
web           -   http://www.halcy0n.com

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: USE flag documentation

[Donnie Berkholz]

On 18:45 Tue 15 Jan     , Alec Warner wrote:
> On 1/15/08, Chris Gianelloni <wolf31o2@gentoo.org> wrote:
> > On Tue, 2008-01-15 at 17:00 -0600, Ryan Hill wrote:
> > > My expectation is that `grep "flag" use.local.desc` will give me a
> > > list of packages using that flag (or having it in the description),
> > > one per line. Putting paragraphs in there doesn't seem right.
> >
> > A single long line still fills this "requirement" for us.  However, it
> > does bring up the point.  Why even have use.local.desc (or
> > metadata.xml's <use> tag) at all?  Is there really a need for a *global*
> > list of flags that are ebuild-specific?  (I don't care or have much
> > opinion, either way, I'm merely presenting some topic for discussion on
> > this.)
> 
> The global use.* files are convenient because it means we don't need
> to generate or push a cache for the data (like for metadata).  If it
> was per package or per-ebuild we would need to generate a cache to
> answer queries like 'what does the "foo" flag do'.

Since Chris only mentioned use.local.desc, I'm assuming he only meant 
local flags rather than use.desc also. In that case, asking what the 
"foo" local flag does doesn't make sense, because it does something 
different depending on the package you're curious about. Centralizing 
what feels like inherently local data seems odd to me. USE flag editors 
would still need to generate a complete list, though, so this would make 
more work for them.

Chris, I'm not entirely clear what you meant by your suggestion of also 
dropping metadata.xml <use>; where would we describe local flags?

Thanks,
Donnie
-- 
gentoo-dev@lists.gentoo.org mailing list

[gentoo-dev] Re: USE flag documentation

[Ryan Hill]

[-- Attachment #1: Type: text/plain, Size: 1375 bytes --]

Mark Loeser wrote:
> Ryan Hill <dirtyepic@gentoo.org> said:

>> My expectation is that `grep "flag" use.local.desc` will give me a list of 
>> packages using that flag (or having it in the description), one per line. 
>> Putting paragraphs in there doesn't seem right.

> One could argue that you can't do that currently for DEPEND strings and
> such, so that seems like a possibly weak argument to me.  Just because
> you can do something right now doesn't mean it was meant to be that way,
> or shouldn't be changed to make things better :)
> 
> Either way, I would prefer (and I'm sure others will as well since it
> will cut down on confusion) if we pick either use.local.desc or to move
> them into metadata.xml.  Having it possibly be in both places just seems
> silly.

If we have to choose between the two, then metadata.xml gets my vote (yeah i'm
contradicting myself here ;)).  I think the benefits of being able to write long
flag descriptions outweigh the benefits of having them all in one place.

I'd like it if we had a util that displayed the descriptions from metadata
before (if) we switch over though.


-- 
fonts,                                            by design, by neglect
gcc-porting,                              for a fact or just for effect
wxwindows @ gentoo     EFFD 380E 047A 4B51 D2BD C64F 8AA8 8346 F9A4 0662


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]