Difference between revisions of "Building installation packages"

From Apache OpenOffice Wiki
Jump to: navigation, search
(+cat)
(Add conditions to Windows section that should allow successful patch creation.)
Line 19: Line 19:
 
===Windows===
 
===Windows===
 
On Windows there are Windows Installer patches (or .msp files) similar to installation packages (or .msi files).  These are self-contained packages that, for example on double-click from the file explorer, perform the update automatically and without the need for further applications.
 
On Windows there are Windows Installer patches (or .msp files) similar to installation packages (or .msi files).  These are self-contained packages that, for example on double-click from the file explorer, perform the update automatically and without the need for further applications.
−
 
−
Msi and msp files are COM Structured Storages (http://en.wikipedia.org/wiki/COM_Structured_Storage) and (at least in the case of AOO) contain at least two streams.  One contains the files to install or update, and the other holds a relational database whose tables contain information about the installation (for msi files) or update process (for msp files).
 
−
 
−
The msi and msp databases can be read or modified in three different ways, each of which depends on the Windows Installer SDK (current version for Windows 7 is 5.0) which is contained in the MS Windows SDK:
 
−
 
−
# Through a set of executables that can read and modify msi and msp files.  Msidb.exe (http://msdn.microsoft.com/en-us/library/windows/desktop/aa370083%28v=vs.85%29.aspx) gives read and write access to the database stream.  Msimsp.exe creates the msp patch file.
 
−
# By using the Windows Script Host together with the WiRunSQL.vbs script to access the database stream via SQL commands.
 
−
# A custom program that uses the Patchwiz.dll to get access to the database stream.
 
−
 
−
Tables can not be deleted from the database stream with method 1 but with method 2.  Never tried method 3.
 
  
 
Windows MSP updates can have three different types (see http://msdn.microsoft.com/en-us/library/windows/desktop/aa370579%28v=vs.85%29.aspx for more details):
 
Windows MSP updates can have three different types (see http://msdn.microsoft.com/en-us/library/windows/desktop/aa370579%28v=vs.85%29.aspx for more details):
 +
*Small Updates
 +
*Minor Upgrades
 +
*Major Upgrades
  
−
;Small Updates:Changes to the msi file and application files. No change of either ProductCode nor ProductVersion
+
As small updates do not allow a change of the version number, a minor upgrade is the one the one best suited for Apache OpenOffice updates.
−
;Minor Upgrades:No Change to ProductCode.<br/>Change of the ProductVersion
+
A major upgrade should be used for ?.0 releases.  While a major upgrade corresponds with our use of .msi files, the creation of minor upgrades requires additional work. On the conceptual level the creation of a minor upgrade is quite simple.
−
;Major Upgrades:Change the installation into a different product.<br/>Change of the ProduceCode.
+
# Locate two installation sets, old and new or source and target, both as a pairs of .msi and .cab file.  The .msi file is a database with a set of tables that describe the files and registry entries to install.  The .cab file contains the actual files.
−
 
+
# Create a .pcp file that is basically a data file that drives the patch creation.
−
So, a minor upgrade is the one best suited for Apache OpenOffice updates, because we don't change the product but only the version number.
+
# Run the MsiMsp.exe command from the Windows installer SDK. This results in a single .msp file.
−
 
+
# The .msp can be applied on a computer which has the source installation set installed.  The result of that is equivalent to installing the target installation set.
−
Creating a msp patch is basically quite simple:
+
−
# Take two msi files, the old version that is to be patched, and the new target version. Lets call them msi_o and msi_t.
+
−
# Check the product codes in both msi files ("ProductCode" in the "Property" table).  They have to be the same. Modify the product code in msi_t if they are not.
+
−
# Create a local pcp file that controls the patch creation process:
+
−
## Copy the template.pcp provided by the Windows Installer SDK to, say, aoo_update.pcp.
+
−
## Update the properies in its "PatchMetadata" table (basically metadata that describe who updates what and when).
+
−
## Update some values in the "Properties" table:
+
−
##* Set PatchOutputPath to the name of the resulting msp patch file.
+
−
##* Set PatchGUID to a newly created UUID.
+
−
## Add a row to the "ImageFamilies" table with generic data for the msi that is to be patched.
+
−
## Add a row to the "UpgradedImages" table with generic data for the patch target.
+
−
## Remove the "PatchSequence".
+
−
# Run MsiMsp.exe on the aoo_update.pcp file.  It creates the msp patch file and log data.  For this it compares the set of files contained in the two msi files (but it also expects these files already unpacked from the msi on disk).
+
−
# The log data can be converted to human readable form (HTML pages) with the wilogutl.exe command.
+
−
 
+
  
−
The resulting msp patch file can be run from the Windows file explorer and will turn a previously installed msi_o into a what installation of msi_t would result in.  Well, almost. Experiments have shown that there are some subtle differences. One is that the about box still read Apache  OpenOffice 3.4.0 instead of 3.4.1. But that may be a "feature" of the update mode.
+
There are a number of conditions that both source and target installation sets have to fulfill.  Breaking this conditions may result in very subtle errors either during the patch creation or application.  The conditions are defined on values in tables in the .msi files of source and target installation sets:
 +
* In the <code>Property</code> table:
 +
** The values of the <code>UpgradeCode</code> property differ.<br> Identical values indicate the same version => no need to create a patch.
 +
** The values of the <code>ProductCode</code> property are identical.
 +
** The values of the <code>PRODUCTBUILDID</code> property differ and the newer value is higher than the old value.
 +
* Adding and deleting files, registry entries, components, features:
 +
** New files can be added but only to new components in new features.
 +
* Files and Components (and registry entries?) must not be deleted.<br>If a file is not needed anymore than it may be possible to set its size to zero instead of deleting it completely.
 +
* For components that exist in the <code>Component</code> table of the old installation set:
 +
** There is a corresponding component in the new installation set (ie. components must not be deleted).
 +
** Its <code>ComponentId</code> values do not change.
 +
** Its <code>Component</code> values do not change.
 +
** That means that the component names (ie the <code>ComponentId</code> values) do not contain the full AOO version number. Just the major version number would be OK.
 +
** Maybe: The <code>KeyPath</code> values point to the same files.
 +
* For registry entries that exist in the <code>Registry</code> table in the old installation set:
 +
** There is a corresponding registry entry in the new installation set (ie. registry entries must not be deleted).
 +
** The <code>Registry</code> values do not change.
 +
** The <code>Key</code> values do not change.
 +
** That means that the component names (both the <code>Registry</code> and <code>Key</code> values) must not contain the full AOO version number.  Just the major version number would be OK.
 +
* In the <code>File</code> table:
 +
** The <code>Sequence</code> values remain identical for files that are in both the old and the new installation sets, regardless of whether a file has changes or not.
 +
** The <code>Sequence</code> values are unique.
 +
** Probably: The <code>Sequence</code> values form a sequence without holes.
  
 
===Current state===
 
===Current state===

Revision as of 08:52, 22 October 2013

Installation packages

The building of installation packages is the last step in building Apache OpenOffice. It takes place in the main/instsetoo_native module. It basically consists of collecting all files that are to be installed and putting them into an archive that can be installed on the targeted operating system. The installation technique depends on the operating system:

Windows
An MSI that is run by setup.exe. The use of setup.exe allows the installation of some Windows redistributables. It is built as loader2.exe in main/desktop/win32/source/setup/. It runs an upgrade instead of a full installation if
  • an upgrade key read from setup.ini exists in the Windows registry
  • setup.exe finds any .msp files
  • there is an instance of AOO already installed and that matches the product code read from setup.ini.
For the download version the msi and setup.exe are wrapped by an NSIS installer.
Linux
A set of RPM or DEB packages that are installed by distribution specific package managers.
MacOSX
A DMG archive that is (can be?) copied into the /Application directory.

Installation packages are created by Perl script main/solenv/bin/make_installer.pl and a larger number of Perl modules in main/solenv/bin/modules/installer/. The make_installer.pl script is run by the makefile main/instsetoo_native/util/makefile.mk.

Patch sets

A patch differs from a full installation package in that it only contains the modified files. For the update from AOO 3.4 to 3.4.1 this leads to size reduction of roughly 90%.

The structure, content and creation of patch sets depends on the operating system.

Windows

On Windows there are Windows Installer patches (or .msp files) similar to installation packages (or .msi files). These are self-contained packages that, for example on double-click from the file explorer, perform the update automatically and without the need for further applications.

Windows MSP updates can have three different types (see http://msdn.microsoft.com/en-us/library/windows/desktop/aa370579%28v=vs.85%29.aspx for more details):

  • Small Updates
  • Minor Upgrades
  • Major Upgrades

As small updates do not allow a change of the version number, a minor upgrade is the one the one best suited for Apache OpenOffice updates. A major upgrade should be used for ?.0 releases. While a major upgrade corresponds with our use of .msi files, the creation of minor upgrades requires additional work. On the conceptual level the creation of a minor upgrade is quite simple.

  1. Locate two installation sets, old and new or source and target, both as a pairs of .msi and .cab file. The .msi file is a database with a set of tables that describe the files and registry entries to install. The .cab file contains the actual files.
  2. Create a .pcp file that is basically a data file that drives the patch creation.
  3. Run the MsiMsp.exe command from the Windows installer SDK. This results in a single .msp file.
  4. The .msp can be applied on a computer which has the source installation set installed. The result of that is equivalent to installing the target installation set.

There are a number of conditions that both source and target installation sets have to fulfill. Breaking this conditions may result in very subtle errors either during the patch creation or application. The conditions are defined on values in tables in the .msi files of source and target installation sets:

  • In the Property table:
    • The values of the UpgradeCode property differ.
      Identical values indicate the same version => no need to create a patch.
    • The values of the ProductCode property are identical.
    • The values of the PRODUCTBUILDID property differ and the newer value is higher than the old value.
  • Adding and deleting files, registry entries, components, features:
    • New files can be added but only to new components in new features.
  • Files and Components (and registry entries?) must not be deleted.
    If a file is not needed anymore than it may be possible to set its size to zero instead of deleting it completely.
  • For components that exist in the Component table of the old installation set:
    • There is a corresponding component in the new installation set (ie. components must not be deleted).
    • Its ComponentId values do not change.
    • Its Component values do not change.
    • That means that the component names (ie the ComponentId values) do not contain the full AOO version number. Just the major version number would be OK.
    • Maybe: The KeyPath values point to the same files.
  • For registry entries that exist in the Registry table in the old installation set:
    • There is a corresponding registry entry in the new installation set (ie. registry entries must not be deleted).
    • The Registry values do not change.
    • The Key values do not change.
    • That means that the component names (both the Registry and Key values) must not contain the full AOO version number. Just the major version number would be OK.
  • In the File table:
    • The Sequence values remain identical for files that are in both the old and the new installation sets, regardless of whether a file has changes or not.
    • The Sequence values are unique.
    • Probably: The Sequence values form a sequence without holes.

Current state

Current state of support for creating patches in the OpenOffice build system:

  • The make_installer.pl scripts does already have some support for creating msp patches. This feature, however, is not activated and thus can not be triggered by the instsetoo_native makefile.
  • make_installer.pl creates a new and random product code GUID on every run. This has to be changed for supporting msp patch files. The product code has to remain constant between updates. There is already some support for constant product codes (see instsetoo_native/inc_openoffice/windows/msi_templates) but that is not yet active.
Retrieved from "https://wiki.openoffice.org/w/index.php?title=Building_installation_packages&oldid=231816"
Personal tools