From 1a7925e1950bf8c1386042404478a0c6ebfece45 Mon Sep 17 00:00:00 2001
From: Michael Buehlmann <buehlmann.michi@gmail.com>
Date: Tue, 29 Mar 2022 19:06:49 -0500
Subject: [PATCH] add CMake docs, update to PEP 517 builds

---
 docs/cpp/library.rst      | 80 ++++++++++++++++++++++++++++++++++++++-
 docs/python/readwrite.rst |  2 +-
 pyproject.toml            |  7 ++++
 setup.py                  |  6 ++-
 4 files changed, 92 insertions(+), 3 deletions(-)
 create mode 100644 pyproject.toml

diff --git a/docs/cpp/library.rst b/docs/cpp/library.rst
index b3712cd..a3f3d20 100644
--- a/docs/cpp/library.rst
+++ b/docs/cpp/library.rst
@@ -1,2 +1,80 @@
 GenericIO and CMake
-===================
\ No newline at end of file
+===================
+
+
+Adding GenericIO as a dependency to a CMake C/C++ project is straight forward.
+As an example, check out the `monofonIC <https://bitbucket.org/ohahn/monofonic>`_
+library which has GenericIO as an optional dependency.
+
+CMake >=3.11, <3.14
+-------------------
+
+If you're using ``CMake >= 3.11``, you can use the ``FetchContent`` routine to
+download GenericIO at compile-time. Alternatively, you can include GenericIO as
+a ``git`` submodule or directly copy the source code into the repository (not
+recommended).
+
+Here is an example for a very basic ``CMakeFile.txt``:
+
+.. code-block:: cmake
+
+    cmake_minimum_required(VERSION 3.11)
+    project(TestGenericIO CXX)
+
+    # Load GenericIO
+    include(FetchContent)
+    FetchContent_Declare(
+        genericio
+        GIT_REPOSITORY https://git.cels.anl.gov/hacc/genericio.git
+        GIT_TAG master
+        GIT_SHALLOW YES
+        GIT_PROGRESS TRUE
+        USES_TERMINAL_DOWNLOAD TRUE   # <---- this is needed only for Ninja
+    )
+
+    FetchContent_GetProperties(genericio)
+    if(NOT genericio_POPULATED)
+        set(FETCHCONTENT_QUIET OFF)
+        FetchContent_Populate(genericio)
+        add_subdirectory(${genericio_SOURCE_DIR} ${genericio_BINARY_DIR})
+    endif()
+
+    # Add an executable
+    add_executable(TestGenericIO test_genericio.cpp)
+
+    # Link to GenericIO
+    target_link_libraries(TestGenericIO PRIVATE genericio::genericio_mpi)
+
+The last line will add the GenericIO headers to the include directories and
+automatically link the library during compile time. If you want to compile your
+program without the MPI library, you can link to the non-MPI version of
+GenericIO: ``genericio::genericio``. If MPI is not available on your system,
+then only the non-MPI version will be available as an option.
+
+CMake >= 3.14
+-------------
+
+With more recent CMake versions, the ``CMakeLists.txt`` file can be simplified
+
+.. code-block:: cmake
+
+    cmake_minimum_required(VERSION 3.14)
+    project(TestGenericIO CXX)
+
+    # Load GenericIO
+    include(FetchContent)
+    FetchContent_Declare(
+        genericio
+        GIT_REPOSITORY https://git.cels.anl.gov/hacc/genericio.git
+        GIT_TAG master
+        GIT_SHALLOW YES
+        GIT_PROGRESS TRUE
+        USES_TERMINAL_DOWNLOAD TRUE   # <---- this is needed only for Ninja
+    )
+    FetchContent_MakeAvailable(genericio)
+
+    # Add an executable
+    add_executable(TestGenericIO test_genericio.cpp)
+
+    # Link to GenericIO
+    target_link_libraries(TestGenericIO PRIVATE genericio::genericio_mpi)
diff --git a/docs/python/readwrite.rst b/docs/python/readwrite.rst
index 2f4e5af..d4176da 100644
--- a/docs/python/readwrite.rst
+++ b/docs/python/readwrite.rst
@@ -123,4 +123,4 @@ References
 
 .. autofunction:: setNaturalDefaultPartition
 
-.. autofunction:: setCollectiveMPIIOThreshold
\ No newline at end of file
+.. autofunction:: setCollectiveMPIIOThreshold
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..346bbad
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,7 @@
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel",
+    "cmake>=3.11",
+]
+build-backend = "setuptools.build_meta"
\ No newline at end of file
diff --git a/setup.py b/setup.py
index ee277fa..c6f3243 100644
--- a/setup.py
+++ b/setup.py
@@ -10,6 +10,10 @@ from setuptools import setup, Extension
 from setuptools.command.build_ext import build_ext
 from distutils.version import LooseVersion
 
+# for more info, check
+# https://github.com/pybind/cmake_example
+# TODO: update the CMakeBuild class
+
 
 class CMakeExtension(Extension):
     def __init__(self, name, sourcedir=""):
@@ -51,7 +55,7 @@ class CMakeBuild(build_ext):
             cmake_args += [
                 "-DCMAKE_LIBRARY_OUTPUT_DIRECTORY_{}={}".format(cfg.upper(), extdir)
             ]
-            if sys.maxsize > 2 ** 32:
+            if sys.maxsize > 2**32:
                 cmake_args += ["-A", "x64"]
             build_args += ["--", "/m"]
         else:
-- 
GitLab