FortranCInterface

Fortran/C Interface Detection

This module automatically detects the API by which C and Fortran languages interact.

Module Variables

Variables that indicate if the mangling is found:

FortranCInterface_GLOBAL_FOUND
Global subroutines and functions.
FortranCInterface_MODULE_FOUND
Module subroutines and functions (declared by “MODULE PROCEDURE”).

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.

FortranCInterface_GLOBAL_PREFIX
Prefix for a global symbol without an underscore.
FortranCInterface_GLOBAL_SUFFIX
Suffix for a global symbol without an underscore.
FortranCInterface_GLOBAL_CASE
The case for a global symbol without an underscore, either UPPER or LOWER.
FortranCInterface_GLOBAL__PREFIX
Prefix for a global symbol with an underscore.
FortranCInterface_GLOBAL__SUFFIX
Suffix for a global symbol with an underscore.
FortranCInterface_GLOBAL__CASE
The case for a global symbol with an underscore, either UPPER or LOWER.
FortranCInterface_MODULE_PREFIX
Prefix for a module symbol without an underscore.
FortranCInterface_MODULE_MIDDLE
Middle of a module symbol without an underscore that appears between the name of the module and the name of the symbol.
FortranCInterface_MODULE_SUFFIX
Suffix for a module symbol without an underscore.
FortranCInterface_MODULE_CASE
The case for a module symbol without an underscore, either UPPER or LOWER.
FortranCInterface_MODULE__PREFIX
Prefix for a module symbol with an underscore.
FortranCInterface_MODULE__MIDDLE
Middle of a module symbol with an underscore that appears between the name of the module and the name of the symbol.
FortranCInterface_MODULE__SUFFIX
Suffix for a module symbol with an underscore.
FortranCInterface_MODULE__CASE
The case for a module symbol with an underscore, either UPPER or LOWER.

Module Functions

FortranCInterface_HEADER

The FortranCInterface_HEADER function is provided to generate a C header file containing macros to mangle symbol names:

FortranCInterface_HEADER(<file>
                         [MACRO_NAMESPACE <macro-ns>]
                         [SYMBOL_NAMESPACE <ns>]
                         [SYMBOLS [<module>:]<function> ...])

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) ...

These macros mangle four categories of Fortran symbols, respectively:

  • 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()

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:

MACRO_NAMESPACE
Replace the default FortranCInterface_ prefix with a given namespace <macro-ns>.
SYMBOLS

List symbols to mangle automatically with C preprocessor definitions:

<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>.
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

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_().

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.

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:

set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
  #                                  ^^^^^  ^^^^^^   ^^^^^
set(FortranCInterface_MODULE_SYMBOLS
    __mymodule_MOD_mysub __my_module_MOD_my_sub)
  #   ^^^^^^^^     ^^^^^   ^^^^^^^^^     ^^^^^^
include(FortranCInterface)

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.)