[wxWidgets.git] / docs / tech / tn0025.txt

            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)


4. Special instructions for libpng
----------------------------------

We use a special hack for libpng as we want to prefix all its symbols with
"wx_" but don't want to use its build system which makes this easily possible
(perhaps we should, but for now we don't). So, when upgrading libpng, you need
to perform an extra step after merging the new version (and before committing
your changes):

Create a temporary build directory and run libpng configure from it using
--with-libpng-prefix=wx_ option. Then run "make" (actually just "make png.lo"
is sufficient as we don't really need to build the library) to create
pnglibconf.h and pngprefix.h files in the build directory. And copy these
files to src/png subdirectory of the wxWidgets source tree, overwriting the
versions there.

Notice that config.h generated by libpng configure is not used, we build it
without -DHAVE_CONFIG_H as it works just fine without it on any ANSI C system
(i.e. anywhere by now).
Commit	Line	Data
01588a9e VZ	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)
fff5f7d5 VZ	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).