Naming UNO Components

[This document is intended to become part of the Developers Guide; once that is done and available online, this document can be removed again.]

Naming Scheme

UNO components that come in the form of a shared library (.so on Linux and Solaris, .dll on Windows, .dylib on Mac) should be named as

NAME[VERSION].uno.(so|dll|dylib)

that is a descriptive NAME, followed by an optional VERSION, followed by the characters “.uno” and the platform-specific extension (“.so”, “.dll”, “.dylib”, etc.). The optional VERSION should be of the form

VERSION  =  MAJOR [.MINOR [.MICRO]]
MAJOR  =  NUMBER
MINOR  =  NUMBER
MICRO  =  NUMBER
NUMBER  =  0  |  1–9 0–9*

How to use the VERSION scheme, if at all, to number different versions of a given component shared library (e.g., only using the MAJOR and increasing it whenever the code is changed, or using all of MAJOR, MINOR, and MICRO) is not specified here.

Examples of component shared library names are

component.uno.so
component1.uno.dll
component0.1.3.uno.dylib

Rationale: The VERSION is optional and is mainly intended to be useful to humans (e.g., when communicating to others that a certain VERSION of a component has a bug); see below for some suggestions when it might be useful to use the optional VERSION and when not. The VERSION is consistently placed before the (platform-specific) extension, never after it; on Linux and Solaris, there is a convention to add a version number after the “.so”, but that version number has different semantics from the VERSION number used here (in short, such a version number changes whenever the shared library's interface changes, but that interface of a component shared library—the few functions component_getFactory etc.—never changes).

The “.uno” is placed next to the platform-specific extension to emphasize that this is a special sort of shared library (its shared library interface consists of only the few functions component_getFactory etc., and the shared library has to be registered with UNO to be useful). As the given naming scheme is only a suggestion, there might be violations of the rule where a component shared library does not contain “.uno” in its name. Therefore, no tool should build assumptions on whether a shared library name contains “.uno” or not (e.g., when pkgchk installs a zip file component, it should not simply register with UNO all those contained shared libraries that contain “.uno” in their names, but should rather use some other mechanism like a manifest file explicitly listing all the contained shared libraries that need to be registered).

For UNO components that are not shared libraries (e.g., a Java component resulting in a jar file), it can also be useful to add “.uno” (and the optional VERSION) to the component's name (e.g., component.uno.jar, or component1.5.uno.jar), for the same reasons as for component shared libraries: to emphasize that it is a UNO component. Again, this is a suggestion, not a hard rule.

Kinds of Components

When deciding whether to add an optional VERSION to a component shared library's name, it might be useful to consider the following kinds of components:

Those component shared libraries that are considered part of OOo (part of an OOo installation set, placed into the program directory during setup, and registered during setup). Their versions are already well defined by the version of the installed OOo itself (as they are part of the OOo build). And because adding explicit version strings to such shared libraries might cause maintenance problems within the OOo build process (e.g., the scp projects refer to a shared library with its complete name, so this would have to be adapted whenever a component's VERSION changes), it might be best to leave the versioning out for this sort of component shared libraries.
Those component shared libraries that are part of a larger component zip file (installed by pkgchk). Here, any versioning can be put into the name of the zip file (e.g., component1.5.zip); pkgchk will unpack the component shared library into a directory path from which the name of the zip file can be deduced, so a human can always track what version of the component zip file is in use. So, in this case it might also be sensible to not use the versioning for the component shared libraries.
Those component shared libraries that are not part of a larger component zip file, but are rather components made up of a single shared library (installed by pkgchk). In this case, it might well make sense to use the versioning, so that a human can easily track what version of such a component got installed (e.g., to mention it in a bug report).

Ways Components Can Evolve

A component shared library's interface (the few functions component_getFactory etc.) is assumed to be stable.
A component's service interface (i.e., the UNO services offered by a component) can change:
- compatibly, by adding a new implementation name, or by adding a new UNO service name to an implementation name;
- incompatibly, by removing an implementation name, or by removing a UNO service name from an implementation name;
- indirectly compatibly, when one of the named UNO services changes compatibly (by adding additional optional interfaces to it). [TODO: Adding optional interfaces to a service is probably not a compatible change, see the mail “Extending Published Services with Optional Interfaces Considered Harmful” from August 14, 2003 at dev@udk.openoffice.org.]
A component shared library's implementation itself can change (bug fixes). Such changes will typically be compatible, unless a known bug is fixed on whose observable behavior clients of the component depend (which, in effect, considered the bug a feature instead).
A component shared library can change its dependencies on other shared libraries (C/C++ runtime libraries like libc.so.6, libstdc++.so.3.0.1, and libstlport_gcc.so; UNO runtime libraries like libcppu.so.3.1.0 and libcppuhelpergcc3.so.3.1.0; OOo libraries like libsvx644li.so). These changes are typically incompatible, as they rely on (compatible or incompatible) changes of the component's environment.