Add post-installation sanity test

[tokito-99]

Describe your changes here:

This PR adds a minimal post-installation sanity test for t8code.

It installs a small external CMake consumer project under doc/cmake_examples/post_install_sanity and adds a post_install_tests target. The target configures, builds, and runs the installed example out-of-tree against the installed T8CODEConfig.cmake.

Closes #2361.

Changes

• Add an installed CMake example using find_package(T8CODE CONFIG REQUIRED).
• Add a tiny executable that initializes/finalizes t8code to verify the installed library can be linked and run.
• Add a top-level post_install_tests target.
• Run post_install_tests after ninja install in the main CMake CI workflow.
• Update generated T8CODEConfig.cmake to find MPI when t8code was built with MPI support.

Testing

Locally tested a reduced non-MPI install-tree workflow:

cmake -S . -B /tmp/t8code-2361-smoke \
  -DCMAKE_INSTALL_PREFIX=/tmp/t8code-2361-install \
  -DT8CODE_BUILD_TESTS=OFF \
  -DT8CODE_BUILD_EXAMPLES=OFF \
  -DT8CODE_BUILD_TUTORIALS=OFF \
  -DT8CODE_BUILD_BENCHMARKS=OFF \
  -DT8CODE_ENABLE_MPI=OFF

cmake --build /tmp/t8code-2361-smoke --parallel 4
cmake --install /tmp/t8code-2361-smoke
cmake --build /tmp/t8code-2361-smoke --target post_install_tests

Result:

1/1 Test #1: t8code_post_install_sanity ....... Passed
100% tests passed

Also ran:

git diff --check

All these boxes must be checked by the AUTHOR before requesting review:

• The PR is small enough to be reviewed easily. If not, consider splitting up the changes in multiple PRs.
• The title starts with one of the following prefixes: Documentation:, Bugfix:, Feature:, Improvement: or Other:.
• If the PR is related to an issue, make sure to link it.
• The author made sure that, as a reviewer, he/she would check all boxes below.

All these boxes must be checked by the REVIEWERS before merging the pull request:

As a reviewer please read through all the code lines and make sure that the code is fully understood, bug free, well-documented and well-structured.

General

• The reviewer executed the new code features at least once and checked the results manually.
• The code follows the t8code coding guidelines.
• New source/header files are properly added to the CMake files.
• The code is well documented. In particular, all function declarations, structs/classes and their members have a proper doxygen documentation. Make sure to add a file documentation for each file!
• README.md files are updated if necessary.
• All new algorithms and data structures are sufficiently optimal in terms of memory and runtime (If this should be merged, but there is still potential for optimization, create a new issue).

Tests

• The code is covered in an existing or new test case using Google Test.
• The code coverage of the project (reported in the CI) should not decrease. If coverage is decreased, make sure that this is reasonable and acceptable.
• Valgrind doesn't find any bugs in the new code. This script can be used to check for errors; see also this wiki article.

If the Pull request introduces code that is not covered by the github action (for example coupling with a new library):

• Should this use case be added to the github action?
• If not, does the specific use case compile and all tests pass (check manually).

Scripts and Wiki

• If a new directory with source files is added, it must be covered by the scripts/internal/find_all_source_files.sh to check the indentation of these files.
• If this PR introduces a new feature, it must be covered in an example or tutorial and a Wiki article.

License

• The author added a BSD statement to doc/ (or already has one).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.28%. Comparing base (66cd94f) to head (30a195b).
⚠️ Report is 33 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2389   +/-   ##
=======================================
  Coverage   82.28%   82.28%           
=======================================
  Files         125      125           
  Lines       20701    20701           
=======================================
  Hits        17033    17033           
  Misses       3668     3668           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tokito-99]

I also noticed the existing post-installation-sanity-checks-for-2361 branch while working on this. This PR takes the same general idea but implements it as a smaller change on top of current main, using portable CMake commands and adding the post-install check to CI after ninja install.

[spenke91]

Thank you so much for this contribution, @tokito-99!👍
I like it a lot and only have a fewsuggestions and remarks. The only one not found in the inline comments is that I am not entirely convinced of having the post-install tests hidden in the doc folder (I know #2361 explicitly suggested that). What do you think about putting it in a sub-directory test/post_install?
In principal, I still like the idea of seeing it as an example on how to include t8code from your own cmake repo, but I'd argue the main purpose of the file is the post-install testing, so to me it just feels wrong in doc. In principal, the information on how to link your project to t8code is also given in the Wiki (https://github.com/DLR-AMR/t8code/wiki/Installation). If we feel (later) that we additionally want a folder doc/cmake_examples, of course we could also link / refer to the post-install tests, but for now the post-install tests suffice I would say.

What do you think? :-)

[spenke91]

Could you explain why this change is necessary or how it is related to the psost-install tests?

[spenke91]

Suggested change

	/** \file t8code_post_install_sanity.cxx
	* This file implements a sanity check that includes t8code from another target and calls some t8code functions.
	*/

[spenke91]

Suggested change

	int
	/// Main function that tries some very basic t8code functionality for testing purposes.

[spenke91]

I suggest to move everything related to the post-install tests to an own cmake file to keep the main t8code file clean.

Then we could simply say something like include(cmake/PostInstallTests.cmake) here.