kolan/CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge topic 'doc-FortranCInterface-variables'

Browse Source 
4f3f75a2 FortranCInterface: Document mangling result variables publicly
47f24cbc FortranCInterface: Improve documentation formatting and organization
9d1f40cc FortranCInterface: Convert docs to a bracket comment
This commit is contained in:
Brad King 2016-02-11 10:41:13 -05:00 committed by CMake Topic Stage
commit 08ccb837c3
1 changed files with 187 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

313
Modules/FortranCInterface.cmake
View File

@ -1,129 +1,190 @@
#.rst: #[=======================================================================[.rst:
# FortranCInterface FortranCInterface
# ----------------- -----------------
#
# Fortran/C Interface Detection Fortran/C Interface Detection
#
# This module automatically detects the API by which C and Fortran 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 Variables that indicate if the mangling is found:
# (declared by "MODULE PROCEDURE")
# ``FortranCInterface_GLOBAL_FOUND``
# A function is provided to generate a C header file containing macros Global subroutines and functions.
# to mangle symbol names:
# ``FortranCInterface_MODULE_FOUND``
# :: Module subroutines and functions (declared by "MODULE PROCEDURE").
#
# FortranCInterface_HEADER(<file> This module also provides the following variables to specify
# [MACRO_NAMESPACE <macro-ns>] the detected mangling, though a typical use case does not need
# [SYMBOL_NAMESPACE <ns>] to reference them and can use the `Module Functions`_ below.
# [SYMBOLS [<module>:]<function> ...])
# ``FortranCInterface_GLOBAL_PREFIX``
# It generates in <file> definitions of the following macros: Prefix for a global symbol without an underscore.
#
# :: ``FortranCInterface_GLOBAL_SUFFIX``
# Suffix for a global symbol without an underscore.
# #define FortranCInterface_GLOBAL (name,NAME) ...
# #define FortranCInterface_GLOBAL_(name,NAME) ... ``FortranCInterface_GLOBAL_CASE``
# #define FortranCInterface_MODULE (mod,name, MOD,NAME) ... The case for a global symbol without an underscore,
# #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ... either ``UPPER`` or ``LOWER``.
#
# These macros mangle four categories of Fortran symbols, respectively: ``FortranCInterface_GLOBAL__PREFIX``
# Prefix for a global symbol with an underscore.
# ::
# ``FortranCInterface_GLOBAL__SUFFIX``
# - Global symbols without '_': call mysub() Suffix for a global symbol with an underscore.
# - Global symbols with '_' : call my_sub()
# - Module symbols without '_': use mymod; call mysub() ``FortranCInterface_GLOBAL__CASE``
# - Module symbols with '_' : use mymod; call my_sub() The case for a global symbol with an underscore,
# either ``UPPER`` or ``LOWER``.
# 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 ``FortranCInterface_MODULE_PREFIX``
# MACRO_NAMESPACE option replaces the default "FortranCInterface_" Prefix for a module symbol without an underscore.
# prefix with a given namespace "<macro-ns>".
# ``FortranCInterface_MODULE_MIDDLE``
# The SYMBOLS option lists symbols to mangle automatically with C Middle of a module symbol without an underscore that appears
# preprocessor definitions: between the name of the module and the name of the symbol.
#
# :: ``FortranCInterface_MODULE_SUFFIX``
# Suffix for a module symbol without an underscore.
# <function> ==> #define <ns><function> ...
# <module>:<function> ==> #define <ns><module>_<function> ... ``FortranCInterface_MODULE_CASE``
# The case for a module symbol without an underscore,
# If the mangling for some symbol is not known then no preprocessor either ``UPPER`` or ``LOWER``.
# definition is created, and a warning is displayed. The
# SYMBOL_NAMESPACE option prefixes all preprocessor definitions ``FortranCInterface_MODULE__PREFIX``
# generated by the SYMBOLS option with a given namespace "<ns>". Prefix for a module symbol with an underscore.
#
# Example usage: ``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.
#
# include(FortranCInterface) ``FortranCInterface_MODULE__SUFFIX``
# FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_") Suffix for a module symbol with an underscore.
#
# This creates a "FC.h" header that defines mangling macros FC_GLOBAL(), ``FortranCInterface_MODULE__CASE``
# FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_(). The case for a module symbol with an underscore,
# either ``UPPER`` or ``LOWER``.
# Example usage:
# Module Functions
# :: ^^^^^^^^^^^^^^^^
#
# include(FortranCInterface) .. command:: FortranCInterface_HEADER
# FortranCInterface_HEADER(FCMangle.h
# MACRO_NAMESPACE "FC_" The ``FortranCInterface_HEADER`` function is provided to generate a
# SYMBOL_NAMESPACE "FC_" C header file containing macros to mangle symbol names::
# SYMBOLS mysub mymod:my_sub)
# FortranCInterface_HEADER(<file>
# This creates a "FCMangle.h" header that defines the same FC_*() [MACRO_NAMESPACE <macro-ns>]
# mangling macros as the previous example plus preprocessor symbols [SYMBOL_NAMESPACE <ns>]
# FC_mysub and FC_mymod_my_sub. [SYMBOLS [<module>:]<function> ...])
#
# Another function is provided to verify that the Fortran and C/C++ It generates in ``<file>`` definitions of the following macros::
# compilers work together:
# #define FortranCInterface_GLOBAL (name,NAME) ...
# :: #define FortranCInterface_GLOBAL_(name,NAME) ...
# #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
# FortranCInterface_VERIFY([CXX] [QUIET]) #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
#
# It tests whether a simple test executable using Fortran and C (and C++ These macros mangle four categories of Fortran symbols, respectively:
# when the CXX option is given) compiles and links successfully. The
# result is stored in the cache entry FortranCInterface_VERIFIED_C (or * Global symbols without '_': ``call mysub()``
# FortranCInterface_VERIFIED_CXX if CXX is given) as a boolean. If the * Global symbols with '_' : ``call my_sub()``
# check fails and QUIET is not given the function terminates with a * Module symbols without '_': ``use mymod; call mysub()``
# FATAL_ERROR message describing the problem. The purpose of this check * Module symbols with '_' : ``use mymod; call my_sub()``
# is to stop a build early for incompatible compiler combinations. The
# test is built in the Release configuration. 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.
# FortranCInterface is aware of possible GLOBAL and MODULE manglings for
# many Fortran compilers, but it also provides an interface to specify The options are:
# new possible manglings. Set the variables
# ``MACRO_NAMESPACE``
# :: Replace the default ``FortranCInterface_`` prefix with a given
# namespace ``<macro-ns>``.
# FortranCInterface_GLOBAL_SYMBOLS
# FortranCInterface_MODULE_SYMBOLS ``SYMBOLS``
# List symbols to mangle automatically with C preprocessor definitions::
# before including FortranCInterface to specify manglings of the symbols
# "MySub", "My_Sub", "MyModule:MySub", and "My_Module:My_Sub". For <function> ==> #define <ns><function> ...
# example, the code: <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.
# set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
# # ^^^^^ ^^^^^^ ^^^^^ ``SYMBOL_NAMESPACE``
# set(FortranCInterface_MODULE_SYMBOLS Prefix all preprocessor definitions generated by the ``SYMBOLS``
# __mymodule_MOD_mysub __my_module_MOD_my_sub) option with a given namespace ``<ns>``.
# # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
# include(FortranCInterface) .. command:: FortranCInterface_VERIFY
#
# tells FortranCInterface to try given GLOBAL and MODULE manglings. The ``FortranCInterface_VERIFY`` function is provided to verify
# (The carets point at raw symbol names for clarity in this example but that the Fortran and C/C++ compilers work together::
# are not needed.)
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_()``.
.. code-block:: cmake
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:
.. code-block:: cmake
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. # Copyright 2008-2009 Kitware, Inc.