unopkg Deployment Tool Specification

packagemanager project

Document - ID	Specification Owner	Last Change	Status
	Daniel Bölzle (db93792)	05/07/04	final
Conforms to	
Applies to	all
Task ID(s)	i20304 - Q-PCD Programmability: Live Deployment and GUI; 115885 – PackageManager GUI i21218 - Q-PCD Macro Security: UNO packages
Category	Feature

Abstract

The unopkg deployment tool is used to deploy/undeploy UNO packages into an Office installation, e.g. UNO components or extensions, e.g. scripts. Have a look at the related Package Manager GUI spec, too.

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

	Name	E-mail Address
User Experience	Bettina Haberer /BH	Bettina.Haberer@sun.com
Development	Daniel Bölzle /DBO	boelzle@sun.com
Quality Assurance	Steffen Grund /SG	Steffen.Grund@sun.com
Documentation	Yvonne Jacoby /YJ	Yvonne.Jacoby@sun.com

Approved for Implementation

	Approved by	Date
User Experience	Bettina Haberer /BH	05/19/2004
Development	Daniel Bölzle /DBO	05/19/2004
Quality Assurance	Steffen Grund /SG	05/19/2004
Documentation	Yvonne Jacoby /YJ	05/19/2004
String Review	unlocalized	

Document Change History

Rev. Level	Change	Initials	Date
1.0	initial draft	DBO	06/14/2004
1.1	approved	DBO	05/07/2004
1.2	added reference to Package Manager Renaming specification	JL	2006-09-29
1.3	added warning when there is another unopkg running	JL	2008-02-27
1.4	Added: “Preventing Installation on wrong platform	JL	2008-04-03

Contents

Glossary	1

1	Motivation	1

2	User Scenarios	1

3	Requirements and Dependencies	1

3.1	Requirements	1

3.2	Technical Dependencies	1

4	Detailed Specification	2

4.1	Command line usage	2

4.2	Warning when unopkg is already running	2

5	Future Tasks	3

6	Notes	3

Glossary

Term	Description
Package	A package denotes a deployable item for an Office installation.

Motivation

Office extensions come in different flavors, e.g. a UNO component (piece of software) or a menu entry (configuration data) or a script (e.g. StarBasic). Generically, those extensions are called packages.
There is the need for a single entry point for all kinds of packages, so the user knows which packages are installed and how to remove them.
There is already an existing tool called pkgchk since OOo 1.1. That tool conflicts with a Solaris admin tool of the same name. Thus it makes sense to EOL (end of life) pkgchk, deprecating it in OOo 2.0. Besides the pkgchk functionality, the unopkg tool has a cleaned up command line syntax and a list command showing all present packages in detail.

User Scenarios

The user wants to add a package into its own Office installation's user/shared layer.

The user wants to remove a previously added package from its own Office installation's user/shared layer.

The user wants to know what packages are installed in its Office installation's user and shared layer as well as installed packages inside open documents.

Requirements and Dependencies

Requirements

[taken from Q-PCD: http://tools.openoffice.org/releases/q-concept.html#4.1.4.Programmability]
...

Currently users have to shut down a running office process before running the pkgchk deployment tool adding or removing packages. It may be desirable that users can deploy packages while running an office process and trigger removal of existing packages. Moreover, the currently used pkgchk deployment tool is a command line tool. If deployment can be performed while running the office process, a proper user interface is nice, too (e.g. in “Tools” menu bar).

...

Technical Dependencies

The command line tool unopkg is dependent on the PackageManager API being implemented.

Detailed Specification

Command line usage

Starting unopkg with -h will print out information about the usage of the tool:
using: unopkg add <options> extension-path...

unopkg validate <options> extension-identifier...

unopkg remove <options> extension-identifier...

unopkg list <options> extension-identifier...

unopkg reinstall <options>

unopkg gui

unopkg -V

unopkg -h

sub-commands:

add add extension

validate checks the prerequisites of an installed extension

and registers it if possible

remove remove extensions by identifier

reinstall export feature: reinstall all deployed extensions

list list information about deployed extensions

gui raise Extension Manager Graphical User Interface (GUI)

options:

-h, --help this help

-V, --version version information

-v, --verbose verbose output to stdout

-f, --force force overwriting existing packages

-s, --suppress-license prevents showing the license provided that

the extension allows it

--log-file <file> custom log file; default: <cache-dir>/log.txt

--shared expert feature: operate on shared installation

deployment context;

run only when no concurrent Office

process(es) are running!

--bundled expert feature: operate on bundled extensions. Only

works with list, validate and reinstall

--deployment-context expert feature: explicit deployment context

<context>

To learn more about the Extension Manager and extensions, see:

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Extensions/Extensions

Warning when unopkg is already running

When there is an instance of unopkg running, for example run “unopkg gui”, and one starts unopkg again, then a warning will appear, reading that the extension manager needs to be closed first. Please note, that this is only the case when no office is running.

When the second unopkg was started with the 'gui' switch then a message box will be displayed:

	English	German	Comment
1	ERROR: unopkg cannot be started. The lock file indicates it as already running. If this does not apply, delete the lock file at:		Output on the console.
2	unopkg cannot be started. The lock file indicates it as already running. If this does not apply, delete the lock file at:		Output in the message box.

If unopkg was started without the 'gui' option then the warning is printed in the console window. The text is the same as the one used in the warning box.

On windows one needs to run unopkg.com to receive console output. Usually it is sufficient to type unopkg. Windows will first try to find a .com executable and then an .exe executable.

Preventing Installation on wrong Platform

Extension can determine one or more target platform. The extension manager will install the extension only on those platforms. On other platforms the installation will be refused and an message is displayed:

English	Comment
The extension '%NAME' does not work on this computer.	%NAME will be replaced with the display name of the extension.

For more information refer to the openoffice.org wiki documentation:

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Extensions/Target_Platform

Synchronization at start-up

For technical details see

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Extensions/Processing_Extensions

If unopkg is run without the gui option and it detects that the repository of the shared or bundled extensions was modified, then it writes a notice on the console, provided that the –verbose switch is also used:

Synchronizing repository for shared extensions

or

Synchronizing repository for bundled extensions.

	English	German	Comment
1	Synchronizing repository for $NAME extensions		$Name is replaced either by shared or bundled.

This is followed by other output which is usually written during add or remove when the verbose option is applied.

Future Tasks

XSLT filter packages ought to be installable using unopkg.

All the existing error messages need to be reworked.

Notes

PackageManager Graphical User Interface

Page 4

<http://so-doc/Teams/Base_Technology/Groups/UNO/projects/packagemanager/packagemanager_gui_spec.sxw>

Joachim Lingner

2004-03-24T15:19:03

Bettina Haberer