# Update instructions for new PETSc versions within the OpenCMISS framework.
# Developers only, Linux only.
#
# Please read the general (development) process agreements in the OpenCMISS documentation.
#
# What's being done before?
# - The generated CMakeLists.txt file has been modified at start and end to fit into the build system.
#   The beginning just contains options and defaults that are passed via command line by the manage script.
#   The end contains additional logic for installation and export of the cmake config files
# - The folder "cmake" contains any other subsequently added logic. The main bulk is in OpenCMISSPETScConfig.cmake,
#   where most of the checks done via python in the native build system are performed using cmake commands etc.
#   The main variables are "SEARCHFUNCTIONS", "SEARCHHEADERS" etc where you can simply add any new function that PETSc looks for; it
#   will create a PETSC_HAVE_XX variable for you.
# - A python script parses the test case makefiles to produce CMakeLists.txt files automatically
#
# Update procedure:
# - Make sure the versions of other packages (MUMPS,PASTIX etc) compatible with the new PETSc
#   version are updated first and compile within the OpenCMISS build system.
# - Download the new PETSc sources to a separate folder
# - Use the "cmake/petsc_configure_opencmiss.sh" to configure and build petsc natively against the OpenCMISS components (change folders etc)
# - The configure stage will create a new CMakeLists.txt file. This is the new base for the existing CMakeLists.txt.
# - Checkout the "devel" branch of the PETSc repo
# - Remove and replace the /src folder with the new contents, also the /bin /conf /config and /include folders. This way git will pickup the new, changed
#   and removed files automatically.
# - Use a merge tool (I use Eclipse "Compare with .. each other") to import new source files/remove old source files in CMakeLists.txt
# - The file "PETScConfig.cmake" is generated by the native PETSc build system (withing the architecture path). Also do a merge
#   to detect any new variables added in the new version. Note that most of them are already cared for in the OpenCMISSPETScConfig script; 
#   this script is more or less the residual of anything that has not yet been transformed into CMake detection logic.
#   Moreover, as the PETScConfig script is generated, it only contains variables for /found/ stuff; anything not found is still checked for
#   in the python scripts. So, different platforms will likely give different configs not yet catered for!
# - Tests: Run the "cmake/convert_tests.py" to parse the makefiles in each examples/(tests|tutorials) folder and automatically generate CMake
#   code to have the tests run within the ctest framework. For more information see the python script; it should suffice to just run it.
# - Test data: Some matrices from the petsc ftp have been added to /share/petsc/datafiles/matrices.
#
# Test procedure:
# - Try building everything locally first in static/shared modes
# - Run the tests
# - Run the development integration tests (ABI: buildbot, Stuttgart: Jenkins) for the "devel" branches