Gentoo USE Flags: Enable SSL Support for curl

Quick take: enable a feature with a single USE flag

To add OpenSSL support to the curl package in Gentoo, add USE="ssl" to /etc/portage/make.conf and rebuild the package with emerge -av curl. Portage will flag the change, recompile curl with OpenSSL defines, and the new capability is visible via equery uses curl.

How Gentoo USE flags work

Gentoo's Portage package manager uses the USE variable to control optional features at build time. A USE flag is a keyword that, when enabled, adds preprocessor defines, enables optional code paths, or adjusts dependency requirements for the emerging package. Portage reads the flag during emerge, applies the relevant compiler options, and modifies dependency constraints that require the associated library.

Key mechanism

Each flag corresponds to a feature that a package can optionally support. For example, the ssl flag for curl tells Portage to link against an SSL library such as OpenSSL or GnuTLS. If the flag is disabled, curl is built without cryptographic support. The flag does not install software on its own; it only influences how Portage configures the build.

Worked example: adding OpenSSL support to curl

1. Edit make.conf

Open /etc/portage/make.conf as root and add the desired flag to the USE variable. If the file already contains a USE line, append ssl to it:

USE="${USE} ssl"

This change applies system-wide, meaning all subsequent package builds will include the flag unless overridden per-package.

2. Rebuild the package

Run the emerge command as root to trigger a rebuild:

emerge -av curl

The -a flag asks for confirmation, and -v shows the version and compile options Portage will use. You should see a reference to SSL in the output, indicating that the flag is being honored.

3. Verify the change

After the build completes, check which flags are active for the installed package:

equery uses curl

This command lists the USE flags currently enabled for curl, confirming that ssl appears in the output. If it does not, the flag may have been overridden by a profile or package-specific setting.

Limits and common mistakes

System-wide vs per-package flag control

Adding a flag to /etc/portage/make.conf enables it for every package on the system. If you only need SSL support for curl and not for other packages, consider using /etc/portage/package.use instead. Create a file such as /etc/portage/package/use/net-misc/curl and add ssl there. This limits the feature flag to a single package, reducing unnecessary compilation overhead elsewhere.

Excessive flags and build impact

Enabling many USE flags increases compile time, binary size, and the complexity of dependency resolution. A flag such as debug or extra may pull in additional libraries and compiler options that are unnecessary for your use case. Periodically review the enabled flags with grep USE /etc/portage/make.conf and remove those you no longer need.

Forgetting --newuse after flag changes

When you modify USE flags, Portage may not automatically re-evaluate existing packages. Run emerge --update --deep --newuse @world to reconcile the system with the new flag configuration. Omitting --newuse can leave packages in an inconsistent state where the flag is set but not actively used during builds.

Masked packages and flag conflicts

Some packages mask certain USE flag combinations, and conflicting flags can cause build failures. Always review the build log when a compile error appears, and resolve masked-package issues with package.accept_keywords only after confirming the flag is safe to enable. If a flag conflict arises, consider whether a different flag or a package-specific setting better suits your needs.

Practical verification steps

Check current USE settings

Inspect the active USE definition in make.conf:

grep USE /etc/portage/make.conf

This returns the line(s) containing the USE variable, showing all flags currently set system-wide.

Inspect a specific package

To see which flags are enabled or disabled for an individual package, use:

equery uses <package>

Replace <package> with the package name, such as curl or nginx. The output lists each flag and whether it is enabled, disabled, or forced.

Preview compile changes

Before actually installing a modified package, run a dry-run emerge to see the flag impact in the compile command:

emerge -pav <package>

The -p flag produces a preview, showing how Portage will configure the build with your current USE settings. Look for the flag name in the displayed options to confirm it will be active.

Wrap-up

Gentoo's USE flag system gives you fine-grained control over package features, but it requires deliberate management. Start with a specific goal such as enabling SSL for curl, use per-package flag files when scope is limited, rebuild affected packages with emerge -av, and verify the result with equery uses. By regularly auditing your flags and running emerge --update --deep --newuse @world after changes, you can keep your system optimized without accumulating unnecessary build artifacts.