Library Deployment

From Apache OpenOffice Wiki
Jump to: navigation, search



Apache OpenOffice has a simple concept to add Basic libraries to an existing installation. Bringing Basic libraries into a Apache OpenOffice installation involves the following steps:

  • Package your libraries as office extension *.oxt package.
  • Start the Extension Manager (Tools → Extension Manager), press the  Add  button, select the extension package you would like to install and press  OK .

Alternatively, you can install the extension also via the command line:

 [<OfficePath>/program] $ unopkg add my_package.oxt

The tool analyzes the package's manifest file and install all referenced items accordingly to their mime types.

The opposite step is necessary to remove a package from your Apache OpenOffice installation:

  • Start the Extension Manager (Tools → Extension Manager), select the package you want to remove and press  Remove 
  • or via the command line:
 [<OfficePath>/program] $ unopkg remove my_package.oxt

You can run unopkg with the option '--help' or '-h' to get a comprehensive overview of all the switches.

Package Structure

An extension package (*.oxt) is a zip file containing Basic libraries, UNO components, type libraries and/or other files. The unopkg tool unzips the content found in the package directory into the cache directory, preserving the file structure of the zip file. Based on the package manifest.xml file the tool installs the referenced content items accordingly to the mime types. All other not referenced content is ignored and is simply unzipped in the cache directory for private usage from package (e.g. images, ...).

Basic libraries

The unopkg tool links Basic library files (.xlb) into Apache OpenOffice by adding them to the Basic library container files (.xlc) that reside in the following paths:
Library File User Installation Shared Installation
script.xlb <OfficeUserPath>/user/basic/script.xlc <OfficePath>/share/basic/script.xlc
dialog.xlb <OfficeUserPath>/user/basic/dialog.xlc <OfficePath>/share/basic/dialog.xlc
The files share/basic/*.xlc are created when new libraries are shared among all users using the unopkg option --shared in a network installation.
The name of a Basic library is determined by the name of its parent directory. Therefore, package complete library folders, including the parent folders into the UNO Basic package. For example, if your library is named MyLib, there has to be a corresponding folder /MyLib in your development environment. This folder must be packaged completely into the UNO package, so that the *.oxt file contains a structure similar to the following:
 my_package.oxt:
     META-INF/mainfest.xml
     description.xml
     MyLib/
         script.xlb
         dialog.xlb
         Module1.xba
         Dialog1.xba

The appropriate manifest.xml file would look like the following:

  <?xml version="1.0" encoding="UTF-8"?>
    <manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
      <manifest:file-entry manifest:media-type="application/vnd.sun.star.basic-library" 
           manifest:full-path="MyLib/"/> 
      <manifest:file-entry manifest:media-type="application/vnd.sun.star.dialog-library" 
           manifest:full-path="MyLib/"/>
  </manifest:manifest>

Other package components

More detailed information about unopkg or Extensions and Extensions deployment in general can be found in the Extensions chapter. Recommended are at least the File Format and the description.xml section.
Documentation note.png The autopilot .xlb libraries are registered in the user/basic/*.xlc files, but located in share/basic. This makes it is possible to delete and disable the autopilots for certain users even in a network installation. This is impossible for libraries deployed with the unopkg tool and libraries deployed with the share option are always shared among all users.

Path Settings

The package directories are called uno-packages by default. There can be one in <OfficePath>/share for shared installations and another one in <OfficePath>/user for single users. The cache directories are created automatically within the respective uno-packages directory. Apache OpenOffice has to be configured to look for these paths in the uno.ini file (on Windows, unorc on Unix) in <OfficePath>/program. When unopkg is launched, it checks this file for package entries. If they do not exist, the following default values are added to uno(.ini|rc).

 [Bootstrap]
 UNO_SHARED_PACKAGES=${$SYSBINDIR/bootstrap.ini::BaseInstallation}/share/uno_packages
 UNO_SHARED_PACKAGES_CACHE=$UNO_SHARED_PACKAGES/cache
 UNO_USER_PACKAGES=${$SYSBINDIR/bootstrap.ini::UserInstallation}/user/uno_packages
 UNO_USER_PACKAGES_CACHE=$UNO_USER_PACKAGES/cache

The settings reflect the default values for the shared package and cache directory, and the user package and cache directory as described above.

In a network installation, all users start the office from a common directory on a file server. The administrator installs the extensions package with the --shared option to make it available for all users of this network installation. Note: for shared installation administrator rights are necessary and most often extensions get installed per user.

Additional Options

By default, the tool logs all actions into the <cache-dir>/log.txt file. You can switch to another log file through the --log-file <file name> option. Option -v (–verbose) logs to stdout, in addition to the log file.

The tool handles errors loosely. It continues after errors even if a package cannot be inflated or a shared library cannot be registered. The tool logs these errors and proceeds silently. If you want the tool to stop on every error, switch on the –strict_error handling.

If there is some inconsistency with the cache, and you want to renew it from the ground up, repeating the installation using the expert command unopkg reinstall to force a reinstallation of all deployed extensions.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages