What makes USE flags global or local?

[Fran]

Reading the documentation I see:

A global USE flag is used by several packages, system-wide. This is what most people see as USE flags.
A local USE flag is used by a single package to make package-specific decisions.

Huh? There are TONS of local USE flags used by more than one package. What makes "subversion" a global USE flag and "git" (used by 12 packages in portage) a local USE flag? Or the "server" USE flag, which is used by at least 30 packages and is local.

Is there any weird hidden rule when choosing the scope of a USE flag?

[NeddySeagoon]

Fran,

The devs determine from time to time if USE flags should be local or global.
Any dev can invent a new local flag ...
When the flag is used by several packages, possibly in different projected, for similar purposes, the interested devs may get together and decide on a common description. The flag than becomes global.

Its a question of configuration management of USE flags and their descriptions.

It makes no difference to users. Both sets of USE flags operate in exactly the same way.

[John R. Graham]

Well, the most important thing to realize is that "global" and "local" are merely documentation concepts. The Package managers have no knowledge at all of the distinction: all USE flags are treated the same and there's no implementation difference when using a global USE flag in an ebuild vs. a local USE flag.

That said, the semi-official threshold is about four, but documentation often lags implementation.

- John

[Fran]

Good to know it's just for documentation. I thought there was a difference in their treatment. I used to put global USE flags in make.conf and local ones in package.use, but lately I've realized it was retarded for some of the flags.

Thanks

[Genone]

The distinction has been kinda stupid for a while. It originally came from the need of a different documentation format for package-specific USE flags (use.desc vs. use.local.desc), but as these days descriptions are contained in metadata.xml the distinction is obsolete.

[aCOSwt]

At the end of the day the real problem is the actual meaning of the use flag.
The actual meaning of one use flag is directly related to the real impact it's setting gets over the package being concerned.
And it is an obvious evidence that, even with global use flags, the impact depends... on the package => You get a unique label and several different meanings.
So even global use flags should be understood locally.

This is *not* a documentation problem, this is a semantic problem.
The concept of global use flag is just void, whatever use flag impacts hic & nunc !

[Bones McCracker]

Good to know it's just for documentation. I thought there was a difference in their treatment. I used to put global USE flags in make.conf and local ones in package.use, but lately I've realized it was retarded for some of the flags.

Thanks

That's the important distinction, but you really must decide for yourself which flags it makes sense to apply globally. The euse tool is handy for this. 'euse -i <useflag>' lists all global and local descriptions.

[Yamakuzure]

The problem is to try to understand USE flags labeling the flags themselves as "global" or "local". If you turn the issue upside down, it becomes a lot clearer.

"Global" USE flag descriptions are those listed in $PORTDIR/profiles/use.desc - while "local" USE flag descriptions are listed in the packages metadata.xml (which are used to (still) generate $PORTDIR/profiles/use.local.desc btw.).

What is meant with global/local description? I try it with a theoretical example:

The "global" description for the USE flag "tiff" is: "Adds support for the TIFF image format".
Now lets say you write an ebuild for package media-gfx/foo, and this program generates some graphics that are saved in png format. You find a configure option to change this from png to tiff. This means that the behavior of your program changes if you enable "tiff" (which you added as a USE flag to allow users to toggle this configuration option).
You can not leave it as this, because the USE flag "tiff" does not the same to your package media-gfx/foo as is described in use.desc.
So you add an entry to your packages metadata.xml that reads:

Code: Select all

<flag name='tiff'>Write files in TIFF format instead of PNG</flag>

Now, while there is the "global" USE flag "tiff", it is a "local" USE flag for your package.

A real world example would be the "calendar" USE flag. While this flag "globally" enables support for calendars (not using mcal), it has a special meaning for dev-scheme/bigloo : It enables the build of an embedded library for calendar programming.

Or the "global" flag "pdf" should add general support for pdf files, but for app-doc/tldp-howto it means to install the documentation in PDF format. Which is something different.

Conclusion: For any USE flag a package supports, a special description (metadata.xml) is "local", otherwise the "global" description is in affect. Thus not the flag itself, but its meaning for a specific package changes.

[SamuliSuominen]

The distinction has been kinda stupid for a while. It originally came from the need of a different documentation format for package-specific USE flags (use.desc vs. use.local.desc), but as these days descriptions are contained in metadata.xml the distinction is obsolete.

How do you mean? Global use flags are still edited directly in profiles/use.desc where as profiles/use.local.desc gets generated from metadata.xml files. As in, the distiction is not obsolete.

[Genone]

The distinction has been kinda stupid for a while. It originally came from the need of a different documentation format for package-specific USE flags (use.desc vs. use.local.desc), but as these days descriptions are contained in metadata.xml the distinction is obsolete.

How do you mean? Global use flags are still edited directly in profiles/use.desc where as profiles/use.local.desc gets generated from metadata.xml files. As in, the distiction is not obsolete.

The same flag can exist in both (unlike in the old days before IUSE was actually used and flags were "upgraded" from local to global), so at best you could call the descriptions global/local. You can't say anymore "flag foo is a global/local flag" based on where it is defined as it is defined in the packages themselves these days.

[John R. Graham]

Well, "kinda stupid" is probably too harsh, but it is ironic that the explanatory documentation appears to be inadequate when the only real distinction between global and local USE flags is the documentation. Three of four times a year since I've been here, the same questions and misconceptions erupt:

• What's the difference between global and local USE flags?
• I've found a local USE flag that applies to seven different packages, all with identical descriptions. What gives? Is the documentation wrong? What should I be doing differently as a result?
• Global USE flags can only be in make.conf, right? Because USE flags in make.conf are applied globally to all packages.
• Local USE flags must be put in package.use because the scope of it is package local, right?
• The individual underlying package build system is aware of and takes action on USE flags, right?

Now, all that said, I don't want to get rid of the concept. When a USE flag applies to thousands of packages (e.g., doc), or even a few, it makes sense to have a single explanation accessible somewhere (currently /usr/portage/profiles/use.desc).

- John

[Bones McCracker]

I think the ability to apply semantically common configuration options across multiple packages is an important and distinguishing feature of Gentoo. It should be cultivated and improved, not allowed to become vestigial in effect because of ambiguous terminology or implementation details.

[John R. Graham]

100% agree.

- John

[Genone]

I never said to get rid of any feature, just the terms "local" and "global" in the context of use flags are obsolete. Rather talk about "default" and "specialized" descriptions of use flags (just a suggestion).

[smartass]

I think the ability to apply semantically common configuration options across multiple packages is an important and distinguishing feature of Gentoo. It should be cultivated and improved, not allowed to become vestigial in effect because of ambiguous terminology or implementation details.

I just wonder how have gentoo devs been able to maintain this. With most packages it's rather obvious what a flag with a global description does, but sometimes I check the ebuild just to find out what it actually does, because the general description is too loose. It works only in some places and the line is very thin.

I think there should be stricter and better policy on deciding whether to supply a specialized description for the flag. When the flag just enables some obvious feature (e.g. SSL support for a browser) the general global description is fine. But when it's not so obvious (e.g. consider the python use flag for vim - if you didn't know, would've you thought it makes it a python IDE (possibly binds to ipython) or that it enables python scripting of vim behavior?), a local description should be provided.
But that would of course result in even more micro management of use flags.

One thing I would appreciate would be some way to distinguish the type of the flag in emerge output, so I'd know whether I should check the description/ebuild.

So here's a concept:
In a way similar to USE_UNPACK the global use flags with different local meanings could have several components.
something like

Code: Select all

python = scripting bindings implementation

would mean that e.g. vim would have a python_scripting use flag, but if someone had the python flag enabled, all possible components of that flag would get selected.
This would make it clearer in the emerge output and would give more flexibility, e.g. being able to select only python bindings globally, but scripting only for some packages.

[Genone]

With most packages it's rather obvious what a flag with a global description does, but sometimes I check the ebuild just to find out what it actually does, because the general description is too loose. It works only in some places and the line is very thin.

I think there should be stricter and better policy on deciding whether to supply a specialized description for the flag. When the flag just enables some obvious feature (e.g. SSL support for a browser) the general global description is fine. But when it's not so obvious (e.g. consider the python use flag for vim - if you didn't know, would've you thought it makes it a python IDE (possibly binds to ipython) or that it enables python scripting of vim behavior?), a local description should be provided.

Three things:
- "being obvious" is a very subjective thing, esp. when talking about people who use a package extensively.
- coming up with a good description that can be read and understood quickly (less than a minute ideally) can be very tricky.
- people in general are lazy by default, so if the default description can (with some interpretation) be applied to their package there isn't much motivation to come up with a new one.
So if you find a package using a flag not matching the description file a bug, best with a improved description that can be copy+pasted without editing.

So here's a concept:
In a way similar to USE_UNPACK the global use flags with different local meanings could have several components.
something like

Code: Select all

python = scripting bindings implementation

would mean that e.g. vim would have a python_scripting use flag, but if someone had the python flag enabled, all possible components of that flag would get selected.
This would make it clearer in the emerge output and would give more flexibility, e.g. being able to select only python bindings globally, but scripting only for some packages.

This would make things even more complex and harder to understand. This concept had already been considered a long time ago (use groups), and once you get to think about how this behaves in all the little details and special cases it gets very messy. More so these days with all the extensions done to the system already.

[smartass]

I completely understand what you say about the lack of motivation to make specific descriptions. That's what the concept I was talking about could improve, because there would be ready-to-use specialized descriptions.

This would make things even more complex and harder to understand. This concept had already been considered a long time ago (use groups), and once you get to think about how this behaves in all the little details and special cases it gets very messy. More so these days with all the extensions done to the system already.

In which way do you think it would be harder to understand?
Could you point me to a discussion/bug involving these use groups please?

[Genone]

In which way do you think it would be harder to understand?

It's basically another, somewhat modified version of USE_EXPAND. In addition to the usual "where does this flag come from" issues it will also get people confused about the differences between USE_EXPAND and this new feature. Also need to handle namespace conflicts (e.g. python_xxx is already used).

Could you point me to a discussion/bug involving these use groups please?

http://www.gentoo.org/proj/en/glep/glep-0029.html
Can't point to discussions as there are no working mail archives. But things haven't become simpler over time.

[smartass]

Thank you.
The issues outlined in the GLEP are convincing.
I'll give it another thought, but I doubt I'll figure out a solution.
Would have been a great feature though ...