[gentoo-dev] New system to replace USE flags

[Dan Armak]

Hi all,

This is a followup to the discussion on the thread "Suggestion: DONT_USE 
flags". It describes a new (suggested) system to replace USE flags. I don't 
include the reasons for switching, they should be obvious.

This is a very long post. It includes not just ideas but syntax examples etc. 
This are just examples, sometimes not even suggestions. If even half of what 
I've written here is implemented, it will be complete success for this memo.

Comments are gladly accepted, only please try to read everything first.

-------

For clarity, let's call the new system With flags. 

With flags can serve different purposes:
1. They can set usage of shared libraries e.g. qt, sdl.
2. They can set ebuild-specific options and program-specific configuration 
details. This doesn't mean duplicating the program's configuration files, but 
rather more global things.
3. They can address h/w availability & utils (e.g. mmx, 3dnow, pcmcia) and 
other misc. things.
This isn't an important distinction, the above 3 things are just examples.

In make.globals (or somewhere else), a large number of With flags will be 
defined. They will all have default values (yes/no), either static or 
dynamically determined based on the values of other With flags.

Note: I may be misunderstaing the use of make.globals. What I need is a file 
with unchanging factory settings, which can be customized in make.conf.

An entry will look like this (2 lines):

qt=yes
an X interface library, used e.g. by KDE.

Every With flag can have 2 parts of increasing verbosity:
1. Name. ex: qt. Default value appended.
2. Description. ex: an X interface library, used e.g. by KDE.

The above gives an example of a static definition of a flag's default value. 
A dynamic definition would look like this:

flagA=yes
flagB=no
flagC=flagA		# gives yes
flagD=!flagA		# ! is not, gives no
flagE=flagA|flagB	# | is inclusive or, gives yes

and so on.

In make.conf there will be a partial list of flags, preferrably with short 
comments, for user setting. A user can thus override any default setting. He 
can also add to make.conf any flag from make.globals and set it, even if it 
isn't in make.conf's default list.

An example entry in make.conf:

qt=yes # override here
an X interface library, used e.g. by KDE. # This is a description

The make.conf entry's description might be longer than the make.globals one.

The default list should only include things which apply to more than just one 
or two packages, and which can be understood by the average end 
user/developer who isn't particularly familiar with the library/package 
discussed. No ebuild-specific (e.g. configuration) settings should go here.

The default way of will be non-interactive, essentially the same as it is 
now. However, emerge (and ebuild) will accept a --interactive parameter.

Whenever an ebuild needs to make any decision, it will call a function 
provided by emerge (or ebuild). So (I know this isn't a shell script, but I 
hate shell scripts!):

# need to know whether to build qt interface
result = with(qt, "foo uses qt to such and such an effect.") 

The second parameter to the with function is the description of the 
applicability of the With flag to this specific ebuild, and what the ebuild 
will do without it.
The ebuild will get a response, it doesn't need to know how the decision was 
made.

The function will have two modes: interactive and noninteractive.

In noninteractive mode (the default), the With answer will be decided based 
on the default value (from make.globals) and the user-defined value if 
present (make.conf).

In interactive mode, activated by the --interactive command line parameter, 
the user will be asked to decide. This is where the description of the flag 
is used.
The user will see:

# emerge --interactive foo.ebuild
Calculating dependencies.. done!
>>> emerge foo to /
Decide: qt (default yes, override No):
Description: an X interface library, used e.g. by KDE
Specifics: foo uses qt to such and such an effect.
[y/N]

Note: not all flags need to be defined somewhere! If an ebuild calls with on 
an undefined flag, it needs to supply a default value. This is the value 
returned to it in noninteractive mode. The call would become:

result = with(qt=yes, "foo uses qt to such and such an effect.") 

Dynamic definitions can be used as well as static, as defined earlier.

The next thing to have is choice betwen mutually exclusive With flags (this 
is sorely lacking in the USE system).

An ebuild might look so:
# Choose between mutually exclusive sound output interfaces
result=which(sdl_mixer, libmikmod, "Any one of these will do for sound.")

In interactive mode, the user will see:

# emerge --interactive foo.ebuild
Calculating dependencies.. done!
>>> emerge foo to /
Choose: sdl_mixer, libmikmod (default sdl_mixer):
Specifics: Any one of these will do for sound.
[sdl_mixer/libmikmod]

sdl_mixer is default, simply because it is named first. That is, the ebuild 
should pass the name of what it wants as default first.
Of course this will accept more than two flags at a time.
There is no Description (only Specifics) because this is not a 'generic' 
situation. An ebuild can request choice between any combination of flags in 
any order.
The last parameter passed to Which is thus the Specifics string, all the 
others are taken to be names of With flags.

In non-interactive mode, the which function will simply return the first flag 
named, sdl_mixer in this example.

As above, a flag undefined in make.globals and make.conf can be used. No 
default value for it is needed. You can just pass a list of flags.

-------

Subsystem: default values of mutually exclusive choices - groups:

It is true that an ebuild can pass any list of flags and get a result. 
However, for noninteractive operation, it would be very useful to assign 
default results outside the ebuild (i.e. not by selecting the order of flags 
passed to which).
For this purpose, flags can be 'registered' in make.globals (or make.conf) as 
belonging to a group (or several groups). An example make.* entry:

sdl_mixer=yes (audio-out)
Description of sdl_mixer.

libmikmod=yes (audio-out)
Description of libmikmod.

The entries thus classified will be arranged by group. The first flag in a 
group to be listed becomes the default choice for that group.

A flag can be part of any number of groups, or none. Example:
libggi=!libsdl (audio-out,video-out)

Whenever an ebuild calls which on flags that are all part of one group (e.g. 
audio-out), this becomes the default for an interactive choice, and the 
result returned from a noninteractive one.

The ebuild doesn't need to know the name of the group, or even that there is 
one.

And, if even this isn't enough, we could add a Groups section in make.* which 
would:
1. Optionally define a group as a list of flags, even if those flags don't 
specify themselves as part of the group.
2. Define the group's order.
3. Provide an extra description of the group.
For example:

<groups>
audio-out=libmikmod,sdl_mixer,libggi
The audio-out group is foobar foobar foo.

In this example, the order in whch the flags are defined is overriden, and 
libmikmod is set to be the new default choice.

The reason we have an entire list and not just a default value is subgroups. 
If an ebuild asks result=which(sdl_mixer,mikmod,libggi,"select audio lib") 
then it will get libmikmod (from noninteractive mode) since it's first in the 
list defined in make.*'s <groups>.
If however it says result=which(libggi,libmikmod,"subgroup choice") then it 
will get sdl_mixer because that's the best ('foremost') choice left without 
sdl_mixer.

-------

Comments welcome!

-- 

Dan Armak
Gentoo Linux Developer
Matan, Israel