| blob | c1e4f64cc958e7fe79578127020f3ca1fbef3baa |
1 #*************************************************************************
2 #
3 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 #
5 # Copyright 2008 by Sun Microsystems, Inc.
6 #
7 # OpenOffice.org - a multi-platform office productivity suite
8 #
9 # $RCSfile: readme.txt,v $
10 #
11 # $Revision: 1.8 $
12 #
13 # This file is part of OpenOffice.org.
14 #
15 # OpenOffice.org is free software: you can redistribute it and/or modify
16 # it under the terms of the GNU Lesser General Public License version 3
17 # only, as published by the Free Software Foundation.
18 #
19 # OpenOffice.org is distributed in the hope that it will be useful,
20 # but WITHOUT ANY WARRANTY; without even the implied warranty of
21 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 # GNU Lesser General Public License version 3 for more details
23 # (a copy is included in the LICENSE file that accompanied this code).
24 #
25 # You should have received a copy of the GNU Lesser General Public License
26 # version 3 along with OpenOffice.org. If not, see
27 # <http://www.openoffice.org/license.html>
28 # for a copy of the LGPLv3 License.
29 #
30 # ************************************************************************/
32 Adapting version after a release of an office
33 =============================================
34 After a release the entries in cli_ure/version/version.txt must be changed to reflect the versions
35 of the assemblies at the time of the release. Please refer to the document at
36 http://udk.openoffice.org/common/man/spec/assemblyversioning.html
37 for more information about versioning of assemblies.
40 Step 1: Remove old office installations.
42 To do this, deinstall all offices,
43 and make sure that there are no assemblies installed in the Global Assembly Cache (GAC). The GAC
44 is contained in C:\Windows\assembly. Change C:\Windows according to your windows installation.
45 Use the Windows Explorer to view the contents of the GAC. Are there any of the following assemblies
46 installed:
48 cli_uretypes.dll
49 cli_basetypes.dll
50 cli_cppuhelper.dll
51 cli_ure.dll
52 cli_oootypes.dll (build in unoil)
54 policy.x.y.cli_uretypes.dll
55 policy.x.y.cli_basetypes.dll
56 policy.x.y.cli_ure.dll
57 policy.x.y.cli_cppuhelper.dll
58 policy.x.y.cli_oootypes.dll (build in unoil)
60 The "x" and "y" in the names of the policy assemblies are to be replaces by version numbers. At the
61 time of writing the real names are:
63 policy.1.0.cli_uretypes.dll
64 policy.1.0.cli_basetypes.dll
65 policy.1.0.cli_ure.dll
66 policy.1.0.cli_cppuhelper.dll
67 policy.1.0.cli_ootypes.dll (build in unoil)
69 After deinstalling the offices, there should none of them remain in the GAC. If there are some, then
70 try to remove them by clicking on them an choose uninstall from the context menu of the mouse.
72 Step 2: Install the office of the last release (respin when using staroffice)
74 Step 3: Determine the versions of the assemblies
76 Use the Windows Explorer to view the contents of the Windows\assembly directory. Locate the assemblies
77 and policy assemblies. See step 1 for the names of those assemblies. Take down the version number as
78 can be found in the version column, which is usually right next to the name column.
80 Step 4: Changing the versions in the cli_ure module.
82 Open the file cli_ure\version\version.txt.
83 The file contains name/value pairs, such as:CLI_URETYPES_NEW_VERSION=1.0.3.0.
84 The first part of the names represent the assemly which they are referring to. So obviously
85 entries starting with CLI_URETYPES refer to the cli_uretypes.dll. Entries which contain the part "POLICY" refer
86 to the policy assembly. For example:
87 CLI_URETYPES_POLICY_VERSION refers to the policy assembly for cli_uretypes which is named
88 policy.1.0.cli_uretypes.dll
90 The versions may already have been incremented because someone has changed code after the
91 last release. So if a version from version.txt is greater then the one of the respective
92 assembly in the GAC then leave it at that.
94 The values have to be adjusted as follows:
96 XYZ_NEW_VERSION : increse the value of the version
97 GAC. "XYZ_" would be "CLI_URETYPES", "CLI_URE", etc.
98 XYZ_OLD_VERSION : must be changes so that the right version part is one less than
99 XYZ_NEW_VERSION. For example
101 CLI_URETYPES_NEW_VERSION=1.0.[3].0
102 CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.[2].0
104 The affected part is marked by the brackets.
106 XYZ_POLICY_VERSION: change the version according to the version of the policy assembly from the
107 GAC.
109 XYZ_POLICY_ASSEMBLY: remain unchanged.
111 Commit the changes and rebuild the project.
113 Step 5: Changing the versions in the unoil module
115 The unoil module builds the cli_oootypes.dll which contains the office types (offapi). Change the contents
116 of unoil/climaker/version.txt similar to the versions.txt in this module. Then rebuild the module
118 //======
119 The automatic test in cli_ure/qa/versioning should be extended. See the readme.txt in that directory
120 for more information.
121 //=====
128 How does the version mechanism works
129 ====================================
131 The assemblies which are build in this project have a strong name and hence a version. The version should
132 be increased whenever something was fixed or the code has changed in any way. For further information
133 have a look at
134 http://udk.openoffice.org/common/man/spec/assemblyversioning.html
136 The versions of all assemblies are contained in cli_ure/version/version.txt. This is the place where
137 the versions are changed. This will happen under two circumstances. First, the versions are
138 adjusted AFTER an office was released. The version.txt must then contain the versions at the
139 time of the release. Second, when something was fixed. Then a version should be changed unless
140 this has already be done for the next release. Please look at the document mentioned further
141 above.
143 If new published UNO types have been added since the last release (product update) then the
144 minor version of cli_uretypes.dll should be incremented. When building the version directory, a script
145 is run that recognizes this and writes a cliureversion.mk file in the bin directory.
146 cliureversion.mk contains all the entries of version.txt. The versions have been incremented
147 by the script. The script obtains the information of new types from unotype_statistics.txt
148 which is build in offapi.
150 The contents of cliureversion.mk is used when building the assemblies in this project. It
151 is also delivered so that instset_native (or instsetoo_native) can use it when building
152 the installation sets.
155 The contents of version.txt
156 ===========================
157 The entries in version.txt are needed for building the assemblies and for building the
158 installation set (msi database).
160 For every assembly exist four
161 entries. For example:
163 CLI_URETYPES_NEW_VERSION=1.0.3.0
164 CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.2.0
165 CLI_URETYPES_POLICY_VERSION=3.0.0.0
166 CLI_URETYPES_POLICY_ASSEMBLY=policy.1.0.cli_uretypes
168 The meaning of these entries is the following:
170 CLI_URETYPES_NEW_VERSION represents the current version of the assembly.
172 CLI_URETYPES_OLD_VERSION represents a range of former versions (which were compatible).
173 It has to be placed in the
174 cli_uretypes.config XML file which is part of the policy assembly. This is done automatically.
175 The XYZ_OLD_VERSION and XYZ_NEW_VERSION values are used for the binding redirection of
176 the policy file.
178 CLI_URETYPES_POLICY_VERSION represents the version of the policy file.
180 CLI_URETYPES_POLICY_ASSEMBLY represents the name of the policy file.
182 Please refer to the document at
183 http://udk.openoffice.org/common/man/spec/assemblyversioning.html
184 about how the versions have to look like.
186 When the minor version is changed, which is the third number from the left, the
187 "old version" and the policy version must be changed as well. Using the former example,
188 an incremented version would look like this:
189 CLI_URETYPES_NEW_VERSION=1.0.4.0
190 CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.3.0
191 CLI_URETYPES_POLICY_VERSION=4.0.0.0
192 CLI_URETYPES_POLICY_ASSEMBLY=policy.1.0.cli_uretypes
194 If the major version changed we would have these values:
195 CLI_URETYPES_NEW_VERSION=2.0.0.0
196 CLI_URETYPES_OLD_VERSION=2.0.0.0-2.0.0.0
197 CLI_URETYPES_POLICY_VERSION=1.0.0.0
198 CLI_URETYPES_POLICY_ASSEMBLY=policy.2.0.cli_uretypes
200 Because a change of a major is only done if the code has changed incompatibly, we must not
201 redirect old client code to the new assembly. Actually we would not need a policy file here.
202 The name of the policy file has changed as well so as to refer to the new version. Since
203 the name is new and refers to the version 2 auf cli_uretypes, we can start with the policy version
204 from 1.
206 The next compatible change would require to change the version to these:
207 CLI_URETYPES_NEW_VERSION=2.0.1.0
208 CLI_URETYPES_OLD_VERSION=2.0.0.0-2.0.1.0
209 CLI_URETYPES_POLICY_VERSION=2.0.0.0
210 CLI_URETYPES_POLICY_ASSEMBLY=policy.2.0.cli_uretypes
213 Automatic incrementation of the version
214 =======================================
215 Currently switched off! See cli_ure/version/makefile.mk
216 The automatic incrementation of the version this is done when new published types have been
217 introduce between two releases.In cli_ure/version/makefile.mk the script
218 cli_ure/source/scripts/increment_version.pl
219 is run which creates the cliureversion.mk with the new versions. This automatism only changes
220 the version parts which have the meaning of a compatible change. Which versions are to be
221 incremented is contained in cli_ure/version/incversions.txt. It contains, for example these entries:
223 CLI_URETYPES_NEW_VERSION
224 CLI_URETYPES_OLD_VERSION
225 CLI_URETYPES_POLICY_VERSION
227 The names are exactly the same as in version.txt. The script knows how to increase the version
228 of the different types:
230 Entries ending on _NEW_VERSION: The third number from the left is incremented.
231 Entries ending on _OLD_VERSION: The third number from the left of the second version is incremented.
232 Entries ending on _POLICY_VERSION: The first number from the left is incremented.
234 For example, the versions in version.txt are:
235 CLI_URETYPES_NEW_VERSION=1.0.4.0
236 CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.3.0
237 CLI_URETYPES_POLICY_VERSION=4.0.0.0
239 If new types have been added the script would create these entries in cliureversion.mk
240 CLI_URETYPES_NEW_VERSION=1.0.5.0
241 CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.4.0
242 CLI_URETYPES_POLICY_VERSION=5.0.0.0
244 As one can see from the incversions.txt, the versions of the cli_ure.dll and cli_cppuhelper.dll
245 are also changed. This is because these are dependent on cli_uretypes.dll.
248 Further notes on increasing the assembly versions
249 ================================
250 Changing a version for one assembly means changing
251 at least the XYZ_NEW_VERSION, XYZ_OLD_VERSION and XYZ_POLICY_VERSION. In case of an incompatible
252 change, that is one of the first two numbers of the version has been changed, the XYZ_POLICY_ASSEMBLY
253 must also be changed.
255 When changing a version of an assembly then the versions of the assemblies which depend on it should
256 be changed as well. For example, when changing the version of cli_uretypes.dll, then the versions of
257 cli_ure.dll and cli_cppuhelper.dll should be changed as well. One can use idlasm.exe to see which
258 assemblies are referenced by an assembly. The information is contained in the assemblie's manifest.
260 If one would not change the versions of the dependent dlls then one would risk that an assembly
261 has the same old version but references a different assembly. For example, say we have a
262 cli_uretypes.dll with version 1 and a cli_ure.dll with version 1. cli_ure.dll references version 1 of
263 cli_uretypes.dll. Now the version of cli_uretypes.dll changes to version 2 and its policy assembly is
264 adapted so that all code that uses version 1 now uses version 2. This would also allow cli_ure.dll
265 o run with the new cli_uretypes.dll. If now cli_ure.dll is build, then it would reference
266 cli_uretypes.dll version 2, because our build environment does not keep the older assembly. The old
267 cli_uretypes.dll version 1 was replaced by version 2. cli_ure.dll now references cli_uretypes.dll version 2
268 but still has the old version.
272 rebasing of assemblies
273 =======================================================
274 Neither assemblies nor policy assemblies may be rebased. This would
275 make the signature invalid. Therefore all assemblies must be contained
276 in postprocess/rebase/no_rebase.txt