# FortranCInterface

This module provides variables and commands to detect Fortran/C Interface.

Load this module in a CMake project with:

    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`

  Boolean indicating whether global subroutines and functions are available.

`FortranCInterface_MODULE_FOUND`

  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 Commands 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_ORDER`

  Added in version 4.1.

  Order of components for module symbols without an underscore:

  `MODULE_THEN_SYMBOL`

    The module name appears before the symbol name, i.e., `<PREFIX><module><MIDDLE><symbol><SUFFIX>`.

  `SYMBOL_THEN_MODULE`

    The module name appears after the symbol name, i.e., `<PREFIX><symbol><MIDDLE><module><SUFFIX>`.

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

`FortranCInterface_MODULE__ORDER`

  Added in version 4.1.

  Order of components for module symbols with an underscore:

  `MODULE_THEN_SYMBOL`

    The module name appears before the symbol name, i.e., `<PREFIX><module><MIDDLE><symbol><SUFFIX>`.

  `SYMBOL_THEN_MODULE`

    The module name appears after the symbol name, i.e., `<PREFIX><symbol><MIDDLE><module><SUFFIX>`.

### 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:

FortranCInterface_HEADER

  Generates a C header file containing macros to mangle symbol names:

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

  This command generates a `<file>` with 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>`.

  `SYMBOL_NAMESPACE`

    Prefix all preprocessor definitions generated by the `SYMBOLS` option with a given namespace `<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.

FortranCInterface_VERIFY

  Verifies that the Fortran and C/C++ compilers work together:

      FortranCInterface_VERIFY([CXX] [QUIET])

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

## 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_()`:

    include(FortranCInterface)
    FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")

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`:

    include(FortranCInterface)
    FortranCInterface_HEADER(
      FCMangle.h
      MACRO_NAMESPACE "FC_"
      SYMBOL_NAMESPACE "FC_"
      SYMBOLS mysub mymod:my_sub
    )

### Example: Additional Manglings

The following example shows how to specify manglings of the symbols `MySub`, `My_Sub`, `MyModule:MySub`, and `My_Module:My_Sub`. 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.)

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

    include(FortranCInterface)

    # ...