xref: /aoo42x/main/cli_ure/readme.txt (revision 537f9df8)
1#**************************************************************
2#
3#  Licensed to the Apache Software Foundation (ASF) under one
4#  or more contributor license agreements.  See the NOTICE file
5#  distributed with this work for additional information
6#  regarding copyright ownership.  The ASF licenses this file
7#  to you under the Apache License, Version 2.0 (the
8#  "License"); you may not use this file except in compliance
9#  with the License.  You may obtain a copy of the License at
10#
11#    http://www.apache.org/licenses/LICENSE-2.0
12#
13#  Unless required by applicable law or agreed to in writing,
14#  software distributed under the License is distributed on an
15#  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16#  KIND, either express or implied.  See the License for the
17#  specific language governing permissions and limitations
18#  under the License.
19#
20#**************************************************************
21
22Adapting version after a release of an office
23=============================================
24After a release the entries in cli_ure/version/version.txt must be changed to reflect the versions
25of the assemblies at the time of the release. Please refer to the document at
26http://udk.openoffice.org/common/man/spec/assemblyversioning.html
27for more information about versioning of assemblies.
28
29
30Step 1: Remove old office installations.
31
32To do this, deinstall all offices,
33and make sure that there are no assemblies installed in the Global Assembly Cache (GAC). The GAC
34is contained in  C:\Windows\assembly. Change C:\Windows according to your windows installation.
35Use the Windows Explorer to view the contents of the GAC. Are there any of the following assemblies
36installed:
37
38cli_uretypes.dll
39cli_basetypes.dll
40cli_cppuhelper.dll
41cli_ure.dll
42cli_oootypes.dll (build in unoil)
43
44policy.x.y.cli_uretypes.dll
45policy.x.y.cli_basetypes.dll
46policy.x.y.cli_ure.dll
47policy.x.y.cli_cppuhelper.dll
48policy.x.y.cli_oootypes.dll (build in unoil)
49
50The "x" and "y" in the names of the policy assemblies are to be replaces by version numbers. At the
51time of writing the real names are:
52
53policy.1.0.cli_uretypes.dll
54policy.1.0.cli_basetypes.dll
55policy.1.0.cli_ure.dll
56policy.1.0.cli_cppuhelper.dll
57policy.1.0.cli_ootypes.dll (build in unoil)
58
59After deinstalling the offices, there should none of them remain in the GAC. If there are some, then
60try to remove them by clicking on them an choose uninstall from the context menu of the mouse.
61
62Step 2: Install the office of the last release (respin when using staroffice)
63
64Step 3: Determine the versions of the assemblies
65
66Use the Windows Explorer to view the contents of the Windows\assembly directory. Locate the assemblies
67and policy assemblies. See step 1 for the names of those assemblies. Take down the version number as
68can be found in the version column, which is usually right next to the name column.
69
70Step 4: Changing the versions in the cli_ure module.
71
72Open the file cli_ure\version\version.txt.
73The file contains name/value pairs, such as:CLI_URETYPES_NEW_VERSION=1.0.3.0.
74The first part of the names represent the assemly which they are referring to. So obviously
75entries starting with CLI_URETYPES refer to the cli_uretypes.dll. Entries which contain the part "POLICY" refer
76to the policy assembly. For example:
77CLI_URETYPES_POLICY_VERSION refers to the policy assembly for cli_uretypes which is named
78policy.1.0.cli_uretypes.dll
79
80The versions may already have been incremented because someone has changed code after the
81last release. So if a version from version.txt is greater then the one of the respective
82assembly in the GAC then leave it at that.
83
84The values have to be adjusted as follows:
85
86XYZ_NEW_VERSION : increse the value of the version
87GAC. "XYZ_" would be "CLI_URETYPES", "CLI_URE", etc.
88XYZ_OLD_VERSION : must be changes so that the right version part is one less than
89XYZ_NEW_VERSION. For example
90
91CLI_URETYPES_NEW_VERSION=1.0.[3].0
92CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.[2].0
93
94The affected part is marked by the brackets.
95
96XYZ_POLICY_VERSION: change the version according to the version of the policy assembly from the
97GAC.
98
99XYZ_POLICY_ASSEMBLY: remain unchanged.
100
101Commit the changes and rebuild the project.
102
103Step 5: Changing the versions in the unoil module
104
105The unoil module builds the cli_oootypes.dll which contains the office types (offapi). Change the contents
106of unoil/climaker/version.txt similar to the versions.txt in this module. Then rebuild the module
107
108//======
109The automatic test in cli_ure/qa/versioning should be extended. See the readme.txt in that directory
110for more information.
111//=====
112
113
114
115
116
117
118How does the version mechanism works
119====================================
120
121The assemblies which are build in this project have a strong name and hence a version. The version should
122be increased whenever something was fixed or the code has changed in any way. For further information
123have a look at
124http://udk.openoffice.org/common/man/spec/assemblyversioning.html
125
126The versions of all assemblies are contained in cli_ure/version/version.txt. This is the place where
127the versions are changed. This will happen under two circumstances. First, the versions are
128adjusted AFTER an office was released. The version.txt must then contain the versions at the
129time of the release. Second, when something was fixed. Then a version should be changed unless
130this has already be done for the next release. Please look at the document mentioned further
131above.
132
133If new published UNO types have been added since the last release (product update) then the
134minor version of cli_uretypes.dll should be incremented. When building the version directory, a script
135is run that recognizes this and writes a cliureversion.mk file in the bin directory.
136cliureversion.mk contains all the entries of version.txt. The versions have been incremented
137by the script. The script obtains the information of new types from unotype_statistics.txt
138which is build in offapi.
139
140The contents of cliureversion.mk is used when building the assemblies in this project. It
141is also delivered so that instset_native (or instsetoo_native) can use it when building
142the installation sets.
143
144
145The contents of version.txt
146===========================
147The entries in version.txt are needed for building the assemblies and for building the
148installation set (msi database).
149
150For every assembly exist four
151entries. For example:
152
153CLI_URETYPES_NEW_VERSION=1.0.3.0
154CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.2.0
155CLI_URETYPES_POLICY_VERSION=3.0.0.0
156CLI_URETYPES_POLICY_ASSEMBLY=policy.1.0.cli_uretypes
157
158The meaning of these entries is the following:
159
160CLI_URETYPES_NEW_VERSION represents the current version of the assembly.
161
162CLI_URETYPES_OLD_VERSION represents a range of former versions (which were compatible).
163It has to be placed in the
164cli_uretypes.config XML file which is part of the policy assembly. This is done automatically.
165The XYZ_OLD_VERSION and XYZ_NEW_VERSION values are used for the binding redirection of
166the policy file.
167
168CLI_URETYPES_POLICY_VERSION represents the version of the policy file.
169
170CLI_URETYPES_POLICY_ASSEMBLY represents the name of the policy file.
171
172Please refer to the document at
173http://udk.openoffice.org/common/man/spec/assemblyversioning.html
174about how the versions have to look like.
175
176When the minor version is changed, which is the third number from the left, the
177"old version" and the policy version must be changed as well. Using the former example,
178an incremented version would look like this:
179CLI_URETYPES_NEW_VERSION=1.0.4.0
180CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.3.0
181CLI_URETYPES_POLICY_VERSION=4.0.0.0
182CLI_URETYPES_POLICY_ASSEMBLY=policy.1.0.cli_uretypes
183
184If the major version changed we would have these values:
185CLI_URETYPES_NEW_VERSION=2.0.0.0
186CLI_URETYPES_OLD_VERSION=2.0.0.0-2.0.0.0
187CLI_URETYPES_POLICY_VERSION=1.0.0.0
188CLI_URETYPES_POLICY_ASSEMBLY=policy.2.0.cli_uretypes
189
190Because a change of a major is only done if the code has changed incompatibly, we must not
191redirect old client code to the new assembly. Actually we would not need a policy file here.
192The name of the policy file has changed as well so as to refer to the new version. Since
193the name is new and refers to the version 2 auf cli_uretypes, we can start with the policy version
194from 1.
195
196The next compatible change would require to change the version to these:
197CLI_URETYPES_NEW_VERSION=2.0.1.0
198CLI_URETYPES_OLD_VERSION=2.0.0.0-2.0.1.0
199CLI_URETYPES_POLICY_VERSION=2.0.0.0
200CLI_URETYPES_POLICY_ASSEMBLY=policy.2.0.cli_uretypes
201
202
203Automatic incrementation of the version
204=======================================
205Currently switched off! See cli_ure/version/makefile.mk
206The automatic incrementation of the version this is done when new published types have been
207introduce between two releases.In cli_ure/version/makefile.mk the script
208cli_ure/source/scripts/increment_version.pl
209is run which creates the cliureversion.mk with the new versions. This automatism only changes
210the version parts which have the meaning of a compatible change. Which versions are to be
211incremented is contained in cli_ure/version/incversions.txt. It contains, for example these entries:
212
213CLI_URETYPES_NEW_VERSION
214CLI_URETYPES_OLD_VERSION
215CLI_URETYPES_POLICY_VERSION
216
217The names are exactly the same as in version.txt. The script knows how to increase the version
218of the different types:
219
220Entries ending on _NEW_VERSION: The third number from the left is incremented.
221Entries ending on _OLD_VERSION: The third number from the left of the second version is incremented.
222Entries ending on _POLICY_VERSION: The first number from the left is incremented.
223
224For example, the versions in version.txt are:
225CLI_URETYPES_NEW_VERSION=1.0.4.0
226CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.3.0
227CLI_URETYPES_POLICY_VERSION=4.0.0.0
228
229If new types have been added the script would create these entries in cliureversion.mk
230CLI_URETYPES_NEW_VERSION=1.0.5.0
231CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.4.0
232CLI_URETYPES_POLICY_VERSION=5.0.0.0
233
234As one can see from the incversions.txt, the versions of the cli_ure.dll and cli_cppuhelper.dll
235are also changed. This is because these are dependent on cli_uretypes.dll.
236
237
238Further notes on increasing the assembly versions
239================================
240Changing a version for one assembly means changing
241at least the XYZ_NEW_VERSION, XYZ_OLD_VERSION and XYZ_POLICY_VERSION. In case of an incompatible
242change, that is one of the first two numbers of the version has been changed, the XYZ_POLICY_ASSEMBLY
243must also be changed.
244
245When changing a version of an assembly then the versions of the assemblies which depend on it should
246be changed as well. For example, when changing the version of cli_uretypes.dll, then the versions of
247cli_ure.dll and cli_cppuhelper.dll should be changed as well. One can use idlasm.exe to see which
248assemblies are referenced by an assembly. The information is contained in the assemblie's manifest.
249
250If one would not change the versions of the dependent dlls then one would risk that an assembly
251has the same old version but references  a different assembly. For example, say we have a
252cli_uretypes.dll with version 1 and a cli_ure.dll with version 1. cli_ure.dll references version 1 of
253cli_uretypes.dll. Now the version of cli_uretypes.dll changes to version 2 and its policy assembly is
254adapted so that all code that uses version 1 now uses version 2. This would also allow cli_ure.dll
255o run with the new cli_uretypes.dll. If now cli_ure.dll is build, then it would reference
256cli_uretypes.dll version 2, because our build environment does not keep the older assembly. The old
257cli_uretypes.dll version 1 was replaced by version 2. cli_ure.dll now references cli_uretypes.dll version 2
258but still has the old version.
259
260
261
262rebasing of assemblies
263=======================================================
264Neither assemblies nor policy assemblies may be rebased. This would
265make the signature invalid. Therefore all assemblies must be contained
266in postprocess/rebase/no_rebase.txt
267