HP-UX Linker and Libraries User's Guide

side-effects in programs that call the old version of the routine. In such cases, it is desirable to retain
the old version as well as the new. This way, old programs continue to run and new programs can
use the new version of the routine. Here are some guidelines to keep in mind when making changes
to a library:
• When creating the first version of a shared library, carefully consider whether or not you need
versioning. It is easier to use library-level versioning from the start.
• When creating future revisions of a library, you must determine when a change represents
an incompatible change, and thus deserves a new version. Some examples of incompatible
changes are as follows:
◦ As a general rule, when an exported function is changed such that calls to the function
from previously compiled object files must not resolve to the new version, the change is
incompatible. If the new version can be used as a wholesale replacement for the old
version, the change is compatible.
◦ For exported data, any change in either the initial value or the size represents an
incompatible change.
◦ Any function that is changed to take advantage of an incompatible change in another
module must be considered incompatible.
Maintaining Old Versions of Library Modules
When using shared library versioning, you need to save the old versions of modules in the library:
• With library-level versioning, when an incompatible change is made to a module, the entire
old version of the library must be retained along with the new version.
• With intra-library versioning, when an incompatible change is made to a module, all the old
versions of the module must be retained along with the new version. The new version number
must correspond to the date the change was made. If several modules are changed
incompatibly in a library, it is a good idea to give all modules the same version date.
Library-Level Versioning
HP-UX 10.0 adds a new library-level versioning scheme that allows you to maintain multiple versions
of shared libraries when you make incompatible changes to the library. By maintaining multiple
versions, applications linked with the older versions continue to run with the older libraries, while
new applications link and run with the newest version of the library. Library-level versioning is very
similar to the library versioning on UNIX System V Release 4.
How to Use Library-Level Versioning
To use library-level versioning, complete the following steps:
1. Name the first version of your shared library with an extension of .0 (that's the number zero),
for example, libA.0. Use the +h option to designate the internal name of the library, for
example, libA.0:
$ ld -b *.o -o libA.0 +h libA.0 Creates the shared library libA.0.
2. Since the linker still looks for libraries ending in .so with the -l option, create a symbolic link
from the usual name of the library ending in .so to the actual library. For example, libA.so
points to libA.0:
$ ln -s libA.0 libA.so libA.so is a symbolic link to libA.0.
3. Link applications as usual, using the -l option to specify libraries. The linker searches for
libA.so. However, if the library it finds has an internal name, the linker places the internal
name of the library in the executable's shared library dependency list. When you run the
application, the dynamic loader loads the library named by this internal name. For example:
$ ld prog.o -lA -lc Binds a.out with libA.0.
Version Control with Shared Libraries 111