Appendix B

Versioning Quick Reference

ELF objects make available global symbols to which other objects can bind. Some of these global symbols can be identified as providing the object's public interface. Other symbols are part of the object's internal implementation and are not intended for external use. An object's interface can evolve from one software release to another. The ability to identify this evolution is desirable.

In addition, identifying the internal implementation changes of an object from one software release to another might be desirable.

Both interface and implementation identifications can be recorded within an object by establishing internal version definitions. See Chapter 5, Application Binary Interfaces and Versioning for a more complete introduction to the concept of internal versioning.

Shared objects are prime candidates for internal versioning. This technique defines their evolution, provides for interface validation during runtime processing (see "Binding to a Version Definition"), and provides for the selective binding of applications (see "Specifying a Version Binding"). Shared objects will be used as the examples throughout this appendix.

The following sections provide a simple overview, or cheat sheet, of the internal versioning mechanism provided by the link-editors as applied to shared objects. The examples recommend conventions and mechanisms for versioning shared objects, from their initial construction through several common update scenarios.

Naming Conventions

A shared object follows a naming convention that includes a major number file suffix. See "Naming Conventions". Within this shared object, one or more version definitions can be created. Each version definition corresponds to one of the following categories:

It defines an industry-standard interface (for example, the System V Application Binary Interface).
It defines a vendor-specific public interface.
It defines a vendor-specific private interface.
It defines a vendor-specific change to the internal implementation of the object.

The following version definition naming conventions help indicate which of these categories the definition represents.

The first three of these categories indicate interface definitions. These definitions consist of an association of the global symbol names that make up the interface, with a version definition name. See "Creating a Version Definition". Interface changes within a shared object are often referred to as minor revisions. Therefore, version definitions of this type are suffixed with a minor version number, which is based on the file names major version number suffix.

The last category indicates a change having occurred within the object. This definition consists of a version definition acting as a label and has no symbol name associated with it. This definition is referred to as being a weak version definition. See "Creating a Weak Version Definition". Implementation changes within a shared object are often referred to as micro revisions. Therefore, version definitions of this type are suffixed with a micro version number based on the previous minor number to which the internal changes have been applied.

Any industry standard interface should use a version definition name that reflects the standard. Any vendor interfaces should use a version definition name unique to that vendor. The company's stock symbol is often appropriate.

Private version definitions indicate symbols that have restricted or uncommitted use, and should have the word "private" clearly visible.

All version definitions result in the creation of associated version symbol names. The use of unique names and the minor/micro suffix convention reduces the chance of symbol collision within the object being built.

The following version definition examples show the possible use of these naming conventions:

SVABI.1: Defines the System V Application Binary Interface standards interface.
SUNW_1.1: Defines a Solaris public interface.
SUNWprivate_1.1: Defines a Solaris private interface.
SUNW_1.1.1: Defines a Solaris internal implementation change.

Defining a Shared Object's Interface

When establishing a shared object's interface, you should first determine which global symbols provided by the shared object can be associated to one of the three interface version definition categories:

Industry standard interface symbols conventionally are defined in publicly available header files and associated manual pages supplied by the vendor, and are also documented in recognized standards literature.
Vendor public interface symbols conventionally are defined in publicly available header files and associated manual pages supplied by the vendor.
Vendor private interface symbols can have little or no public definition.

By defining these interfaces, a vendor is indicating the commitment level of each interface of the shared object. Industry standard and vendor public interfaces remain stable from release to release. You are free to bind to these interfaces safe in the knowledge that your application will continue to function correctly from release to release.

Industry-standard interfaces might be available on systems provided by other vendors. You can achieve a higher level of binary compatibility by restricting your applications to use these interfaces.

Vendor public interfaces might not be available on systems provided by other vendors. However, these interfaces will remain stable during the evolution of the system on which they are provided.

Vendor private interfaces are very unstable, and can change, or even be deleted, from release to release. These interfaces provide for uncommitted or experimental functionality, or are intended to provide access for vendor-specific applications only. If you want to achieve any level of binary compatibility, you should avoid using these interfaces.

Any global symbols that do not fall into one of the above categories should be reduced to local scope so that they are no longer visible for binding. See "Reducing Symbol Scope".

Versioning a Shared Object

Having determined a shared object's available interfaces, the associated version definitions are created using a mapfile and the link-editor's -M option. See "Defining Additional Symbols" for an introduction to this mapfile syntax.

The following example defines a vendor public interface in the shared object libfoo.so.1:

$ cat mapfile
SUNW_1.1 {                   # Release X.
        global:
                foo2;
                foo1;
        local:
                *;
};
$ cc -G -o libfoo.so.1 -h libfoo.so.1 -z text -M mapfile foo.c

The global symbols foo1 and foo2 are assigned to the shared object's public interface SUNW_1.1. Any other global symbols supplied from the input files are reduced to local by the auto-reduction directive "*". See "Reducing Symbol Scope".

Note - Each version definition mapfile entry should be accompanied by a comment reflecting the release or date of the update. This information helps coordinate multiple updates of a shared object, possibly by different developers, into one version definition suitable for delivery of the shared object as part of a software release.

Versioning an Existing (Non-versioned) Shared Object

Versioning an existing, non-versioned shared object requires extra care. The shared object delivered in a previous software release has made available all its global symbols for others to bind with. Although you can determine the shared object's intended interfaces, others might have discovered and bound to other symbols. Therefore, the removal of any symbols might result in an application's failure on delivery of the new versioned shared object.

The internal versioning of an existing, non-versioned shared object can be achieved if the interfaces can be determined, and applied, without breaking any existing applications. The runtime linker's debugging capabilities can be useful to help verify the binding requirements of various applications. See "Debugging Library". However, this determination of existing binding requirements assumes that all users of the shared object are known.

If the binding requirements of an existing, non-versioned shared object cannot be determined, then you should create a new shared object file using a new versioned name. See "Coordination of Versioned Filenames". In addition to this new shared object, the original shared object must also be delivered so as to satisfy the dependencies of any existing applications.

If the implementation of the original shared object is to be frozen, then maintaining and delivering the shared object binary might be sufficient. If, however, the original shared object might require updating then an alternative source tree from which to generate the shared object can be more applicable. Updating might be necessary through patches, or because its implementation must evolve to remain compatible with new platforms.

Updating a Versioned Shared Object

The only changes that can be made to a shared object that can be absorbed by internal versioning are compatible changes. See "Interface Compatibility". Any incompatible changes require producing a new shared object with a new external versioned name. See "Coordination of Versioned Filenames".

Compatible updates that can be accommodated by internal versioning fall into three basic categories:

Adding new symbols
Creating new interfaces from existing symbols
Internal implementation changes

The first two categories are achieved by associating an interface version definition with the appropriate symbols. The latter is achieved by creating a weak version definition that has no associated symbols.