[This document is intended to become part of the Developers Guide; once that is done and available online, this document can be removed again.]
UNO components that come in the form of a shared library (
Linux and Solaris,
.dll on Windows,
.dylib on Mac)
should be named as
that is a descriptive
NAME, followed by an optional
VERSION, followed by the characters “
.uno” and the platform-specific extension (“
.dylib”, etc.). The optional
VERSIONshould be of the form
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
MICRO) is not specified here.
Examples of component shared library names are
VERSION is optional and is mainly
intended to be useful to humans (e.g., when communicating to others that a
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 “
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).
.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
.uno” or not (e.g., when
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.,
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
scpprojects refer to a shared library with its complete name, so this would have to be adapted whenever a component's
VERSIONchanges), 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
zipfile (installed by
pkgchk). Here, any versioning can be put into the name of the
pkgchkwill unpack the component shared library into a directory path from which the name of the
zipfile can be deduced, so a human can always track what version of the component
zipfile 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
zipfile, 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_getFactoryetc.) 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
- 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
libstlport_gcc.so; UNO runtime libraries like
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.