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
# "gtk+_packages.data", transform those data into build
# configurations, */CMakeLists.txt, and patch those results.  The shell
# script that implements all of this is run as follows:

./update_gtk+_packages.sh

# N.B. there are no plans to keep gtk_packages.xml, gtk_packages.rnc,
# or gtk+_packages.data under version control.  However, all
# essential files referred to by update_gtk+_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
# gtk+_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.

# Check for any errors in the above procedure:
less gtk+_packages.stderr

# That file currently shows there are 17 dependencies of gtk+ that are
# found with good jhbuild configurations and 22 dependencies of gtk+
# that are not found (because there are no jhbuild configurations for
# them).

# 10 of those "not found" packages are officially ignored as a matter of policy.
# See configure_epa.cmake for the full list, and the reasons for the
# policy.

# Some of those "not found" packages (i.e., libjpeg, libpng, and libtiff)
# still may require epa_build configurations, but for now we
# are putting up with the CMake warnings about these missing packages
# until we evaluate whether their lack compromises the
# wxwidgets capabilities on Unix (wxwidgets is the only PLplot-related
# package that depends on gtk+, and that dependency only occurs for
# the Unix case).

# The rest of the "not found" packages such as pkg-config and libffi have
# epa_build configurations that have been independently implemented.
# Some of those have hand-generated configurations (e.g.,
# pkg-config/CMakeLists.txt).  

# Other "not found" packages have been configured with a template
# (e.g., libffi).  This is done by adding additional configurations to
# add_packages.xml, processing 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.  The shell script
# that implements this is run as follows:

./update_added_packages.sh

# Look for any bad results:
less add_packages.stderr

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

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

cmake -DFILENAME:FILEPATH=gtk+_packages.data -P configure_epa.cmake
patch --reverse --no-backup-if-mismatch -p0 <configured_gtk+.patch
git 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
git diff

OTHER NOTES:

It is becoming clear that substantial numbers of users are
beginning to switch from the classical combination of MinGW and MSYS
to the more modern 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 for epa_build since apparently MSYS2 (a
simplified fork of modern Cygwin) has fewer bugs and uses more
up-to-date versions of software than the traditional MSYS (a
simplified fork of ancient Cygwin).

There are still a number of outstanding development issues for epa_build.
Please consult with AWI if you wish to work on one or more of these.

* 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
subset of the gtk+ stack of libraries that currently have epa_build
configuration problems for MinGW/MSYS.

* A qt5_lite epa_build configuration is planned which would enable
me to test PLplot against Qt5 (see recent list discussions concerning
Qt5).

* The qt4_lite build works fine on Linux but has not yet been tested on
Windows.

* The gtk+ complete stack of libraries (only required on Unix to
satisfy a wxwidgets Unix dependency) builds fine on Linux.  Part of
these good Linux build results are for the pango/cairo subset of the
gtk+ stack which is necessary on all platforms to support the "cairo"
PLplot device driver and the libLASi library (necessary to support the
psttf PLplot device driver).  Unfortunately, the pango/cairo subset of
gtk+ appears to have a number of build issues on Wine.  I suspect most
of those issues are not due to Wine bugs so I expect they will show up
on Microsoft Windows as soon as someone attempts a build of pango or
plplot (as opposed to plplot_lite) on that platform.

* Currently epa_build has only been tested on Windows using my
(extraordinarily slow) MinGW/MSYS/Wine platform for the plplot_lite
case.  The Wine developers view any deviation from Microsoft Windows
behaviour as a Wine bug.  So since it is unlikely that I am by
accident taking advantage of some Wine bug to make this work, it
should be trivial (and more than an order of magnitude faster than the
Wine case) to follow what I have done for the MinGW/MSYS/Microsoft
Windows case _if_ the bash.exe environment variable approach I
document in cmake/epa_build/README is religiously followed. I also
believe it should be straightforward to make the plplot_lite case work
on the Cygwin platform, a mingw-w64/MSYS2 Windows platform, and a Windows
platform consisting of the combination of MSYS (bash.exe and other
MSYS tools are required for testing PLplot but will not be used for
building it in this case) and MSVC.  I have access to none of those
platforms so volunteers are needed for this testing of epa_build for
the plplot_lite case.

* The epa_build of octave has not been configured.  Octave has an
enormous number of dependencies (much worse than PLplot), and I have
no experience building octave.  So I have decided to indefinitely put
off working on this epa_build configuration.  As a result, the octave
component of the plplot epa_build is currently disabled both for
plplot and plplot_lite, and it will likely be a long time before this
limitation is removed unless someone else is motivated to 
make this work.

