1(doc_multi)= 2 3# Maintaining Your PETSc Installation(s) 4 5Sometimes it is useful to have multiple concurrently built versions of PETSc installed, 6for example you may have a `arch-darwin-opt` and `arch-darwin-debug`. This would allow 7you to run a highly optimized performance version of your code and a debug version simply 8by changing the `$PETSC_ARCH` environment variable. 9 10## Environmental Variables `$PETSC_DIR` And `$PETSC_ARCH` 11 12:::{note} 13Applications completely providing their own makefiles do not need to use `$PETSC_DIR` 14or `$PETSC_ARCH` 15 16`$PETSC_ARCH` is only needed for in-place installations. For out-of-place 17installations see {ref}`documentation <doc_config_install>`. 18::: 19 20`$PETSC_DIR` and `$PETSC_ARCH` (in-place installs only) are used by the PETSc 21makefiles to indicate which directory and configuration of PETSc to use when compiling 22examples or application code. These variables can be set as environment variables or 23specified on the command line: 24 25- Specify environment variable for bash (can be specified in `~/.bashrc` or 26 `~/.bash_profile`): 27 28 ```console 29 $ export PETSC_DIR=/absolute/path/to/petsc 30 $ export PETSC_ARCH=linux-gnu-c-debug 31 ``` 32 33- Specify environment variable for csh/tcsh (can be specified in `~/.cshrc`): 34 35 ```console 36 $ setenv PETSC_DIR /absolute/path/to/petsc 37 $ setenv PETSC_ARCH linux-gnu-c-debug 38 ``` 39 40- Specify variable on commandline (bash) to build an example in 41 `$PETSC_DIR/src/ts/tutorials`: 42 43 ```console 44 $ PETSC_ARCH=linux-gnu-c-debug make PETSC_DIR=/absolute/path/to/petsc ex1 45 ``` 46 47`$PETSC_DIR` should point to the location of the PETSc installation. For out-of-place 48installations this is the `--prefix` location. For in-place installations it is the 49directory where you ran `configure`. 50 51(doc_multi_confcache)= 52 53## Configure Caching 54 55The first time you build PETSc, you must first run `configure` which (among other 56things) serves to identify key characteristics about the computing environment: 57 58- The type of operating system 59- Available compilers, their locations, and versions 60- Location of common system header-files 61- Location of common system libraries 62- Whether your system supports certain instruction types (e.g. AVX) 63- And more... 64 65While many things that `configure` must check are liable to change in between 66consecutive `configure` invocations, some things are very unlikely -- if ever -- to 67change. Hence `configure` can safely cache and reuse these values in subsequent 68`configure` runs, helping to speed up the lengthy process. A similar system is also used 69when determining whether to rebuild various packages installed through PETSc. 70 71:::{note} 72While the caching system used by `configure` is very useful, it usually errs on 73the side of caution. If a change has occurred in your system which could reasonably 74change how a package/program is compiled, `configure` will automatically rebuild this 75software for you. 76 77If you would like to enforce that `configure` does not use any cached values, you may 78use the `--force` option when configuring your PETSc installation: 79 80```console 81$ ./configure --some-args --force 82``` 83 84Keep in mind however that this will only disable `configure`'s cache, not any other 85caching mechanism potentially in use, such as [CCache](https://ccache.dev/). 86::: 87 88:::{admonition} Caution 89:class: yellow 90 91If one still suspects malfeasance due to `configure` caching, or some corruption has 92occurred due to a faulty `configure` one may use the nuclear option 93`--with-clean`. This will **permanently delete all build files, including installed 94packages** under `$PETSC_DIR/$PETSC_ARCH` (effectively a "clean slate") before 95running `configure`. The only thing preserved during this process is the 96`reconfigure` script: 97 98```console 99$ ./configure --many-args --with-clean 100``` 101::: 102 103## Reconfigure 104 105For the reasons listed {ref}`above <doc_multi_confcache>`, the automatically generated 106`$PETSC_DIR/$PETSC_ARCH/lib/petsc/conf/reconfigure-$PETSC_ARCH.py` (henceforth referred 107to simply as `reconfigure`) script is generated for you upon successfully finishing 108`configure`. `reconfigure` is a short-hand way of repeating your original 109`configure` invocation with the same arguments. In addition, `reconfigure` will also 110always explicitly define `PETSC_ARCH` within the `configure` arguments, so there is no 111need to specify which PETSc installation you wish to reconfigure. 112 113For example running the following `configure`: 114 115```console 116$ ./configure --download-mpich --download-fblaslapack --with-debugging=1 117``` 118 119Will result in the following `reconfigure`: 120 121```python 122#!/usr/local/opt/python@3.9/bin/python3.9 123if __name__ == '__main__': 124 import sys 125 import os 126 sys.path.insert(0, os.path.abspath('config')) 127 import configure 128 configure_options = [ 129 '--download-mpich', 130 '--download-fblaslapack', 131 '--with-debugging=1', 132 'PETSC_ARCH=arch-darwin-c-debug', 133 ] 134 configure.petsc_configure(configure_options) 135``` 136 137In order to rerun this `configure` with the same arguments simply do: 138 139```console 140$ $PETSC_DIR/$PETSC_ARCH/lib/petsc/conf/reconfigure-$PETSC_ARCH.py 141``` 142 143:::{Note} 144The `reconfigure` script also comes with one additional powerful tool, namely the 145ability to additively set new `configure` options, and also to change the values of 146previous `configure` options! This is particularly useful if one has a lot of 147{ref}`external packages <doc_externalsoftware>` installed through PETSc and would like 148to install another. 149 150One need only call `reconfigure`, supplying any additional command-line arguments as 151if it were the regular `configure`. Suppose one had an installation of PETSc with the following arguments (represented in the `reconfigure` script): 152 153```python 154#!/usr/local/opt/python@3.9/bin/python3.9 155if __name__ == '__main__': 156 import sys 157 import os 158 sys.path.insert(0, os.path.abspath('config')) 159 import configure 160 configure_options = [ 161 '--download-mpich', 162 '--download-fblaslapack', 163 '--with-debugging=1', 164 'PETSC_ARCH=arch-darwin-c-debug', 165 ] 166 configure.petsc_configure(configure_options) 167``` 168 169Then calling it with new arguments: 170 171```console 172$ $PETSC_DIR/$PETSC_ARCH/lib/petsc/conf/reconfigure-$PETSC_ARCH.py --download-zlib 173``` 174 175Will install [zlib](https://zlib.net/) into that `reconfigure`'s home 176`$PETSC_ARCH`. 177::: 178 179While it is automatically done for you the first time you `configure` and build PETSc, 180it is useful to symlink the `reconfigure` script for each `$PETSC_ARCH` that you 181intend to rebuild often into your `$PETSC_DIR`: 182 183```console 184$ ln -s $PETSC_DIR/$PETSC_ARCH/lib/petsc/conf/reconfigure-$PETSC_ARCH.py $PETSC_DIR/ 185``` 186 187## Updating or Reinstalling PETSc 188 189If you follow the main or release branches of PETSc you can update your libraries with: 190 191```console 192$ git pull 193$ make libs 194``` 195 196Most of the time this will work, if there are errors regarding compiling Fortran stubs you 197need to also do: 198 199```console 200$ make allfortranstubs 201``` 202