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. Submodules
-------------

All third party libraries are managed using Git submodules. This includes
3rdparty/catch and expat, jpeg, png, tiff and zlib subdirectories of src.

As always with submodules, updating a library involves updating its sources in
the submodule, pushing this submodule out and then committing the changes in
the top-level repository.


2. Updating the submodule
-------------------------

All submodules use `master` branch for the upstream master and `wx` for the
version used by wxWidgets. To update the latter, just merge the appropriate
commit from master into `wx`, e.g.

    $ cd src/expat
    $ git checkout wx
    $ git merge R_x_y_z # For the latest x.y.z release

After resolving any conflicts, commit the result, test the build under MSW and
under Unix using `--disable-sys-libs` configure option, and push the updated
branch out. Notice that you may want to use the ssh GitHub repository URL
instead of the default (because more convenient for checking them out) HTTPS
one:

    $ git push --set-upstream git@github.com:wxWidgets/libexpat.git wx


3. Generating build files (libexpat, libtiff)
---------------------------------------------

We include the generated build files of libexpat and libtiff. For libexpat run
`buildconf.sh`. For libtiff run `autogen.sh`. Commit the changes.


4. Updating the main repository
-------------------------------

If there are any changes to the source files used by the library, update the
corresponding `build/bakefiles/$lib.bkl` file (e.g. `expat.bkl` for Expat) and
rerun bakefile to regenerate most of the makefiles and project files. Currently
you will need to update `build/msw/wx_wx$lib.vcxproj{,.filters}` files
manually.

Commit these changes and the submodule and create a PR to test them as usual.


5. 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 pnglibconf.h pngprefix.h`
to create these files in the build directory. Next, search for the line
containing `PNG_ZLIB_VERNUM` in the `pnglibconf.h` and set it to 0 to disable
zlib version checks (this looks dangerous but seems to be unavoidable with the
current build system). And then, finally, 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).