#121392# Made STLport a public part of the URE; documentation reviewed.

1 files changed, 184 insertions, 166 deletions

diff --git a/ure/source/README b/ure/source/README
index 06e39a0fab63..a53b6393a276 100644
--- a/ure/source/README
+++ b/ure/source/README
@@ -2,9 +2,9 @@
 #
 #   $RCSfile: README,v $
 #
-#   $Revision: 1.7 $
+#   $Revision: 1.8 $
 #
-#   last change: $Author: sb $ $Date: 2005-06-02 08:25:54 $
+#   last change: $Author: sb $ $Date: 2005-06-10 13:47:41 $
 #
 #   The Contents of this file are made available subject to the terms of
 #   either of the following licenses
@@ -60,10 +60,10 @@
 #*************************************************************************
 
 
-Overview of  URE installation:
-------------------------------
+Overview of URE installation
+-----------------------------
 
-Unix-like platforms (Linux x86, Solaris x86, Solaris SPARC):
+Linux x86, Solaris x86, and Solaris SPARC:
 
 /opt/openoffice.org/ure/LICENSE
 /opt/openoffice.org/ure/README
@@ -78,6 +78,8 @@ Unix-like platforms (Linux x86, Solaris x86, Solaris SPARC):
 /opt/openoffice.org/ure/lib/libuno_sal.so.3
 /opt/openoffice.org/ure/lib/libuno_salhelpergcc3.so.3  [Linux x86 only]
 /opt/openoffice.org/ure/lib/libuno_salhelperC52.so.3  [Solaris only]
+/opt/openoffice.org/ure/lib/libstlport_gcc.so  [Linux x86 only]
+/opt/openoffice.org/ure/lib/libstlport_sunpro.so  [Solaris only]
 /opt/openoffice.org/ure/share/java/unoloader.jar
 /opt/openoffice.org/ure/share/java/juh.jar
 /opt/openoffice.org/ure/share/java/jurt.jar
@@ -131,8 +133,6 @@ Unix-like platforms (Linux x86, Solaris x86, Solaris SPARC):
 /opt/openoffice.org/ure/lib/uriproc.uno.so  [private]
 /opt/openoffice.org/ure/lib/uuresolver.uno.so  [private]
 /opt/openoffice.org/ure/lib/libxml2.so.2  [private]
-/opt/openoffice.org/ure/lib/libstlport_gcc.so  [private; Linux x86 only]
-/opt/openoffice.org/ure/lib/libstlport_sunpro.so  [private; Solaris only]
 /opt/openoffice.org/ure/lib/libgcc_s.so.1  [private; Linux x86 only]
 /opt/openoffice.org/ure/lib/libstdc++.so.6  [private; Linux x86 only]
 /opt/openoffice.org/ure/share/java/java_uno.jar  [private]
@@ -150,6 +150,7 @@ Program Files\URE\bin\cppu3.dll
 Program Files\URE\bin\cppuhelper3MSC.dll
 Program Files\URE\bin\sal3.dll
 Program Files\URE\bin\salhelper3MSC.dll
+Program Files\URE\bin\stlport_vc7145.dll
 Program Files\URE\java\unoloader.jar
 Program Files\URE\java\juh.jar
 Program Files\URE\java\jurt.jar
@@ -198,194 +199,211 @@ Program Files\URE\bin\typemgr.uno.dll  [private]
 Program Files\URE\bin\uriproc.uno.dll  [private]
 Program Files\URE\bin\uuresolver.uno.dll  [private]
 Program Files\URE\bin\libxml2.dll  [private]
-Program Files\URE\bin\stlport_vc7145.dll  [private]
 Program Files\URE\bin\msvcr71.dll  [private]
 Program Files\URE\bin\msvcp71.dll  [private]
 Program Files\URE\bin\uwinapi.dll  [private]
 Program Files\URE\java\java_uno.jar  [private]
 Program Files\URE\misc\javavendors.xml  [private]
 
-Files marked as "private" are private to the URE installation.  Applications
-that use the URE must not make any assumptions about their existance or
-functionality.
+Files marked as [private] are private to the URE installation.  To avoid
+stability issues, applications that use the URE should not access the
+functionality of these files.
 
 
-Notes on the public files of a URE installation:
-------------------------------------------------
+Public Files in a URE Installation
+----------------------------------
 
-uno is an executable to run UNO components.  See the SDK Developer's Guide for
-details.
+A URE installation contains the following public files:
 
-regcomp, regmerge, and regview are tools to work with binary registries that
-contain UNO type or service information.  See the SDK Developer's Guide for
-details.  (Note that these tools may in the future be superseded by a more
-elaborate mechanism, like unopkg already used by OpenOffice.org.)
+- uno is the executable file that runs UNO components.  For more details, see
+the SDK Developer's Guide.
 
-javaldx is a helper program specific to Sun's JDK/JRE (and compatible) that is
-needed on Unix-like platforms so that processes can reliably start a Java VM.
-Executables like uno and regcomp automatically take care of running this helper.
+- regcomp, regmerge, and regview are tools that work with binary registries that
+contain UNO type or UNO service information.  For more details, see the SDK
+Developer's Guide.
 
-cppu, cppuhelper, sal, and salhelper are the public C++ UNO runtime dynamic
-libraries that client code can call.  See the "C++ Reference" section of the SDK
-HTML documentation for details of the functionality offered.  (The corresponding
-C++ header files are not part of the URE, but are part of the SDK.)
+- javaldx is a helper program on Linux x86, Solaris x86, and Solaris SPARC that
+enables Java executables to use a Java VM, such as the Sun JDK/JRE.  Executables
+such as uno and regcomp run this helper automatically.
 
-unoloader.jar, juh.jar, jurt.jar, and ridl.jar are the public Java UNO runtime
-JARs that client code can call.  See the "Java UNO Runtime Reference" section of
-the SDK HTML documentation for details of the functionality offered.
+- cppu, cppuhelper, sal, and salhelper are the public C++ UNO runtime dynamic
+libraries that client code can call.  For details on the functionality that
+these libraries offer, see the "C++ Reference" section of the SDK HTML
+documentation.  The corresponding C++ header files are not in the URE, but
+rather in the SDK.
 
-types.rdb and services.rdb are preconfigured UNO type and service registries.
-See "Notes on deployment" below for details.
+-  stlport is the dynamic library of STLport 4.5, which is used in the public
+interface of cppuhelper and salhelper, and thus also has to be part of the
+public interface of the URE.  The corresponding C++ header files are not in the
+URE, but rather in the SDK.
 
+- unoloader.jar, juh.jar, jurt.jar, and ridl.jar are the public Java UNO runtime
+Java[tm] Archives (JARs) that client code can call.  For details on the
+functionality that these files offer, see the "Java UNO Runtime Reference"
+section of the SDK HTML documentation.
 
-Notes on deployment:
---------------------
+- types.rdb and services.rdb are preconfigured UNO type and service registries.
+For more details, see the "Deploying a URE" section of this README.
 
-Per default, the URE is installed in a platform-specific location
-(/opt/openoffice.org/ure on Unix-like platforms, Program Files\URE on Windows).
-This can be overridden during installation (e.g., with rpm --relocate on Linux).
-The URE is designed so that multiple instances, installed in arbitrary
-locations, can coexist on a single system.  (See below for the use of a per-user
-javasettings_$(_OS)_$(_ARCH).xml file.)
 
-The URE installation comes preconfigured with a number of UNO types (types.rdb)
-and UNO services (services.rdb).  The UNO deployment variable UNO_TYPES is
-automatically set up so that UNO types are searched for in the following places,
-in the given order:
+Deploying a URE
+---------------
 
-Unix-like platforms:
-- share/misc/types.rdb within the URE installation;
-- /etc/opt/ure/types.rdb, if it exists;
-- ~/.ure/types.rdb, if it exists.
+By default, the URE is installed in /opt/openoffice.org/ure on Linux x86,
+Solaris x86, and Solaris SPARC, and in Program Files\URE on Windows. If you
+want, you can override this location when you install the URE, for example, with
+rpm --relocate on Linux.  The URE is designed so that multiple instances of the
+URE can coexist on a single system in different locations.
 
-Windows:
-- misc/types.rdb within the URE installation;
-- Documents and Settings\<User Name>\Application Data\URE\types.rdb, if it
-  exists.
 
-Similarly, the UNO deployment variable UNO_SERVICES is automatically set up so
-that UNO services are searched for in the following places, in the given order:
+UNO Deployment Variables
+------------------------
 
-Unix-like platforms:
-- share/misc/services.rdb within the URE installation;
-- /etc/opt/ure/services.rdb, if it exists;
-- ~/.ure/services.rdb, if it exists.
+The URE installation is preconfigured with several UNO types and UNO services.
+The available types and services are listed in the types.rdb and services.rdb
+files respectively.  The location of these files is stored by two UNO deployment
+variables, namely UNO_TYPES and UNO_SERVICES.  These variables are set up by a
+unorc or uno.ini that is private to the URE installation.  This private file
+also contains the private deployment variables URE_INTERNAL_LIB_DIR and
+URE_INTERNAL_JAVA_DIR, which are required by the URE.
 
-Windows:
-- misc/services.rdb within the URE installation;
-- Documents and Settings\<User Name>\Application Data\URE\services.rdb, if it
-  exists.
-
-(Note that on Windows there currently is no support for system-wide deployment,
-for example under Documents and Settings\All Users\Application Data\URE; this
-may be added in the future.)
-
-See the SDK Developer's Guide and <http://udk.openoffice.org/common/man/concept/
-micro_deployment.html> for details about the UNO deployment variables and
-mechnisms to override them.
-
-Additional UNO types and services can be deployed using regcomp.  No additional
-UNO types and services should be deployed into the types.rdb and services.rdb
-within the URE installation.
-
-(The URE installation contains a private unorc or uno.ini that is responsible
-for setting up UNO_TYPES and UNO_SERVICES.  That file additionally contains the
-private deployment variables URE_INTERNAL_LIB_DIR and URE_INTERNAL_JAVA_DIR,
-which are necessary for a properly working URE.)
-
-When a URE executable (uno etc.) starts a Java VM, it uses the URE Java
-Framework (see <http://udk.openoffice.org/common/man/spec/
-javavendorextension.sxw>) to search for a suitable JDK/JRE installation.  The
-URE installation comes preconfigured with a (private) javavendors.xml that
-supports various JDK/JRE versions, and with a (private) jvmfwk3rc or jvmfwk3.ini
-that specifies where information about suitable JDK/JRE installations is stored:
-
-Unix-like platforms:
-- Information is first looked for in
-  /etc/opt/ure/javasettings_${_OS}_${_ARCH}.xml;
-- if no information is found there, then information is looked for in
-  ~/.ure/javasettings_${_OS}_${_ARCH}.xml;
-- if no information is found there, a suitable JDK/JRE installation is searched
-  for, and any relevant information is stored in
-  ~/.ure/javasettings_${_OS}_${_ARCH}.xml (which is created as necessary).
+The UNO_TYPES and UNO_SERVICES variables automatically search the following
+locations for types.rdb and services.rdb files:
+
+Linux x86, Solaris x86, and Solaris SPARC:
+
+- <URE installation>/share/misc/
+- /etc/opt/ure/
+- ~/.ure/
 
 Windows:
-- Information is first looked for in Documents and Settings\<User
-  Name>\Application Data\URE\javasettings_${_OS}_${_ARCH}.xml;
-- if no information is found there, a suitable JDK/JRE installation is searched
-  for, and any relevant information is stored in
-  ~/.ure/javasettings_${_OS}_${_ARCH}.xml (which is created as necessary).
 
-(On Unix-like platforms, a system administrator can copy some existing
+- <URE installation>\misc\
+- Documents and Settings\<User Name>\Application Data\URE\
+
+NOTE: The URE on Windows does not support a system-wide deployment of additional
+types.rdb and services.rdb files.  That is, you cannot store additional
+types.rdb and services.rdb files in a Documents and Settings\All
+Users\Application Data\URE directory.
+
+For details on how to override the UNO deployment variables, see the SDK
+Developer's Guide or go to http://udk.openoffice.org/common/man/concept/
+micro_deployment.html.
+
+If you want to deploy additional UNO types and services, use regcomp.
+
+CAUTION: Do not deploy these types and services to the types.rdb and
+services.rdb in the URE installation.
+
+
+URE Java Framework
+------------------
+
+When a URE executable, such as uno, starts a Java VM, the URE Java Framework
+searches for a suitable JDK/JRE installation.  For more information on the URE
+Java Framework, go to http://udk.openoffice.org/common/man/spec/
+javavendorextension.sxw.  The private javavendors.xml file in a URE installation
+provides preconfigured support for various JDK/JRE versions.  The private
+jvmfwk3rc or jvmfwk3.ini file specifies the location of a suitable JDK/JRE
+installation.  When an executable tries to start a Java VM, the URE searches the
+relevant Java settings file for information on a suitable JDK/JRE version.
+
+NOTE: On any platform, you can delete the javasettings_${_OS}_${_ARCH}.xml file
+if the file contains problematic stale data.
+
+By default, the URE searches for a Java settings file in the following
+locations:
+
+Linux x86, Solaris x86, and Solaris SPARC:
+
+- /etc/opt/ure/javasettings_${_OS}_${_ARCH}.xml
+- ~/.ure/javasettings_${_OS}_${_ARCH}.xml
+
+NOTE: If these files do not contain information about a JDK/JRE, the URE
+searches for a suitable JDK/JRE installation and stores the relevant information
+in the ~/.ure/javasettings_${_OS}_${_ARCH}.xml file.  If you want all users to
+access the same JDK/JRE, log on as root and copy an existing
 ~/.ure/javasettings_${_OS}_${_ARCH}.xml to
-/etc/opt/ure/javasettings_${_OS}_${_ARCH}.xml, so that all users automatically
-find the same JDK/JRE installation.  On Windows, there currently is no support
-for such a system-wide deployment, for example under Documents and Settings\All
-Users\Application Data\URE; this may be added in the future.  On any platform,
-any javasettings_${_OS}_${_ARCH}.xml file can simply be deleted in case it
-contains any stale data and might thus cause problems.)
-
-The location of a suitable JDK/JRE installation can also be specified directly
-with the UNO_JAVA_JFW_JREHOME deployment variable, see
-<http://udk.openoffice.org/common/man/spec/javavendorextension.sxw> for details.
-
-Within the SDK (when configured for the URE; see the "Installation Guide"
-section of the SDK HTML documentation for details), the selected Java
-(environment variable OO_SDK_JAVA_HOME) is used when any of the executables
-javac, jar, or java is run (typically from a makefile).  However, when a URE
-executable (uno etc.) starts a Java VM, the URE Java Framework mechanism is used
-instead, as explained above.  Note that this may lead to problems when those two
-Java versions are incompatible (e.g., when the SDK uses Java 5 to create class
-files, and the URE Java Framework mechanism selects a Java 1.4 VM which cannot
-read them).
-
-On Linux x86, the URE contains a libgcc_s.so.1 that is necessary to run binary
-UNO components that are compiled with GCC.  Compatibility problems can occur
-when additional UNO components are deployed, compiled with a GCC version that
-differs from the one used to compile the URE itself.  The libgcc_s.so.1 (which
-is part of GCC) evolves along at least two dimensions: the version of GCC, and
-the version of glibc available while building GCC itself.  While UNO components
-requiring an old version of libgcc_s.so.1 typically also work with a newer
-version, the reverse is generally not true (one symptom is that throwing C++
-exceptions invariably leads to process abort).  The URE shipped by Sun
-Microsystems, Inc. includes a libgcc_s.so.1 corresponding to GCC 3.4.1 built on
-a glibc 2.2.4 system.  The solution to the compatibility issue is to always use
-a sufficiently recent version of libgcc_s.so.1 that fulfills the requirements of
-the URE itself and any additionally deployed UNO components.  Thus, if
-necessary, either permanently replace the libgcc_s.so.1 in the URE installation,
-or use LD_PRELOAD.
-
-
-Notes on programming:
----------------------
+/etc/opt/ure/javasettings_${_OS}_${_ARCH}.xml.
+
+Windows:
+
+- Documents and Settings\<User Name>\Application
+  Data\URE\javasettings_${_OS}_${_ARCH}.xml
+
+NOTE: If this file does not contain information about a JDK/JRE, the URE
+searches for a suitable JDK/JRE installation and stores the relevant information
+in the Documents and Settings\<User Name>\Application
+Data\URE\javasettings_${_OS}_${_ARCH}.xml file.  The URE on Windows does not
+support a system-wide deployment of the Java settings file.  That is, you cannot
+store the file in a Documents and Settings\All Users\Application Data\URE
+directory.
+
+You can also use the UNO_JAVA_JFW_JREHOME deployment variable to specify the
+location of a JDK/JRE installation.  For more information on this variable, see
+http://udk.openoffice.org/common/man/spec/javavendorextension.sxw.
+
+You might experience problems in an SDK environment that uses different JDK/JRE
+versions for the SDK and the URE.  This problem arises when the OO_SDK_JAVA_HOME
+SDK environment variable specifies a different Java VM than the Java VM that is
+used in the URE Java Framework.  See the "Installation Guide" section of the SDK
+HTML documentation to find out how to set the  OO_SDK_JAVA_HOME environment
+variable.
+
+
+GNU Compiler Collection on Linux x86
+------------------------------------
+
+On Linux x86, the URE uses libgcc_s.so.1 to run binary UNO components that were
+compiled with the GNU Compiler Collection (GCC).  The libgcc_s.so.1 corresponds
+to GCC 3.4.1 as built on a glibc 2.2.4 system.  To avoid GCC compatibility
+issues, use the same GCC version (or later) when you compile the UNO binaries.
+Otherwise, use LD_PRELOAD to replace the libgcc_s.so.1 in URE with a matching
+version.
+
+
+C++ and Java UNO Components
+---------------------------
 
 C++ UNO components run from within the uno executable can depend on an
 environment in which the public C++ UNO runtime dynamic libraries (cppu,
-cppuhelper, sal, salhelper) are already available (i.e., on Unix-like platforms,
-a component dynamic library need not make sure that the UNO runtime dynamic
-libraries it needs can be found on its RPATH).
-
-Java UNO components can depend on an environment in which the public Java UNO
-runtime JARs are already available (i.e., a component JAR need not list in its
-manifest Class-Path the UNO runtime JARs it needs).
-
-If a Java UNO component JAR brings along new UNO types in the form of Java
-classes, it should make use of the new manifest UNO-Type-Path entry:  Analogous
-to the standard Class-Path manifest entry, the UNO-Type-Path manifest entry can
-contain (relative) URLs of JARs or directories that contain (Java classes
-representing) additional UNO types.  The UnoClassLoader (see below) evaluates
-this manifest entry, and makes sure that those UNO types are available within
-the whole Java UNO environment.  As a special case, "<>" (a less-than sign
-immediately followed by a greater-than sign) can be specified in the
-UNO-Type-Path entry, denoting the current JAR itself.  This is mainly useful for
-backwards compatibility, when any additional UNO types are directly included in
-the JAR; also for backwards compatibility, a missing UNO-Type-Path is equivalent
-to one containing only "<>".
-
-If a Java application wants to make use of the Java UNO environment, it has to
-make sure that all relevant classes are loaded through the UnoClassLoader (see
+cppuhelper, sal, salhelper, stlport) are already available (that is, on
+Linux x86, Solaris x86, and Solaris SPARC, a component dynamic library need not
+make sure that the UNO runtime dynamic libraries it needs can be found on its
+RPATH).
+
+Similarly, Java UNO components can depend on an environment in which the public
+Java UNO runtime JARs are already available (that is, a component JAR need not
+list in its manifest Class-Path the UNO runtime JARs it needs).
+
+If a Java UNO component requires additional UNO types, use the UNO-Type-Path
+manifest entry to specify the location of the UNO types.  The UNO-Type-Path is
+similar to the Class-Path manifest entry and can contain URLs of JARs and
+directories that contain the Java classes that represent additional UNO types.
+The UnoClassLoader evaluates the UNO-Type-Path manifest entry to ensure that the
+additional UNO types are available to the Java UNO environment.
+
+The UNO-Type-Path can have the following entries:
+
+- UNO-Type-Path:
+Current JAR does not contain UNO types.
+
+- UNO-Type-Path: <>
+Current JAR contains UNO types.
+
+- UNO-Type-Path: any/other/jar.jar yet/another/jar.jar
+Current JAR brings other JARs that contain UNO types.
+
+- UNO-Type-Path: any/other/jar.jar <> yet/another/jar.jar
+Current JAR and other JARs that the current JARs uses contain UNO types.
+
+NOTE: If you do not include the UNO-Type-Path manifest entry, the URE assumes
+that the current JAR contains UNO types.
+
+If a Java application requires the Java UNO environment, the UnoClassLoader must
+be set up to load the relevant Java classes.  For example, Runner.java in the
+uretest bundle is packed as runner.jar, which the makefiles use to launch the
+javaclient.jar application.  For more information, see
 com.sun.star.lib.unoloader.UnoClassLoader and
 com.sun.star.lib.unoloader.UnoLoader in the "Java UNO Runtime Reference" section
-of the SDK HTML documentation).  A simple example of how to do that is
-Runner.java in the uretest bundle (packed up as runner.jar, which is used in the
-makefiles to launch the example javaclient.jar application).
+of the SDK HTML documentation.