From Fedora Project Wiki
(clarify why two digits)
(typo correction)
 
(2 intermediate revisions by the same user not shown)
Line 5: Line 5:
In cases where upstream ships unversioned .so '''library''' (so this is not needed for plugins, drivers, etc.), the packager '''MUST''' try to convince upstream to start versioning it.
In cases where upstream ships unversioned .so '''library''' (so this is not needed for plugins, drivers, etc.), the packager '''MUST''' try to convince upstream to start versioning it.


If tjat fails due to unwilling or unresposive upstream, the packager may start versioning downstream but this must be done with caution and ideally only in rare cases.  We don't want to create a library that could conflict with upstream if they later start providing versioned shared libraries. Under no cicumstances should the unversioned library should be shipped in Fedora.
If that fails due to unwilling or unresposive upstream, the packager may start versioning downstream but this must be done with caution and ideally only in rare cases.  We don't want to create a library that could conflict with upstream if they later start providing versioned shared libraries. Under no cicumstances should the unversioned library should be shipped in Fedora.


For downstream versioning, the name should be composed like this:
For downstream versioning, the name should be composed like this:
Line 26: Line 26:
correct object.
correct object.


Keep in mind that altough the SONAME and the filename should be the same, the
Keep in mind that although the filename is usually the library's SONAME plus an incrementing minor version there's nothing that intrinsically links these.  ldconfig uses the SONAME as the value for a symlink to the actual filename.  Then the dynamic linker uses that symlink to find the library, disregarding the actual filename. The dynamic linker also
SONAME field actually matters when dynamically linking. The dynamic linker also
does only simple equality check on the field and do not check for ABI
does only simple equality check on the field and do not check for ABI
incompatibilities and similar problems. This is the main reason for using the
incompatibilities and similar problems. This is the main reason for using the

Latest revision as of 16:54, 3 April 2014


Downstream .so name versioning

In cases where upstream ships unversioned .so library (so this is not needed for plugins, drivers, etc.), the packager MUST try to convince upstream to start versioning it.

If that fails due to unwilling or unresposive upstream, the packager may start versioning downstream but this must be done with caution and ideally only in rare cases. We don't want to create a library that could conflict with upstream if they later start providing versioned shared libraries. Under no cicumstances should the unversioned library should be shipped in Fedora.

For downstream versioning, the name should be composed like this:

libfoobar.so.0.n

The n should initially be a small integer (for instance, "1"). we use two digits here ("0.n") because the common practice with upstreams is to use only a single digit here. Using multiple digits helps us avoid potential future conflicts. Do not forget to add the SONAME field (see below) to the library.

When new versions of the library are released, you should use the Package-x-generic-16.pngabi-compliance-checker tool to check for differences in the build shared libraries, and if it detects any incompatibilities, bump the n number by one. (reasons below).

SONAME handling

When running an executable linked to shared object with SONAME field, the dynamic linker check for this field instead of filename to determine which object to link with. This allows developers to simply link against the unversioned library symlink and the dynamic linker will still links against the correct object.

Keep in mind that although the filename is usually the library's SONAME plus an incrementing minor version there's nothing that intrinsically links these. ldconfig uses the SONAME as the value for a symlink to the actual filename. Then the dynamic linker uses that symlink to find the library, disregarding the actual filename. The dynamic linker also does only simple equality check on the field and do not check for ABI incompatibilities and similar problems. This is the main reason for using the Package-x-generic-16.pngabi-compliance-checker tool and the name bumping.

The SONAME field is written to the shared object by linker, using (at least in case of ld) the -soname SONAME flags. This can be passed as option to Package-x-generic-16.pnggcc like this:

$ gcc $CFLAGS -Wl,-soname,libfoo.so.0.n -o libfoo.so.0.n

If you want to check if the SONAME field is set and what value it has, use the objdump command (from Package-x-generic-16.pngbinutils):

$ objdump -p /path/to/libfoo.so.0.n | grep 'SONAME'