Merge branch 'main' into package-compiler-in-cmake

.github/workflows/SpellCheck.yml

@@ -10,4 +10,4 @@ jobs:
       - name: Checkout Actions Repository
         uses: actions/checkout@v4
       - name: Check spelling
-        uses: crate-ci/[email protected].13
+        uses: crate-ci/[email protected].17

.github/workflows/ci.yml

@@ -186,6 +186,17 @@ jobs:
           cd build
           make -j2
 
+      - name: Test external CMake project
+        if: ${{ matrix.test_type == 'regular' }}
+        run: |
+          cd examples/external
+          ./build.sh
+          mpirun -n 2 ./build/simple_trixi_controller_c \
+              ../../libtrixi-julia \
+              ../../LibTrixi.jl/examples/libelixir_p4est2d_dgsem_euler_sedov.jl
+        env:
+          LIBTRIXI_DEBUG: all
+
       - name: Prepare coverage reporting
         if: ${{ matrix.test_type == 'coverage' }}
         run: |

LibTrixi.jl/Project.toml

@@ -1,7 +1,7 @@
 name = "LibTrixi"
 uuid = "7e097bd5-a775-4bc1-90b6-ad92bd7220c1"
 authors = ["Michael Schlottke-Lakemper <[email protected]>", "Benedict Geihe <[email protected]>"]
-version = "0.1.4-pre"
+version = "0.1.5-pre"
 
 [deps]
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"

README.md

@@ -230,6 +230,9 @@ statements from the C or Julia part of the library, respectively. All values are
 case-sensitive and must be provided all lowercase.
 
 ### Linking against libtrixi
+
+#### Make
+
 To use libtrixi in your program, you need to specify `-I$LIBTRIXI_PREFIX/include` for the
 include directory with header and module files, `-L$LIBTRIXI_PREFIX/lib` for the library
 directory, and `-ltrixi` for the library itself during your build process. Optionally, you
@@ -246,7 +249,19 @@ make -f MakefileExternal LIBTRIXI_PREFIX=path/to/libtrixi/prefix
 ```
 to build `simple_trixi_controller_f`.
 
-Note: On Linux and FreeBSD systems (i.e., *not* on macOS or Windows), Julia may internally
+#### CMake
+
+A CMake module for the discovery of an installed libtrixi library is provided with
+[`cmake/FindLibTrixi.cmake`](cmake/FindLibTrixi.cmake). Before calling
+`find_package(LibTrixi)`, the CMake variable `LIBTRIXI_PREFIX` must be set to
+`<install_directory>`. An example `CMakeLists.txt` can be found in
+[`examples/external/CMakeLists.txt`](examples/external/CMakeLists.txt).
+To see the commands required to build an example program with this CMake project,
+please refer to [`examples/external/build.sh`](examples/external/build.sh).
+
+#### Note on thread-local storage (TLS)
+
+On Linux and FreeBSD systems (i.e., *not* on macOS or Windows), Julia may internally
 use a faster implementation for thread-local storage (TLS), which is used whenever Julia
 functions such task management, garbage collection etc. are used in a multithreaded
 context, or when they are themselves multithreaded. To activate the fast TLS in your

cmake/FindLibTrixi.cmake

@@ -0,0 +1,28 @@
+#
+# Stop if already found
+#
+if ( LIBTRIXI_FOUND )
+    return()
+endif()
+
+#
+# Look for include, libs, version file
+#
+find_path ( LIBTRIXI_INCLUDE_DIR trixi.h PATHS ${LIBTRIXI_PREFIX}/include )
+find_library ( LIBTRIXI_LIBRARY trixi PATHS ${LIBTRIXI_PREFIX}/lib )
+find_file ( LIBTRIXI_VERSION_FILE LIBTRIXI_VERSION PATHS ${LIBTRIXI_PREFIX}/share/julia )
+
+#
+# Extract version
+#
+file ( STRINGS ${LIBTRIXI_VERSION_FILE} LIBTRIXI_VERSION_STRING )
+
+#
+# Finalize
+#
+include ( FindPackageHandleStandardArgs )
+find_package_handle_standard_args(
+    LibTrixi
+    REQUIRED_VARS   LIBTRIXI_LIBRARY LIBTRIXI_INCLUDE_DIR
+    VERSION_VAR     LIBTRIXI_VERSION_STRING
+)

docs/doxygen/Doxyfile

@@ -943,7 +943,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../../src/trixi.h ../../src/trixi.c ../../src/trixi_version.c ../../src/trixi.f90 libtrixi.dox
+INPUT                  = ../../src/trixi.h ../../src/api.c ../../src/api.f90 libtrixi.dox
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

docs/src/index.md

@@ -228,8 +228,10 @@ set to `all`. Alternative values for the variable are `c` or `julia` to only sho
 statements from the C or Julia part of the library, respectively. All values are
 case-sensitive and must be provided all lowercase.
 
-
 ### Linking against libtrixi
+
+#### Make
+
 To use libtrixi in your program, you need to specify `-I$LIBTRIXI_PREFIX/include` for the
 include directory with header and module files, `-L$LIBTRIXI_PREFIX/lib` for the library
 directory, and `-ltrixi` for the library itself during your build process. Optionally, you
@@ -246,6 +248,19 @@ make -f MakefileExternal LIBTRIXI_PREFIX=path/to/libtrixi/prefix
 ```
 to build `simple_trixi_controller_f`.
 
+#### CMake
+
+A CMake module for the discovery of an installed libtrixi library is provided with
+[`cmake/FindLibTrixi.cmake`](https://github.com/trixi-framework/libtrixi/tree/main/cmake/FindLibTrixi.cmake).
+Before calling `find_package(LibTrixi)`, the CMake variable `LIBTRIXI_PREFIX` has to be set to
+`<install_directory>`. An example `CMakeLists.txt` can be found in
+[`examples/external/CMakeLists.txt`](https://github.com/trixi-framework/libtrixi/tree/main/examples/external/CMakeLists.txt).
+To see the commands required to build an example program with this CMake project,
+please refer to
+[`examples/external/build.sh`](https://github.com/trixi-framework/libtrixi/tree/main/examples/external/build.sh).
+
+#### Note on thread-local storage (TLS)
+
 Note: On Linux and FreeBSD systems (i.e., *not* on macOS or Windows), Julia may internally
 use a faster implementation for thread-local storage (TLS), which is used whenever Julia
 functions such task management, garbage collection etc. are used in a multithreaded

examples/external/CMakeLists.txt

@@ -0,0 +1,33 @@
+# Specify the minimum version
+cmake_minimum_required ( VERSION 3.9 )
+
+# Specify a project name
+project(ExternalLibTrixi)
+
+# Additional cmake modules (should contain FindLibTrixi.cmake)
+list ( APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/../../cmake" )
+
+# Find MPI
+find_package( MPI REQUIRED )
+
+# Find LibTrixi
+find_package( LibTrixi REQUIRED )
+
+# Set sources
+set ( TARGET_NAME simple_trixi_controller_c )
+add_executable ( ${TARGET_NAME} ${CMAKE_SOURCE_DIR}/../simple_trixi_controller.c )
+
+# Set libraries to link
+target_link_libraries(
+        ${TARGET_NAME}
+        PRIVATE MPI::MPI_C ${LIBTRIXI_LIBRARY}
+)
+
+# Set include directories
+target_include_directories(
+    ${TARGET_NAME}
+    PRIVATE ${LIBTRIXI_INCLUDE_DIR}
+)
+
+# Set compiler flag for position independent code
+target_compile_options( ${TARGET_NAME} PRIVATE "-fPIC" )

examples/external/build.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+mkdir build
+cd    build
+cmake -DLIBTRIXI_PREFIX=$PWD/../../../install ..
+make