Packaging:AutoProvidesAndRequiresFiltering

Summary

RPM has no general or standard mechanism to enable filtering of auto-generated requires and provides; this guideline describes how Fedora has implemented such a system.

• MUST: Packages must not provide RPM dependency information when that information is not global in nature, or are otherwise handled (e.g. through a virtual provides system). e.g. a plugin package containing a binary shared library must not "provide" that library unless it is accessible through the system library paths.
• MUST: When filtering automatically generated RPM dependency information, the filtering system implemented by Fedora must be used, except where there is a compelling reason to deviate from it.

Rationale

RPM has no general mechanism to enable filtering of auto-generated requires and provides; this feature aims to implement one.

The auto requires and provides system contained in RPM is quite useful; however, it often picks up "private" package capabilities that shouldn't be advertised as global, things that are "just wrong", or things prohibited by policy (e.g. deps from inside %{_docdir}).

For example:

• Various "plugin" packages (e.g. Pidgin, Perl, Apache, KDE) are marked as "providing" private shared libraries outside the system path.
• Files in %{_docdir} are routinely scanned, and can trigger prov/req when this is explicitly forbidden by policy.

As it stands, filtering these auto-generated requires and provides is difficult and messy at best, and horribly deep magic in many cases; with little guidance on how to do it.^[1] This feature aims to make the following tasks easy:

• preventing files/directories from being scanned for requires (pre-scan filtering)
• preventing files/directories from being scanned for provides (pre-scan filtering)
• removing items from the requires stream (post-scan filtering)
• removing items from the provides stream (post-scan filtering)

Macros defining the filtering system: macros.filtering

Examples

A brief comparison of other auto req/prov filtering systems.

Pidigin plugin package

On a x86_64 machine, the pidgin-libnotify provides pidgin-libnotify.so()(64bit), which it shouldn't, as this library is not inside the paths searched by the system for libraries; that is, it's a private, not global, "provides" and as such must not be exposed globally by RPM.

To filter this out, we could use:

%filter_provides_in %{_libdir}/purple-2/.*\\.so$
%filter_setup

Arch-specific perl-* package

e.g. to ensure an arch-specific perl-* package won't provide or require things that it shouldn't, we could use an invocation as such:

# we don't want to provide private Perl extension libs
%filter_provides_in %{perl_vendorarch}/.*\\.so$ 
%filter_provides_in -P %{perl_archlib}/(?!CORE/libperl).*\\.so$ 

# actually set up the filtering
%filter_setup

%_docdir filtering

By policy, nothing under %_docdir is allowed to either "provide" or "require" anything. We can prevent this from happening by preventing anything under %_docdir from being scanned:

# we don't want to either provide or require anything from _docdir, per policy
%filter_provides_in %{_docdir} 
%filter_requires_in %{_docdir}

# actually set up the filtering
%filter_setup

Usage

Beware of Multilib
Be careful of using these macros in a multilib situation, as they may interfere with the "coloring" of elf32/64 executables done internally by RPM to support multilib installs.

Location of macro invocation

It's strongly recommended that these filtering macros be invoked before %description, but after any other definitions. This will keep them in a consistent place across packages, and help prevent them from being mixed up with other sections.

Preventing files/directories from being scanned for provides (pre-scan filtering)

The %filter_provides_in macro is used to define the files or directories that should not be scanned for any "provides" information. This macro may be safely invoked multiple times, and can handle regular expressions. The -P flag can be passed to specify that a PCRE is being used.

We can filter by regex:

# we don't want to provide private Perl extension libs
%filter_provides_in %{perl_vendorarch}/.*\\.so$ 
%filter_provides_in -P %{perl_archlib}/(?!CORE/libperl).*\\.so$ 

Or by anything matching, say, a directory:

# we don't want to either provide or require anything from _docdir, per policy
%filter_provides_in %{_docdir}

Preventing files/directories from being scanned for requires (pre-scan filtering)

The %filter_requires_in macro is used to define the files or directories that should not be scanned for any "requires" information; it does for requires what the %filter_provides_in macro does for provides and is invoked in the same fashion.

Removing items from the provides stream (post-scan filtering)

Post-scan provides filtering is invoked through the %filter_from_provides. This macro can be fed PCRE's to filter from the stream of auto-found provides.

For example, if we're finding that the auto-prov system is finding an incorrect provide, we can filter it:

%filter_from_provides /bad-provide/d

Note that we should always specify this in terms of a regexp.

Removing items from the requires stream (post-scan filtering)

The %filter_from_requires macro is used to filter "requires"; it does for requires what the %filter_from_provides macro does for provides and is invoked in the same fashion.

General filter setup

The %filter_setup macro must be invoked after defining any specific overrides; this macro does all the heavy lifting of implementing the filtering desired:

# ... filtering defines here
%filter_setup