summaryrefslogtreecommitdiffstats
path: root/Modules/FortranCInterface.cmake
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2016-02-09 21:38:20 (GMT)
committerBrad King <brad.king@kitware.com>2016-02-10 14:54:36 (GMT)
commit9d1f40ccc1e45b918498800029034f3bebafb031 (patch)
treedaa581dd489687eeafc3d93e55375625e0212797 /Modules/FortranCInterface.cmake
parent4f593abe7270d43ba5a9c882067ae34328fdf30b (diff)
downloadCMake-9d1f40ccc1e45b918498800029034f3bebafb031.zip
CMake-9d1f40ccc1e45b918498800029034f3bebafb031.tar.gz
CMake-9d1f40ccc1e45b918498800029034f3bebafb031.tar.bz2
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.
Diffstat (limited to 'Modules/FortranCInterface.cmake')
-rw-r--r--Modules/FortranCInterface.cmake253
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.