Upstream paraview source and ThirdParty submodules
==================================================

Paraview source is tightly bound to various releases of third-party
libraries, including VTK. Paraview source therefore provides its own
ThirdParty and VTK subdirectories contain a copy of the required source.

In the upstream paraview git repository at
https://gitlab.kitware.com/paraview/paraview
the third-party sources are managed as git submodules pointing to a
specific commit in the upstream source.

Paraview no longer provides release tarballs. The last version at
https://gitlab.kitware.com/paraview/paraview/-/releases is v5.8.0

The paraview git repo does provide tarballs from all tags at
https://gitlab.kitware.com/paraview/paraview/-/tags
However these tarballs are automatically generated by git archive.
git archive does not include submodules in the generated tarball, so
the required third-party source is missing.

To work around these issues, debian maintainers now have to generated
the upstream source tarball manually after pulling the submodules.
The used method is suggested at
https://stackoverflow.com/a/67389978/12401525

The steps are
1) Clone the upstream repository
2) Checkout the desired tag (to obtain a specific release version)
3) Pull the submodules.
   3b)  manually remove excluded submodules and commit locally
4) Generate a tarball including submodule source.

For instance, to obtain v5.11.2 source including submodules as
paraview-v5.11.2+dfsg.tar.gz:

UPSTREAM_TAG=v5.11.2
git clone https://gitlab.kitware.com/paraview/paraview.git
cd paraview
git checkout ${UPSTREAM_TAG}
git submodule update --init --recursive
# manually remove excluded submodules: e.g. rm -r VTK; git commit -a -m "remove VTK to enable external build"
git ls-files --recurse-submodules | tar caf ../paraview-${UPSTREAM_TAG}+dfsg.tar.gz -T-

In some cases, including VTK, the paraview build can access the
third-party library as an external library,
e.g. with -DPARAVIEW_USE_EXTERNAL_VTK=ON
The third-party source for these libraries can therefore be excluded
from the debian source tarball using Files-Excluded in debian/copyright.

Some third-party sources are not available as external libraries,
however, e.g. IceT, so the process outlined above must still be
followed.

This manual procedure does not cooperate with uscan (debian/watch)
such that repacking with excluded files (VTK) cannot be done
automatically.  Delete excluded files manually then run
gbp import-orig against the cleaned upstream source directory.
