docs/tech/tn0025.txt

   1             How to update a third party library to a newer version
   2             ======================================================
   3
   4 0. Introduction
   5 ---------------
   6
   7 wxWidgets includes several third party libraries, i.e. libraries which are
   8 used by wxWidgets and distributed with it but which we don't maintain nor even
   9 modify, inasmuch as possible, ourselves. These libraries are developed by
  10 their maintainers and from time to time we need to replace the versions used
  11 by wxWidgets with newer versions.
  12
  13
  14 1. Vendor branches
  15 ------------------
  16
  17 Normally all third party libraries should be managed using Subversion vendor
  18 branches. I.e. we should have the latest version of the library under
  19 /wx/wxWidgets/vendor directory in the repository. Currently only expat, libpng
  20 and libtiff are handled like this, while libjpeg and zlib are not. Hopefully
  21 these exceptions will disappear soon, the rest of this note assumes that we
  22 are using a vendor branch for the library $(LIB).
  23
  24 We also use $(OLD_VERSION) and $(VERSION) below for the current version of the
  25 library and the version we are upgrading to. $(OLD_VERSION) can be determined
  26 by doing
  27
  28     svn ls https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)
  29
  30 as normally it's the latest version present in this directory. You can, of
  31 course, also look at the library sources currently in the trunk to find out
  32 its version.
  33
  34
  35 NB: the instructions here are based on the Subversion documentation, see
  36 http://svnbook.red-bean.com/en/1.6/svn.advanced.vendorbr.html for more
  37 information about vendor branches.
  38
  39
  40 2. Updating the current branch
  41 ------------------------------
  42
  43 The first thing to do is to checkout a pristine copy of the version currently
  44 being used, e.g.
  45
  46     cd /some/temp/directory
  47     svn checkout https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current $(LIB)
  48
  49 Now delete all the old files:
  50
  51     cd $(LIB)
  52     find . -type f -not -path '*/.svn/*' -exec rm {} \;
  53
  54 or, if you are using zsh, just
  55
  56     rm **/*(.)
  57
  58 Next, get the version of the library you are updating to and unpack it into
  59 the same directory. Examine "svn status" output and add all the files with "?"
  60 in the first column using "svn add" and delete all the files with "!" in the
  61 first column using "svn rm".
  62
  63 Finally commit and tag the new version:
  64
  65     svn commit -m 'Update $(LIB) to $(VERSION).'
  66     svn cp https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/current \
  67         https://svn.wxwidgets.org/svn/wx/wxWidgets/vendor/$(LIB)/$(VERSION) \
  68         -m 'Tagging $(LIB) $(VERSION).'
  69
  70 You can now do
  71
  72     rm -rf /some/temp/directory/$(LIB)
  73
  74 as it won't be needed any longer.
  75
  76
  77 3. Merging the current branch
  78 -----------------------------
  79
  80 Now switch to wxWidgets checkout and run
  81
  82     svn merge ^/wxWidgets/vendor/$(LIB)/$(OLD_VERSION) ^/wxWidgets/vendor/$(LIB)/current src/$(LIBDIR)
  83
  84 Notice that you may need to escape the circumflexes with backslashes if they
  85 are special for your shell. Also notice that the directory of the library may
  86 be different from its name, e.g. we use libpng for the vendor branch but just
  87 png for the name of the directory.
  88
  89 Unless you are very lucky, the merge will result in conflicts and you will
  90 need to resolve them by examining the differences -- this is the difficult
  91 part.
  92
  93 Once everything was resolved, test your changes. As building the third party
  94 libraries is quite different between Unix and Windows, please do it under both
  95 platforms. Under Windows it's enough to just build everything as usual as the
  96 built-in libraries are used by default. Please build both static and dynamic
  97 wxWidgets libraries as some problems arise only in one of those configurations.
  98 Under Unix you need to configure with --with-$(LIB)=builtin option to ensure
  99 that the newly updated built-in version of the library is used and not the
 100 system version. If upgrading an image format library, please build and run the
 101 image sample. In any case, run the unit tests to check that everything still
 102 works.
 103
 104 After testing and correcting the problems, simply commit your changes:
 105
 106     svn commit -m 'Update $(LIB) to $(VERSION).' src/$(LIBDIR)
 107
 108
 109 4. Special instructions for libpng
 110 ----------------------------------
 111
 112 We use a special hack for libpng as we want to prefix all its symbols with
 113 "wx_" but don't want to use its build system which makes this easily possible
 114 (perhaps we should, but for now we don't). So, when upgrading libpng, you need
 115 to perform an extra step after merging the new version (and before committing
 116 your changes):
 117
 118 Create a temporary build directory and run libpng configure from it using
 119 --with-libpng-prefix=wx_ option. Then run "make" (actually just "make png.lo"
 120 is sufficient as we don't really need to build the library) to create
 121 pnglibconf.h and pngprefix.h files in the build directory. And copy these
 122 files to src/png subdirectory of the wxWidgets source tree, overwriting the
 123 versions there.
 124
 125 Notice that config.h generated by libpng configure is not used, we build it
 126 without -DHAVE_CONFIG_H as it works just fine without it on any ANSI C system
 127 (i.e. anywhere by now).