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