From 786a75ab8a67312048d1add0fb6727a11a6a5e34 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Tue, 5 Aug 2025 23:42:07 +0200 Subject: [PATCH] FortranCInterface: Update documentation - Added intro code block showing how to include this module. - Used "commands" instead of "functions". - Reworded descriptions. - Added dedicated examples section. --- Modules/FortranCInterface.cmake | 165 +++++++++++++++++++------------- 1 file changed, 98 insertions(+), 67 deletions(-) diff --git a/Modules/FortranCInterface.cmake b/Modules/FortranCInterface.cmake index 70ad3c7fea..d559ab71f8 100644 --- a/Modules/FortranCInterface.cmake +++ b/Modules/FortranCInterface.cmake @@ -5,25 +5,39 @@ FortranCInterface ----------------- -Fortran/C Interface Detection +This module provides variables and commands to detect Fortran/C Interface. -This module automatically detects the API by which C and Fortran -languages interact. +Load this module in a CMake project with: -Module Variables -^^^^^^^^^^^^^^^^ +.. code-block:: cmake -Variables that indicate if the mangling is found: + include(FortranCInterface) + +This module automatically detects the API by which C and Fortran languages +interact. + +Variables +^^^^^^^^^ + +Result Variables +"""""""""""""""" + +Including this module defines the following variables that indicate if the +mangling is found: ``FortranCInterface_GLOBAL_FOUND`` - Global subroutines and functions. + Boolean indicating whether global subroutines and functions are available. ``FortranCInterface_MODULE_FOUND`` - Module subroutines and functions (declared by "MODULE PROCEDURE"). + Boolean indicating whether module subroutines and functions (declared by + ``MODULE PROCEDURE``) are available. + +Input Variables +""""""""""""""" This module also provides the following variables to specify the detected mangling, though a typical use case does not need -to reference them and can use the `Module Functions`_ below. +to reference them and can use the `Commands`_ below. ``FortranCInterface_GLOBAL_PREFIX`` Prefix for a global symbol without an underscore. @@ -99,29 +113,48 @@ to reference them and can use the `Module Functions`_ below. The module name appears *after* the symbol name, i.e., ````. -Module Functions -^^^^^^^^^^^^^^^^ +Variables For Additional Manglings +"""""""""""""""""""""""""""""""""" + +This module is aware of possible ``GLOBAL`` and ``MODULE`` manglings for +many Fortran compilers, but it also provides an interface to specify +new possible manglings. The following variables can be set before including +this module to specify additional manglings: + +``FortranCInterface_GLOBAL_SYMBOLS`` + +``FortranCInterface_MODULE_SYMBOLS`` + +before including this module to specify manglings of the symbols +``MySub``, ``My_Sub``, ``MyModule:MySub``, and ``My_Module:My_Sub``. + +Commands +^^^^^^^^ + +This module provides the following commands: .. command:: FortranCInterface_HEADER - The ``FortranCInterface_HEADER`` function is provided to generate a - C header file containing macros to mangle symbol names: + Generates a C header file containing macros to mangle symbol names: .. code-block:: cmake - FortranCInterface_HEADER( - [MACRO_NAMESPACE ] - [SYMBOL_NAMESPACE ] - [SYMBOLS [:] ...]) + FortranCInterface_HEADER( + + [MACRO_NAMESPACE ] + [SYMBOL_NAMESPACE ] + [SYMBOLS [:] ...] + ) - It generates in ```` definitions of the following macros: + This command generates a ```` with definitions of the following + macros: .. code-block:: c - #define FortranCInterface_GLOBAL (name,NAME) ... - #define FortranCInterface_GLOBAL_(name,NAME) ... - #define FortranCInterface_MODULE (mod,name, MOD,NAME) ... - #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ... + #define FortranCInterface_GLOBAL (name,NAME) ... + #define FortranCInterface_GLOBAL_(name,NAME) ... + #define FortranCInterface_MODULE (mod,name, MOD,NAME) ... + #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ... These macros mangle four categories of Fortran symbols, respectively: @@ -139,6 +172,10 @@ Module Functions Replace the default ``FortranCInterface_`` prefix with a given namespace ````. + ``SYMBOL_NAMESPACE`` + Prefix all preprocessor definitions generated by the ``SYMBOLS`` + option with a given namespace ````. + ``SYMBOLS`` List symbols to mangle automatically with C preprocessor definitions:: @@ -148,77 +185,71 @@ Module Functions If the mangling for some symbol is not known then no preprocessor definition is created, and a warning is displayed. - ``SYMBOL_NAMESPACE`` - Prefix all preprocessor definitions generated by the ``SYMBOLS`` - option with a given namespace ````. - .. command:: FortranCInterface_VERIFY - The ``FortranCInterface_VERIFY`` function is provided to verify - that the Fortran and C/C++ compilers work together: + Verifies that the Fortran and C/C++ compilers work together: .. code-block:: cmake FortranCInterface_VERIFY([CXX] [QUIET]) - It tests whether a simple test executable using Fortran and C (and C++ - when the CXX option is given) compiles and links successfully. The - result is stored in the cache entry ``FortranCInterface_VERIFIED_C`` + This command tests whether a simple test executable using Fortran and C + (and C++ when the ``CXX`` option is given) compiles and links successfully. + The result is stored in the cache entry ``FortranCInterface_VERIFIED_C`` (or ``FortranCInterface_VERIFIED_CXX`` if ``CXX`` is given) as a boolean. - If the check fails and ``QUIET`` is not given the function terminates with a + If the check fails and ``QUIET`` is not given the command terminates with a fatal error message describing the problem. The purpose of this check is to stop a build early for incompatible compiler combinations. The test is built in the ``Release`` configuration. -Example Usage -^^^^^^^^^^^^^ +Examples +^^^^^^^^ + +Examples: Basic Usage +""""""""""""""""""""" + +The following example creates a ``FC.h`` header that defines mangling macros +``FC_GLOBAL()``, ``FC_GLOBAL_()``, ``FC_MODULE()``, and ``FC_MODULE_()``: .. code-block:: cmake - include(FortranCInterface) - FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_") + include(FortranCInterface) + FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_") -This creates a "FC.h" header that defines mangling macros ``FC_GLOBAL()``, -``FC_GLOBAL_()``, ``FC_MODULE()``, and ``FC_MODULE_()``. +The next example creates a ``FCMangle.h`` header that defines the same +``FC_*()`` mangling macros as the previous example plus preprocessor symbols +``FC_mysub`` and ``FC_mymod_my_sub``: .. code-block:: cmake - include(FortranCInterface) - FortranCInterface_HEADER(FCMangle.h - MACRO_NAMESPACE "FC_" - SYMBOL_NAMESPACE "FC_" - SYMBOLS mysub mymod:my_sub) + include(FortranCInterface) + FortranCInterface_HEADER( + FCMangle.h + MACRO_NAMESPACE "FC_" + SYMBOL_NAMESPACE "FC_" + SYMBOLS mysub mymod:my_sub + ) -This creates a "FCMangle.h" header that defines the same ``FC_*()`` -mangling macros as the previous example plus preprocessor symbols -``FC_mysub`` and ``FC_mymod_my_sub``. +Example: Additional Manglings +""""""""""""""""""""""""""""" -Additional Manglings -^^^^^^^^^^^^^^^^^^^^ - -FortranCInterface is aware of possible ``GLOBAL`` and ``MODULE`` manglings -for many Fortran compilers, but it also provides an interface to specify -new possible manglings. Set the variables:: - - FortranCInterface_GLOBAL_SYMBOLS - FortranCInterface_MODULE_SYMBOLS - -before including FortranCInterface to specify manglings of the symbols +The following example shows how to specify manglings of the symbols ``MySub``, ``My_Sub``, ``MyModule:MySub``, and ``My_Module:My_Sub``. -For example, the code: +The following code tells this module to try given ``GLOBAL`` and ``MODULE`` +manglings. (The carets point at raw symbol names for clarity in this +example but are not needed.) .. code-block:: cmake - set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_) - # ^^^^^ ^^^^^^ ^^^^^ - set(FortranCInterface_MODULE_SYMBOLS - __mymodule_MOD_mysub __my_module_MOD_my_sub) - # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^ - include(FortranCInterface) + set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_) + # ^^^^^ ^^^^^^ ^^^^^ + set(FortranCInterface_MODULE_SYMBOLS + __mymodule_MOD_mysub __my_module_MOD_my_sub) + # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^ -tells FortranCInterface to try given ``GLOBAL`` and ``MODULE`` manglings. -(The carets point at raw symbol names for clarity in this example but -are not needed.) + include(FortranCInterface) + + # ... #]=======================================================================] #-----------------------------------------------------------------------------