ure/source/README

   1 #
   2 # This file is part of the LibreOffice project.
   3 #
   4 # This Source Code Form is subject to the terms of the Mozilla Public
   5 # License, v. 2.0. If a copy of the MPL was not distributed with this
   6 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
   7 #
   8 # This file incorporates work covered by the following license notice:
   9 #
  10 #   Licensed to the Apache Software Foundation (ASF) under one or more
  11 #   contributor license agreements. See the NOTICE file distributed
  12 #   with this work for additional information regarding copyright
  13 #   ownership. The ASF licenses this file to you under the Apache
  14 #   License, Version 2.0 (the "License"); you may not use this file
  15 #   except in compliance with the License. You may obtain a copy of
  16 #   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  17 #
  18
  19 Overview of URE installation
  20 -----------------------------
  21
  22 Linux x86, Solaris x86, and Solaris SPARC:
  23
  24 /opt/openoffice.org/ure/LICENSE
  25 /opt/openoffice.org/ure/THIRDPARTYLICENSEREADME.html
  26 /opt/openoffice.org/ure/README
  27 /opt/openoffice.org/ure/bin/uno
  28 /opt/openoffice.org/ure/bin/regcomp
  29 /opt/openoffice.org/ure/bin/regmerge
  30 /opt/openoffice.org/ure/bin/regview
  31 /opt/openoffice.org/ure/bin/javaldx
  32 /opt/openoffice.org/ure/lib/libuno_cppu.so.3
  33 /opt/openoffice.org/ure/lib/libuno_cppuhelpergcc3.so.3  [Linux x86 only]
  34 /opt/openoffice.org/ure/lib/libuno_cppuhelperC52.so.3  [Solaris only]
  35 /opt/openoffice.org/ure/lib/libuno_purpenvhelpergcc3.so.3  [Linux x86 only]
  36 /opt/openoffice.org/ure/lib/libuno_purpenvhelperC52.so.3  [Solaris only]
  37 /opt/openoffice.org/ure/lib/libuno_sal.so.3
  38 /opt/openoffice.org/ure/lib/libuno_salhelpergcc3.so.3  [Linux x86 only]
  39 /opt/openoffice.org/ure/lib/libuno_salhelperC52.so.3  [Solaris only]
  40 /opt/openoffice.org/ure/share/java/unoloader.jar
  41 /opt/openoffice.org/ure/share/java/juh.jar
  42 /opt/openoffice.org/ure/share/java/jurt.jar
  43 /opt/openoffice.org/ure/share/java/ridl.jar
  44 /opt/openoffice.org/ure/share/misc/types.rdb
  45 /opt/openoffice.org/ure/share/misc/services.rdb
  46 /opt/openoffice.org/ure/lib/libxml2.so.2  [external]
  47 /opt/openoffice.org/ure/lib/libgcc_s.so.1  [external; Linux x86 only]
  48 /opt/openoffice.org/ure/lib/libstdc++.so.6  [external; Linux x86 only]
  49 /opt/openoffice.org/ure/bin/startup.sh  [private]
  50 /opt/openoffice.org/ure/bin/uno.bin  [private]
  51 /opt/openoffice.org/ure/bin/regcomp.bin  [private]
  52 /opt/openoffice.org/ure/lib/unorc  [private]
  53 /opt/openoffice.org/ure/lib/libreg.so.3  [private]
  54 /opt/openoffice.org/ure/lib/libstore.so.3  [private]
  55 /opt/openoffice.org/ure/lib/libxmlreader.so  [private]
  56 /opt/openoffice.org/ure/lib/libjvmaccessgcc3.so.3  [private; Linux x86 only]
  57 /opt/openoffice.org/ure/lib/libjvmaccessC52.so.3  [private; Solaris only]
  58 /opt/openoffice.org/ure/lib/libjvmfwk.so.3  [private]
  59 /opt/openoffice.org/ure/lib/libsunjavaplugin.so  [private]
  60 /opt/openoffice.org/ure/lib/JREProperties.class  [private]
  61 /opt/openoffice.org/ure/lib/jvmfwk3rc  [private]
  62 /opt/openoffice.org/ure/lib/libgcc3_uno.so  [private; Linux x86 only]
  63 /opt/openoffice.org/ure/lib/libsunpro5_uno.so  [private; Solaris only]
  64 /opt/openoffice.org/ure/lib/libjava_uno.so  [private]
  65 /opt/openoffice.org/ure/lib/libunsafe_uno_uno.so  [private]
  66 /opt/openoffice.org/ure/lib/libaffine_uno_uno.so  [private]
  67 /opt/openoffice.org/ure/lib/liblog_uno_uno.so  [private]
  68 /opt/openoffice.org/ure/lib/libjpipe.so  [private]
  69 /opt/openoffice.org/ure/lib/libjuh.so  [private]
  70 /opt/openoffice.org/ure/lib/libjuhx.so  [private]
  71 /opt/openoffice.org/ure/lib/libsal_textenc.so  [private]
  72 /opt/openoffice.org/ure/lib/acceptor.uno.so  [private]
  73 /opt/openoffice.org/ure/lib/binaryurp.uno.so  [private]
  74 /opt/openoffice.org/ure/lib/bootstrap.uno.so  [private]
  75 /opt/openoffice.org/ure/lib/connector.uno.so  [private]
  76 /opt/openoffice.org/ure/lib/introspection.uno.so  [private]
  77 /opt/openoffice.org/ure/lib/invocadapt.uno.so  [private]
  78 /opt/openoffice.org/ure/lib/invocation.uno.so  [private]
  79 /opt/openoffice.org/ure/lib/javaloader.uno.so  [private]
  80 /opt/openoffice.org/ure/lib/javavm.uno.so  [private]
  81 /opt/openoffice.org/ure/lib/namingservice.uno.so  [private]
  82 /opt/openoffice.org/ure/lib/proxyfac.uno.so  [private]
  83 /opt/openoffice.org/ure/lib/reflection.uno.so  [private]
  84 /opt/openoffice.org/ure/lib/streams.uno.so  [private]
  85 /opt/openoffice.org/ure/lib/textinstream.uno.so  [private]
  86 /opt/openoffice.org/ure/lib/textoutstream.uno.so  [private]
  87 /opt/openoffice.org/ure/lib/stocservices.uno.so  [private]
  88 /opt/openoffice.org/ure/lib/uuresolver.uno.so  [private]
  89 /opt/openoffice.org/ure/share/java/java_uno.jar  [private]
  90 /opt/openoffice.org/ure/share/misc/javavendors.xml  [private]
  91
  92 Windows:
  93
  94 Program Files\URE\LICENSE
  95 Program Files\URE\THIRDPARTYLICENSEREADME.html
  96 Program Files\URE\README
  97 Program Files\URE\bin\uno.exe
  98 Program Files\URE\bin\regcomp.exe
  99 Program Files\URE\bin\regmerge.exe
 100 Program Files\URE\bin\regview.exe
 101 Program Files\URE\bin\cppu3.dll
 102 Program Files\URE\bin\cppuhelper3MSC.dll
 103 Program Files\URE\bin\purpenvhelper3MSC.dll
 104 Program Files\URE\bin\sal3.dll
 105 Program Files\URE\bin\salhelper3MSC.dll
 106 Program Files\URE\java\unoloader.jar
 107 Program Files\URE\java\juh.jar
 108 Program Files\URE\java\jurt.jar
 109 Program Files\URE\java\ridl.jar
 110 Program Files\URE\misc\types.rdb
 111 Program Files\URE\misc\services.rdb
 112 Program Files\URE\bin\libxml2.dll  [external]
 113 Program Files\URE\bin\uno.ini  [private]
 114 Program Files\URE\bin\reg3.dll  [private]
 115 Program Files\URE\bin\store3.dll  [private]
 116 Program Files\URE\bin\xmlreader.dll  [private]
 117 Program Files\URE\bin\jvmaccess3MSC.dll  [private]
 118 Program Files\URE\bin\jvmfwk3.dll  [private]
 119 Program Files\URE\bin\libsunjavaplugin.dll  [private]
 120 Program Files\URE\bin\JREProperties.class  [private]
 121 Program Files\URE\bin\jvmfwk3.ini  [private]
 122 Program Files\URE\bin\msci_uno.dll  [private]
 123 Program Files\URE\bin\java_uno.dll  [private]
 124 Program Files\URE\bin\cli_uno.dll [private]
 125 Program Files\URE\bin\unsafe_uno_uno.dll  [private]
 126 Program Files\URE\bin\affine_uno_uno.dll  [private]
 127 Program Files\URE\bin\log_uno_uno.dll  [private]
 128 Program Files\URE\bin\jpipe.dll  [private]
 129 Program Files\URE\bin\jpipx.dll  [private]
 130 Program Files\URE\bin\juh.dll  [private]
 131 Program Files\URE\bin\juhx.dll  [private]
 132 Program Files\URE\bin\sal_textenc.dll  [private]
 133 Program Files\URE\bin\acceptor.uno.dll  [private]
 134 Program Files\URE\bin\binaryurp.uno.dll  [private]
 135 Program Files\URE\bin\bootstrap.uno.dll  [private]
 136 Program Files\URE\bin\connector.uno.dll  [private]
 137 Program Files\URE\bin\introspection.uno.dll  [private]
 138 Program Files\URE\bin\invocadapt.uno.dll  [private]
 139 Program Files\URE\bin\invocation.uno.dll  [private]
 140 Program Files\URE\bin\javaloader.uno.dll  [private]
 141 Program Files\URE\bin\javavm.uno.dll  [private]
 142 Program Files\URE\bin\namingservice.uno.dll  [private]
 143 Program Files\URE\bin\proxyfac.uno.dll  [private]
 144 Program Files\URE\bin\reflection.uno.dll  [private]
 145 Program Files\URE\bin\streams.uno.dll  [private]
 146 Program Files\URE\bin\textinstream.uno.dll  [private]
 147 Program Files\URE\bin\textoutstream.uno.dll  [private]
 148 Program Files\URE\bin\stocservices.uno.dll  [private]
 149 Program Files\URE\bin\uuresolver.uno.dll  [private]
 150 Program Files\URE\bin\uwinapi.dll  [private]
 151 Program Files\URE\java\java_uno.jar  [private]
 152 Program Files\URE\misc\javavendors.xml  [private]
 153
 154 %windir%\assembly\cli_basetypes.dll [GAC]
 155 %windir%\assembly\cli_ure.dll [GAC]
 156 %windir%\assembly\cli_uretypes.dll [GAC]
 157 %windir%\assembly\cli_cppuhelper.dll [GAC]
 158 %windir%\assembly\policy.1.0.cli_basetypes.dll [GAC]
 159 %windir%\assembly\policy.1.0.cli_ure.dll [GAC]
 160 %windir%\assembly\policy.1.0.cli_uretypes.dll [GAC]
 161 %windir%\assembly\policy.1.0.cli_cppuhelper.dll [GAC]
 162
 163 Files marked as [external] are included in the URE installation because the URE
 164 needs them and it cannot be guaranteed that they are available on a given
 165 system.  Applications using the URE may need those files too, so they are made
 166 available as non-private files of the URE installation.  However, in an ideal
 167 world, those files would not need to be included in the URE installation.
 168
 169 Files marked as [private] are private to the URE installation.  To avoid
 170 stability issues, applications that use the URE should not access the
 171 functionality of these files.
 172
 173 Files marked as [GAC] are installed in the Global Assembly Cache on Windows. The
 174 file path reflects the path as seen in the Explorer with the Assembly
 175 Cache Viewer Tool (Shfusion.dll) installed. The actual paths are different.
 176
 177
 178 Public Files in a URE Installation
 179 ----------------------------------
 180
 181 A URE installation contains the following public files:
 182
 183 - uno is the executable file that runs UNO components.  For more details, see
 184 the SDK Developer's Guide.
 185
 186 - regcomp, regmerge, and regview are tools that work with binary registries that
 187 contain UNO type or UNO service information.  For more details, see the SDK
 188 Developer's Guide.
 189
 190 - javaldx is a helper program on Linux x86, Solaris x86, and Solaris SPARC that
 191 enables Java executables to use a Java VM, such as the Sun JDK/JRE.  Executables
 192 such as uno and regcomp run this helper automatically.
 193
 194 - cppu, cppuhelper, purpenvhelper, sal, and salhelper are the public C++ UNO
 195 runtime dynamic libraries that client code can call.  For details on the
 196 functionality that these libraries offer, see the "C++ Reference" section of the
 197 SDK HTML documentation.  The corresponding C++ header files are not in the URE,
 198 but rather in the SDK.
 199
 200 - unoloader.jar, juh.jar, jurt.jar, and ridl.jar are the public Java UNO runtime
 201 Java[tm] Archives (JARs) that client code can call.  For details on the
 202 functionality that these files offer, see the "Java UNO Runtime Reference"
 203 section of the SDK HTML documentation.
 204
 205 - types.rdb and services.rdb are preconfigured UNO type and service registries.
 206 For more details, see the "Deploying a URE" section of this README.
 207
 208
 209 Deploying a URE
 210 ---------------
 211
 212 By default, the URE is installed in /opt/openoffice.org/ure on Linux x86,
 213 Solaris x86, and Solaris SPARC, and in Program Files\URE on Windows. If you
 214 want, you can override this location when you install the URE, for example, with
 215 rpm --relocate on Linux.  The URE is designed so that multiple instances of the
 216 URE can coexist on a single system in different locations.
 217
 218 On Windows, the path to the installed URE is stored in the registry under the
 219 path "HKEY_CLASSES_ROOT\Software\LibreOffice\URE" and key "Path".
 220
 221
 222 UNO Deployment Variables
 223 ------------------------
 224
 225 The URE installation is preconfigured with several UNO types and UNO services.
 226 The available types and services are listed in the types.rdb and services.rdb
 227 files respectively.  The location of these files is stored by two UNO deployment
 228 variables, namely UNO_TYPES and UNO_SERVICES.  These variables are set up by a
 229 unorc or uno.ini that is private to the URE installation.  This private file
 230 also contains the private deployment variables URE_INTERNAL_LIB_DIR,
 231 URE_INTERNAL_JAVA_DIR, and URE_INTERNAL_JAVA_CLASSPATH, which are required by
 232 the URE.
 233
 234 The UNO_TYPES and UNO_SERVICES variables automatically search the following
 235 locations for types.rdb and services.rdb files:
 236
 237 Linux x86, Solaris x86, and Solaris SPARC:
 238
 239 - <URE installation>/share/misc/ types.rdb and services.rdb, respectively
 240 - any URLs listed in the public deployment variables URE_MORE_TYPES and
 241   URE_MORE_SERVICES, respectively
 242
 243 Windows:
 244
 245 - <URE installation>\misc\ types.rdb and services.rdb, respectively
 246 - any URLs listed in the public deployment variables URE_MORE_TYPES and
 247   URE_MORE_SERVICES, respectively
 248
 249 NOTE: The URE on Windows does not support a system-wide deployment of additional
 250 types.rdb and services.rdb files.  That is, you cannot store additional
 251 types.rdb and services.rdb files in a Documents and Settings\All
 252 Users\Application Data\URE directory.
 253
 254 URE_MORE_TYPES and URE_MORE_SERVICES each contain zero or more space-separated
 255 URI descriptors.  A URI descriptor is either a URI (denoting an individual file)
 256 or a URI embeded in "<" and ">*" (denoting all the files contained non-
 257 recursively within the directory denoted by the given URI).
 258
 259 The Java UNO environment needs type information in the form of Java class files
 260 instead of rdb files.  Additional types are searched for in any URLs listed in
 261 the public deployment variable URE_MORE_JAVA_TYPES.
 262
 263 For details on how to override the UNO deployment variables, see the SDK
 264 Developer's Guide or go to http://udk.openoffice.org/common/man/concept/
 265 micro_deployment.html.
 266
 267 If you want to deploy additional UNO types and services, use regcomp.
 268
 269 CAUTION: Do not deploy these types and services to the types.rdb and
 270 services.rdb in the URE installation.
 271
 272
 273 URE Java Framework
 274 ------------------
 275
 276 When a URE executable, such as uno, starts a Java VM, the URE Java Framework
 277 searches for a suitable JDK/JRE installation.  For more information on the URE
 278 Java Framework, go to http://udk.openoffice.org/common/man/spec/
 279 javavendorextension.sxw.  The private javavendors.xml file in a URE installation
 280 provides preconfigured support for various JDK/JRE versions.  The private
 281 jvmfwk3rc or jvmfwk3.ini file specifies the location of a suitable JDK/JRE
 282 installation.  When an executable tries to start a Java VM, the URE searches the
 283 relevant Java settings file for information on a suitable JDK/JRE version.
 284
 285 NOTE: On any platform, you can delete the javasettings_${_OS}_${_ARCH}.xml file
 286 if the file contains problematic stale data.
 287
 288 By default, the URE does not search for a Java settings file, but instead
 289 searches for a suitable JDK/JRE installation whenever necessary.  You can
 290 override this by setting the URE_OVERRIDE_JAVA_JFW_SHARED_DATA and
 291 URE_OVERRIDE_JAVA_JFW_USER_DATA deployment variables.  If
 292 URE_OVERRIDE_JAVA_JFW_USER_DATA is set, the URE will update the relevant
 293 information in
 294 ${URE_OVERRIDE_JAVA_JFW_USER_DATA}/javasettings_${_OS}_${_ARCH}.xml when it
 295 searches for a suitable JDK/JRE installation.  You can also use the
 296 UNO_JAVA_JFW_JREHOME deployment variable to specify the location of a JDK/JRE
 297 installation.  For more information on this variable, see
 298 http://udk.openoffice.org/common/man/spec/javavendorextension.sxw.
 299
 300 The URE allows clients to extend the content of UNO_JAVA_JFW_CLASSPATH_URLS (see
 301 http://udk.openoffice.org/common/man/spec/javavendorextension.sxw):  The content
 302 of the public deployment variable URE_MORE_JAVA_CLASSPATH_URLS, if set, is
 303 added to the end of the URE's UNO_JAVA_JFW_CLASSPATH_URLS list.
 304
 305 You might experience problems in an SDK environment that uses different JDK/JRE
 306 versions for the SDK and the URE.  This problem arises when the OO_SDK_JAVA_HOME
 307 SDK environment variable specifies a different Java VM than the Java VM that is
 308 used in the URE Java Framework.  See the "Installation Guide" section of the SDK
 309 HTML documentation to find out how to set the  OO_SDK_JAVA_HOME environment
 310 variable.
 311
 312
 313 GNU Compiler Collection on Linux x86
 314 ------------------------------------
 315
 316 On Linux x86, the URE uses libgcc_s.so.1 to run binary UNO components that were
 317 compiled with the GNU Compiler Collection (GCC).  The libgcc_s.so.1 corresponds
 318 to GCC 3.4.1 as built on a glibc 2.2.4 system.  To avoid GCC compatibility
 319 issues, use the same GCC version (or later) when you compile the UNO binaries.
 320 Otherwise, use LD_PRELOAD to replace the libgcc_s.so.1 in URE with a matching
 321 version.
 322
 323
 324 C++ and Java UNO Components
 325 ---------------------------
 326
 327 C++ UNO components run from within the uno executable can depend on an
 328 environment in which the public C++ UNO runtime dynamic libraries (cppu,
 329 cppuhelper, purpenvhelper, sal, salhelper) and the external dynamic libraries
 330 (libxml2 etc.) are already available (that is, on Linux x86, Solaris x86, and
 331 Solaris SPARC, a component dynamic library need not make sure that the UNO
 332 runtime dynamic libraries it needs can be found on its RPATH).
 333
 334 Similarly, Java UNO components can depend on an environment in which the public
 335 Java UNO runtime JARs are already available (that is, a component JAR need not
 336 list in its manifest Class-Path the UNO runtime JARs it needs).
 337
 338 If a Java UNO component requires additional UNO types, use the UNO-Type-Path
 339 manifest entry to specify the location of the UNO types.  The UNO-Type-Path is
 340 similar to the Class-Path manifest entry and can contain URLs of JARs and
 341 directories that contain the Java classes that represent additional UNO types.
 342 The UnoClassLoader evaluates the UNO-Type-Path manifest entry to ensure that the
 343 additional UNO types are available to the Java UNO environment.
 344
 345 The UNO-Type-Path can have the following entries:
 346
 347 - UNO-Type-Path:
 348 Current JAR does not contain UNO types.
 349
 350 - UNO-Type-Path: <>
 351 Current JAR contains UNO types.
 352
 353 - UNO-Type-Path: any/other/jar.jar yet/another/jar.jar
 354 Current JAR brings other JARs that contain UNO types.
 355
 356 - UNO-Type-Path: any/other/jar.jar <> yet/another/jar.jar
 357 Current JAR and other JARs that the current JARs uses contain UNO types.
 358
 359 NOTE: If you do not include the UNO-Type-Path manifest entry, the URE assumes
 360 that the current JAR contains UNO types.
 361
 362 If a Java application requires the Java UNO environment, the UnoClassLoader must
 363 be set up to load the relevant Java classes.  For example, Runner.java in the
 364 uretest bundle is packed as runner.jar, which the makefiles use to launch the
 365 javaclient.jar application.  For more information, see
 366 com.sun.star.lib.unoloader.UnoClassLoader and
 367 com.sun.star.lib.unoloader.UnoLoader in the "Java UNO Runtime Reference" section
 368 of the SDK HTML documentation.