FortranCInterface: Convert docs to a bracket comment
Use a bracket comment to hold the documentation instead of a block of line comments. This will make further updates easier.
This commit is contained in:
Brad King
parent
4f593abe72
commit
9d1f40ccc1
|
|
@ -1,129 +1,130 @@
|
||||||
#.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. Variables indicate if the mangling is found:
|
||||||
#
|
|
||||||
# ::
|
::
|
||||||
#
|
|
||||||
# FortranCInterface_GLOBAL_FOUND = Global subroutines and functions
|
FortranCInterface_GLOBAL_FOUND = Global subroutines and functions
|
||||||
# FortranCInterface_MODULE_FOUND = Module subroutines and functions
|
FortranCInterface_MODULE_FOUND = Module subroutines and functions
|
||||||
# (declared by "MODULE PROCEDURE")
|
(declared by "MODULE PROCEDURE")
|
||||||
#
|
|
||||||
# A function is provided to generate a C header file containing macros
|
A function is provided to generate a C header file containing macros
|
||||||
# to mangle symbol names:
|
to mangle symbol names:
|
||||||
#
|
|
||||||
# ::
|
::
|
||||||
#
|
|
||||||
# FortranCInterface_HEADER(<file>
|
FortranCInterface_HEADER(<file>
|
||||||
# [MACRO_NAMESPACE <macro-ns>]
|
[MACRO_NAMESPACE <macro-ns>]
|
||||||
# [SYMBOL_NAMESPACE <ns>]
|
[SYMBOL_NAMESPACE <ns>]
|
||||||
# [SYMBOLS [<module>:]<function> ...])
|
[SYMBOLS [<module>:]<function> ...])
|
||||||
#
|
|
||||||
# It generates in <file> definitions of the following macros:
|
It generates in <file> definitions of the following macros:
|
||||||
#
|
|
||||||
# ::
|
::
|
||||||
#
|
|
||||||
# #define FortranCInterface_GLOBAL (name,NAME) ...
|
#define FortranCInterface_GLOBAL (name,NAME) ...
|
||||||
# #define FortranCInterface_GLOBAL_(name,NAME) ...
|
#define FortranCInterface_GLOBAL_(name,NAME) ...
|
||||||
# #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
|
#define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
|
||||||
# #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
|
#define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
|
||||||
#
|
|
||||||
# These macros mangle four categories of Fortran symbols, respectively:
|
These macros mangle four categories of Fortran symbols, respectively:
|
||||||
#
|
|
||||||
# ::
|
::
|
||||||
#
|
|
||||||
# - Global symbols without '_': call mysub()
|
- Global symbols without '_': call mysub()
|
||||||
# - Global symbols with '_' : call my_sub()
|
- Global symbols with '_' : call my_sub()
|
||||||
# - Module symbols without '_': use mymod; call mysub()
|
- Module symbols without '_': use mymod; call mysub()
|
||||||
# - Module symbols with '_' : use mymod; call my_sub()
|
- Module symbols with '_' : use mymod; call my_sub()
|
||||||
#
|
|
||||||
# If mangling for a category is not known, its macro is left undefined.
|
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
|
All macros require raw names in both lower case and upper case. The
|
||||||
# MACRO_NAMESPACE option replaces the default "FortranCInterface_"
|
MACRO_NAMESPACE option replaces the default "FortranCInterface_"
|
||||||
# prefix with a given namespace "<macro-ns>".
|
prefix with a given namespace "<macro-ns>".
|
||||||
#
|
|
||||||
# The SYMBOLS option lists symbols to mangle automatically with C
|
The SYMBOLS option lists symbols to mangle automatically with C
|
||||||
# preprocessor definitions:
|
preprocessor definitions:
|
||||||
#
|
|
||||||
# ::
|
::
|
||||||
#
|
|
||||||
# <function> ==> #define <ns><function> ...
|
<function> ==> #define <ns><function> ...
|
||||||
# <module>:<function> ==> #define <ns><module>_<function> ...
|
<module>:<function> ==> #define <ns><module>_<function> ...
|
||||||
#
|
|
||||||
# If the mangling for some symbol is not known then no preprocessor
|
If the mangling for some symbol is not known then no preprocessor
|
||||||
# definition is created, and a warning is displayed. The
|
definition is created, and a warning is displayed. The
|
||||||
# SYMBOL_NAMESPACE option prefixes all preprocessor definitions
|
SYMBOL_NAMESPACE option prefixes all preprocessor definitions
|
||||||
# generated by the SYMBOLS option with a given namespace "<ns>".
|
generated by the SYMBOLS option with a given namespace "<ns>".
|
||||||
#
|
|
||||||
# Example usage:
|
Example usage:
|
||||||
#
|
|
||||||
# ::
|
::
|
||||||
#
|
|
||||||
# include(FortranCInterface)
|
include(FortranCInterface)
|
||||||
# FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
|
FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
|
||||||
#
|
|
||||||
# This creates a "FC.h" header that defines mangling macros FC_GLOBAL(),
|
This creates a "FC.h" header that defines mangling macros FC_GLOBAL(),
|
||||||
# FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
|
FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
|
||||||
#
|
|
||||||
# Example usage:
|
Example usage:
|
||||||
#
|
|
||||||
# ::
|
::
|
||||||
#
|
|
||||||
# include(FortranCInterface)
|
include(FortranCInterface)
|
||||||
# FortranCInterface_HEADER(FCMangle.h
|
FortranCInterface_HEADER(FCMangle.h
|
||||||
# MACRO_NAMESPACE "FC_"
|
MACRO_NAMESPACE "FC_"
|
||||||
# SYMBOL_NAMESPACE "FC_"
|
SYMBOL_NAMESPACE "FC_"
|
||||||
# SYMBOLS mysub mymod:my_sub)
|
SYMBOLS mysub mymod:my_sub)
|
||||||
#
|
|
||||||
# This creates a "FCMangle.h" header that defines the same FC_*()
|
This creates a "FCMangle.h" header that defines the same FC_*()
|
||||||
# mangling macros as the previous example plus preprocessor symbols
|
mangling macros as the previous example plus preprocessor symbols
|
||||||
# FC_mysub and FC_mymod_my_sub.
|
FC_mysub and FC_mymod_my_sub.
|
||||||
#
|
|
||||||
# Another function is provided to verify that the Fortran and C/C++
|
Another function is provided to verify that the Fortran and C/C++
|
||||||
# compilers work together:
|
compilers work together:
|
||||||
#
|
|
||||||
# ::
|
::
|
||||||
#
|
|
||||||
# FortranCInterface_VERIFY([CXX] [QUIET])
|
FortranCInterface_VERIFY([CXX] [QUIET])
|
||||||
#
|
|
||||||
# It tests whether a simple test executable using Fortran and C (and C++
|
It tests whether a simple test executable using Fortran and C (and C++
|
||||||
# when the CXX option is given) compiles and links successfully. The
|
when the CXX option is given) compiles and links successfully. The
|
||||||
# result is stored in the cache entry FortranCInterface_VERIFIED_C (or
|
result is stored in the cache entry FortranCInterface_VERIFIED_C (or
|
||||||
# FortranCInterface_VERIFIED_CXX if CXX is given) as a boolean. If the
|
FortranCInterface_VERIFIED_CXX if CXX is given) as a boolean. If the
|
||||||
# check fails and QUIET is not given the function terminates with a
|
check fails and QUIET is not given the function terminates with a
|
||||||
# FATAL_ERROR message describing the problem. The purpose of this check
|
FATAL_ERROR message describing the problem. The purpose of this check
|
||||||
# is to stop a build early for incompatible compiler combinations. The
|
is to stop a build early for incompatible compiler combinations. The
|
||||||
# test is built in the Release configuration.
|
test is built in the Release configuration.
|
||||||
#
|
|
||||||
# FortranCInterface is aware of possible GLOBAL and MODULE manglings for
|
FortranCInterface is aware of possible GLOBAL and MODULE manglings for
|
||||||
# many Fortran compilers, but it also provides an interface to specify
|
many Fortran compilers, but it also provides an interface to specify
|
||||||
# new possible manglings. Set the variables
|
new possible manglings. Set the variables
|
||||||
#
|
|
||||||
# ::
|
::
|
||||||
#
|
|
||||||
# FortranCInterface_GLOBAL_SYMBOLS
|
FortranCInterface_GLOBAL_SYMBOLS
|
||||||
# FortranCInterface_MODULE_SYMBOLS
|
FortranCInterface_MODULE_SYMBOLS
|
||||||
#
|
|
||||||
# before including FortranCInterface to specify manglings of the symbols
|
before including FortranCInterface to specify manglings of the symbols
|
||||||
# "MySub", "My_Sub", "MyModule:MySub", and "My_Module:My_Sub". For
|
"MySub", "My_Sub", "MyModule:MySub", and "My_Module:My_Sub". For
|
||||||
# example, the code:
|
example, the code:
|
||||||
#
|
|
||||||
# ::
|
::
|
||||||
#
|
|
||||||
# set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
|
set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
|
||||||
# # ^^^^^ ^^^^^^ ^^^^^
|
# ^^^^^ ^^^^^^ ^^^^^
|
||||||
# set(FortranCInterface_MODULE_SYMBOLS
|
set(FortranCInterface_MODULE_SYMBOLS
|
||||||
# __mymodule_MOD_mysub __my_module_MOD_my_sub)
|
__mymodule_MOD_mysub __my_module_MOD_my_sub)
|
||||||
# # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
|
# ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
|
||||||
# include(FortranCInterface)
|
include(FortranCInterface)
|
||||||
#
|
|
||||||
# tells FortranCInterface to try given GLOBAL and MODULE manglings.
|
tells FortranCInterface to try given GLOBAL and MODULE manglings.
|
||||||
# (The carets point at raw symbol names for clarity in this example but
|
(The carets point at raw symbol names for clarity in this example but
|
||||||
# are not needed.)
|
are not needed.)
|
||||||
|
#]=======================================================================]
|
||||||
|
|
||||||
#=============================================================================
|
#=============================================================================
|
||||||
# Copyright 2008-2009 Kitware, Inc.
|
# Copyright 2008-2009 Kitware, Inc.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue