Rebuilding PETSc and PyLith#
For instructions on how to build PyLith from source, please see the PyLith Installer Documentation.
Rebuilding PETSc#
Updating and rebuilding PETSc is quite simple once it has been configured and built once before.
Warning
Updating the PETSc knepley/pylith branch that PyLith uses almost always involves rebasing and forced pushes.
As a result, you cannot simply use git pull to update the knepley/pylith branch.
Instead, you need to delete the old knepley/pylith branch and then check it out again to get the current version.
# Change to PETSc source Directory
cd $PETSC_DIR
# Switch to the main branch and fetch the updates, pruning deleted branches.
git checkout main
git fetch -p
# Remove your old knepley/pylith branch and then get the current knepley/pylith branch.
git branch -D knepley/pylith
git checkout knepley/pylith
# Reconfigure
arch-pylith-debug/lib/petsc/conf/reconfigure-arch-pylith-debug.py
# Rebuild
make
Important
After rebuilding PETSc, you should rebuild PyLith. If there are incompatibilities between the two, then you will normally get compilation errors building PyLith. If there are incompatibilities and you do not rebuild PyLith, then you will usually get a segmentation fault when running PyLith.
Rebuilding PyLith#
Overview#
Pylith uses the GNU Build System (often called autotools, which consists of autoconf, automake, and libtool) to configure and build.
The configure options and checks are defined in configure.ac with additional macros in the m4 directory.
Note that the m4 directory is a Git submodule corresponding to the geodynamics/autoconf_cig Git repository.
Updating your fork#
It is a good idea to keep your main branch and any other branches you use from the geodynamics/pylith repository up to date.
See Updating Your Local Branch To Match The Upstream Repository for how to merge updates from the upstream (geodynamics/pylith) repository.
Makefiles#
The PyLith configure script uses automake to convert each Makefile.am file into a Makefile.
The organization and content of the Makefile.am file depends on whether it is related to the C++ library, SWIG interface files, Python modules, C++ unit tests, Python unit tests, MMS tests, full-scale tests, or examples.
For the C++ library files within the libsrc directory, the libsrc/Makefile.am contains the implementation files while the header files are listed in the Makefile.am file within the underlying directories.
For the SWIG interface files within the modulesrc directory, Makefile.am file contains information on how to build the SWIG Python module.
The Python modules use a single Makefile.am file in the pylith directory.
Each test suite (C++ unit tests for each subpackage, Python unit tests, and each suite of full-scale tests) use a single Makefile.am.
These files define how the tests are built, additional input files that should be included in the source distribution, and temporary files that should be deleted.
Each suite of examples contains a Makefile.am that defines the files that are to be included in the source distribution.
It also defines which files are created and should be deleted upon make clean.
Build Targets#
Several build targets are defined to make it easy to rebuild/reinstall PyLith and rerun tests whenever the source code changes.
Each target can be run using make TARGET where TARGET is one of the following:
allBuild all source code.
installBuild and install.
checkRun the entire test suite.
Tip
On a machine with multiple cores, faster builds of the C++ code (library and C++ unit tests) are available using the -jNTHREADS command line argument, where NTHREADS is the number of threads to use.
We usually set the number of threads equal to twice the number of physical cores.
After modifying code, the C++ library, SWIG modules, and Python code need to be rebuilt and reinstalled before running a PyLith simulation.
# Change to top-level PyLith build directory.
cd $PYLITH_BUILDDIR
# Reinstall everything using 8 threads to build library.
make install -j8
# Rebuild and reinstall only the library using 8 threads.
make install -j8 -C libsrc
# Rebuild and reinstall only the SWIG modules
make install -C modulesrc
# Reinstall only the Python modules
make install -C pylith
After modifying the C++ code, only the C++ library needs to be rebuilt before running C++ unit tests or MMS tests.
# Change to top-level PyLith build directory.
cd $PYLITH_BUILDDIR/build/pylith-debug
# Rebuild the library using 8 threads.
make -j8 -C libsrc
# Rerun the C++ unit tests.
make check -C tests/libtests
Similarly, after changing the Python code, only the Python modules need to be reinstalled before running a Python unit test. However, if changes are also made to the C++ code, then the C++ library and modules must be rebuilt and reinstalled before running a Python unit test.
# Change to top-level PyLith build directory.
cd $PYLITH_BUILDDIR/build/pylith-debug
# Reinstall PyLith Python modules.
make install -C pylith
# Rerun Python unit tests.
make check -C tests/pytests