From 9d1f40ccc1e45b918498800029034f3bebafb031 Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 9 Feb 2016 16:38:20 -0500 Subject: 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. --- Modules/FortranCInterface.cmake | 253 ++++++++++++++++++++-------------------- 1 file 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( -# [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() -# -# 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 "". -# -# The SYMBOLS option lists symbols to mangle automatically with C -# preprocessor definitions: -# -# :: -# -# ==> #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 -# 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_(). -# -# 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( + [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() + +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 "". + +The SYMBOLS option lists symbols to mangle automatically with C +preprocessor definitions: + +:: + + ==> #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 +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_(). + +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. -- cgit v0.12 From 47f24cbccaaeb125a8b7ead420340d2bf8bf89ef Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 9 Feb 2016 16:43:27 -0500 Subject: FortranCInterface: Improve documentation formatting and organization Organize content into sections. Define functions via explicit markup blocks so we can cross-reference them. --- Modules/FortranCInterface.cmake | 148 +++++++++++++++++++++------------------- 1 file changed, 78 insertions(+), 70 deletions(-) diff --git a/Modules/FortranCInterface.cmake b/Modules/FortranCInterface.cmake index 881e8b1..c872d6d 100644 --- a/Modules/FortranCInterface.cmake +++ b/Modules/FortranCInterface.cmake @@ -5,73 +5,96 @@ 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: +languages interact. -:: +Module Variables +^^^^^^^^^^^^^^^^ - FortranCInterface_GLOBAL_FOUND = Global subroutines and functions - FortranCInterface_MODULE_FOUND = Module subroutines and functions - (declared by "MODULE PROCEDURE") +Variables that indicate if the mangling is found: -A function is provided to generate a C header file containing macros -to mangle symbol names: +``FortranCInterface_GLOBAL_FOUND`` + Global subroutines and functions. -:: +``FortranCInterface_MODULE_FOUND`` + Module subroutines and functions (declared by "MODULE PROCEDURE"). - FortranCInterface_HEADER( - [MACRO_NAMESPACE ] - [SYMBOL_NAMESPACE ] - [SYMBOLS [:] ...]) +Module Functions +^^^^^^^^^^^^^^^^ -It generates in definitions of the following macros: +.. command:: FortranCInterface_HEADER -:: + The ``FortranCInterface_HEADER`` function is provided to generate a + C header file containing macros to mangle symbol names:: - #define FortranCInterface_GLOBAL (name,NAME) ... - #define FortranCInterface_GLOBAL_(name,NAME) ... - #define FortranCInterface_MODULE (mod,name, MOD,NAME) ... - #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ... + FortranCInterface_HEADER( + [MACRO_NAMESPACE ] + [SYMBOL_NAMESPACE ] + [SYMBOLS [:] ...]) -These macros mangle four categories of Fortran symbols, respectively: + 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) ... - - 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() + These macros mangle four categories of Fortran symbols, respectively: -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 "". + * 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()`` -The SYMBOLS option lists symbols to mangle automatically with C -preprocessor definitions: + 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: - ==> #define ... - : ==> #define _ ... + ``MACRO_NAMESPACE`` + Replace the default ``FortranCInterface_`` prefix with a given + namespace ````. -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 "". + ``SYMBOLS`` + List symbols to mangle automatically with C preprocessor definitions:: -Example usage: + ==> #define ... + : ==> #define _ ... -:: + 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 ````. + +.. 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_(). - -Example usage: +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 @@ -79,40 +102,25 @@ Example usage: SYMBOL_NAMESPACE "FC_" 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 -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. +``FC_mysub`` and ``FC_mymod_my_sub``. -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 +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: +``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_) # ^^^^^ ^^^^^^ ^^^^^ @@ -121,7 +129,7 @@ example, the code: # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^ 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 are not needed.) #]=======================================================================] -- cgit v0.12 From 4f3f75a2461af79bf1eb01b61a06d396d89521c5 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 10 Feb 2016 10:35:48 -0500 Subject: FortranCInterface: Document mangling result variables publicly Some projects may want to use the detailed mangling information directly instead of using the FortranCInterface_HEADER function. We already provide variables encoding the mangling information, so just document them as available. --- Modules/FortranCInterface.cmake | 52 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/Modules/FortranCInterface.cmake b/Modules/FortranCInterface.cmake index c872d6d..c12dd4c 100644 --- a/Modules/FortranCInterface.cmake +++ b/Modules/FortranCInterface.cmake @@ -18,6 +18,58 @@ Variables that indicate if the mangling is found: ``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 ^^^^^^^^^^^^^^^^ -- cgit v0.12