From 18f8c7ea80b57211e8e594e1376861e4feaa55a3 Mon Sep 17 00:00:00 2001 From: Rüdiger Timm Date: Thu, 9 Mar 2006 09:49:40 +0000 Subject: INTEGRATION: CWS jl31 (1.3.14); FILE MERGED 2006/03/01 09:59:05 jl 1.3.14.4: #i62317# 2006/02/21 15:25:45 jl 1.3.14.3: # 2006/02/21 11:49:31 jl 1.3.14.2: #i62141# 2006/02/20 16:57:52 jl 1.3.14.1: #i62141# --- cli_ure/readme.txt | 362 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 270 insertions(+), 92 deletions(-) (limited to 'cli_ure/readme.txt') diff --git a/cli_ure/readme.txt b/cli_ure/readme.txt index 091d3a6ea084..9b2818b26244 100644 --- a/cli_ure/readme.txt +++ b/cli_ure/readme.txt @@ -1,94 +1,272 @@ +/************************************************************************* + * + * OpenOffice.org - a multi-platform office productivity suite + * + * $RCSfile: readme.txt,v $ + * + * $Revision: 1.4 $ + * + * last change: $Author: rt $ $Date: 2006-03-09 10:49:40 $ + * + * The Contents of this file are made available subject to + * the terms of GNU Lesser General Public License Version 2.1. + * + * + * GNU Lesser General Public License Version 2.1 + * ============================================= + * Copyright 2005 by Sun Microsystems, Inc. + * 901 San Antonio Road, Palo Alto, CA 94303, USA + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License version 2.1, as published by the Free Software Foundation. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, + * MA 02111-1307 USA + * + ************************************************************************/ -Necessary enty in scp2, for example cli_types (gac + program\assembly) + policy assembly -======================== - -#if defined WNT && (defined M1300 || defined M1310) // currently the only cli platform - -File gid_File_Lib_Cli_Types - TXT_FILE_BODY; - Styles = (PACKED, PATCH); - Name = "cli_types.dll"; - Dir = gid_Dir_Program_Assembly; -End - -#endif - -#if defined WNT && (defined M1300 || defined M1310) // currently the only cli platform - -File gid_File_Lib_Cli_Types_Assembly - TXT_FILE_BODY; - Styles = (PACKED, ASSEMBLY, PATCH, DONTRENAMEINPATCH); - Name = "cli_types.dll"; - Dir = gid_Dir_Program; - Assemblyname = "cli_types"; - PublicKeyToken = "ce2cb7e279207b9e"; - Version = "1.1.1.0"; - Culture = "neutral"; - Attributes = "0"; -End - -#endif - -#if defined WNT && (defined M1300 || defined M1310) // currently the only cli platform - -File gid_File_Lib_Policy_Cli_Types_Assembly - TXT_FILE_BODY; - Styles = (PACKED, ASSEMBLY, PATCH, DONTRENAMEINPATCH); - Name = "policy.1.1.cli_types.dll"; - Dir = gid_Dir_Program; - Assemblyname = "policy.1.1.cli_types"; - PublicKeyToken = "ce2cb7e279207b9e"; - Version = "1.0.0.0"; - Culture = "neutral"; - Attributes = "0"; -End - -#endif - -#if defined WNT && (defined M1300 || defined M1310) // currently the only cli platform - -File gid_File_Lib_Policy_Cli_Types_Config - TXT_FILE_BODY; - Styles = (PACKED, ASSIGNCOMPOMENT, PATCH, DONTRENAMEINPATCH); - Name = "cli_types.config"; - Dir = gid_Dir_Program; - AssignComponent = gid_File_Lib_Policy_Cli_Types_Assembly; -End - - - - -Versions of assemblies -========================== -SRC680 m122 - cli_types.dll 1.1.0.0 (the version was actually changed some time before that milestone) - no policy assembly - cli_cppuhelper 1.0.0.0 - no policy assembly - cli_basetypes.dll 1.0.0.0 - no policy assembly - cli_ure.dll 1.0.0.0 - no policy assembly - -SRC680 m140 - cli_types.dll 1.1.1.0 (added types) - policy.1.1.cli_types.dll 1.0.0.0 - cli_cppuhelper 1.0.0.0 - no policy assembly - cli_basetypes.dll 1.0.0.0 - no policy assembly - cli_ure.dll 1.0.0.0 - no policy assembly - -SRC680 m143 (or a little later) - cli_types.dll 1.1.1.0 (added types) - policy.1.1.cli_types.dll 1.0.0.0 - cli_cppuhelper 1.0.1.0 (references cli_types.dll 1.1.1.0) - policy.1.0.cli_cppuhelper.dll - cli_basetypes.dll 1.0.0.0 - no policy assembly - cli_ure.dll 1.0.1.0 (references cli_types.dll 1.1.1.0) - policy.1.0.cli_ure.dll - - +Adapting version after a release of an office +============================================= +After a release the entries in cli_ure/version/version.txt must be changed to reflect the versions +of the assemblies at the time of the release. Please refer to the document at +http://udk.openoffice.org/common/man/spec/assemblyversioninghistory.html +for more information about versioning of assemblies. + +Step 1: Remove old office installations. +To do this, deinstall all offices, +and make sure that there are no assemblies installed in the Global Assembly Cache (GAC). The GAC +is contained in C:\Windows\assembly. Change C:\Windows according to your windows installation. +Use the Windows Explorer to view the contents of the GAC. Are there any of the following assemblies +installed: + +cli_types.dll +cli_basetypes.dll +cli_cppuhelper.dll +cli_ure.dll + +policy.x.y.cli_types.dll +policy.x.y.cli_basetypes.dll +policy.x.y.cli_ure.dll +policy.x.y.cli_cppuhelper.dll + +The "x" and "y" in the names of the policy assemblies are to be replaces by version numbers. At the +time of writing the real names are: + +policy.1.1.cli_types.dll +policy.1.0.cli_basetypes.dll +policy.1.0.cli_ure.dll +policy.1.0.cli_cppuhelper.dll + +After deinstalling the offices, there should none of them remain in the GAC. If there are some, then +try to remove them by clicking on them an choose uninstall from the context menu of the mouse. + +Step 2: Install the office of the last release (respin when using staroffice) + +Step 3: Determine the versions of the assemblies +Use the Windows Explorer to view the contents of the Windows\assembly directory. Locate the assemblies +and policy assemblies. See step 1 for the names of those assemblies. Take down the version number as +can be found in the version column, which is usually right next to the name column. + +Step 4: Changing the versions in the cli_ure project. +Open the file cli_ure\version\version.txt. +The file contains name/value pairs, such as:CLI_TYPES_NEW_VERSION=1.1.3.0. +The first part of the names represent the assemly which they are referring to. So obviously +entries starting with CLI_TYPES refer to the cli_types.dll. Entries which contain the part "POLICY" refer +to the policy assembly. For example: +CLI_TYPES_POLICY_VERSION refers to the policy assembly for cli_types which is named +policy.1.1.cli_types.dll + +The versions may already have been incremented because someone has changed code after the +last release. So if a version from version.txt is greater then the one of the respective +assembly in the GAC then leave it at that. + +The values have to be adjusted as follows: + +XYZ_NEW_VERSION : change the version according to the version of the assembly from the +GAC. "XYZ_" would be "CLI_TYPES", "CLI_URE", etc. +XYZ_OLD_VERSION : must be changes so that the right version part is one less than +XYZ_NEW_VERSION. For example + +CLI_TYPES_NEW_VERSION=1.1.[3].0 +CLI_TYPES_OLD_VERSION=1.1.0.0-1.1.[2].0 + +The affected part is marked by the brackets. + +XYZ_POLICY_VERSION: change the version according to the version of the policy assembly from the +GAC. + +XYZ_POLICY_ASSEMBLY: remain unchanged. + + +Commit the changes and rebuild the project. + +The document +http://udk.openoffice.org/common/man/spec/assemblyversioninghistory.html +should be updated to contain the new versions. + +The automatic test in cli_ure/qa/versioning should be extended. See the readme.txt in that directory +for more information. + + + + + + + +How does the version mechanism works +==================================== + +The assemblies which are build in this project have a strong name and hence a version. The version should +be increased whenever something was fixed or the code has changed in any way. For further information +have a look at +http://udk.openoffice.org/common/man/spec/assemblyversioning.html + +The versions of all assemblies are contained in cli_ure/version/version.txt. This is the place where +the versions are changed. This will happen under two circumstances. First, the versions are +adjusted AFTER an office was released. The version.txt must then contain the versions at the +time of the release. Second, when something was fixed. Then a version should be changed unless +this has already be done for the next release. Please look at the document mentioned further +above. + +If new published UNO types have been added since the last release (product update) then the +minor version of cli_types.dll should be incremented. When building the version directory, a script +is run that recognizes this and writes a cliureversion.mk file in the bin directory. +cliureversion.mk contains all the entries of version.txt. The versions have been incremented +by the script. The script obtains the information of new types from unotype_statistics.txt +which is build in offapi. + +The contents of cliureversion.mk is used when building the assemblies in this project. It +is also delivered so that instset_native (or instsetoo_native) can use it when building +the installation sets. + + +The contents of version.txt +=========================== +The entries in version.txt are needed for building the assemblies and for building the +installation set (msi database). + +For every assembly exist four +entries. For example: + +CLI_TYPES_NEW_VERSION=1.1.3.0 +CLI_TYPES_OLD_VERSION=1.1.0.0-1.1.2.0 +CLI_TYPES_POLICY_VERSION=3.0.0.0 +CLI_TYPES_POLICY_ASSEMBLY=policy.1.1.cli_types + +The meaning of these entries is the following: + +CLI_TYPES_NEW_VERSION represents the current version of the assembly. + +CLI_TYPES_OLD_VERSION represents a range of former versions (which were compatible). +It has to be placed in the +cli_types.config XML file which is part of the policy assembly. This is done automatically. +The XYZ_OLD_VERSION and XYZ_NEW_VERSION values are used for the binding redirection of +the policy file. + +CLI_TYPES_POLICY_VERSION represents the version of the policy file. + +CLI_TYPES_POLICY_ASSEMBLY represents the name of the policy file. + +Please refer to the document at +http://udk.openoffice.org/common/man/spec/assemblyversioning.html +about how the versions have to look like. + +When the minor version is changed, which is the third number from the left, the +"old version" and the policy version must be changed as well. Using the former example, +an incremented version would look like this: +CLI_TYPES_NEW_VERSION=1.1.4.0 +CLI_TYPES_OLD_VERSION=1.1.0.0-1.1.3.0 +CLI_TYPES_POLICY_VERSION=4.0.0.0 +CLI_TYPES_POLICY_ASSEMBLY=policy.1.1.cli_types + +If the major version changed we would have these values: +CLI_TYPES_NEW_VERSION=2.0.0.0 +CLI_TYPES_OLD_VERSION=2.0.0.0-2.0.0.0 +CLI_TYPES_POLICY_VERSION=1.0.0.0 +CLI_TYPES_POLICY_ASSEMBLY=policy.2.0.cli_types + +Because a change of a major is only done if the code has changed incompatibly, we must not +redirect old client code to the new assembly. Actually we would not need a policy file here. +The name of the policy file has changed as well so as to refer to the new version. Since +the name is new and refers to the version 2 auf cli_types, we can start with the policy version +from 1. + +The next compatible change would require to change the version to these: +CLI_TYPES_NEW_VERSION=2.0.1.0 +CLI_TYPES_OLD_VERSION=2.0.0.0-2.0.1.0 +CLI_TYPES_POLICY_VERSION=2.0.0.0 +CLI_TYPES_POLICY_ASSEMBLY=policy.2.0.cli_types + + +Automatic incrementation of the version +======================================= +The automatic incrementation of the version this is done when new published types have been +introduce between two releases.In cli_ure/version/makefile.mk the script +cli_ure/source/scripts/increment_version.pl +is run which creates the cliureversion.mk with the new versions. This automatism only changes +the version parts which have the meaning of a compatible change. Which versions are to be +incremented is contained in cli_ure/version/incversions.txt. It contains, for example these entries: + +CLI_TYPES_NEW_VERSION +CLI_TYPES_OLD_VERSION +CLI_TYPES_POLICY_VERSION + +The names are exactly the same as in version.txt. The script knows how to increase the version +of the different types: + +Entries ending on _NEW_VERSION: The third number from the left is incremented. +Entries ending on _OLD_VERSION: The third number from the left of the second version is incremented. +Entries ending on _POLICY_VERSION: The first number from the left is incremented. + +For example, the versions in version.txt are: +CLI_TYPES_NEW_VERSION=1.1.4.0 +CLI_TYPES_OLD_VERSION=1.1.0.0-1.1.3.0 +CLI_TYPES_POLICY_VERSION=4.0.0.0 + +If new types have been added the script would create these entries in cliureversion.mk +CLI_TYPES_NEW_VERSION=1.1.5.0 +CLI_TYPES_OLD_VERSION=1.1.0.0-1.1.4.0 +CLI_TYPES_POLICY_VERSION=5.0.0.0 + +As one can see from the incversions.txt, the versions of the cli_ure.dll and cli_cppuhelper.dll +are also changed. This is because these are dependent on cli_types.dll. + + +Further notes on increasing the assembly versions +================================ +Changing a version for one assembly means changing +at least the XYZ_NEW_VERSION, XYZ_OLD_VERSION and XYZ_POLICY_VERSION. In case of an incompatible +change, that is one of the first two numbers of the version has been changed, the XYZ_POLICY_ASSEMBLY +must also be changed. + +When changing a version of an assembly then the versions of the assemblies which depend on it should +be changed as well. For example, when changing the version of cli_types.dll, then the versions of +cli_ure.dll and cli_cppuhelper.dll should be changed as well. One can use idlasm.exe to see which +assemblies are referenced by an assembly. The information is contained in the assemblie's manifest. + +If one would not change the versions of the dependent dlls then one would risk that an assembly +has the same old version but references a different assembly. For example, say we have a +cli_types.dll with version 1 and a cli_ure.dll with version 1. cli_ure.dll references version 1 of +cli_types.dll. Now the version of cli_types.dll changes to version 2 and its policy assembly is +adapted so that all code that uses version 1 now uses version 2. This would also allow cli_ure.dll +to run with the new cli_types.dll. If now cli_ure.dll is build, then it would reference +cli_types.dll version 2, because our build environment does not keep the older assembly. The old +cli_types.dll version 1 was replaced by version 2. cli_ure.dll now references cli_types.dll version 2 +but still has the old version. + + + +rebasing of assemblies +======================================================= +Neither assemblies nor policy assemblies may be rebased. This would +make the signature invalid. Therefore all assemblies must be contained +in postprocess/rebase/no_rebase.txt \ No newline at end of file -- cgit