Difference between revisions of "Documentation/DevGuide/Extensions/File Format"

Latest revision as of 15:44, 15 February 2021

An extension is a zip file having a name that ends in .oxt (formerly .uno.pkg or .zip). The file extension .oxt is associated with the MIME / media type vnd.openofficeorg.extension. The .oxt file serves as a wrapper for all the items of an extension, and contains files which list and describe those items. An extension can contain UNO components, type libraries, configuration files, dialog or basic libraries, etc.

An extension should contain a description.xml (see description.xml) and must contain a directory META-INF (all uppercase). The META-INF directory contains a manifest.xml which lists all items and their media-type.

For backward compatibility, legacy bundles (extension .uno.pkg, .zip) that have been formerly deployed using pkgchk are deployable, too. Migrate legacy bundles to the current .oxt format. This can easily be done using the GUI, exporting a legacy bundle as an .oxt file. When a legacy bundle is exported, a manifest.xml file is generated, enumerating the detected items of the bundle. Note: Legacy bundles will be deprecated in OpenOffice 4.0, and support for them could be dropped in a future release; please convert them to .oxt.

Depending on its media-type, the respective file needs to be treated particularly. For example a UNO component needs to be registered before it can be used. All media types which do not require a particular handling of the file are ignored currently (and actually need not be contained in the manifest.xml).

Runtime Libraries

The extensions need to bring their own runtime libraries, such as C or C++, when it is not guaranteed that these libraries are shipped with Apache OpenOffice or are installed on the users' systems. They typically need to reside in the same directory as the libraries containing the UNO components.

Please note that there is a peculiarity of libraries build with MS Visual Studio 2008. The runtime libraries (C, C++) need either be installed in the system or must reside next to the library in order to be found. It does not matter if the runtime libraries are contained in the Apache OpenOffice installation (<office>/OpenOffice.org/Basis/program). As a consequence extensions need always contain the runtime libraries which they use.

The runtime libraries must not be referenced by the manifest.xml.

Shared Library UNO Components

The media-type for a shared library UNO component is application/vnd.sun.star.uno-component;type=native, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=native" 
                       manifest:full-path="myComponent.uno.so"/>

Shared Library UNO Components for particular Platforms

When you implement a UNO native component, for example, a .dll or .so file, then this file is only deployable on that specific platform. It is often convenient to package a bundle for different platforms. For instance, you compile your component for x86 Linux, Solaris SPARC and Windows. You have to tell the Extension Manager which version of your component file corresponds to which platform via a platform attribute supplied with the media-type, for example,

  <manifest:file-entry manifest:media-type= "application/vnd.sun.star.uno-component;type=native;platform=Windows"
                      manifest:full-path="windows/mycomp.uno.dll"/>
  <manifest:file-entry manifest:media-type= "application/vnd.sun.star.uno-component;type=native;platform=Linux_x86"
                       manifest:full-path="linux/myComp.uno.so"/>
  <manifest:file-entry manifest:media-type= "application/vnd.sun.star.uno-component;type=native;platform=Solaris_SPARC"
                       manifest:full-path="solsparc/myComp.uno.so"/>

Uno Jar Components

The media-type for a UNO Jar component is application/vnd.sun.star.uno-component;type=Java, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=Java" 
                       manifest:full-path="myComponent.uno.jar"/>

UNO Python Components

unopkg now supports registration of Python components (.py files). Those files are registered using the com.sun.star.loader.Python loader. For details concerning Python-UNO, please refer to https://www.openoffice.org/udk/python/python-bridge.html. The media-type for a UNO Python component is application/vnd.sun.star.uno-component;type=Python, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=Python" 
                       manifest:full-path="myComponent.uno.py"/>

Passively Registered UNO Components

Beginning with OpenOffice.org 3.4, UNO components can use passive registration, see Passive_Component_Registration. Components written that way are no longer individually listed in the manifest.xml file. Instead, one or more XML files (with root element <components>) containing the relevant information are registered in the manifest.xml file with media type application/vnd.sun.star.uno_components, optionally giving a platform attribute. For an example extension containing passively registered UNO components, see desktop/test/deployment/passive/.

RDB Type Library

The media-type for a UNO RDB type library is application/vnd.sun.star.uno-typelibrary;type=RDB, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-typelibrary;type=RDB"
                       manifest:full-path="myTypes.uno.rdb"/>

Jar Type Library

The media-type for a UNO Jar typelibrary is application/vnd.sun.star.uno-typelibrary;type=Java, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-typelibrary;type=Java" 
                       manifest:full-path="myTypes.uno.jar"/>

Keep in mind that the RDB variant of that type library must be deployed also. This is currently necessary, because your Java UNO types may be referenced from native UNO code.

Apache OpenOffice Basic Libraries

Apache OpenOffice Basic libraries are linked to the basic library container files. Refer to OpenOffice Basic for additional information. The media-type for a Apache OpenOffice Basic Library is "application/vnd.sun.star.basic-library", for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.basic-library" 
                       manifest:full-path="myBasicLib/"/>

Dialog Libraries

Dialog libraries are linked to the basic dialog library container files. Refer to OpenOffice Basic for additional information. The media-type for a dialog library is application/vnd.sun.star.dialog-library, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.dialog-library" 
                       manifest:full-path="myDialog/"/>

Configuration Data Files

The media-type for a configuration data file is application/vnd.sun.star.configuration-data, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-data" 
                       manifest:full-path="myData.xcu"/>

Configuration Schema Files

The media-type for a configuration schema file is application/vnd.sun.star.configuration-schema, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-schema" 
                       manifest:full-path="mySchema.xcs"/>

Be careful not to install schemata (.xcs files) which contain the same elements (oor:package, oor:name) but have different definitions.

Extension Tooltip Description

Deprecated as of OopenOffice.org 3.1. See Extension Description for details.

If you want to add a tooltip description (which shows up in the balloon help of a bundle node in the Extension Manager dialog), then you can do so by specifying localized UTF-8 files, for example,

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.package-bundle-description;locale=en" 
                       manifest:full-path="readme.en" />
  <manifest:file-entry manifest:media-type="application/vnd.sun.star.package-bundle-description;locale=de" 
                       manifest:full-path="readme.de" />
  <manifest:file-entry manifest:media-type="application/vnd.sun.star.package-bundle-description" 
                       manifest:full-path="readme.txt" />

The best matching locale (against the current installation's locale) is taken. The locale is of the form locale=language-country-variant.

Executable Files

The media type for an executable is application/vnd.sun.star.executable. This media type is new since OpenOffice.org 2.4. If an extension uses it then it should also use the dependency OpenOffice.org-minimal-version set to 2.4. This media type was introduced to work-around the problem that the executable attribute (Unix files, does not apply for Windows files) will not be preserved when Apache OpenOffice extracts a zipped extension. Also, when an extension was zipped on Windows, then the attribute is lost. Using the media type for a Windows executable does not have an effect since there is no such file attribute on Windows. On Unix the executable attribute is set when the extension is being installed. If it is installed for the current user then the user executable flag is set and if it is installed for all users, that is as shared extension, then the executable flag is set for user,group and other. Example:

  <manifest:file-entry manifest:media-type="application/vnd.sun.star.executable" 
                       manifest:full-path="hello"/>

All other contents of the extension are simply copied into the Extension Manager cache. You can, for instance, deploy an image for add-on menus within a package, or any other file needed by your component. The Apache OpenOffice configuration is used to find out in which path this file is located in a particular installation. When you define a package containing additional files, include an .xcu configuration data file, which points to your files. Use a variable %origin% as a placeholder for the exact path where the file will be copied by the Extension Manager. When unopkg installs the data, it replaces the path with an URL containing a macro and writes into the configuration. This URL has to be expanded before it is a valid file URL. This can be done using the com.sun.star.util.MacroExpander service. The %origin% variable is, for instance, used by the ImageIdentifier property of add-on menus and toolbar items, which is described in the Configuration section.