Add post-installation sanity test

.github/workflows/test_t8code.yml

@@ -103,6 +103,8 @@ jobs:
       run: cd build && ninja $MAKEFLAGS
     - name: ninja install
       run: cd build && ninja install $MAKEFLAGS
+    - name: post-installation sanity tests
+      run: cd build && ninja post_install_tests
     - name: serial tests (if MPI is enabled)
       run: cd build && ctest $MAKEFLAGS -R _serial
       if: ${{ inputs.MPI == 'ON' }}

CMakeLists.txt

@@ -64,6 +64,42 @@ cmake_dependent_option( T8CODE_BUILD_DOCUMENTATION_SPHINX "Build t8code's docume
 set(T8CODE_CUSTOM_PARALLEL_TEST_COMMAND "" CACHE STRING "Define a custom command for parallel tests , e.g.: mpirun -np 8 (overwrites standard mpirun -np 4 if build with mpi)")
 set(T8CODE_CUSTOM_SERIAL_TEST_COMMAND "" CACHE STRING "Define a custom command for serial tests.")
 
+set(T8CODE_POST_INSTALL_TEST_SOURCE_DIR ${CMAKE_INSTALL_FULL_DOCDIR}/cmake_examples/post_install_sanity)
+set(T8CODE_POST_INSTALL_TEST_BINARY_DIR ${PROJECT_BINARY_DIR}/post_install_tests)
+set(T8CODE_POST_INSTALL_TEST_CMAKE_ARGS
+  -DCMAKE_PREFIX_PATH=${CMAKE_INSTALL_PREFIX}
+)
+
+if(CMAKE_BUILD_TYPE)
+  list(APPEND T8CODE_POST_INSTALL_TEST_CMAKE_ARGS -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE})
+endif()
+
+if(DEFINED SC_DIR AND NOT "${SC_DIR}" STREQUAL "")
+  list(APPEND T8CODE_POST_INSTALL_TEST_CMAKE_ARGS -DSC_DIR=${SC_DIR})
+endif()
+
+if(DEFINED P4EST_DIR AND NOT "${P4EST_DIR}" STREQUAL "")
+  list(APPEND T8CODE_POST_INSTALL_TEST_CMAKE_ARGS -DP4EST_DIR=${P4EST_DIR})
+endif()
+
+install( DIRECTORY ${PROJECT_SOURCE_DIR}/doc/cmake_examples/post_install_sanity
+  DESTINATION ${CMAKE_INSTALL_DOCDIR}/cmake_examples
+)
+
+add_custom_target( post_install_tests
+  COMMAND ${CMAKE_COMMAND} -E rm -rf ${T8CODE_POST_INSTALL_TEST_BINARY_DIR}
+  COMMAND ${CMAKE_COMMAND} -E make_directory ${T8CODE_POST_INSTALL_TEST_BINARY_DIR}
+  COMMAND ${CMAKE_COMMAND}
+          -G ${CMAKE_GENERATOR}
+          -S ${T8CODE_POST_INSTALL_TEST_SOURCE_DIR}
+          -B ${T8CODE_POST_INSTALL_TEST_BINARY_DIR}
+          ${T8CODE_POST_INSTALL_TEST_CMAKE_ARGS}
+  COMMAND ${CMAKE_COMMAND} --build ${T8CODE_POST_INSTALL_TEST_BINARY_DIR}
+  COMMAND ${CMAKE_CTEST_COMMAND} --test-dir ${T8CODE_POST_INSTALL_TEST_BINARY_DIR} --output-on-failure
+  COMMENT "Build and run the installed t8code post-installation sanity example"
+  VERBATIM
+)
+
 # Reading the option T8CODE_TEST_LEVEL: Possible choices are T8_TEST_LEVEL_FULL, T8_TEST_LEVEL_MEDIUM, or T8_TEST_LEVEL_BASIC. Default is T8_TEST_LEVEL_FULL.
 set(T8CODE_TEST_LEVEL "T8_TEST_LEVEL_FULL" CACHE STRING "Test level: T8_TEST_LEVEL_FULL for full tests, T8_TEST_LEVEL_MEDIUM for less thorough tests, T8_TEST_LEVEL_BASIC for minimal tests. (WARNING: Use with care.)")
 set_property(CACHE T8CODE_TEST_LEVEL PROPERTY STRINGS "T8_TEST_LEVEL_FULL" "T8_TEST_LEVEL_MEDIUM" "T8_TEST_LEVEL_BASIC")

doc/cmake_examples/post_install_sanity/CMakeLists.txt

@@ -0,0 +1,31 @@
+#  This file is part of t8code.
+#  t8code is a C library to manage a collection (a forest) of multiple
+#  connected adaptive space-trees of general element types in parallel.
+#
+#  Copyright (C) 2026 the developers
+#
+#  t8code is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation; either version 2 of the License, or
+#  (at your option) any later version.
+#
+#  t8code is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with t8code; if not, write to the Free Software Foundation, Inc.,
+#  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+cmake_minimum_required( VERSION 3.19 )
+
+project( T8CODE_POST_INSTALL_SANITY LANGUAGES C CXX )
+
+find_package( T8CODE CONFIG REQUIRED )
+
+add_executable( t8code_post_install_sanity t8code_post_install_sanity.cxx )
+target_link_libraries( t8code_post_install_sanity PRIVATE T8CODE::T8 )
+
+enable_testing()
+add_test( NAME t8code_post_install_sanity COMMAND t8code_post_install_sanity )

doc/cmake_examples/post_install_sanity/README.md

@@ -0,0 +1,12 @@
+# t8code post-installation sanity test
+
+This directory contains a minimal external CMake project that checks whether an installed t8code package can be found,
+linked, and run.
+
+Configure it with the t8code installation prefix in `CMAKE_PREFIX_PATH`:
+
+```sh
+cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/t8code/install
+cmake --build build
+ctest --test-dir build --output-on-failure
+```

doc/cmake_examples/post_install_sanity/t8code_post_install_sanity.cxx

@@ -0,0 +1,42 @@
+/*
+  This file is part of t8code.
+  t8code is a C library to manage a collection (a forest) of multiple
+  connected adaptive space-trees of general element types in parallel.
+
+  Copyright (C) 2026 the developers
+
+  t8code is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  t8code is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with t8code; if not, write to the Free Software Foundation, Inc.,
+  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
+#include <t8.h>
+
+int
+main (int argc, char **argv)
+{
+  int mpiret = sc_MPI_Init (&argc, &argv);
+  SC_CHECK_MPI (mpiret);
+
+  sc_init (sc_MPI_COMM_WORLD, 1, 1, NULL, SC_LP_ESSENTIAL);
+  t8_init (SC_LP_PRODUCTION);
+
+  t8_global_productionf ("t8code post-installation sanity test succeeded.\n");
+
+  sc_finalize ();
+
+  mpiret = sc_MPI_Finalize ();
+  SC_CHECK_MPI (mpiret);
+
+  return 0;
+}

src/config.cmake.in

@@ -2,6 +2,12 @@
 
 include( CMakeFindDependencyMacro )
 
+set( T8CODE_ENABLE_MPI @T8CODE_ENABLE_MPI@ )
+
+if( T8CODE_ENABLE_MPI )
+    find_dependency( MPI 3.0 COMPONENTS C )
+endif()
+
 find_dependency( P4EST CONFIG )
 find_dependency( SC CONFIG )
 
@@ -11,7 +17,6 @@ set( T8CODE_BUILD_TUTORIALS @T8CODE_BUILD_TUTORIALS@ )
 set( T8CODE_BUILD_EXAMPLES @T8CODE_BUILD_EXAMPLES@ )
 set( T8CODE_BUILD_MESH_HANDLE @T8CODE_BUILD_MESH_HANDLE@ )
 
-set( T8CODE_ENABLE_MPI @T8CODE_ENABLE_MPI@ )
 set( T8CODE_ENABLE_VTK @T8CODE_ENABLE_VTK@ )
 
 set( T8CODE_USE_SYSTEM_SC @T8CODE_USE_SYSTEM_SC@ )