PETSc Debian Package Description
                      --------------------------------

INTRODUCTION

This source package is distributed in five binary packages: the shared
libraries are in libpetsc-real3.23; header files, static libraries and important
files for building examples are in libpetsc-real3.23-dev, this also sets up
various alternatives links; debugging libraries are in libpetsc-real3.23-dbg;
extensive documentation and source code from "tests" and "tutorials"
directories are in petsc3.23-doc.

Standard packages are configured for real numbers.  Complex numbers are
configured in the libpetsc-complex* packages. The preferred default
configuration may be set using alternatives (petsc and libpetsc.so.3.23).

The preferred PETSc installation is located at /usr/lib/petsc. This is a symlink
to the actual installation, managed by Debian alternatives (see below). The
standard installation is located at
  /usr/lib/petscdir/petsc<PETSC_VERSION>/<arch>-real
e.g.
  /usr/lib/petscdir/petsc3.23/x86_64-linux-gnu-real

Preferred minor patch versions of each major version (e.g. 3.23)
are linked via
  /usr/lib/petscdir/3.23
(also, preferred versions of 3.23-real and 3.23-complex). These links are
controlled by alternatives.

libpetsc.so is also controlled by alternatives (libpetsc.so.3.23)


With libpetsc3.23-dev installed, you can build programs against it two ways:

     1. Standard build convention: use -I/usr/include/petsc for headers and
	link to optimized libraries in /usr/lib, so your resulting binaries
	will only depend on libpetsc3.23.0.
     2. PETSc build convention: adapt a makefile from one of their tests or
	tutorial directories and build with make PETSC_DIR=/usr/lib/petsc
     3. Use pkg-config (via /usr/lib/<arch>/pkgconfig/PETSC.pc).

Of these, the latter two are probably easier, as they automatically set up
all of the include paths and library linkages for PETSc and its various
dependencies.

EXAMPLES

For your testing convenience, petsc3.23-doc comes with the source code of
the full PETSc test and tutorial suite.  Just do:

	tar xzf /usr/share/doc/petsc3.23-doc/src.tar.gz

then cd src, and use the PETSc build convention make command above with target
testexamples or testfortran (add _uni to the target name for single-processor
operation).  This will build and run the entire suite.  Then choose an
appropriate example to modify for your own purposes, and you're off.

NOTE: not all of the examples work!  If one fails for you, please try to patch
it to make it work; you can often use a similar example in the same directory
to do this.  You may be able to get some help from the upstream maintainers for
this, see the homepage for details, but the examples do not seem to be
consistently maintained.  If you file a bug report because of a failed example,
I will forward it upstream and leave it open until it's fixed, but can't
promise I'll try to fix it.

DEBUGGING LIBRARY

With libpetsc-real3.23-dbg installed, a debug version is available at
  /usr/lib/petscdir/petsc3.23/x86_64-linux-gnu-real-debug

This library includes unstripped symbols and also has internal PETSc debugging
switched on. It may be accessed
1) by setting PETSC_DIR
2) via the pkg-config file in
  /usr/lib/petscdir/petsc3.23/x86_64-linux-gnu-real-debug/lib/pkgconfig
3) or by configuring as preferred alternative with update-alternatives.

REPORTING BUGS and BUILDING FROM SOURCE

Also, upstream does not maintain old versions of PETSc.  If you have trouble
with the version in stable, you should file a bug report (see
http://bugs.debian.org/ for directions), then try building the version in
unstable, by adding an unstable source code line to /etc/apt/sources.list, then
typing (as a normal user):

	fakeroot apt-get --compile source petsc

This will download and build everything for you.

If the unstable version does not solve your problem, or the customizations
below don't meet your needs, file a bug report, and if your problem is not
specific to the Debian package then I'll forward it upstream.

CUSTOMIZING THE DEBIAN PETSC PACKAGE

There are several ways to customize this package:

1) To use a different PETSC_ARCH variable (e.g. linux_alpha_dec to use the
   Compaq compilers on an Alpha), do:

	apt-get source petsc
	cd petsc-3.23.0.dsfg1
	fakeroot debian/rules PETSC_ARCH=linux_alpha_dec binary

   Note that this will only build architecture-dependent packages, and with
   different package names, different directory names (still linked from
   /usr/lib/petsc), and different shared library sonames.

2) You can also build the libraries to use the lam or mpich MPI implementation
   instead of the default openmpi by setting PETSC_MPI=lam (or mpich) and
   PETSC_MPI_DIR=/usr/lib/lam (or mpich, or mpich-mpd or mpich-shmem) and build
   as with the Compaq compilers above.  This will also result in only
   architecture-dependent packages with different package names, directory
   names, and shared library sonames.

If needed, you can change the soname of your custom library by using the configure
flag --shared-library-extension=<ext>, which changes the library and soname to
libpetsc<ext>.so

Note that individual users can build against non-default installed versions of
PETSc simply by setting the PETSC_DIR environment variable to the target
directory instead of /usr/lib/petsc, for example to build against the lam
version a user might set PETSC_DIR=/usr/lib/petscdir/petsc3.23/x86_64-linux-gnu-lam-real .

NOTE ON SYMBOLIC LINKS THROUGH /etc/alternatives

Because it is possible and often desirable to have multiple versions of PETSc
installed at the same time, this package facilitates the process by setting up
multiple symbolic links through /etc/alternatives.  To switch the default
symbolic links from one installed version to another, you should use the
update-alternatives Debian script (in /usr/sbin).  For example:

	update-alternatives --display petsc

will show you the current symlink from /usr/lib/petsc, and all of its
accompanying "slave" links, as well as all of the other possible values of
links if you have multiple versions of PETSc installed.  The command:

	update-alternatives --config petsc

(as root) will present you with a list of possible values to choose from, if
there is more than one.

When setting your preference for /usr/lib/petsc via "update-alternatives --config petsc",
it is important for consistency to also update your preference for the
main shared library files provided by libpetsc-real3.23 or libpetsc-complex3.23.
These alternative links are controlled by libpetsc.so.3.23:

	update-alternatives --config libpetsc.so.3.23

The preferred alternative for the major petsc version (e.g. 3.23) is linked in
/usr/lib/petscdir/3.23 and set by

	update-alternatives --config petsc3.23

To maintain the consistency of the master and slave symlinks, it is very
important that you use the Debian update-alternatives command, and do NOT
hand-edit the symbolic links yourself.

The full set of PETSc alternatives is:

petsc	- set the default version (real or complex) of PETSc (/usr/lib/petsc)

libpetsc_real.so
	- set the default PETSc shared library with real number support

libpetsc_complex.so
	- set the default PETSc shared library with complex number support

petsc3.23
	- set the preferred version (real or complex, or debug) of PETSc 3.23
	  (/usr/lib/petscdir/3.23)

libpetsc.so.3.23
	- set the preferred version (real or complex) for the shared library
	  of PETSc 3.23


===== 64-bit indexing =====

Support for 64-bit indexing is provided in libpetsc64* packages.
These enables PETSc to be used on larger systems with more than 2 billion elements.

Suitesparse does not support 64-bit indexing on 32-bit platforms
(armel armhf i386 powerpc x32) and Suitesparse support has therefore been
dropped from the 64-bit builds on these architectures.


 -- Drew Parsons <dparsons@debian.org>, Sat, 20 June 2020 10:00:00 +0800