summaryrefslogtreecommitdiffstats
path: root/Modules/FortranCInterface.cmake
diff options
context:
space:
mode:
authorKitware Robot <kwrobot@kitware.com>2013-10-15 15:17:36 (GMT)
committerBrad King <brad.king@kitware.com>2013-10-15 18:12:03 (GMT)
commitf051814ed0e63badbfd68049354f36259dbf4b49 (patch)
treef4e6f885f86c882d723a7dd53d2b702d0c7fdffb /Modules/FortranCInterface.cmake
parente94958e99c4dec26c86ce8b76d744c04ba960675 (diff)
downloadCMake-f051814ed0e63badbfd68049354f36259dbf4b49.zip
CMake-f051814ed0e63badbfd68049354f36259dbf4b49.tar.gz
CMake-f051814ed0e63badbfd68049354f36259dbf4b49.tar.bz2
Convert builtin help to reStructuredText source files
Run the convert-help.bash script to convert documentation: ./convert-help.bash "/path/to/CMake-build/bin" Then remove it.
Diffstat (limited to 'Modules/FortranCInterface.cmake')
-rw-r--r--Modules/FortranCInterface.cmake162
1 files changed, 103 insertions, 59 deletions
diff --git a/Modules/FortranCInterface.cmake b/Modules/FortranCInterface.cmake
index c59e1f8..dccb26f 100644
--- a/Modules/FortranCInterface.cmake
+++ b/Modules/FortranCInterface.cmake
@@ -1,85 +1,129 @@
-# - Fortran/C Interface Detection
+#.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")
+#
+# ::
+#
+# 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> ...])
+#
+# ::
+#
+# 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()
+#
+# ::
+#
+# #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_"
+# 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> ...
+#
+# ::
+#
+# <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
+# 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_().
+#
+# ::
+#
+# 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)
+#
+# ::
+#
+# 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)
+#
+# ::
+#
+# 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.)
+# (The carets point at raw symbol names for clarity in this example but
+# are not needed.)
#=============================================================================
# Copyright 2008-2009 Kitware, Inc.