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.

# Change to PETSc source Directory
cd $PETSC_DIR

# Fetch the updates, pruning deleted branches.
git fetch -p

# Ensure you are on the `knepley/pylith` branch and then pull updates.
git checkout knepley/pylith
git pull

# 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#

As long as you setup your main branch to correspond to upstream/main, you should never have to use the main branch in your fork. You only use your fork for your feature branches.

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:

all: Build all source code.
install: Build and install.
check: Run 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.

Listing 342 Rebuilding Pylith C++ library, SWIG modules, and Python modules#

# Change to top-level PyLith build directory.
cd $PYLITH_BUILDDIR

# Reinstall everything using 16 threads to build library.
make install -j16

# Rebuild and reinstall only the library using 16 threads.
make install -j16 -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.

Listing 343 Rebuilding Pylith C++ library and rerunning the C++ unit tests#

# Change to top-level PyLith build directory.
cd $PYLITH_BUILDDIR/build/pylith-debug

# Rebuild the library using 16 threads.
make -j16 -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.

Listing 344 Rebuilding Pylith Python modules and rerunning Python unit tests#

# 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