USEful - Audit and manipulate USE and EXPAND_USE flags
TL;DR Show a compact and filtered list of USE flags which haven’t been explicitly set by you so that you can review them. And more.
The USEful(1) command enables auditing Gentoo’s USE and EXPAND_USE flags. The reason why USEful was originally written is to list flags enabled or disabled implicitely by either the profile or ebuild IUSE defaults. However, other features are available such as listing what packages have a given EXPAND_USE variable or flag, figuring out which USE flags in your /etc/portage/make.conf or package.use became useless over time (which is where the name USEful came from), and more are planned in the future.
USEful takes advantage of caching to speed up computation. Once the cache is primed, USEful is much faster than your average USE manipulation utility. This comes in very handy, for example, when initially setting up a new machine or updating one that hasn’t been updated in a long time. Thus is typically when you need to review a lot of USE and EXPAND_USE flags which state, either in the selected profile or in ebuilds, may be set to an undesirable default.
Show all implicitely set USE and EXPAND_USE flags. If this comes out empty it means all flags have been looked at, either enabled, disabled or ignored. This is the most important command.
USEful flags all
Show silently enabled USE flags to make sure I really want them enabled:
USEful enabled
Show silently disabled USE flags to see which ones I may need to enable:
USEful disabled
List all EXPAND_USE variables in @world:
USEful expands
Show all VIDEO_CARDS flags, keep minus symbol in front to see which are disabled:
USEful -k all-flags VIDEO_CARDS
Now, show all packages in @world with the VIDEO_CARDS variable:
USEful packages VIDEO_CARDS
Show all LIBREOFFICE_EXTENSIONS flags disabled by default because I bet I want those enabled:
USEful disabled LIBREOFFICE_EXTENSIONS
Show PYTHON_TARGETS not explicitly set by me:
USEful enabled PYTHON_TARGETS
- -1, -c, --column, --in-column
-
Show output one item per line only. Convenient for programmatical use.
- -k, --keep, --keep—minus
-
Keep the minus symbol in front of disabled flags. The default is to remove it, in which case, when listing both enabled and disabled flags, those which would appear both enabled and disabled will only appear once without the minus symbol in front.
- --[no-]prepend
-
Prepend flags (or don’t) with the EXPAND_USE variable name followed by an underscore. When showing output in column --prepend is the default. Otherwise the default is --no-prepend.
- -q, --quiet
-
Suppress all informational output (errors, warning, etc…). Convenient for programmatical use.
- -r, --regen, --force-regen
-
Force regeneration of cache.
- ad, all-disabled ['EXPAND_USE variable']
-
List all disabled flags for the EXPAND_USE variable passed as parameter. No filtering is performed, thus all disabled flags are shown, except those masked, forced, removed or bound to FEATURES settings. If no EXPAND_USE variable is passed then the default is USE.
- ae, all-enabled ['EXPAND_USE variable']
-
List all enabled flags for the EXPAND_USE variable passed as parameter. No filtering is performed, thus all enabled flags are shown, except those masked, forced, removed or bound to FEATURES settings. If no EXPAND_USE variable is passed then the default is USE.
- af, all-flags ['EXPAND_USE variable']
-
List all enabled and disabled flags for the EXPAND_USE variable passed as parameter. Some flags may appear both as enabled and disabled meaning both states appear in @world for various possible reasons. If the `-k' option is used, these flags will appear only once, without the minus symbol. If no EXPAND_USE variable is passed then the default is USE.
- ap, all-packages
-
List all packages and their flags for USE and all EXPAND_USE variables. The output format is similar to what `emerge -vpe @world' would produce, albeit stripped of information not pertinent to USEful. Absolutely no filtering is done, including for flags which are masked, forced, removed or bound to FEATURES settings.
- d, disabled ['EXPAND_USE variable']
-
List all implicitely disabled flags for the EXPAND_USE variable passed as parameter. Flags explicitly disabled in /etc/portage/make.conf or /etc/portage/package.use, as well as flags ignored using config files in /etc/USEful, will not be listed. If no EXPAND_USE variable is passed then the default is USE.
- e, enabled ['EXPAND_USE variable']
-
List all implicitely enabled flags for the EXPAND_USE variable passed as parameter. Flags explicitly enabled in /etc/portage/make.conf or /etc/portage/package.use, as well as flags ignored using config files in /etc/USEful, will not be listed. If no EXPAND_USE variable is passed then the default is USE.
- x, expands
-
List all EXPAND_USE variables.
- f, flags ['EXPAND_USE variable']
-
List all implicitely enabled and disabled flags for the EXPAND_USE variable passed as parameter. Flags explicitly enabled or disabled in /etc/portage/make.conf or /etc/portage/package.use, as well as flags ignored using config files in /etc/USEful, will not be listed. If no EXPAND_USE variable is passed then the default is USE.
- h, help
-
Show a cheatsheet of commands and options.
- p, packages ['EXPAND_USE variable']
-
List all packages having the EXPAND_USE variable passed as parameter. The output format is similar to what `emerge -vpe @world' would produce, albeit stripped of information not pertinent to USEful. Flags which are masked, forced, removed or bound to FEATURES settings are not shown. If no EXPAND_USE variable is passed then the default is USE. The `all' paramater passed instead of an EXPAND_USE variable name does not work for this command.
- w, where 'flag' ['EXPAND_USE variable']
-
Show in which package(s) if any the flag is present. Flags which are masked, forced, removed or bound to FEATURES settings will not be shown. If no EXPAND_USE variable is passed then the default is USE. If the `-k' option is used, then the exact value passed as `flag' is searched for, including a possible minus symbol in front. This enables to not only search for a flag but also for its enabled or disabled state. Without the `-k' option both enabled and disabled occurrences of the flag will be shown. Note that in this case if `flag' starts with a minus symbol then it is stripped. The `all' paramater passed instead of an EXPAND_USE variable name does not work for this command.
Most commands will accept `all' instead of an EXPAND_USE variable name. This will instruct the command to loop through all the possible EXPAND_USE variables, including USE, and show them as nicely as possible depending on other settings.
Of all the commands which take an EXPAND_USE variable name as a parameter, this is currently not allowed for the `packages' and `where' command.
The point of using USEful is to let you be easily able to review implicitely set flags. However, in most cases there are going to be a lot of them making the output of USEful overwhelming. One way around that is to explicitly set all flags, which is often an undesirable solution. When you don’t want to set some flags explicitly but want to mark them as reviewed so that they don’t perpetually come back and clutter the output of USEful, you can ignore them.
If you want to ignore an implicitly disabled flag you need to add a minus symbol on front of it. You can either ignore the enabled or disabled flag, or both of them. In this latter case you need to list it twice, both with and without the minus symbol.
In order to globally ignore flags, just add them to a file in /etc/USEful named the same as the EXPAND_USE variable they belong to (or USE for USE flags). There can be more than one ignored flag per line, you can skip lines, and a line starting with the sharp sign (#) is a comment.
To ignore a USE or EXPAND_USE flag only for a specific atom, add it to /etc/USEful/package.use. This files’s name is not random: its syntax is exactly the same as that of /etc/portage/package.use.
You should update your system to the current on-disk state of your ebuild repositories (i.e., Portage tree and overlays) before running USEful. Otherwise results cannot be guaranteed.
Not implemented yet (i.e., TODO list):
-
option to list only global or local flags
-
support wildcards in /etc/portage/package.use and /etc/USEful/package.use
-
support repository constraints in /etc/portage/package.use and /etc/USEful/package.use
-
automatically detect stale cache
-
cache in background (daemon?)
-
add enable/disable/prune/sort with alphabetical sorting
-
implement useless command
-
more exhaustive error checking
USEful is being developped by Denis Dupeyron <[email protected]>.