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

2 files changed, 266 insertions, 239 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.
diff --git a/ure/source/uretest/README b/ure/source/uretest/README
index bba244944e4c..b860cca8cb56 100644
--- a/ure/source/uretest/README
+++ b/ure/source/uretest/README
@@ -2,9 +2,9 @@
 #
 #   $RCSfile: README,v $
 #
-#   $Revision: 1.3 $
+#   $Revision: 1.4 $
 #
-#   last change: $Author: sb $ $Date: 2005-05-30 07:38:02 $
+#   last change: $Author: sb $ $Date: 2005-06-10 13:48:08 $
 #
 #   The Contents of this file are made available subject to the terms of
 #   either of the following licenses
@@ -60,74 +60,83 @@
 #*************************************************************************
 
 
-This directory contains tests for the UNO Runtime Environment (URE).  There are
-two makefiles, Makefile and Makefile.pln, each to be executed with a
-sufficiently recent GNU make.
-
-The first, Makefile, is intended to be run from within a configured SDK
-environment (where the SDK is configured to work with a URE installation, not an
-office installation; see .../docs/install.html within the SDK installation).
-Three things need to be noted:
-
-- The SDK must be configured to use a C++ compiler (which is in principle
-  optional when working with the SDK, but needed by Makefile).
-
-- The SDK must be configured to use a JDK (which is in principle optional when
-  working with the SDK, but needed by Makefile).
-
-- On Linux x86, the environment variable GCCS_COMPAT can be used to work around
-  incompatibilities between the GCC version used to build the URE and the GCC
-  version used while executing the tests (see above for the configured C++
-  compiler).  See the README of the UDK for further details.
-
-The second, Makefile.pln, is intended to be run without setting up any special
-environment.  Currently, this variant is only intended to work on Linux x86.
-The things that must be set up manually are:
-
-- The environment variable SDK_HOME must point to the base directory of some
-  OpenOffice.org Software Development Kit (SDK) (e.g.,
-  /opt/OpenOffice.org2.0_SDK).  This is only necessary to have access to some
-  UNO programming tools and files that are not part of the URE (idlc, cppumaker,
-  javamaker, UNOIDL files, and C++ headers).
-
-- The environment variable URE_HOME, if set, can be used to overwrite the
-  default URE location (/opt/openoffice.org/ure).
-
-- The environment variable GCCS_COMPAT can be used to work around
-  incompatibilities between the GCC version used to build the URE and the GCC
-  version used while executing the tests (see next).  See the README of the UDK
-  for further details.
-
-- A GCC installation (including g++) is expected to be available on the PATH.
-  See the SDK Installation Guide ($SDK_HOME/docs/install.html) for minimum
-  version requirements.
-
-- A JDK installation (java, javac, jar) is expected ot be available on the PATH.
-  See the SDK Installation Guide ($SDK_HOME/docs/install.html) for minimum
-  version requirements.
-
-The tests that are executed in Makefile and Makefile.pln are the same, though
-they are built differently (note that Makefile uses a local sub-directory
-./out.sdk for generated files, while Makefile.pln uses ./out.pln):
-
-- test-regview checks that the regview executable from the URE installation
-  works reliably (only in Makefile.pln; the other executables from the URE
-  installation are tested indirectly when making the other tests).
-
-- test-cpptest builds a C++ UNO component (cppmain.uno) that is run via the uno
-  executable.  It first tries to instantiate all the UNO services and singletons
-  that are part of the URE installation.  Then it tries to instantiate and call
-  a C++ UNO component (ccptest.uno) and a Java UNO component (javatest.uno),
-  both of which must throw a special exception which in turn is caught by
-  cppmain.uno.
-
-- test-javatest builds a Java UNO component (javamain.uno) that is run via the
-  uno executable.  It tries to instantiate and call a C++ UNO component
-  (cpptest.uno) and a Java UNO component (javatest.uno), both of which must
-  throw a special exception which in turn is caught by javamain.uno.
-
-- test-clientserver builds a server C++ UNO component (cppserver.uno) that is
-  run via the uno executable and listens on a pipe connection, and a Java UNO
-  component (javaclient.uno) that us run via the java executable and connects to
-  the server (after waiting for five seconds to give the server time to start
-  up).
+This directory contains test files for the UNO Runtime Environment (URE) as well
+as the Makefile and Makefile.pln makefiles.  To execute the makefiles, you need
+GNU make 3.80 or later.
+
+
+Makefile
+--------
+
+Before you execute Makefile, you need to configure the Software Development Kit
+(SDK) environment to work with a URE installation, a C++ compiler, and a JDK.
+For more information, read the .../docs/install.html file in the SDK
+installation.
+
+NOTE: On Linux x86, if the Makefile accesses a GCC that is incompatible with the
+GCC that was used to build the URE, use the GCCS_COMPAT environment variable as
+a workaround.  For more details, see the UDK README file.
+
+
+Makefile.pln
+------------
+
+You can only run Makefile.pln on Linux x86.  You do not need to configure your
+SDK environment to use this makefile, however, you do need to set the following
+environment variables:
+
+- SDK_HOME
+Points to the base directory of an OpenOffice.org SDK so that you can access UNO
+programming tools and files that are not part of the URE.  For example, idlc,
+cppumaker, javamaker, UNOIDL files, and C++ headers.
+
+- PATH
+Points to a GCC installation (including g++) as well as a JDK installation that
+contains the java, javac, and jar executables.  For the minimum version
+requirements, see the SDK Installation Guide ($SDK_HOME/docs/install.html).
+
+- URE_HOME (optional)
+Overwrites the default URE location, that is, /opt/openoffice.org/ure.
+
+- GXX_INCLUDE_PATH (optional)
+Overwrites the default location of the GCC C++ headers (/usr/include/g++).  This
+information is needed by the STLport included in the URE.
+
+- GCCS_COMPAT (optional)
+Fixes incompatibility issues between the GCC that was used to build the URE and
+the GCC that Makefile.pln accesses.  For more details, see the UDK README file.
+
+
+Tests
+-----
+
+Makefile and Makefile.pln can execute the following tests:
+
+- test-cpptest
+Builds a C++ UNO component, cppmain.uno, and runs the component with the uno
+executable.  The component first attempts to instantiate all the UNO services
+and singletons that are part of the URE installation.  The component then tries
+to instantiate and to call another C++ UNO component (ccptest.uno) as well as a
+Java UNO component (javatest.uno).  The test completes when these components
+throw a special exception that is caught by cppmain.uno.
+
+- test-javatest
+Builds a Java UNO component, javamain.uno, and runs the component with the uno
+executable.  The component tries to instantiate and to call a C++ UNO component
+(cpptest.uno) as well as a Java UNO component (javatest.uno).  The test
+completes when these components throw a special exception that is caught by
+javamain.uno.
+
+- test-clientserver
+Builds a server C++ UNO component, cppserver.uno, and a client Java UNO
+component, javaclient.uno.  The uno executable runs the cppserver.uno component
+which listens on a pipe connection.  The java executable runs the javaclient.uno
+component which connects to the server after a five second pause so that the
+server has enough time to start.
+
+- test-regview (Makefile.pln only)
+Checks that the regview executable of the URE installation works reliably.
+
+NOTE: The files that are generated when Makefile and Makefile.pln execute are
+saved to different local directories.  Makefile outputs the generated files to
+./out.sdk whereas Makefile.pln outputs the files to ./out.pln.