document mpl CMake package, fixes #38

doc/CMakeLists.txt

@@ -9,6 +9,7 @@ configure_file(${sphinx_source_dir}/conf.py.in ${sphinx_binary_dir}/conf.py @ONL
 
 set(documentation_sources
     sphinx/auxiliary.rst
+    sphinx/cmake_integration.rst
     sphinx/communicator.rst
     sphinx/conf.py.in
     sphinx/constants.rst

doc/sphinx/cmake_integration.rst

@@ -0,0 +1,29 @@
+CMake integration
+=================
+
+MPL provides supporting files for CMake integration. These are also installed during the installation step.  CMake integration is realized via the ``mpl`` CMake package, which provides the library target ``mpl::mpl``.  The following example ``CMakeLists.txt`` file illustrates the usage of the ``mpl`` CMake package for creating an MPL application. First, the ``mpl`` package is loaded via the ``find_package`` function. Then, all targets with MPL dependency must be linked against ``mpl::mpl``.  In this way, CMake adds all necessary compiler flags and linker flags that are required for building an MPL application.
+
+.. code-block:: CMake
+
+	# MPI CMake module available since version 3.10
+	cmake_minimum_required(VERSION 3.10)
+
+	project(hello_mpl)
+
+	# project requires c++17 to build
+	set(CMAKE_CXX_STANDARD 17)
+	set(CMAKE_CXX_STANDARD_REQUIRED ON)
+	set(CMAKE_CXX_EXTENSIONS OFF)
+
+	# find the MPL library and its dependencies, e.g., an MPI library
+	find_package(mpl REQUIRED)
+
+	# create executable and link against mpl and its dependencies
+	add_executable(hello_world hello_world.cc)
+	target_link_libraries(hello_world PRIVATE mpl::mpl)
+
+When using ``find_package``, CMake searches in a set of platform-dependent standard directories for the requested CMake package.  CMake may fail to find the MPL CMake package when MPL was installed in a custom directory.  If MPL was installed in a custom directory, add the installation directory (given via ``CMAKE_INSTALL_PREFIX`` during MPL configuration see :ref:`Installation`) to the ``CMAKE_PREFIX_PATH`` variable during the configuration of the MPL application, e.g.:
+
+.. code:: shell
+
+   user@host:~/hello_mpl/build$ cmake -DCMAKE_PREFIX_PATH:PATH=/path/to/mpl ..

doc/sphinx/index.rst

@@ -7,6 +7,7 @@ MPL: A message passing library
    :caption: Contents:
 
    installation
+   cmake_integration
    data_types
    environmental_management
    group

doc/sphinx/installation.rst

@@ -1,3 +1,5 @@
+.. _Installation:
+
 Installation
 ============
 
@@ -20,7 +22,7 @@ The option ``-DCMAKE_INSTALL_PREFIX:PATH`` specifies the installation path.
 
 Usually, CMake will find the required MPI installation as well as the Boost Test library automatically. Depending on the local setup, however, CMake may need some hints to find these dependencies. See the CMake documentation on `FindMPI <https://cmake.org/cmake/help/git-master/module/FindMPI.html#variables-for-locating-mpi>`__ and `FindBoost <https://cmake.org/cmake/help/git-master/module/FindBoost.html?highlight=boost#hints>`__ for further details.
 
-Cmake can also be utilized to install the MPL header files. Just call CMake a second time and specify the ``--install`` option now, e.g.,
+CMake can also be utilized to install the MPL header files. Just call CMake a second time and specify the ``--install`` option now, e.g.,
 
 .. code:: shell
 

docs/html/_images/graphviz-16a03f36baf6be5b49a90962c57dfe7f18cff7d9.png.map

@@ -1,5 +1,5 @@
 <map id="%3" name="%3">
-<area shape="rect" id="node1" title="hindexed_layout&lt; T &gt;" alt="" coords="5,5,188,53"/>
-<area shape="rect" id="node2" title="layout&lt; T &gt;" alt="" coords="236,5,347,53"/>
-<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="188,27,220,27,220,32,188,32"/>
+<area shape="rect" id="node1" title="hindexed_layout&lt; T &gt;" alt="" coords="5,5,228,53"/>
+<area shape="rect" id="node2" title="layout&lt; T &gt;" alt="" coords="276,5,408,53"/>
+<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="228,27,262,27,262,32,228,32"/>
 </map>

docs/html/_images/graphviz-2d04970c66a65834a6d291ebce1dd1f3027efd86.png.map

@@ -1,5 +1,5 @@
 <map id="%3" name="%3">
-<area shape="rect" id="node1" title="indexed_layout&lt; T &gt;" alt="" coords="5,5,180,53"/>
-<area shape="rect" id="node2" title="layout&lt; T &gt;" alt="" coords="228,5,339,53"/>
-<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="180,27,212,27,212,32,180,32"/>
+<area shape="rect" id="node1" title="indexed_layout&lt; T &gt;" alt="" coords="5,5,217,53"/>
+<area shape="rect" id="node2" title="layout&lt; T &gt;" alt="" coords="265,5,397,53"/>
+<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="218,27,252,27,252,32,218,32"/>
 </map>

docs/html/_images/graphviz-2fe2b7a5c0e73a720999a18e538a3c0cb6940c8d.png.map

@@ -1,5 +1,5 @@
 <map id="%3" name="%3">
-<area shape="rect" id="node1" title="layout&lt; T &gt;" alt="" coords="204,5,315,53"/>
-<area shape="rect" id="node2" title="null_layout&lt; T &gt;" alt="" coords="5,5,156,53"/>
-<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="157,27,189,27,189,32,157,32"/>
+<area shape="rect" id="node1" title="layout&lt; T &gt;" alt="" coords="236,5,368,53"/>
+<area shape="rect" id="node2" title="null_layout&lt; T &gt;" alt="" coords="5,5,188,53"/>
+<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="188,27,222,27,222,32,188,32"/>
 </map>

docs/html/_images/graphviz-30b51fc3e7b9c12ac05f4874ce6c904b0adfdb00.png.map

@@ -1,29 +1,29 @@
 <map id="%3" name="%3">
-<area shape="rect" id="node1" title="layout&lt; T &gt;" alt="" coords="515,401,625,449"/>
-<area shape="rect" id="node2" title="layout&lt; void &gt;" alt="" coords="284,5,419,53"/>
-<area shape="poly" id="edge1" title="template&#45;instance" alt="" coords="420,36,446,47,469,63,498,100,521,142,539,186,552,231,567,317,572,386,566,386,562,318,547,232,534,188,517,144,494,103,465,67,443,51,418,41"/>
-<area shape="rect" id="node3" title="contiguous_layout&lt; T &gt;" alt="" coords="252,77,451,125"/>
-<area shape="poly" id="edge2" title="public&#45;inheritance" alt="" coords="453,123,468,135,493,163,513,195,542,263,560,330,568,386,563,386,555,331,537,265,508,197,489,167,465,139,450,128"/>
-<area shape="rect" id="node4" title="empty_layout&lt; T &gt;" alt="" coords="272,149,431,197"/>
-<area shape="poly" id="edge3" title="public&#45;inheritance" alt="" coords="432,186,468,207,504,248,532,296,551,344,563,386,558,387,546,346,527,298,500,252,465,211,429,191"/>
-<area shape="rect" id="node5" title="heterogeneous_layout" alt="" coords="5,5,188,53"/>
-<area shape="poly" id="edge4" title="public&#45;inheritance" alt="" coords="189,27,268,27,268,32,189,32"/>
-<area shape="rect" id="node6" title="hindexed_block_layout&lt; T &gt;" alt="" coords="236,221,467,269"/>
-<area shape="poly" id="edge5" title="public&#45;inheritance" alt="" coords="449,268,468,279,495,303,518,331,553,386,548,389,514,334,491,307,465,283,446,272"/>
-<area shape="rect" id="node7" title="hindexed_layout&lt; T &gt;" alt="" coords="260,293,443,341"/>
-<area shape="poly" id="edge6" title="public&#45;inheritance" alt="" coords="441,339,468,351,529,390,526,394,465,356,439,344"/>
-<area shape="rect" id="node8" title="indexed_block_layout&lt; T &gt;" alt="" coords="240,365,463,413"/>
-<area shape="poly" id="edge7" title="public&#45;inheritance" alt="" coords="464,405,500,411,499,416,463,410"/>
-<area shape="rect" id="node9" title="indexed_layout&lt; T &gt;" alt="" coords="264,437,439,485"/>
-<area shape="poly" id="edge8" title="public&#45;inheritance" alt="" coords="439,444,499,434,500,439,440,450"/>
-<area shape="rect" id="node10" title="iterator_layout&lt; T &gt;" alt="" coords="260,509,443,557"/>
-<area shape="poly" id="edge9" title="public&#45;inheritance" alt="" coords="439,506,465,495,526,456,529,461,468,500,441,511"/>
-<area shape="rect" id="node11" title="null_layout&lt; T &gt;" alt="" coords="276,581,427,629"/>
-<area shape="poly" id="edge10" title="public&#45;inheritance" alt="" coords="426,587,465,567,491,544,514,517,548,462,553,465,518,520,495,548,468,572,428,592"/>
-<area shape="rect" id="node12" title="strided_vector_layout&lt; T &gt;" alt="" coords="236,653,467,701"/>
-<area shape="poly" id="edge11" title="public&#45;inheritance" alt="" coords="449,651,465,639,500,599,527,552,546,505,558,464,563,465,551,507,532,555,504,602,468,643,452,655"/>
-<area shape="rect" id="node13" title="subarray_layout&lt; T &gt;" alt="" coords="260,725,443,773"/>
-<area shape="poly" id="edge12" title="public&#45;inheritance" alt="" coords="442,728,465,711,489,684,508,653,537,586,555,519,563,464,568,465,560,521,542,588,513,656,493,687,468,715,445,732"/>
-<area shape="rect" id="node14" title="vector_layout&lt; T &gt;" alt="" coords="268,797,435,845"/>
-<area shape="poly" id="edge13" title="public&#45;inheritance" alt="" coords="434,804,450,795,465,783,494,747,517,707,534,663,547,618,562,533,566,465,572,465,567,534,552,620,539,665,521,709,498,750,469,787,453,800,436,809"/>
+<area shape="rect" id="node1" title="layout&lt; T &gt;" alt="" coords="607,401,739,449"/>
+<area shape="rect" id="node2" title="layout&lt; void &gt;" alt="" coords="336,5,499,53"/>
+<area shape="poly" id="edge1" title="template&#45;instance" alt="" coords="500,33,532,44,560,63,592,100,617,141,636,186,651,231,668,318,674,387,668,388,662,319,646,233,631,187,612,144,588,103,557,67,530,49,498,38"/>
+<area shape="rect" id="node3" title="contiguous_layout&lt; T &gt;" alt="" coords="296,77,539,125"/>
+<area shape="poly" id="edge2" title="public&#45;inheritance" alt="" coords="540,121,560,135,587,163,608,194,641,263,660,331,670,387,665,388,655,333,636,265,604,197,582,166,557,139,537,126"/>
+<area shape="rect" id="node4" title="empty_layout&lt; T &gt;" alt="" coords="321,149,513,197"/>
+<area shape="poly" id="edge3" title="public&#45;inheritance" alt="" coords="514,184,538,193,560,207,599,248,629,296,651,345,665,387,659,389,646,347,624,299,595,251,557,211,536,198,512,189"/>
+<area shape="rect" id="node5" title="heterogeneous_layout" alt="" coords="5,5,228,53"/>
+<area shape="poly" id="edge4" title="public&#45;inheritance" alt="" coords="228,27,322,27,322,32,228,32"/>
+<area shape="rect" id="node6" title="hindexed_block_layout&lt; T &gt;" alt="" coords="276,221,559,269"/>
+<area shape="poly" id="edge5" title="public&#45;inheritance" alt="" coords="538,267,560,279,590,303,616,331,654,388,650,391,612,335,586,307,557,284,535,272"/>
+<area shape="rect" id="node7" title="hindexed_layout&lt; T &gt;" alt="" coords="306,293,529,341"/>
+<area shape="poly" id="edge6" title="public&#45;inheritance" alt="" coords="528,339,560,351,596,370,629,391,627,395,594,374,558,356,526,344"/>
+<area shape="rect" id="node8" title="indexed_block_layout&lt; T &gt;" alt="" coords="281,365,553,413"/>
+<area shape="poly" id="edge7" title="public&#45;inheritance" alt="" coords="554,406,593,412,593,417,553,411"/>
+<area shape="rect" id="node9" title="indexed_layout&lt; T &gt;" alt="" coords="311,437,523,485"/>
+<area shape="poly" id="edge8" title="public&#45;inheritance" alt="" coords="523,444,593,434,593,439,524,449"/>
+<area shape="rect" id="node10" title="iterator_layout&lt; T &gt;" alt="" coords="306,509,529,557"/>
+<area shape="poly" id="edge9" title="public&#45;inheritance" alt="" coords="526,507,558,495,594,476,627,455,629,460,596,481,560,500,528,512"/>
+<area shape="rect" id="node11" title="null_layout&lt; T &gt;" alt="" coords="326,581,509,629"/>
+<area shape="poly" id="edge10" title="public&#45;inheritance" alt="" coords="508,589,534,580,557,567,586,544,612,516,650,460,654,463,616,519,590,548,560,572,536,585,510,594"/>
+<area shape="rect" id="node12" title="strided_vector_layout&lt; T &gt;" alt="" coords="276,653,559,701"/>
+<area shape="poly" id="edge11" title="public&#45;inheritance" alt="" coords="539,651,557,639,595,599,624,552,646,504,659,462,665,464,651,506,629,554,599,603,560,643,542,656"/>
+<area shape="rect" id="node13" title="subarray_layout&lt; T &gt;" alt="" coords="306,725,529,773"/>
+<area shape="poly" id="edge12" title="public&#45;inheritance" alt="" coords="528,730,557,711,582,684,604,654,636,585,655,518,665,462,670,463,660,519,641,587,608,656,587,688,560,715,530,734"/>
+<area shape="rect" id="node14" title="vector_layout&lt; T &gt;" alt="" coords="316,797,519,845"/>
+<area shape="poly" id="edge13" title="public&#45;inheritance" alt="" coords="518,807,539,797,557,783,588,748,612,707,631,663,646,618,662,532,668,463,674,463,668,532,651,619,636,665,617,710,592,751,560,787,541,801,520,811"/>
 </map>

docs/html/_images/graphviz-32657ab9ca2e1517ec7d4ca4e52e7abf5a13049d.png.map

@@ -1,5 +1,5 @@
 <map id="%3" name="%3">
-<area shape="rect" id="node1" title="layout&lt; T &gt;" alt="" coords="220,5,331,53"/>
-<area shape="rect" id="node2" title="vector_layout&lt; T &gt;" alt="" coords="5,5,172,53"/>
-<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="172,27,205,27,205,32,172,32"/>
+<area shape="rect" id="node1" title="layout&lt; T &gt;" alt="" coords="256,5,388,53"/>
+<area shape="rect" id="node2" title="vector_layout&lt; T &gt;" alt="" coords="5,5,208,53"/>
+<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="208,27,242,27,242,32,208,32"/>
 </map>

docs/html/_images/graphviz-493f5c123c3794b9e4a6e33505e8ae1b40c4e3fc.png.map

@@ -1,3 +1,3 @@
 <map id="%3" name="%3">
-<area shape="rect" id="node1" title="indexed_layout&lt; T &gt;::parameter" alt="" coords="5,5,268,53"/>
+<area shape="rect" id="node1" title="indexed_layout&lt; T &gt;::parameter" alt="" coords="5,5,328,53"/>
 </map>

docs/html/_images/graphviz-5e9c10696d2a74ced952470cc07fde1d0fd4c305.png.map

@@ -1,5 +1,5 @@
 <map id="%3" name="%3">
-<area shape="rect" id="node1" title="layout&lt; T &gt;" alt="" coords="284,5,395,53"/>
-<area shape="rect" id="node2" title="strided_vector_layout&lt; T &gt;" alt="" coords="5,5,236,53"/>
-<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="236,27,268,27,268,32,236,32"/>
+<area shape="rect" id="node1" title="layout&lt; T &gt;" alt="" coords="336,5,468,53"/>
+<area shape="rect" id="node2" title="strided_vector_layout&lt; T &gt;" alt="" coords="5,5,288,53"/>
+<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="288,27,322,27,322,32,288,32"/>
 </map>

docs/html/_images/graphviz-73a94ba4e7fda2781dd07b8f7c66639e011d14e5.png.map

@@ -1,5 +1,5 @@
 <map id="%3" name="%3">
-<area shape="rect" id="node1" title="contiguous_layout&lt; T &gt;" alt="" coords="5,5,204,53"/>
-<area shape="rect" id="node2" title="layout&lt; T &gt;" alt="" coords="252,5,363,53"/>
-<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="204,27,237,27,237,32,204,32"/>
+<area shape="rect" id="node1" title="contiguous_layout&lt; T &gt;" alt="" coords="5,5,248,53"/>
+<area shape="rect" id="node2" title="layout&lt; T &gt;" alt="" coords="296,5,428,53"/>
+<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="248,27,282,27,282,32,248,32"/>
 </map>

docs/html/_images/graphviz-7cc5f119006863e9f7de602a258b430ee27465da.png.map

@@ -1,5 +1,5 @@
 <map id="%3" name="%3">
-<area shape="rect" id="node1" title="empty_layout&lt; T &gt;" alt="" coords="5,5,164,53"/>
-<area shape="rect" id="node2" title="layout&lt; T &gt;" alt="" coords="212,5,323,53"/>
-<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="164,27,197,27,197,32,164,32"/>
+<area shape="rect" id="node1" title="empty_layout&lt; T &gt;" alt="" coords="5,5,197,53"/>
+<area shape="rect" id="node2" title="layout&lt; T &gt;" alt="" coords="245,5,377,53"/>
+<area shape="poly" id="edge1" title="public&#45;inheritance" alt="" coords="198,27,231,27,231,32,198,32"/>
 </map>

docs/html/_images/graphviz-a88047141da1e6f9351d2e770cb76de2850241b3.png.map

@@ -1,3 +1,3 @@
 <map id="%3" name="%3">
-<area shape="rect" id="node1" title="layout&lt; T &gt;" alt="" coords="5,5,116,53"/>
+<area shape="rect" id="node1" title="layout&lt; T &gt;" alt="" coords="5,5,137,53"/>
 </map>

docs/html/_images/graphviz-e909d2f3f3ee6c6e4cd9f365c541fc84db805e58.png.map

@@ -1,3 +1,3 @@
 <map id="%3" name="%3">
-<area shape="rect" id="node1" title="hindexed_layout&lt; T &gt;::parameter" alt="" coords="5,5,276,53"/>
+<area shape="rect" id="node1" title="hindexed_layout&lt; T &gt;::parameter" alt="" coords="5,5,337,53"/>
 </map>

docs/html/_sources/cmake_integration.rst.txt

@@ -0,0 +1,29 @@
+CMake integration
+=================
+
+MPL provides supporting files for CMake integration. These are also installed during the installation step.  CMake integration is realized via the ``mpl`` CMake package, which provides the library target ``mpl::mpl``.  The following example ``CMakeLists.txt`` file illustrates the usage of the ``mpl`` CMake package for creating an MPL application. First, the ``mpl`` package is loaded via the ``find_package`` function. Then, all targets with MPL dependency must be linked against ``mpl::mpl``.  In this way, CMake adds all necessary compiler flags and linker flags that are required for building an MPL application.
+
+.. code-block:: CMake
+
+	# MPI CMake module available since version 3.10
+	cmake_minimum_required(VERSION 3.10)
+
+	project(hello_mpl)
+
+	# project requires c++17 to build
+	set(CMAKE_CXX_STANDARD 17)
+	set(CMAKE_CXX_STANDARD_REQUIRED ON)
+	set(CMAKE_CXX_EXTENSIONS OFF)
+
+	# find the MPL library and its dependencies, e.g., an MPI library
+	find_package(mpl REQUIRED)
+
+	# create executable and link against mpl and its dependencies
+	add_executable(hello_world hello_world.cc)
+	target_link_libraries(hello_world PRIVATE mpl::mpl)
+
+When using ``find_package``, CMake searches in a set of platform-dependent standard directories for the requested CMake package.  CMake may fail to find the MPL CMake package when MPL was installed in a custom directory.  If MPL was installed in a custom directory, add the installation directory (given via ``CMAKE_INSTALL_PREFIX`` during MPL configuration see :ref:`Installation`) to the ``CMAKE_PREFIX_PATH`` variable during the configuration of the MPL application, e.g.:
+
+.. code:: shell
+
+   user@host:~/hello_mpl/build$ cmake -DCMAKE_PREFIX_PATH:PATH=/path/to/mpl ..

docs/html/_sources/index.rst.txt

@@ -7,6 +7,7 @@ MPL: A message passing library
    :caption: Contents:
 
    installation
+   cmake_integration
    data_types
    environmental_management
    group

docs/html/_sources/installation.rst.txt

@@ -1,3 +1,5 @@
+.. _Installation:
+
 Installation
 ============
 
@@ -20,7 +22,7 @@ The option ``-DCMAKE_INSTALL_PREFIX:PATH`` specifies the installation path.
 
 Usually, CMake will find the required MPI installation as well as the Boost Test library automatically. Depending on the local setup, however, CMake may need some hints to find these dependencies. See the CMake documentation on `FindMPI <https://cmake.org/cmake/help/git-master/module/FindMPI.html#variables-for-locating-mpi>`__ and `FindBoost <https://cmake.org/cmake/help/git-master/module/FindBoost.html?highlight=boost#hints>`__ for further details.
 
-Cmake can also be utilized to install the MPL header files. Just call CMake a second time and specify the ``--install`` option now, e.g.,
+CMake can also be utilized to install the MPL header files. Just call CMake a second time and specify the ``--install`` option now, e.g.,
 
 .. code:: shell