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 ~/.bashrc or ~/.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/python@3.9/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/python@3.9/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

Maintaining Your PETSc Installation(s)#

Environmental Variables $PETSC_DIR And $PETSC_ARCH#

Configure Caching#

Reconfigure#

Updating or Reinstalling PETSc#

Environmental Variables `$PETSC_DIR` And `$PETSC_ARCH`#