Installing Configuration Data
with Native Installers

OpenOffice.org 2.0

Document - ID	Specification Owner	Last Change	Status
	Joerg Barfurth	2004-12-16	Final
Conforms to	
Applies to	scp, officecfg; installers
Task ID(s)	I25937,i20537
Category	Feature

Abstract

This document describes how installation-dependent configuration data can be installed with native installers. The mechanism used previously had certain conceptual problems and can't be readily ported to non-native installers. The document also describes how installation-dependent configuration data is defined for the new schema.

In the solution described, installation-dependent configuration is defined together with its globally available counterpart in module officecfg. During the build process this master data is split into globally available common data, locale-dependent data and installation-dependent data.

During installation, installation-dependent data is installed into a special configuration tree, that supports multiple files per component. Thus such data is held physically separated and merged together only at runtime.

i-Team Members (The specification owner is part of the i-Team)

	Name	E-mail Address
User Experience	N/A	
Development	Joerg Barfurth	Joerg.Barfurth@sun.com
Quality Assurance	Olaf Felka	Olaf.Felka@sun.com
Documentation	N/A	

Approved for Implementation

	Approved by	Date
User Experience	N/A	-
Development	Joerg Barfurth	2004-06-14
Quality Assurance	Olaf Felka	2004-06-25
Documentation	N/A	-
String Review	N/A	-

Document Change History

Rev. Level	Change	Initials	Date
0.1	Initial version	JB	2004-02-26
0.2	Completed missing parts of details section Incorporated feedback from i-Team	JB	2004-03-08
0.9	Completed missing detail	JB	2004-06-14
1.0	Now approved: change status to Final	JB	2004-06-25
1.1	Changes for #118253#: Remove spool directory and drop configimport step from postinstall; use multi-layer backend instead. Add missing namespace URI.	JB	2004-12-16

Contents

Glossary	1

1	Motivation	1

2	User Scenarios	1

3	Goals	1

4	Requirements and Dependencies	1

4.1	Requirements	1

4.2	Technical Dependencies	1

5	Competitive Analyses	1

6	Detailed Specification	1

6.1	G11n	2

6.2	Error Conditions	2

7	Future Tasks	2

8	Notes	2

9	References	2

Glossary

Term	Description
Configuration Data	Data Values stored under certain Keys in the OpenOffice.org Configuration Database
Installation-Dependent Configuration Data	Configuration Data whose presence or values depend on the selection of installation options or modules.
Locale-Dependent Configuration Data	Configuration Data whose values depend on the selected UI locale.

Motivation

The installation process of the OpenOffice.org 2.0 application will be different from the setup applications used by prior versions. The installation now will be excuted by native installers for each platform.

Installation-dependent configuration data formerly was defined in the SCP project and written into the OpenOffice.org Configuration Database by specialized code in the setup application. To port this approach to the new installer would require a significant (re)implementation effort.

The SCP configuration items have several fundamental problems. One is, that their approach to describing configuration keys and values is not well aligned with the native concepts of the OpenOffice.org Configuration Registry. This means that several features of the configuration system can't be described in scp configuration items, while other features are available only through a non-obvious mapping. Another problem is that it is hard to determine the final state and consistency of installed configuration from sources, as the final data is combined from multiple items scattered into unrelated places (in scp and officecfg). Lastly the SCP items are written individually one by one, which may produce unnecessary performance problems and increases the potential of finding inconsistent installed data. A last point is that uninstalling SCP ConfigurationItems is not sure to work properly in all cases.

To avoid these problems a new framework for handling installation dependent configuration data is needed that remedies these problems. The port to native installers provides an opportunity to create such a new framework without requiring significantly more work than a port of the old system would need.

User Scenarios

A user installs an optional module/package. The configuration data needed for this module to work is installed quickly and completely. Errors are reported via the mechanisms of the installer.

A user uninstalls an optional module/package. The configuration data needed for this module is removed completely and without residue.

A developer defines default data for a Configuration Component, some of which is installation-dependent.

Goals

Installation-dependent configuration data can be easily be defined and maintained by developers.

Configuration-data that supports all (or nearly all) features of the OOR registry data formats can be installed dynamically.

All default configuration data data is created in the same format in a single location.

Requirements and Dependencies

Requirements

Installion of configuration data can be easily integrated into all native installer systems that are currently being addressed.

Installation-dependent configuration data can be uninstalled cleanly and completely on a module-by-module basis.

Installing configuration data is done no slower with native installers than the 'create local settings' step of the OpenOffice.org 1.1 setup.

Creation of language packs is supported for locale-dependent configuration data.

Existing items are migrated without loss, except for items which become obsolete in the next release.

Non-requirement: It is not required that values that are calculated at install-time are written.

[#118253#] No own binaries must be run during postinstall.

Technical Dependencies

This feature is tightly integrated with the native installer effort. It is both needed to complete that effort and the solution needs to be integrated into each native installer.

Some configuration settings that setup of prior versions writes can't be handled with the new solution. All these settings are scheduled to be replaced and/or provided by new mechanisms (platform integration backends). The replacements must be available, before the old settings can be abandoned.

The merged-data cache maintained by the configuration management services must be used to prevent negative impacts on startup performance to the additional layer files that need to be parsed and merged.

Competitive Analysis

N/A

Detailed Specification

Concept

Defining Configuration Data Modules

The configuration data for one configuration component is completely defined in one file in officecfg. A subtree that should be installable separately is defined inline and marked by a special attribute.

Even today installation-dependent settings can be defined in officecfg, if it spans an entire component and does not require values that can be determined only at installation-time. On the other hand, even now locale-specific settings are defined inline within their component data trees in officecfg. At build time they are separated into distinct files that can be deployed individually. This approach is extended to also handle installation-dependent configuration data subtrees.

All default configuration data for a configuration component is defined in one single xcu file. Any node in the configuration xml source file may be annotated with a single attribute install:module=”<module-name>”. This attribute will not become part of the configuration file format specification [1]. It is considered an external attribute associated with our build system. The install namespace prefix is assciated with the new namespace URI http://openoffice.org/2004/installation.

To our build system the presence of the install:module attribute indicates, that subtree rooted in this node is optional part of the component data. At this time the nodes of this subtree may not contain further install:module attributes, so nested modules are not possible. This facility may be added if it is required (see Future tasks). The minimal size of a module subtree is a single node.

The <module-name> value is a string that should consist exclusively of alphanumeric characters. It serves as an arbitrary identifier for installable modules. The use of the same <module-name> in different configuration components usually implies a semantic connection. Technically they are connected only insofar, as the module-name values are used to trigger building of the corresponding module files.

The build process in officecfg is changed, so that the language-neutral <component-name>.xcu files produced, only contain leaf nodes (set or prop or 'replaced' nodes), that are not part of a module subtree. Additionally for each module-name used in a component a file <component-name>-<module-name>.xcu is produced, which contains the tree spanning all leaf nodes that are part of the module subtree(s) belonging to module module-name. The language-specific configuration files produced contain the locale-dependent leaf nodes from the entire source file, regardless of module association.

Installing Configuration Data Modules

Configuration module files are handled by a new configuration backend, which can handle multiple layer file per component. Storage for this backend is organized similar to the existing file-based backend. The configuration package structure is represented as directory hierarchy. The individual components are not represented by a single <component>.xcu file, but by a directory containing multiple xcu files. The name of the directory is the name of the component, the names of the contained xcu files are arbitrary except for the extension. The location of the (new) data tree is $(install)/share/registry/modules.

At runtime all layer files in the directory representing the requested component are read and merged in arbitrary order.

G11n

The approach described here assumes that localization will not follow the same modularization as the core package, i.e. that there will be a core-package, optional feature packages and a localization package for each locale that contains localizations for both coreand optional features.

It is possible create installable packages that bring along all their localizations, but those have to be created without using the full build system specified here and don't use the normal localization mechanism.

There is a possible improvement of locale handling by allowing 'lang' and 'lang-sublang' style locale tags to both be used and properly resolved at runtime. Here the lang (-only) tag would be the default for all sub-languages. This is out of scope for the present concept.

Error Conditions

Most invalid configuration data is detected at build time and signaled through build failure.

Future Tasks

The approach can be extended to allow nested modules. The problem is that correct installation in such cases would require a dependency of the contained module on its containing module and that module spooling would need to be defined so as to respect the order implied by this dependency.

This extension is not implemented now, because there currently appears to be no requirement for it.

Notes

There are two options how to handle the non-optional office-core data files. One is to treat them as but one case of a module. This means that nested module support (see Future Tasks) will need to be implemented. An alternative option is to put them into a separate layer. In that case there would be a reorganization of the local data that makes 'core', 'install-modules' and 'localization-data' three separate layers, which have to be merged in that order. The latter solution was chosen at this time.

This approach assumes that no two optional modules/packages that are installed concurrently will need to set the same configuration item, but to different values. This can be defined in the source (for mutually exclusive packages), but there is no defined conflict resolution during merging when such conflicting files a installed.

An extra solution would be needed for values that are known only at installation time. At present it appears that such items won't be needed any more.

There are some values that are different for different releases. These values are identified by placeholders in the source files, e.g. '${PRODUCTNAME}'. These placeholders have previously been used in scp particles, to be able to write configured values into fixed configuration files.. These placeholders will now be placed directly into the xml files and are replaced at pack time.

Data migration can largely be scripted and has to be done only once as part of the implementation effort.

References

[1] Configuration file format specification:
http://util.openoffice.org/common/configuration/oor-document-format.html

[2] Configuration storage organization specification:
http://util.openoffice.org/common/configuration/oor-registry.html

Installing Configuration Data with Native Installers

Page 4

http://specs.openoffice.org/installation/native_installer/scp-to-officecfg.sxw

Installing Configuration Data with Native Installers

Jörg Barfurth

2004-01-22T16:31:19

Jörg Barfurth