From f051814ed0e63badbfd68049354f36259dbf4b49 Mon Sep 17 00:00:00 2001 From: Kitware Robot Date: Tue, 15 Oct 2013 11:17:36 -0400 Subject: 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. --- Modules/FortranCInterface.cmake | 162 +++++++++++++++++++++++++--------------- 1 file changed, 103 insertions(+), 59 deletions(-) (limited to 'Modules/FortranCInterface.cmake') diff --git a/Modules/FortranCInterface.cmake b/Modules/FortranCInterface.cmake index c59e1f839e..dccb26fb41 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( -# [MACRO_NAMESPACE ] -# [SYMBOL_NAMESPACE ] -# [SYMBOLS [:] ...]) +# +# :: +# +# FortranCInterface_HEADER( +# [MACRO_NAMESPACE ] +# [SYMBOL_NAMESPACE ] +# [SYMBOLS [:] ...]) +# # It generates in 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 "". # # The SYMBOLS option lists symbols to mangle automatically with C # preprocessor definitions: -# ==> #define ... -# : ==> #define _ ... +# +# :: +# +# ==> #define ... +# : ==> #define _ ... +# # 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 "". # # 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. -- cgit v1.2.1