Maintaining Your PETSc Installation(s)#
Sometimes it is useful to have multiple concurrently built versions of PETSc installed,
for example you may have a arch-darwin-opt and arch-darwin-debug. This would allow
you to run a highly optimized performance version of your code and a debug version simply
by changing the $PETSC_ARCH environment variable.
Environmental Variables $PETSC_DIR And $PETSC_ARCH#
Note
Applications completely providing their own makefiles do not need to use $PETSC_DIR
or $PETSC_ARCH
$PETSC_ARCH is only needed for in-place installations. For out-of-place
installations see documentation.
$PETSC_DIR and $PETSC_ARCH (in-place installs only) are used by the PETSc
makefiles to indicate which directory and configuration of PETSc to use when compiling
examples or application code. These variables can be set as environment variables or
specified on the command line:
Specify environment variable for bash (can be specified in
~/.bashrcor~/.bash_profile):$ export PETSC_DIR=/absolute/path/to/petsc $ export PETSC_ARCH=linux-gnu-c-debug
Specify environment variable for csh/tcsh (can be specified in
~/.cshrc):$ setenv PETSC_DIR /absolute/path/to/petsc $ setenv PETSC_ARCH linux-gnu-c-debug
Specify variable on commandline (bash) to build an example in
$PETSC_DIR/src/ts/tutorials:$ PETSC_ARCH=linux-gnu-c-debug make PETSC_DIR=/absolute/path/to/petsc ex1
$PETSC_DIR should point to the location of the PETSc installation. For out-of-place
installations this is the --prefix location. For in-place installations it is the
directory where you ran configure.
Configure Caching#
The first time you build PETSc, you must first run configure which (among other
things) serves to identify key characteristics about the computing environment:
The type of operating system
Available compilers, their locations, and versions
Location of common system header-files
Location of common system libraries
Whether your system supports certain instruction types (e.g. AVX)
And more…
While many things that configure must check are liable to change in between
consecutive configure invocations, some things are very unlikely – if ever – to
change. Hence configure can safely cache and reuse these values in subsequent
configure runs, helping to speed up the lengthy process. A similar system is also used
when determining whether to rebuild various packages installed through PETSc.
Note
While the caching system used by configure is very useful, it usually errs on
the side of caution. If a change has occurred in your system which could reasonably
change how a package/program is compiled, configure will automatically rebuild this
software for you.
If you would like to enforce that configure does not use any cached values, you may
use the --force option when configuring your PETSc installation:
$ ./configure --some-args --force
Keep in mind however that this will only disable configure’s cache, not any other
caching mechanism potentially in use, such as CCache.
Caution
If one still suspects malfeasance due to configure caching, or some corruption has
occurred due to a faulty configure one may use the nuclear option
--with-clean. This will permanently delete all build files, including installed
packages under $PETSC_DIR/$PETSC_ARCH (effectively a “clean slate”) before
runnning configure. The only thing preserved during this process is the
reconfigure script:
$ ./configure --many-args --with-clean
Reconfigure#
For the reasons listed above, the automatically generated
$PETSC_DIR/$PETSC_ARCH/lib/petsc/conf/reconfigure-$PETSC_ARCH.py (henceforth refered
to simply as reconfigure) script is generated for you upon successfully finishing
configure. reconfigure is a short-hand way of repeating your original
configure invocation with the same arguments. In addition, reconfigure will also
always explicitly define PETSC_ARCH within the configure arguments, so there is no
need to specificy which PETSc installation you wish to reconfigure.
For example running the following configure:
$ ./configure --download-mpich --download-fblaslapack --with-debugging=1
Will result in the following reconfigure:
#!/usr/local/opt/[email protected]/bin/python3.9
if __name__ == '__main__':
import sys
import os
sys.path.insert(0, os.path.abspath('config'))
import configure
configure_options = [
'--download-mpich',
'--download-fblaslapack',
'--with-debugging=1',
'PETSC_ARCH=arch-darwin-c-debug',
]
configure.petsc_configure(configure_options)
In order to rerun this configure with the same arguments simply do:
$ $PETSC_DIR/$PETSC_ARCH/lib/petsc/conf/reconfigure-$PETSC_ARCH.py
Note
The reconfigure script also comes with one additional powerful tool, namely the
ability to additively set new configure options, and also to change the values of
previous configure options! This is particularly useful if one has a lot of
external packages installed through PETSc and would like
to install another.
One need only call reconfigure, supplying any additional command-line arguments as
if it were the regular configure. Suppose one had an installation of PETSc with the following arguments (represented in the reconfigure script):
#!/usr/local/opt/[email protected]/bin/python3.9
if __name__ == '__main__':
import sys
import os
sys.path.insert(0, os.path.abspath('config'))
import configure
configure_options = [
'--download-mpich',
'--download-fblaslapack',
'--with-debugging=1',
'PETSC_ARCH=arch-darwin-c-debug',
]
configure.petsc_configure(configure_options)
Then calling it with new arguments:
$ $PETSC_DIR/$PETSC_ARCH/lib/petsc/conf/reconfigure-$PETSC_ARCH.py --download-zlib
Will install zlib into that reconfigure’s home
$PETSC_ARCH.
While it is automatically done for you the first time you configure and build PETSc,
it is useful to symlink the reconfigure script for each $PETSC_ARCH that you
intend to rebuild often into your $PETSC_DIR:
$ ln -s $PETSC_DIR/$PETSC_ARCH/lib/petsc/conf/reconfigure-$PETSC_ARCH.py $PETSC_DIR/
Updating or Reinstalling PETSc#
If you follow the main or release branches of PETSc you can update your libraries with:
$ git pull
$ make libs
Most of the time this will work, if there are errors regarding compiling Fortran stubs you need to also do:
$ make allfortranstubs