Merge pull request #182 from LLNL/feature/cmake

Support CMake FetchContent

CMakeLists.txt

@@ -1,6 +1,5 @@
 cmake_minimum_required(VERSION 3.10)
-set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/cmake")
-
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
 # -------------------------------------------------------------------------------- #
 # Metall general configuration
@@ -340,7 +339,7 @@ function(add_metall_executable name source)
 
     if (Boost_FOUND)
         add_executable(${name} ${source})
-        target_include_directories(${name} PRIVATE ${CMAKE_SOURCE_DIR}/include)
+        target_include_directories(${name} PRIVATE ${PROJECT_SOURCE_DIR}/include)
         common_setup_for_metall_executable(${name})
 
         set(ADDED_METALL_EXE TRUE PARENT_SCOPE)

README.md

@@ -83,10 +83,10 @@ g++ -std=c++17 your_program.cpp -lstdc++fs -I${BOOST_ROOT}/include -I${METALL_RO
 
 ## Use Metall from CMake Project
 
-Metall provides a CMake Package Configuration File.
-One can easily include an installed Metall package from a CMake project.
+Metall provides CMake Package Configuration File.
+One can easily include Metall package from a CMake project.
 
-Instruction and a simple CMake file example are placed [here](./example/cmake_find_package).
+Instructions and examples are placed [here](./example/cmake).
 
 # Build Example Programs
 

example/cmake/FetchContent/CMakeLists.txt

@@ -0,0 +1,52 @@
+cmake_minimum_required(VERSION 3.14)
+
+project(myproject)
+
+# Metall requires C++ 17
+set(CMAKE_CXX_STANDARD 17)
+
+# Boost header files are required
+find_package(Boost 1.64)
+
+# Download and setup Metall.
+include(FetchContent)
+FetchContent_Declare(
+        metall
+        GIT_REPOSITORY https://github.com/LLNL/metall.git
+        GIT_TAG master
+)
+FetchContent_MakeAvailable(metall)
+
+
+# ---------------------------------------- #
+#  For using Metall CXX API
+# ---------------------------------------- #
+if (Boost_FOUND)
+    find_package(Threads)
+
+    add_executable(cpp_example ../src/cpp_example.cpp)
+
+    # Need Boost header files
+    target_include_directories(cpp_example PRIVATE ${Boost_INCLUDE_DIRS})
+
+    # Link Metall
+    # Although target_link_libraries() is used, no library file (e.g., *.a file) is linked.
+    # Only include path will be set here.
+    target_link_libraries(cpp_example PRIVATE Metall)
+
+    # This is required if one uses GCC
+    target_link_libraries(cpp_example PRIVATE stdc++fs)
+
+    target_link_libraries(cpp_example PRIVATE Threads::Threads)
+endif ()
+
+
+# ---------------------------------------- #
+# For using Metall C API
+# ---------------------------------------- #
+if (Boost_FOUND)
+    add_executable(c_example ../src/c_example.c)
+
+    # Link Metall C library (libmetall_c)
+    target_link_libraries(c_example PRIVATE metall_c)
+endif ()

example/cmake/FetchContent/README.md

@@ -0,0 +1,19 @@
+
+On this page, we describe how to download, install, and link Metall from a CMake project.
+
+To just find/link an already installed Metall package from a CMake project, see another example [here](../find_package).
+
+Here is an example CMake file that downloads, installs, and links Metall package [CMakeLists.txt](CMakeLists.txt).
+
+## Build
+
+Here is how to use the CMake file in this directory.
+
+```bash
+mkdir build
+cd build
+
+cmake ../ -DBOOST_ROOT=/path/to/boost \
+-DBUILD_C=ON # Required to use Metall C API
+make
+```

example/cmake/README.md

@@ -0,0 +1,4 @@
+
+To just **find/link an already installed** Metall package from a CMake project, see [find_package](../find_package).
+
+To **have CMake download, install, and link** Metall, see [FetchContent](../FetchContent).

example/cmake_find_package/CMakeLists.txt → example/cmake/find_package/CMakeLists.txt

@@ -15,27 +15,30 @@ message(STATUS "Metall_FOUND = ${Metall_FOUND}")
 
 # Boost header files are required to use Metall C++ API
 find_package(Boost 1.64)
+find_package(Threads)
 
-if (Boost_FOUND)
-    add_executable(cpp_example cpp_example.cpp)
+if (Boost_FOUND AND Threads_FOUND)
+    add_executable(cpp_example ../src/cpp_example.cpp)
 
     # Need Boost header files
     target_include_directories(cpp_example PRIVATE ${Boost_INCLUDE_DIRS})
 
     # Link Metall
     # Although target_link_libraries() is used, no library file (e.g., *.a file) is linked.
     # Only include path will be set here.
-    target_link_libraries(cpp_example Metall::Metall)
+    target_link_libraries(cpp_example PRIVATE Metall::Metall)
 
     # This is required if one uses GCC
-    target_link_libraries(cpp_example stdc++fs)
+    target_link_libraries(cpp_example PRIVATE stdc++fs)
+
+    target_link_libraries(cpp_example PRIVATE Threads::Threads)
 endif ()
 
 
 # ---------------------------------------- #
 # For using Metall C API
 # ---------------------------------------- #
-add_executable(c_example c_example.c)
+add_executable(c_example ../src/c_example.c)
 
 # Link Metall C library (libmetall_c)
-target_link_libraries(c_example Metall::metall_c)
+target_link_libraries(c_example PRIVATE Metall::metall_c)

example/cmake/find_package/README.md

@@ -0,0 +1,55 @@
+# Find Metall from CMake Project
+
+On this page, we describe how to **find/link an already installed** Metall package from a CMake project.
+
+To have CMake download, install, and link Metall, see another example [here](../FetchContent).
+
+Here is an example CMake file that finds an already installed Metall package [CMakeLists.txt](CMakeLists.txt).
+
+## 0. (pre-step) Install Metall
+
+Here is how to build example programs.
+
+### 0-1. Install Metall Manually
+
+To install Metall at `"/path/to/install"`, for example:
+```bash
+cd metall
+mkdir build
+cd build
+
+cmake ../ -DCMAKE_INSTALL_PREFIX="/path/to/install"
+# (option) add the following options to build the Metall C API library
+-DBOOST_ROOT=/path/to/boost -DBUILD_C=ON 
+
+make && make install
+```
+
+
+### 0-2. Install Metall using Spack
+
+Alternatively, one can install Metall using Spack.
+
+```bash
+# Install Metall using Spack
+# Boost is also install
+spack install metall
+```
+
+
+## 1. Build
+
+Here is how to use the CMake file in this directory.
+
+```bash
+mkdir build
+cd build
+
+export CMAKE_PREFIX_PATH="/path/to/install"
+# Or
+spack load metall # Spack exports CMAKE_PREFIX_PATH
+
+cmake ../ \
+-DBOOST_ROOT=/path/to/boost # Required to build programs that uses Metall C++ API.
+make
+```

src/CMakeLists.txt

@@ -17,7 +17,7 @@ if (BUILD_C)
     add_library(${PROJECT_NAME}::metall_c ALIAS metall_c)
 
     target_include_directories(metall_c PUBLIC
-            $<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include>
+            $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
             $<INSTALL_INTERFACE:include>)
 
     common_setup_for_metall_executable(metall_c)