Extensions Integration into Installation Set

From Apache OpenOffice Wiki
Revision as of 12:34, 11 June 2010 by Is (Talk | contribs)

Jump to: navigation, search

How to integrate an extension into OpenOffice.org / StarOffice installation sets.

Note: For integration of spellchecker dictionary extensions please see Spellchecker_Integration_into_Installation_Set instead.

Note: For more information about extensions please look at the packaging notes for bundled extensions: Documentation/DevGuide/Extensions/Packaging_Notes

Global rules for extensions

Starting with OpenOffice.org 3.3 there are some important changes concerning the integration of extensions into an installation set. The most important simplification is, that during installation no longer the tool unopkg is called. Instead every extension is handled like a zip file with flag ARCHIVE and is repackaged during the packaging process into a native package (Solaris pkg, Linux rpm, Windows msi database), that is installed or uninstalled like every other package. The registration of the extension into the database of OpenOffice.org happens during the start of the application, no longer during installation. This makes the installation much more robust and independent from shell scripts on Unix or CustomActions on Windows.

All extensions are now installed into the directory “share/extensions/<oxtfilename>“. So it is necessary to define the file (now with flag ARCHIVE!) and the directory and a module in scp2 project. Furthermore for Unixes it is necessary to define a package in setup_native, so that the content of the oxt file is repackages into a native Unix package. The inclusion of specific shellscripts is no longer required for this Unix packages and there are no more the difficult dependencies necessary, that were caused by the usage of unopkg during the installation.

In the following description the changes that are required starting with OpenOffice.org 3.3 are added to the old descriptions.

Old text for OpenOffice.org before version 3.3

All extensions that need to be registered during installation process have to be installed into the directory “share/extension/install” in the Office installation. "Installed" means in this context only "copied" or "unpacked" from the installation set and does not include the registration process in the Office product. The scripts (Unix) and CustomActions (Windows), that register the extensions using the tool "unopkg", look only in the directory “share/extension/install” for oxt files.

All extensions have to be included into an own module in scp project. Therefore they are packed into their own RPM (Linux) or Solaris package (Solaris) and can be selected and deselected during the installation process on all platforms. The module defined in scp should not contain any additional content.

A few questions

Info: This questions were asked before release of OpenOffice.org 3.3

QUESTIONS paragraph 1

- "Extensions need to be copied or unpacked", that means that we can put the zip, oxt... or the unzipped version of the extension?

You do not have to take care about it. In scp (see later) you have to define the oxt file. This is packed into RPM, pkg or whatever. And this rpm installs the oxt file into the directory share/extension/install. This is the only important thing: The oxt file has to be located in share/extension/install after the installation process.

- What format are accepted (OXT, ZIP, .uno.pkg)? That means are old extensions supported?

At the end of the installation, only oxt files are searched in the directory share/extension/install. Other files are not found and therefore not installed with unopkg. Of course this can be changed to all extension types supported by unopkg in the future.

- Can those instructions be used to add customization to the OOo msi package or are those instructions only valid if you add the extension to the build tree and compile OOo with the extension?

You do not change the msi package, you only add an oxt-file to the installation set. Of course you have to create a new installation set after delivering the oxt file and making the required changes in scp. When you install the msi installation set, at the end of the installation unopkg is executed and registers the extension to OpenOffice.org. If you want to make an additional customization for OpenOffice.org, you can of course do so.

- Talking about the customization of the OOo MSI, under Windows and Unix, do we need to create a custom action or a script, or does the OOo process manages that?

What kind of customization do you mean? Typically the installation is customized by using custom actions (Windows) or shell scripts (Unix). Which OOo process should manage this?

- If we need to create the custom action, which command line do we need to use (unopkg add --shared <extension name>)?

No, you do not need to create the CustomAction for the Windows Installer. It is already implemented. At the end of the installation, the CustomAction RegisterExtension (you can see it for example with Orca tool), is executed. It searches all oxt files in share/extension/install and registers them by calling unopkg. You do not have to take care about it. You only have to define your new oxt file in the scp project.

- Will the extension be installed on the OOo install (unopkg add --shared <extension name>) or in the profile with the option?

It will be installed for all users in the OOo installation (share/uno_packages/cache/ )

QUESTIONS paragraph 2

- What is that SCP project you are talking about? You are talking about including the extension to the build tree and compile OOo with the extension?

scp2 is a project in the cvs. It is used to describe the content of an installation set, like files, directories, registryitems, ... The new oxt file has to be created in the build environment. But then it is not automatically part of the installation set. For this, the changes in scp2 are required. Then the packaging process knows, that the oxt file has to be part of the installation set, in which rpm, to which directory it shall be installed, shall it be deselectable during installation, and so on, and so on.

- Do we need to create SCP files also for Windows? In that second paragraph, you only deal with RPM (Linux) or Solaris package (Solaris).

You have to define the "File" and the "Module" for all platforms in the project scp2. For Windows this is all. For the Unixes further steps are required, to make the "Module" to a package, like a rpm, pkg, ...

- What do you mean by "additional content"?

The "Module" should not contain more content, than this one oxt file. No further files, no additional directories, no registry items ,... This module only has to contain this one oxt file.

Changes in scp projects

Changes in scp2 for OpenOffice.org version 3.3 and later:

In scp projects you have to add a file (the extension), a directory for this file and a module. This can be easily explained with the following example of the extension

   File gid_File_Oxt_Myextension
       Styles = (PACKED, ARCHIVE);
       Dir = gid_Brand_Dir_Share_Extensions_Myextension;
       Name = "myExtension.oxt";

Take care of the required flag ARCHIVE. The directory has also to be created in scp2. The directory must be created inside the directory share/extensions, so you must not change the directory parent. It is recommended to use as directory name the name of the extension with the file extension .oxt. An extension like myExtension.oxt should be installed into a directory share/extensions/myExtensions .

   Directory gid_Brand_Dir_Share_Extensions_Myextension
       ParentID = gid_Brand_Dir_Share_Extensions;
       DosName = "myExtension";

It is important, that you do not change the ParentID. This must be: gid_Brand_Dir_Share_Extensions .

Finally a module has to be defined. This can be visible or invisible. Typically modules are used to offer the user in the customized installation the chance to deselect this functionality. For Unixes Modules are also used to define the content of package like RPM or Solaris pkg.

So the module definition could look like the following:

   Module gid_Module_Optional_Myextension
       Name = "My extension”;
       Description = "Description of my extension";
       ParentID = gid_Module_Optional;
       Default = YES;
       Files = (gid_File_Oxt_Myextension);

Of course “Name” and “Description” have to be localized. That is all in the scp projects. This has to be done for all platforms. The additional tasks are platform dependent.

Changes in scp2 for OpenOffice.org before version 3.3:

In scp projects you have to add a file (the extension) and a module. This can be easily explained with the following example of the extension

   File gid_File_Oxt_Myextension
       Styles = (PACKED);
       Dir = gid_Brand_Dir_Share_Extension_Install;
       Name = "myExtension.oxt";

It is important to use “gid_Brand_Dir_Share_Extension_Install”. Only with this directory global id the extensions are installed into the correct directory.

Additionally a module has to be defined in scp projects:

   Module gid_Module_Optional_Myextension
       Name = "My extension”;
       Description = "Description of my extension";
       ParentID = gid_Module_Optional;
       Default = YES;
       Files = (gid_File_Oxt_Myextension);

Of course “Name” and “Description” have to be localized. That is all in the scp projects. This has to be done for all platforms. The additional tasks are platform dependent.

Platform dependent tasks


OpenOffice.org 3.3 or later:

Congratulations, you have done it already. At the start of OpenOffice.org the extensions are found in the directory share/extensions and are automatically registered to the application.

Before OpenOffice.org 3.3:

Congratulations, you have done it already. There are two CustomActions executed at the end of the installation and at the start of the deinstallation. The CustomAction at the end of the installation registers all extensions, that are located in "share/extension/install". The CustomAction for the uninstallation process deregisters all extensions located in "share/extension/install". Therefore your new extension is automatically registered or deregistered without any further action.


For the Unix platforms it is required, that a RPM or Solaris package is created from the content of the new module that you defined in scp projects. Therefore you have to define a new package, which currently happens in the project "setup_native". The file "setup_native/source/packinfo/packinfo_office.txt" is a list of all packages of OpenOffice.org.

The new package has a dependency to the packages core01 till core08, so that the program "unopkg" can be executed successfully. Additionally this new package must include as "script" the script file "shellscripts_extensions.txt", that contains scripts required for the installation of RPMs or Solaris Packages that contain extensions.


   module = "gid_Module_Optional_Myextension"
   script = "shellscripts_extensions.txt"
   solarispackagename = "%WITHOUTDOTUNIXPRODUCTNAME-myextension"
   packagename = "%UNIXPRODUCTNAME-myextension"
   linuxreplaces = "%WITHOUTDOTUNIXPRODUCTNAME-myextension"
   copyright = "1999-2007 by OpenOffice.org"
   solariscopyright = "solariscopyrightfile"
   vendor = "OpenOffice.org"
   description = "MY extension for %PRODUCTNAME %PRODUCTVERSION"

That's it. Now the installation set contains a new package, that includes your extension.

Personal tools