diff options
Diffstat (limited to 'Modules')
| -rw-r--r-- | Modules/FortranCInterface.cmake | 253 |
1 files changed, 127 insertions, 126 deletions
diff --git a/Modules/FortranCInterface.cmake b/Modules/FortranCInterface.cmake index 70c3fd7..881e8b1 100644 --- a/Modules/FortranCInterface.cmake +++ b/Modules/FortranCInterface.cmake @@ -1,129 +1,130 @@ -#.rst: -# 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: -# -# :: -# -# FortranCInterface_GLOBAL_FOUND = Global subroutines and functions -# FortranCInterface_MODULE_FOUND = Module subroutines and functions -# (declared by "MODULE PROCEDURE") -# -# A 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 -# MACRO_NAMESPACE option replaces the default "FortranCInterface_" -# prefix with a given namespace "<macro-ns>". -# -# The SYMBOLS option lists 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. The -# SYMBOL_NAMESPACE option prefixes all preprocessor definitions -# generated by the SYMBOLS option with a given namespace "<ns>". -# -# 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_(). -# -# Example usage: -# -# :: -# -# 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. -# -# 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. -# -# 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.) +#[=======================================================================[.rst: +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: + +:: + + FortranCInterface_GLOBAL_FOUND = Global subroutines and functions + FortranCInterface_MODULE_FOUND = Module subroutines and functions + (declared by "MODULE PROCEDURE") + +A 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 +MACRO_NAMESPACE option replaces the default "FortranCInterface_" +prefix with a given namespace "<macro-ns>". + +The SYMBOLS option lists 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. The +SYMBOL_NAMESPACE option prefixes all preprocessor definitions +generated by the SYMBOLS option with a given namespace "<ns>". + +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_(). + +Example usage: + +:: + + 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. + +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. + +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.) +#]=======================================================================] #============================================================================= # Copyright 2008-2009 Kitware, Inc. |