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
that is a descriptiveNAME
[VERSION
].uno.
(so
|dll
|dylib
)
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'sVERSION
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 bypkgchk
). Here, any versioning can be put into the name of thezip
file (e.g.,component1.5.zip
);pkgchk
will unpack the component shared library into a directory path from which the name of thezip
file can be deduced, so a human can always track what version of the componentzip
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 bypkgchk
). 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
, andlibstlport_gcc.so
; UNO runtime libraries likelibcppu.so.3.1.0
andlibcppuhelpergcc3.so.3.1.0
; OOo libraries likelibsvx644li.so
). These changes are typically incompatible, as they rely on (compatible or incompatible) changes of the component's environment.
Author: Stephan Bergmann (Last modification $Date: 2003/08/21 13:27:10 $). Copyright 2003 OpenOffice.org Foundation. All Rights Reserved. |