tdf#157613 make sure surface is not a null pointer

[LibreOffice.git] / ure / source / README

#
# This file is part of the LibreOffice project.
#
# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
#
# This file incorporates work covered by the following license notice:
#
#   Licensed to the Apache Software Foundation (ASF) under one or more
#   contributor license agreements. See the NOTICE file distributed
#   with this work for additional information regarding copyright
#   ownership. The ASF licenses this file to you under the Apache
#   License, Version 2.0 (the "License"); you may not use this file
#   except in compliance with the License. You may obtain a copy of
#   the License at http://www.apache.org/licenses/LICENSE-2.0 .
#

Overview of URE installation
-----------------------------

ELF platforms (Linux, Solaris, *BSD):

/opt/libreoffice/ure/LICENSE
/opt/libreoffice/ure/THIRDPARTYLICENSEREADME.html
/opt/libreoffice/ure/README
/opt/libreoffice/ure/bin/uno
/opt/libreoffice/ure/bin/regview
/opt/libreoffice/ure/bin/javaldx
/opt/libreoffice/ure/lib/libuno_cppu.so.3
/opt/libreoffice/ure/lib/libuno_cppuhelpergcc3.so.3
/opt/libreoffice/ure/lib/libuno_purpenvhelpergcc3.so.3
/opt/libreoffice/ure/lib/libuno_sal.so.3
/opt/libreoffice/ure/lib/libuno_salhelpergcc3.so.3
/opt/libreoffice/ure/share/java/unoloader.jar
/opt/libreoffice/ure/share/java/juh.jar
/opt/libreoffice/ure/share/java/jurt.jar
/opt/libreoffice/ure/share/java/libreoffice.jar
/opt/libreoffice/ure/share/java/ridl.jar
/opt/libreoffice/ure/share/misc/types.rdb
/opt/libreoffice/ure/share/misc/services.rdb
/opt/libreoffice/ure/lib/libxml2.so.2  [external]
/opt/libreoffice/ure/bin/uno.bin  [private]
/opt/libreoffice/ure/lib/unorc  [private]
/opt/libreoffice/ure/lib/libreglo.so  [private]
/opt/libreoffice/ure/lib/libstorelo.so  [private]
/opt/libreoffice/ure/lib/libunoidllo.so  [private]
/opt/libreoffice/ure/lib/libxmlreaderlo.so  [private]
/opt/libreoffice/ure/lib/libjvmaccesslo.so  [private]
/opt/libreoffice/ure/lib/libjvmfwklo.so  [private]
/opt/libreoffice/ure/lib/JREProperties.class  [private]
/opt/libreoffice/ure/lib/jvmfwk3rc  [private]
/opt/libreoffice/ure/lib/libgcc3_uno.so  [private]
/opt/libreoffice/ure/lib/libjava_uno.so  [private]
/opt/libreoffice/ure/lib/libunsafe_uno_uno.so  [private]
/opt/libreoffice/ure/lib/libaffine_uno_uno.so  [private]
/opt/libreoffice/ure/lib/liblog_uno_uno.so  [private]
/opt/libreoffice/ure/lib/libjpipe.so  [private]
/opt/libreoffice/ure/lib/libjuh.so  [private]
/opt/libreoffice/ure/lib/libjuhx.so  [private]
/opt/libreoffice/ure/lib/libsal_textenclo.so  [private]
/opt/libreoffice/ure/lib/libbinaryurplo.so  [private]
/opt/libreoffice/ure/lib/libbootstraplo.so  [private]
/opt/libreoffice/ure/lib/libi18nlangtag.so  [private]
/opt/libreoffice/ure/lib/libintrospectionlo.so  [private]
/opt/libreoffice/ure/lib/libinvocadaptlo.so  [private]
/opt/libreoffice/ure/lib/libinvocationlo.so  [private]
/opt/libreoffice/ure/lib/libiolo.so  [private]
/opt/libreoffice/ure/lib/libjavaloaderlo.so  [private]
/opt/libreoffice/ure/lib/libjavavmlo.so  [private]
/opt/libreoffice/ure/lib/libnamingservicelo.so  [private]
/opt/libreoffice/ure/lib/libproxyfaclo.so  [private]
/opt/libreoffice/ure/lib/libreflectionlo.so  [private]
/opt/libreoffice/ure/lib/libstocserviceslo.so  [private]
/opt/libreoffice/ure/lib/libuuresolverlo.so  [private]
/opt/libreoffice/ure/share/java/java_uno.jar  [private]
/opt/libreoffice/ure/share/java/java_websocket.jar [private]
/opt/libreoffice/ure/share/misc/javavendors.xml  [private]

Windows:

Program Files\URE\LICENSE
Program Files\URE\THIRDPARTYLICENSEREADME.html
Program Files\URE\README
Program Files\URE\bin\uno.exe
Program Files\URE\bin\regview.exe
Program Files\URE\bin\cppu3.dll
Program Files\URE\bin\cppuhelper3MSC.dll
Program Files\URE\bin\purpenvhelper3MSC.dll
Program Files\URE\bin\sal3.dll
Program Files\URE\bin\salhelper3MSC.dll
Program Files\URE\java\unoloader.jar
Program Files\URE\java\libreoffice.jar
Program Files\URE\java\juh.jar
Program Files\URE\java\jurt.jar
Program Files\URE\java\ridl.jar
Program Files\URE\misc\types.rdb
Program Files\URE\misc\services.rdb
Program Files\URE\bin\libxml2.dll  [external]
Program Files\URE\bin\uno.ini  [private]
Program Files\URE\bin\reglo.dll  [private]
Program Files\URE\bin\storelo.dll  [private]
Program Files\URE\bin\unoidllo.dll  [private]
Program Files\URE\bin\xmlreaderlo.dll  [private]
Program Files\URE\bin\jvmaccesslo.dll  [private]
Program Files\URE\bin\jvmfwklo.dll  [private]
Program Files\URE\bin\JREProperties.class  [private]
Program Files\URE\bin\jvmfwk3.ini  [private]
Program Files\URE\bin\msci_uno.dll  [private]
Program Files\URE\bin\java_uno.dll  [private]
Program Files\URE\bin\cli_uno.dll [private]
Program Files\URE\bin\unsafe_uno_uno.dll  [private]
Program Files\URE\bin\affine_uno_uno.dll  [private]
Program Files\URE\bin\log_uno_uno.dll  [private]
Program Files\URE\bin\jpipe.dll  [private]
Program Files\URE\bin\jpipx.dll  [private]
Program Files\URE\bin\juh.dll  [private]
Program Files\URE\bin\juhx.dll  [private]
Program Files\URE\bin\sal_textenclo.dll  [private]
Program Files\URE\bin\binaryurplo.dll  [private]
Program Files\URE\bin\bootstraplo.dll  [private]
Program Files\URE\bin\i18nlangtag.dll  [private]
Program Files\URE\bin\introspectionlo.dll  [private]
Program Files\URE\bin\invocadaptlo.dll  [private]
Program Files\URE\bin\invocationlo.dll  [private]
Program Files\URE\bin\iolo.dll  [private]
Program Files\URE\bin\javaloaderlo.dll  [private]
Program Files\URE\bin\javavmlo.dll  [private]
Program Files\URE\bin\namingservicelo.dll  [private]
Program Files\URE\bin\proxyfaclo.dll  [private]
Program Files\URE\bin\reflectionlo.dll  [private]
Program Files\URE\bin\stocserviceslo.dll  [private]
Program Files\URE\bin\uuresolverlo.dll  [private]
Program Files\URE\bin\uwinapi.dll  [private]
Program Files\URE\java\java_uno.jar  [private]
Program Files\URE\java\java_websocket.jar [private]
Program Files\URE\misc\javavendors.xml  [private]

%windir%\assembly\cli_basetypes.dll [GAC]
%windir%\assembly\cli_ure.dll [GAC]
%windir%\assembly\cli_uretypes.dll [GAC]
%windir%\assembly\cli_cppuhelper.dll [GAC]
%windir%\assembly\policy.1.0.cli_basetypes.dll [GAC]
%windir%\assembly\policy.1.0.cli_ure.dll [GAC]
%windir%\assembly\policy.1.0.cli_uretypes.dll [GAC]
%windir%\assembly\policy.1.0.cli_cppuhelper.dll [GAC]

Files marked as [external] are included in the URE installation because the URE
needs them and it cannot be guaranteed that they are available on a given
system.  Applications using the URE may need those files too, so they are made
available as non-private files of the URE installation.  However, in an ideal
world, those files would not need to be included in the URE installation.

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.

Files marked as [GAC] are installed in the Global Assembly Cache on Windows. The
file path reflects the path as seen in the Explorer with the Assembly
Cache Viewer Tool (Shfusion.dll) installed. The actual paths are different.


Public Files in a URE Installation
----------------------------------

A URE installation contains the following public files:

- uno is the executable file that runs UNO components.  For more details, see
the SDK Developer's Guide.

- regview is a tool that works with old-format binary registries that contain
UNO type or UNO service information.  For more details, see the SDK Developer's
Guide.

- javaldx is a helper program on Linux, Solaris, and *BSD that
enables Java executables to use a Java VM, such as OpenJDK or the Sun JDK/JRE.
Executables such as uno run this helper automatically.

- cppu, cppuhelper, purpenvhelper, 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.

- libreoffice.jar and unoloader.jar are the public Java UNO runtime
Java[tm] Archives (JARs) that client code can call.
juh.jar, jurt.jar, ridl.jar, unoil.jar are still provided for backwards compatibility,
but are basically empty and have been merged into libreoffice.jar.
For details on the functionality that these files offer, see the
"Java UNO Runtime Reference" section of the SDK HTML documentation.

- types.rdb and services.rdb are preconfigured UNO type and service registries.
For more details, see the "Deploying a URE" section of this README.


Deploying a URE
---------------

By default, the URE is installed in /opt/libreoffice/ure on Linux,
Solaris, and *BSD, 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.

On Windows, the path to the installed URE is stored in the registry under the
path "HKEY_CLASSES_ROOT\Software\LibreOffice\URE" and key "Path".


UNO Deployment Variables
------------------------

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,
URE_INTERNAL_JAVA_DIR, and URE_INTERNAL_JAVA_CLASSPATH, which are required by
the URE.

The UNO_TYPES and UNO_SERVICES variables automatically search the following
locations for types.rdb and services.rdb files:

Linux, Solaris, and *BSD:

- <URE installation>/share/misc/ types.rdb and services.rdb, respectively
- any URLs listed in the public deployment variables URE_MORE_TYPES and
  URE_MORE_SERVICES, respectively

Windows:

- <URE installation>\misc\ types.rdb and services.rdb, respectively
- any URLs listed in the public deployment variables URE_MORE_TYPES and
  URE_MORE_SERVICES, respectively

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.

URE_MORE_TYPES and URE_MORE_SERVICES each contain zero or more space-separated
URI descriptors.  A URI descriptor is either a URI (denoting an individual file)
or a URI embedded in "<" and ">*" (denoting all the files contained non-
recursively within the directory denoted by the given URI).

The Java UNO environment needs type information in the form of Java class files
instead of rdb files.  Additional types are searched for in any URLs listed in
the public deployment variable URE_MORE_JAVA_TYPES.

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.


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 does not search for a Java settings file, but instead
searches for a suitable JDK/JRE installation whenever necessary.  You can
override this by setting the URE_OVERRIDE_JAVA_JFW_SHARED_DATA and
URE_OVERRIDE_JAVA_JFW_USER_DATA deployment variables.  If
URE_OVERRIDE_JAVA_JFW_USER_DATA is set, the URE will update the relevant
information in
${URE_OVERRIDE_JAVA_JFW_USER_DATA}/javasettings_${_OS}_${_ARCH}.xml when it
searches for a suitable JDK/JRE installation.  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.

The URE allows clients to extend the content of UNO_JAVA_JFW_CLASSPATH_URLS (see
http://udk.openoffice.org/common/man/spec/javavendorextension.sxw):  The content
of the public deployment variable URE_MORE_JAVA_CLASSPATH_URLS, if set, is
added to the end of the URE's UNO_JAVA_JFW_CLASSPATH_URLS list.

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.


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, purpenvhelper, sal, salhelper) and the external dynamic libraries
(libxml2 etc.) are already available (that is, on Linux, Solaris, and
*BSD, 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.