summaryrefslogtreecommitdiffstats
path: root/Modules
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2016-02-09 21:43:27 (GMT)
committerBrad King <brad.king@kitware.com>2016-02-10 15:33:25 (GMT)
commit47f24cbccaaeb125a8b7ead420340d2bf8bf89ef (patch)
tree321a6eac764310b5a6c3bda72af832480196d055 /Modules
parent9d1f40ccc1e45b918498800029034f3bebafb031 (diff)
downloadCMake-47f24cbccaaeb125a8b7ead420340d2bf8bf89ef.zip
CMake-47f24cbccaaeb125a8b7ead420340d2bf8bf89ef.tar.gz
CMake-47f24cbccaaeb125a8b7ead420340d2bf8bf89ef.tar.bz2
FortranCInterface: Improve documentation formatting and organization
Organize content into sections. Define functions via explicit markup blocks so we can cross-reference them.
Diffstat (limited to 'Modules')
-rw-r--r--Modules/FortranCInterface.cmake148
1 files 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(<file>
- [MACRO_NAMESPACE <macro-ns>]
- [SYMBOL_NAMESPACE <ns>]
- [SYMBOLS [<module>:]<function> ...])
+Module Functions
+^^^^^^^^^^^^^^^^
-It generates in <file> 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(<file>
+ [MACRO_NAMESPACE <macro-ns>]
+ [SYMBOL_NAMESPACE <ns>]
+ [SYMBOLS [<module>:]<function> ...])
-These macros mangle four categories of Fortran symbols, respectively:
+ 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) ...
- - 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 "<macro-ns>".
+ * 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:
- <function> ==> #define <ns><function> ...
- <module>:<function> ==> #define <ns><module>_<function> ...
+ ``MACRO_NAMESPACE``
+ Replace the default ``FortranCInterface_`` prefix with a given
+ namespace ``<macro-ns>``.
-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>".
+ ``SYMBOLS``
+ List symbols to mangle automatically with C preprocessor definitions::
-Example usage:
+ <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.
+
+ ``SYMBOL_NAMESPACE``
+ Prefix all preprocessor definitions generated by the ``SYMBOLS``
+ option with a given namespace ``<ns>``.
+
+.. 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.)
#]=======================================================================]