Merge topic 'doc-FortranCInterface-variables'
4f3f75a2FortranCInterface: Document mangling result variables publicly47f24cbcFortranCInterface: Improve documentation formatting and organization9d1f40ccFortranCInterface: Convert docs to a bracket comment
This commit is contained in:
Brad King
CMake Topic Stage
commit
08ccb837c3
|
|
@ -1,129 +1,190 @@
|
|||
#.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.
|
||||
|
||||
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
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
.. command:: 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>``.
|
||||
|
||||
.. command:: 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
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
.. 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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue