This file contains directions for developers of the epa_build project.
If you are only interested in using that project, you should be
consulting the README file instead.

The GNOME Tool Kit stack of libraries is normally built by jhbuild
which keeps its configuration files in xml form.  Here is how you
convert that form of build-configuration data to the epa_build form.

# Download the jhbuild data for GTK_VERSION=3.9.4, collect all the
# *.xml results into one giant xml file, "gtk_packages.xml", patch
# that file, create a schema for that file, "gtk_packages.rnc" (not
# used for anything but debugging of xml issues), convert that file to
# a sequential form that can be read in by cmake called
# "pango_packages.data", transform those data into build
# configurations, */CMakeLists.txt, and patch those results.
./update_pango_packages.sh

Check for any errors:

# Check for errors:
less  pango_packages.stderr

# That file currently shows there are 10 "good"
# packages (ones found as a result of the pango package dependency
# chain) and 14 "bad" packages (ones not found this way which have to
# be configured another way).

# N.B. there are no plans to keep gtk_packages.xml, gtk_packages.rnc,
# or pango_packages.data under version control.  However, all
# essential files referred to by update_pango_packages.sh such as
# gtk_xml_recursive_process.py, patch_gtk_packages.xml, and
# gtk_transform.py are all kept under version control so that
# gtk_packages_$GTK_VERSION.xml, gtk_packages_$GTK_VERSION.rnc, and
# pango_packages.data can be reproduced at any time for the current
# $GTK_VERSION value or produced for some updated $GTK_VERSION value
# in the future.  Note that in that latter case, it will be necessary
# to edit the file names in patch_gtk_packages.xml to conform to the
# new version.

# One known issue with the gtk+ stack and other software we build is
# certain package dependencies are completely missing (called "bad
# packages above) such as pkg-config and libffi which have to be built
# independently.  For some of those missing packages we use a
# hand-generated configuration (e.g., pkg-config/CMakeLists.txt).  For
# others that can be configured with a template (e.g., libffi) we add
# additional configurations to add_packages.xml, process that file
# with enough starting packages to include all dependent packages
# in the resulting sequential file called "add_packages.data" which
# is then processed to generated added build configurations such as libffi.

./update_added_packages.sh

# Look for any bad results:
less add_packages.stderr

# It turns out there is one "bad" package, pkg-config which must be
# configured with a hand-edited configuration.

# N.B. The build configurations generated by
# "./update_pango_packages.sh" and "./update_added_packages.sh" are
# committed under svn control so that care should be used to keep
# everything consistent so that the above scripts introduce no svn
# diffs.

# Assuming no changes have been made to the essential files used by
# "update_pango_packages.sh" (which are gtk_xml_recursive_process.py,
# patch_gtk_packages.xml, and gtk_transform.py) to generate
# pango_packages.data, then you can quickly check for such consistency
# without running "./update_pango_packages.sh" using

cmake -DFILENAME:FILEPATH=pango_packages.data -P configure_epa.cmake
patch --reverse --no-backup-if-mismatch -p0 <configured_pango.patch
svn diff

# Similarly, assuming no changes have been made to the essential files
# used by "update_added_packages.sh" (which are add_packages.xml and
# gtk_transform.py) to generate add_packages.data, then you can
# quickly check for such consistency without running
# "./update_added_packages.sh" using
cmake -DFILENAME:FILEPATH=add_packages.data -P configure_epa.cmake
svn diff

OTHER NOTES:

The epa_build configurations are still missing for certain packages.
For example, a build of a strong-enough version of cmake so that it
can support "https" downloads (sometimes required by epa_build itself)
requires that cmake not use its weak internal curl library and instead
use a fully configured external curl library.  So the cmake epa_build
should be configured with an external libcurl epa_build dependency,
but that dependency does not exist yet.  So I plan to use the
directions (actually for the mingw-w64 fork of MinGW rather than for
MinGW itself) in
<http://www.gaia-gis.it/gaia-sins/mingw64_how_to.html> as a guide to
create an epa_build configure for both libcurl and its openssl
dependency.  Note, that URL contains mingw-w64 build directions for a
large number of free software packages so it may also be useful to
solve some epa_build problems for some packages for the pango/cairo
stack of libraries that currently have epa_build configuration
problems for MinGW/MSYS.

Also, it is becoming clear that many users are switching from the
classical combination of MinGW and MSYS to the combination of
mingw-w64 and MSYS2 (see <http://sourceforge.net/p/msys2/wiki/MSYS2
installation/> for install directions for that newer version).  Note
that new platform cannot be currently tested on Wine because of
<http://bugs.winehq.org/show_bug.cgi?id=35561> so my (AWI's)
participation in such tests could only be indirect.  Nevertheless, I
would encourage such tests since apparently MSYS2 (a simplification of
modern Cygwin) has fewer bugs and uses more up-to-date versions of
software than the traditional MSYS (a simplification of ancient
Cygwin).

