Merge pull request #2074 from ArthurSonzogni/develop

Add CMake fetchcontent documentation and tests

README.md

@@ -133,6 +133,33 @@ add_library(foo ...)
 target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
 ```
 
+##### Embedded (FetchContent)
+
+Since CMake v3.11,
+[FetchContent](https://cmake.org/cmake/help/v3.11/module/FetchContent.html) can
+be used to automatically download the repository as a dependency at configure type.
+
+Example:
+```cmake
+include(FetchContent)
+
+FetchContent_Declare(json
+  GIT_REPOSITORY https://github.com/nlohmann/json
+  GIT_TAG v3.7.3)
+
+FetchContent_GetProperties(json)
+if(NOT json_POPULATED)
+  FetchContent_Populate(json)
+  add_subdirectory(${json_SOURCE_DIR} ${json_BINARY_DIR} EXCLUDE_FROM_ALL)
+endif()
+
+target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
+
+**Note**: The repository https://github.com/nlohmann/json download size is huge.
+It contains all the dataset used for the benchmarks. You might want to depend on
+a smaller repository. For instance, you might want to replace the URL above by
+https://github.com/ArthurSonzogni/nlohmann_json_cmake_fetchcontent
+
 #### Supporting Both
 
 To allow your project to support either an externally supplied or an embedded JSON library, you can use a pattern akin to the following:

test/CMakeLists.txt

@@ -189,3 +189,4 @@ endforeach()
 add_subdirectory(cmake_import)
 add_subdirectory(cmake_import_minver)
 add_subdirectory(cmake_add_subdirectory)
+add_subdirectory(cmake_fetch_content)

test/cmake_fetch_content/CMakeLists.txt

+if (${CMAKE_VERSION} VERSION_GREATER "3.11.0")
+  add_test(NAME cmake_fetch_content_configure
+    COMMAND ${CMAKE_COMMAND}
+    -G "${CMAKE_GENERATOR}"
+    -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
+    -Dnlohmann_json_source=${PROJECT_SOURCE_DIR}
+    ${CMAKE_CURRENT_SOURCE_DIR}/project
+  )
+  add_test(NAME cmake_fetch_content_build
+    COMMAND ${CMAKE_COMMAND} --build .
+  )
+  set_tests_properties(cmake_fetch_content_configure PROPERTIES
+    FIXTURES_SETUP cmake_fetch_content
+  )
+  set_tests_properties(cmake_fetch_content_build PROPERTIES
+    FIXTURES_REQUIRED cmake_fetch_content
+  )
+endif()

test/cmake_fetch_content/project/CMakeLists.txt

+cmake_minimum_required(VERSION 3.11)
+
+project(DummyImport CXX)
+
+include(FetchContent)
+
+FetchContent_Declare(json
+  GIT_REPOSITORY ${CMAKE_CURRENT_SOURCE_DIR}/../../..
+  GIT_TAG HEAD)
+
+FetchContent_GetProperties(json)
+if(NOT json_POPULATED)
+  FetchContent_Populate(json)
+  add_subdirectory(${json_SOURCE_DIR} ${json_BINARY_DIR} EXCLUDE_FROM_ALL)
+endif()
+
+add_executable(with_namespace_target main.cpp)
+target_link_libraries(with_namespace_target nlohmann_json::nlohmann_json)
+
+add_executable(without_namespace_target main.cpp)
+target_link_libraries(without_namespace_target nlohmann_json)

test/cmake_fetch_content/project/main.cpp

+#include <nlohmann/json.hpp>
+
+int main(int argc, char **argv)
+{
+    nlohmann::json j;
+
+    return 0;
+}