From 01588a9e314d136222e9aaede0082b40506611bf Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sun, 7 Jul 2013 17:35:18 +0000 Subject: [PATCH] Add instructions for upgrading third party libraries. Describe the process for upgrading the libraries for which we already use svn vendor branches. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@74450 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/tech/index.txt | 1 + docs/tech/tn0025.txt | 106 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 docs/tech/tn0025.txt diff --git a/docs/tech/index.txt b/docs/tech/index.txt index b0fc874..f8736ac 100644 --- a/docs/tech/index.txt +++ b/docs/tech/index.txt @@ -25,5 +25,6 @@ tn0021.txt How to add a new wxUSE_XXX preprocessor constant tn0022.txt Making a new release tn0023.txt Adding a new app/screenshot to the wxWidgets.org front page tn0024.txt How to add a new XRC handler +tn0025.txt How to update a third party library to a newer version Version: $Id$ diff --git a/docs/tech/tn0025.txt b/docs/tech/tn0025.txt new file mode 100644 index 0000000..f4635c9 --- /dev/null +++ b/docs/tech/tn0025.txt @@ -0,0 +1,106 @@ + How to update a third party library to a newer version + ====================================================== + +0. Introduction +--------------- + +wxWidgets includes several third party libraries, i.e. libraries which are +used by wxWidgets and distributed with it but which we don't maintain nor even +modify, inasmuch as possible, ourselves. These libraries are developed by +their maintainers and from time to time we need to replace the versions used +by wxWidgets with newer versions. + + +1. Vendor branches +------------------ + +Normally all third party libraries should be managed using Subversion vendor +branches. I.e. we should have the latest version of the library under +/wx/wxWidgets/vendor directory in the repository. Currently only expat, libpng +and libtiff are handled like this, while libjpeg and zlib are not. Hopefully +these exceptions will disappear soon, the rest of this note assumes that we +are using a vendor branch for the library $(LIB). + +We also use $(OLD_VERSION) and $(VERSION) below for the current version of the +library and the version we are upgrading to. $(OLD_VERSION) can be determined +by doing + + svn ls https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB) + +as normally it's the latest version present in this directory. You can, of +course, also look at the library sources currently in the trunk to find out +its version. + + +NB: the instructions here are based on the Subversion documentation, see +http://svnbook.red-bean.com/en/1.6/svn.advanced.vendorbr.html for more +information about vendor branches. + + +2. Updating the current branch +------------------------------ + +The first thing to do is to checkout a pristine copy of the version currently +being used, e.g. + + cd /some/temp/directory + svn checkout https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current $(LIB) + +Now delete all the old files: + + cd $(LIB) + find . -type f -not -path '*/.svn/*' -exec rm {} \; + +or, if you are using zsh, just + + rm **/*(.) + +Next, get the version of the library you are updating to and unpack it into +the same directory. Examine "svn status" output and add all the files with "?" +in the first column using "svn add" and delete all the files with "!" in the +first column using "svn rm". + +Finally commit and tag the new version: + + svn commit -m 'Update $(LIB) to $(VERSION).' + svn cp https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current \ + https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/$(VERSION) \ + -m 'Tagging $(LIB) $(VERSION).' + +You can now do + + rm -rf /some/temp/directory/$(LIB) + +as it won't be needed any longer. + + +3. Merging the current branch +----------------------------- + +Now switch to wxWidgets checkout and run + + svn merge ^/wxWidgets/vendor/$(LIB)/$(OLD_VERSION) ^/wxWidgets/vendor/$(LIB)/current src/$(LIBDIR) + +Notice that you may need to escape the circumflexes with backslashes if they +are special for your shell. Also notice that the directory of the library may +be different from its name, e.g. we use libpng for the vendor branch but just +png for the name of the directory. + +Unless you are very lucky, the merge will result in conflicts and you will +need to resolve them by examining the differences -- this is the difficult +part. + +Once everything was resolved, test your changes. As building the third party +libraries is quite different between Unix and Windows, please do it under both +platforms. Under Windows it's enough to just build everything as usual as the +built-in libraries are used by default. Please build both static and dynamic +wxWidgets libraries as some problems arise only in one of those configurations. +Under Unix you need to configure with --with-$(LIB)=builtin option to ensure +that the newly updated built-in version of the library is used and not the +system version. If upgrading an image format library, please build and run the +image sample. In any case, run the unit tests to check that everything still +works. + +After testing and correcting the problems, simply commit your changes: + + svn commit -m 'Update $(LIB) to $(VERSION).' src/$(LIBDIR) -- 2.7.4