diff options
| -rw-r--r-- | Modules/FortranCInterface.cmake | 148 |
1 files changed, 78 insertions, 70 deletions
diff --git a/Modules/FortranCInterface.cmake b/Modules/FortranCInterface.cmake index 881e8b1..c872d6d 100644 --- a/Modules/FortranCInterface.cmake +++ b/Modules/FortranCInterface.cmake @@ -5,73 +5,96 @@ FortranCInterface Fortran/C Interface Detection This module automatically detects the API by which C and Fortran -languages interact. Variables indicate if the mangling is found: +languages interact. -:: +Module Variables +^^^^^^^^^^^^^^^^ - FortranCInterface_GLOBAL_FOUND = Global subroutines and functions - FortranCInterface_MODULE_FOUND = Module subroutines and functions - (declared by "MODULE PROCEDURE") +Variables that indicate if the mangling is found: -A function is provided to generate a C header file containing macros -to mangle symbol names: +``FortranCInterface_GLOBAL_FOUND`` + Global subroutines and functions. -:: +``FortranCInterface_MODULE_FOUND`` + Module subroutines and functions (declared by "MODULE PROCEDURE"). - FortranCInterface_HEADER(<file> - [MACRO_NAMESPACE <macro-ns>] - [SYMBOL_NAMESPACE <ns>] - [SYMBOLS [<module>:]<function> ...]) +Module Functions +^^^^^^^^^^^^^^^^ -It generates in <file> definitions of the following macros: +.. command:: FortranCInterface_HEADER -:: + The ``FortranCInterface_HEADER`` function is provided to generate a + C header file containing macros to mangle symbol names:: - #define FortranCInterface_GLOBAL (name,NAME) ... - #define FortranCInterface_GLOBAL_(name,NAME) ... - #define FortranCInterface_MODULE (mod,name, MOD,NAME) ... - #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ... + FortranCInterface_HEADER(<file> + [MACRO_NAMESPACE <macro-ns>] + [SYMBOL_NAMESPACE <ns>] + [SYMBOLS [<module>:]<function> ...]) -These macros mangle four categories of Fortran symbols, respectively: + It generates in ``<file>`` definitions of the following macros:: -:: + #define FortranCInterface_GLOBAL (name,NAME) ... + #define FortranCInterface_GLOBAL_(name,NAME) ... + #define FortranCInterface_MODULE (mod,name, MOD,NAME) ... + #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ... - - Global symbols without '_': call mysub() - - Global symbols with '_' : call my_sub() - - Module symbols without '_': use mymod; call mysub() - - Module symbols with '_' : use mymod; call my_sub() + These macros mangle four categories of Fortran symbols, respectively: -If mangling for a category is not known, its macro is left undefined. -All macros require raw names in both lower case and upper case. The -MACRO_NAMESPACE option replaces the default "FortranCInterface_" -prefix with a given namespace "<macro-ns>". + * Global symbols without '_': ``call mysub()`` + * Global symbols with '_' : ``call my_sub()`` + * Module symbols without '_': ``use mymod; call mysub()`` + * Module symbols with '_' : ``use mymod; call my_sub()`` -The SYMBOLS option lists symbols to mangle automatically with C -preprocessor definitions: + If mangling for a category is not known, its macro is left undefined. + All macros require raw names in both lower case and upper case. -:: + The options are: - <function> ==> #define <ns><function> ... - <module>:<function> ==> #define <ns><module>_<function> ... + ``MACRO_NAMESPACE`` + Replace the default ``FortranCInterface_`` prefix with a given + namespace ``<macro-ns>``. -If the mangling for some symbol is not known then no preprocessor -definition is created, and a warning is displayed. The -SYMBOL_NAMESPACE option prefixes all preprocessor definitions -generated by the SYMBOLS option with a given namespace "<ns>". + ``SYMBOLS`` + List symbols to mangle automatically with C preprocessor definitions:: -Example usage: + <function> ==> #define <ns><function> ... + <module>:<function> ==> #define <ns><module>_<function> ... -:: + 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 ``<ns>``. + +.. command:: FortranCInterface_VERIFY + + The ``FortranCInterface_VERIFY`` function is provided to verify + that the Fortran and C/C++ compilers work together:: + + 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`` + (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 + 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 +^^^^^^^^^^^^^ + +.. code-block:: cmake 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_(). - -Example usage: +This 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(FCMangle.h @@ -79,40 +102,25 @@ Example usage: SYMBOL_NAMESPACE "FC_" SYMBOLS mysub mymod:my_sub) -This creates a "FCMangle.h" header that defines the same FC_*() +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. - -Another function is provided to verify that the Fortran and C/C++ -compilers work together: - -:: - - 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 (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 -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. +``FC_mysub`` and ``FC_mymod_my_sub``. -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 +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 -"MySub", "My_Sub", "MyModule:MySub", and "My_Module:My_Sub". For -example, the code: +``MySub``, ``My_Sub``, ``MyModule:MySub``, and ``My_Module:My_Sub``. +For example, the code: -:: +.. code-block:: cmake set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_) # ^^^^^ ^^^^^^ ^^^^^ @@ -121,7 +129,7 @@ example, the code: # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^ include(FortranCInterface) -tells FortranCInterface to try given GLOBAL and MODULE manglings. +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.) #]=======================================================================] |