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