Difference between revisions of "Building installation packages"
m (Renamed HowTo to How To Create Patches) |
m (Add a Known Issues section) |
||
Line 123: | Line 123: | ||
:to create an updated version of the <code>releases.xml</code> file. Follow the last message in the output to copy the updated file to <code>instsetoo_native/data/</code> and commit it to SVN. | :to create an updated version of the <code>releases.xml</code> file. Follow the last message in the output to copy the updated file to <code>instsetoo_native/data/</code> and commit it to SVN. | ||
− | + | ===Known Issues=== | |
+ | *Deinstallation of a patch (not deinstallation of a patched OpenOffice) is prevented by the test that checks if OpenOffice is still running. | ||
+ | *After application of a patch Windows asks to reboot to activate changes to registry entries. That should not be necessary. | ||
[[Category:Documentation/Building Guide]] | [[Category:Documentation/Building Guide]] |
Revision as of 12:10, 13 December 2013
Contents
Installation packages
The building of installation packages is the last step in building OpenOffice. It is triggered by the makefile.mk
in main/instsetoo_native/util/
but most of the work is done by the solenv/bin/make_installer.pl
and modules under solenv/bin/modules/installer/
. 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 files and other items like registry entries (only on Windows) are defined as script items in the scp2
module. The installation technique depends on the operating system:
- Windows
- An MSI that is run by
setup.exe
. The use ofsetup.exe
allows the installation of some Windows redistributables. It is built asloader2.exe
inmain/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
.
- an upgrade key read from
- 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.
How To Create Installation Sets
Installation sets are created when you run build
in instsetoo_native
. How to set up the build system is described in the building guide and step by step building guide. When your build system is configured you can build OpenOffice like this:
cd main/instsetoo_native source ../winenv.set.sh # or another *.[sS]et.sh, the name depends on your platform build --all
You can speed up the building process by running it in multiple parallel processes like this
build --all -P4 -- -P4
where the numbers depend on how much your CPU can handle and if you still want to work with your computer while you are building. On a 4 core CPU the -P4 -- -P4
option leaves a Linux system responsive while a Windows system starts to lag.
The build
command in instsetoo_native/<code> (with or without the <code>--all
option) builds installation sets for all languages that where given to configure
via the --with-lang
option. Without the --with-lang
option the set of languages defaults to en-US
. There is a second multiplication factor for the installation sets that are built: the package format. The set of package formats depends on the platform. For Windows that is msi
, for Linux that is deb
and/or rpm
and for Mac that is dmg
. There is another package format that is available on all platforms. The archive
is built by default, but only for en-US
, even when more languages where specified via --with-lang
.
If you want to build only one installation set for a fixed combination of language and package format then
cd instsetoo_native/util dmake <target>_<language>.<package>
The list of available targets is listed when you run
dmake help
The list of available languages is the one you gave to --with-lang
and the list of available package formats is the one explained above (archive
, msi
, deb
, rpm
, dmg
).
Patches on Windows
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%.
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.
- 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.
- 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.
Conditions for creating patches
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.
- The values of the
- 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.
jani: would rename be possible ? zero length files are often a problem with backup/copy.
andre:No, the name has to remain unchanged. But maybe we can put one byte into files.
- 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
andKey
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.
- The
Current state
The patch creation on Windows has been reimplemented. The existing implementation was inactive, incomplete and undocumented and therefore could not be reused.
Workflow
In the typical use case patches are created from the previous version to the currently released version.
The process of creating MSP patches can be broken down into three steps:
- Build installation sets of OpenOffice with the additional option
release=t
.
- This enforces the conditions that where described above by integrating information about the source release into the build process. This information is taken from downloadable installation sets. These are expected in the
ext_sources/
directory. When they are missing (which is the default) then they are downloaded fromarchive.apache.org
. This should not lead to band width problems because release builds usually are made only by the release manager twice a year. - Possible optimizations (to reduce the amount of additional disk space):
- Use only the MSI files of previous releases. Most of the required information can be extracted from them. This approach has two disadvantages:
- MSI files of older releases are not stored anywhere.
- When files are removed then, to fulfill the patch requirements, the files of the previous release are used instead. These files are contained in the CAB file and are not present in the MSI.
- Use only the MSI files of previous releases. Most of the required information can be extracted from them. This approach has two disadvantages:
- Create the patch.
- This is done by the new Perl script
solenv/bin/patch_tool.pl
. It performs four basic steps:- For both the previous and the current release unpack the downloadable installation sets (not necessary for the current release) to get access to MSI and CAB files and unpack the CAB file (requirement of the msimsp.exe that will ultimately create the MSP patch.
- Check that all requirements (listed above) are fulfilled.
- Set up a PCP file that is basically an MSI with some additional restrictions. Its tables describe for example the version numbers of previous and current release so that when the patch is applied, Windows can check that the patch is applicable to the installed version of OpenOffice.
- Run the msimsp.exe program of the Windows SDK with the PCP as driver file. After about 15 minutes it creates the MSP patch file.
- Add information about the current release to
instsetoo_native/data/releases.xml
.
- The most important part of the information is the URL of where the release can be found on the Apache servers. When the next release is build the
releases.xml
file can also be used to guess the (then) previous release version.
The patch creation mechanism should be able to handle other combinations of source and target versions. This case is just not handled by the instsetoo_native/util/makefile.mk
. You have to call solennv/bin/patch_tool.pl
from the command line and provide --source-version
and --target-version
options.
How To Create Patches
Creating patches is quite simple:
- Prepare to build OpenOffice as you usually do.
- (Optional but recommended) Provide downloadable installation sets in
ext_sources/
for the languages you are interested in. - (Optional but recommended) Define the previous release number by adding a or modifying the line in
instsetoo_native/util/openoffice.lst
that definesPREVIOUS_VERSION
. You find it in thevariables
section of the product which you are building (most likely 'Apache_OpenOffice' and/or 'Apache_OpenOffice_SDK'). For example
... Apache_OpenOffice { Settings { variables { ... PRODUCTVERSION 4.1.0 PREVIOUS_VERSION 4.0.1 ...
- Got to
instsetoo_native
and callbuild
with your favorite options and an additionalrelease=t
. For example
build --all -P4 -- -P4 release=t
- When that the build has finished go to
instsetoo_native/util/
and run
dmake patch-create
- This will produce the MSP files as
instsetoo_native/wntmsci12.pro/Apache OpenOffice/msp/VERSION/LANGUAGE/openoffice.msp
. The VERSION part encodes the previous and current version. For an upgrade from 4.0.1 to 4.1 it would bev-4-0-1_v-4-1-0
- Still in
instsetoo_native/util/
run
dmake patch-update-releases-xml
- to create an updated version of the
releases.xml
file. Follow the last message in the output to copy the updated file toinstsetoo_native/data/
and commit it to SVN.
Known Issues
- Deinstallation of a patch (not deinstallation of a patched OpenOffice) is prevented by the test that checks if OpenOffice is still running.
- After application of a patch Windows asks to reboot to activate changes to registry entries. That should not be necessary.