Fine‑Tuning Gentoo Packages with USE Flags: A Step‑by‑Step Guide

Goal

After this guide you will know how to:

• Define optional features for Gentoo ebuilds using USE flags.
• Apply flags globally or to individual packages.
• Rebuild only the packages that depend on the changed flags.
• Verify that the change took effect and roll back if necessary.

Prerequisites

• Gentoo 24.x or newer, fully updated (emerge --sync and emerge --update --deep @world).
• Root or sudo privileges to edit /etc/portage/make.conf and /etc/portage/package.use, and to run emerge.
• Installed app-portage/gentoolkit for equery (optional but recommended).

Step 1: Identify Desired Flags

Each ebuild exposes a set of USE flags that toggle optional features. To discover them, use:

equery use app-editors/vim

This lists all flags for vim. Flags prefixed with a minus (-) are disabled by default; those without are enabled by default.

Step 2: Apply Flags Globally or Per‑Package

Global Flags – /etc/portage/make.conf

To add a flag to every package, edit make.conf and append it to the USE variable. For example, to enable SSL for all packages and disable GTK support globally:

# /etc/portage/make.conf
USE="ssl -gtk"

Make sure to separate flags with spaces. Do not use commas or semicolons.

Per‑Package Flags – /etc/portage/package.use

When you want a flag only for a specific package, create or edit package.use. The syntax is:

category/package flag1 flag2

Example – enable gtk only for vim:

# /etc/portage/package.use
app-editors/vim gtk

For a wildcard that matches all packages in a category, use category/*. For example, to disable gtk for all packages in app-misc:

app-misc/* -gtk

Step 3: Rebuild Affected Packages

After changing USE flags, you must rebuild any package that now requires a different build configuration. Use the --ask and --verbose options to preview the action:

emerge --ask --verbose --update --deep @world

Key points:

• --deep ensures transitive dependencies are considered.
• Portage will list only the packages that will be rebuilt because of the flag change.
• Review the list carefully; large global changes can trigger many rebuilds.

If you prefer to rebuild just the packages that depend on a specific flag, you can narrow the set:

emerge --ask --verbose --update $(egrep "^app-editors/vim" /var/lib/portage/world)

However, the @world approach is safer because it respects the current world set and dependency graph.

Step 4: Verify the Change

After emergence completes, confirm that the flag is active:

1. Check active flags for a package:

   equery use app-editors/vim | grep gtk
   

   The output should show +gtk if enabled, -gtk if disabled.
2. Inspect the build log:

   grep -i "gtk" /var/log/emerge.log | tail -n 20
   

   Look for lines that indicate the flag was considered during compile.
3. Run emerge --info to see the global USE variable:

   emerge --info | grep USE
   

   The line should reflect your make.conf setting.

When using emerge --pretend before the real run, you can catch potential dependency conflicts early. For example:

emerge --pretend --verbose --update @world

Portage will list any packages that would be rebuilt and any errors that might occur.

Step 5: Rollback Options

If a rebuild fails or you decide the change was undesirable, you can revert it:

1. Undo the flag modification in make.conf or package.use.
2. Run a fresh emerge --ask --update --deep @world to rebuild affected packages with the previous configuration.
3. Alternatively, if you only want to remove packages that were built with the new flag and are no longer needed, run:

   emerge --depclean
   

   This removes orphaned packages, but use it cautiously after verifying the --pretend output.

Practical Example

Suppose you want to enable ssl support for python and gnome-terminal only, without touching other packages. Follow these steps:

1. Create /etc/portage/package.use entries:

   dev-lang/python ssl
   x11-apps/gnome-terminal ssl
   

2. Run a pretend emergence to see what will change:

   emerge --pretend --verbose --update @world
   

3. Approve the rebuilds and run the real command:

   emerge --ask --verbose --update @world
   

4. Verify the ssl flag is active:

   equery use dev-lang/python | grep ssl
   

Limitations & Notes

• USE flags are ebuild‑specific; a flag that exists for one package may not exist for another.
• Changing global flags can trigger massive rebuilds; consider using binhosts or emerge --usepkgonly to speed up the process.
• Always test changes on a staging system before applying them to production.
• Some flags are mutually exclusive; enabling one may automatically disable another.

Conclusion

Gentoo’s USE flags provide fine‑grained control over package features. By following the steps above, you can safely add or remove flags, rebuild only what’s necessary, and verify the outcome. This approach keeps your system lean, avoids unnecessary recompilation, and gives you confidence that the selected features are active.