Yocto Private Libraries: Prevent a Bundled Copy from Becoming Another Package Provider

An application ships a private copy of a shared library. After packaging, an unrelated command unexpectedly depends on the application's package. The private library may have entered Yocto's shared-library provider map under the same name as a public implementation.

PRIVATE_LIBS can prevent that registration, but it also changes dependency discovery for the package that declares it. Apply it to a verified packaging relationship, rather than using it as a general switch for unexplained dependency errors.

Establish which package advertised the library

The automatic runtime dependency guide describes shlibdeps. During packaging, library SONAMEs are associated with their containing packages. Consumers are inspected, and the recorded provider information can produce runtime package dependencies.

This is separate from selecting a recipe through DEPENDS. Merely preferring the public library recipe does not explain or correct a private copy registered during package generation.

Start with the unexpected consumer dependency. Identify its needed library name, the provider package and the actual library file. Compare the public and private copies' SONAMEs. Inspect their containing split packages rather than assuming the main application package owns every installed file.

Use the target toolchain's readelf -d on the actual ELF objects to inspect their dynamic sections; the GNU readelf reference documents that option. A library's disk filename and its declared SONAME need not be identical, so record both.

Exclude a specific private name

The PRIVATE_LIBS reference identifies private libraries that the shared-library resolver should ignore. Its purpose is to stop unrelated packages acquiring dependencies on an application's internal implementation.

For an illustrative package that really contains its own libsensorcodec.so.1, PRIVATE_LIBS:${PN} = "libsensorcodec.so.1" expresses a narrow exclusion. If another split package owns that library, scope the setting to that package instead. Verify the expanded package name in recipe metadata.

The examined package implementation reads package-specific PRIVATE_LIBS, falling back to the unqualified value. Its Linux provider scan applies fnmatch patterns to the SONAME. The setting is therefore not a full-path selector, and a broad wildcard can suppress several names.

Use the observed name rather than a broad lib*.so* pattern. If the implementation is intended for external consumers, reconsider the private classification instead of hiding its public interface.

Account for the consumer-side exclusion

The same implementation also checks PRIVATE_LIBS while resolving the declaring package's needed libraries. Matching names skip provider lookup. This matters when one package contains both a private copy and an executable intended to use the system library with the same SONAME.

In that mixed case, a matching exclusion can suppress automatic discovery of the executable's system dependency. The implementation explicitly notes this limitation. A clean provider map alone is therefore insufficient validation.

Inventory every matching needed name inside the declaring package. Determine whether each consumer uses the private payload or genuinely needs a separate public package. Where necessary, separate the package responsibilities or declare a justified explicit dependency. Do not assume that suppressing automatic lookup makes the dependency unnecessary.

The broader EXCLUDE_FROM_SHLIBS control excludes a whole scan rather than selected private names. In the examined code, a set value returns before shared-library processing. That is usually too broad for a package that still needs normal shared-library dependency discovery.

Verify both sides after repackaging

Regenerate packaging and packagedata through BitBake for the affected recipes. Inspect the resulting provider records and final dependency metadata, not only the recipe's handwritten RDEPENDS assignment.

The unrelated consumer should retain its intended public-library dependency without acquiring the application as a substitute provider. Meanwhile, the application package must still contain its private implementation and retain every genuine external requirement.

Finally, test the two consumers in representative images with only their intended dependencies. PRIVATE_LIBS edits resolver metadata; it does not rename a SONAME, move a file, alter a loader search path or prove ABI compatibility. The repair is complete only when the package relationships and actual runtime payload agree.