CMake cleanup (#1060)

- Move all install logic inside gsl_install.cmake
  - This makes reading the logic easier, and avoids the enable language
    issue with `GNUInstallDirs` by having it included after the project
    call
- Have all functions inside gsl_functions.cmake
- Use CMake idiom PROJECT_IS_TOP_LEVEL
- Update README.md

CMakeLists.txt

@@ -1,16 +1,12 @@
 cmake_minimum_required(VERSION 3.1.3...3.16)
-
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/")
-include(guidelineSupportLibrary)
+include(gsl_functions)
 
 project(GSL
     VERSION 4.0.0
     LANGUAGES CXX
 )
 
-# Must include after the project call due to GNUInstallDirs requiring a language be enabled (IE. CXX)
-include(GNUInstallDirs)
-
 # Creates a library GSL which is an interface (header files only)
 add_library(GSL INTERFACE)
 
@@ -22,20 +18,16 @@ add_library(GSL INTERFACE)
 # whether GSL was added via `add_subdirectory` or `find_package`
 add_library(Microsoft.GSL::GSL ALIAS GSL)
 
-# Determine whether this is a standalone project or included by other projects
+# https://cmake.org/cmake/help/latest/variable/PROJECT_IS_TOP_LEVEL.html
-set(GSL_STANDALONE_PROJECT OFF)
+string(COMPARE EQUAL ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_SOURCE_DIR} PROJECT_IS_TOP_LEVEL)
-if (CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
-    set(GSL_STANDALONE_PROJECT ON)
-endif()
 
-### Project options
+option(GSL_INSTALL "Generate and install GSL target" ${PROJECT_IS_TOP_LEVEL})
-option(GSL_INSTALL "Generate and install GSL target" ${GSL_STANDALONE_PROJECT})
+option(GSL_TEST "Build and perform GSL tests" ${PROJECT_IS_TOP_LEVEL})
-option(GSL_TEST "Build and perform GSL tests" ${GSL_STANDALONE_PROJECT})
 
 # This GSL implementation generally assumes a platform that implements C++14 support.
 set(gsl_min_cxx_standard "14")
 
-if (GSL_STANDALONE_PROJECT)
+if (PROJECT_IS_TOP_LEVEL)
     gsl_set_default_cxx_standard(${gsl_min_cxx_standard})
 else()
     gsl_client_set_cxx_standard(${gsl_min_cxx_standard})
@@ -47,12 +39,8 @@ add_subdirectory(include)
 # Add natvis file
 gsl_add_native_visualizer_support()
 
-# Add packaging support
-gsl_create_packaging_file()
-
 if (GSL_INSTALL)
-    # Setup install/export logic
+    include(gsl_install)
-    gsl_install_logic()
 endif()
 
 if (GSL_TEST)

README.md

@@ -179,43 +179,42 @@ Include the library using:
 
 ## Usage in CMake
 
-The library provides a Config file for CMake, once installed it can be found via
+The library provides a Config file for CMake, once installed it can be found via `find_package`.
-
-    find_package(Microsoft.GSL CONFIG)
 
 Which, when successful, will add library target called `Microsoft.GSL::GSL` which you can use via the usual
 `target_link_libraries` mechanism.
 
+```cmake
+find_package(Microsoft.GSL CONFIG REQUIRED)
+
+target_link_libraries(foobar PRIVATE Microsoft.GSL::GSL)
+```
+
 ### FetchContent
 
-If you are using cmake version 3.11+ you can use the offical FetchContent module.
+If you are using CMake version 3.11+ you can use the offical [FetchContent module](https://cmake.org/cmake/help/latest/module/FetchContent.html).
 This allows you to easily incorporate GSL into your project.
 
 ```cmake
-# NOTE: This example uses cmake version 3.14 (FetchContent_MakeAvailable).
+# NOTE: This example uses CMake version 3.14 (FetchContent_MakeAvailable).
 # Since it streamlines the FetchContent process
 cmake_minimum_required(VERSION 3.14)
 
 include(FetchContent)
 
-# In this example we are picking a specific tag.
-# You can also pick a specific commit, if you need to.
 FetchContent_Declare(GSL
     GIT_REPOSITORY "https://github.com/microsoft/GSL"
-    GIT_TAG "v3.1.0"
+    GIT_TAG "v4.0.0"
+    GIT_SHALLOW ON
 )
 
 FetchContent_MakeAvailable(GSL)
 
-# Now you can link against the GSL interface library
+target_link_libraries(foobar PRIVATE Microsoft.GSL::GSL)
-add_executable(foobar)
-
-# Link against the interface library (IE header only library)
-target_link_libraries(foobar PRIVATE GSL)
 ```
 
 ## Debugging visualization support
 For Visual Studio users, the file [GSL.natvis](./GSL.natvis) in the root directory of the repository can be added to your project if you would like more helpful visualization of GSL types in the Visual Studio debugger than would be offered by default.
 
-If you are using cmake this will be done automatically for you.
+If you are using CMake this will be done automatically for you.
 See 'GSL_VS_ADD_NATIVE_VISUALIZERS'

cmake/gsl_functions.cmake

@@ -4,32 +4,19 @@
 # for multiple versions of cmake.
 #
 # Any functions/macros should have a gsl_* prefix to avoid problems
-if (CMAKE_VERSION VERSION_GREATER 3.10 OR CMAKE_VERSION VERSION_EQUAL 3.10)
-    include_guard()
-else()
-    if (DEFINED guideline_support_library_include_guard)
-        return()
-    endif()
-    set(guideline_support_library_include_guard ON)
-endif()
-
-# Necessary for 'write_basic_package_version_file'
-include(CMakePackageConfigHelpers)
 
 function(gsl_set_default_cxx_standard min_cxx_standard)
     set(GSL_CXX_STANDARD "${min_cxx_standard}" CACHE STRING "Use c++ standard")
 
-    set(GSL_CXX_STD "cxx_std_${GSL_CXX_STANDARD}")
-
-    if (MSVC)
-        set(GSL_CXX_STD_OPT "-std:c++${GSL_CXX_STANDARD}")
-    else()
-        set(GSL_CXX_STD_OPT "-std=c++${GSL_CXX_STANDARD}")
-    endif()
-
     # when minimum version required is 3.8.0 remove if below
     # both branches do exactly the same thing
     if (CMAKE_VERSION VERSION_LESS 3.7.9)
+        if (MSVC)
+            set(GSL_CXX_STD_OPT "-std:c++${GSL_CXX_STANDARD}")
+        else()
+            set(GSL_CXX_STD_OPT "-std=c++${GSL_CXX_STANDARD}")
+        endif()
+
         include(CheckCXXCompilerFlag)
         CHECK_CXX_COMPILER_FLAG("${GSL_CXX_STD_OPT}" COMPILER_SUPPORTS_CXX_STANDARD)
 
@@ -39,7 +26,8 @@ function(gsl_set_default_cxx_standard min_cxx_standard)
             message(FATAL_ERROR "The compiler ${CMAKE_CXX_COMPILER} has no c++${GSL_CXX_STANDARD} support. Please use a different C++ compiler.")
         endif()
     else()
-        target_compile_features(GSL INTERFACE "${GSL_CXX_STD}")
+        # Compiler must support at least this standard
+        target_compile_features(GSL INTERFACE "cxx_std_${GSL_CXX_STANDARD}")
         # on *nix systems force the use of -std=c++XX instead of -std=gnu++XX (default)
         set(CMAKE_CXX_EXTENSIONS OFF)
     endif()
@@ -82,35 +70,3 @@ function(gsl_add_native_visualizer_support)
         endif()
     endif()
 endfunction()
-
-function(gsl_install_logic)
-    install(TARGETS GSL EXPORT Microsoft.GSLConfig)
-    install(
-        DIRECTORY include/gsl
-        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
-    )
-    # Make library importable by other projects
-    install(EXPORT Microsoft.GSLConfig NAMESPACE Microsoft.GSL:: DESTINATION ${CMAKE_INSTALL_DATADIR}/cmake/Microsoft.GSL)
-    export(TARGETS GSL NAMESPACE Microsoft.GSL:: FILE Microsoft.GSLConfig.cmake)
-
-    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/Microsoft.GSLConfigVersion.cmake DESTINATION ${CMAKE_INSTALL_DATADIR}/cmake/Microsoft.GSL)
-endfunction()
-
-# Add find_package() versioning support. The version for
-# generated Microsoft.GSLConfigVersion.cmake will be used from
-# last project() command. The version's compatibility is set between all
-# minor versions (as it was in prev. GSL releases).
-function(gsl_create_packaging_file)
-    if(${CMAKE_VERSION} VERSION_LESS "3.14.0")
-        write_basic_package_version_file(
-            ${CMAKE_CURRENT_BINARY_DIR}/Microsoft.GSLConfigVersion.cmake
-            COMPATIBILITY SameMajorVersion
-        )
-    else()
-        write_basic_package_version_file(
-            ${CMAKE_CURRENT_BINARY_DIR}/Microsoft.GSLConfigVersion.cmake
-            COMPATIBILITY SameMajorVersion
-            ARCH_INDEPENDENT
-        )
-    endif()
-endfunction()

cmake/gsl_install.cmake

@@ -0,0 +1,26 @@
+include(GNUInstallDirs)
+include(CMakePackageConfigHelpers)
+
+# Install header files
+install(DIRECTORY "${PROJECT_SOURCE_DIR}/include/gsl" DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+
+set(export_name "Microsoft.GSLConfig")
+set(namespace "Microsoft.GSL::")
+set(cmake_files_install_dir ${CMAKE_INSTALL_DATADIR}/cmake/Microsoft.GSL)
+
+# Add find_package() support
+target_include_directories(GSL INTERFACE $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
+install(TARGETS GSL EXPORT ${export_name})
+install(EXPORT ${export_name} NAMESPACE ${namespace} DESTINATION ${cmake_files_install_dir})
+export(TARGETS GSL NAMESPACE ${namespace} FILE ${export_name}.cmake)
+
+set(gls_config_version "${CMAKE_CURRENT_BINARY_DIR}/Microsoft.GSLConfigVersion.cmake")
+
+# Add find_package() versioning support
+if(${CMAKE_VERSION} VERSION_LESS "3.14.0")
+    write_basic_package_version_file(${gls_config_version} COMPATIBILITY SameMajorVersion)
+else()
+    write_basic_package_version_file(${gls_config_version} COMPATIBILITY SameMajorVersion ARCH_INDEPENDENT)
+endif()
+
+install(FILES ${gls_config_version} DESTINATION ${cmake_files_install_dir})

include/CMakeLists.txt

@@ -1,4 +1,3 @@
-
 # Add include folders to the library and targets that consume it
 # the SYSTEM keyword suppresses warnings for users of the library
 #
@@ -7,14 +6,8 @@
 #
 # IE:
 #   #include <gsl/gsl>
-if(GSL_STANDALONE_PROJECT)
+if(PROJECT_IS_TOP_LEVEL)
-    target_include_directories(GSL INTERFACE
+    target_include_directories(GSL INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>)
-        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
-        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
-    )
 else()
-    target_include_directories(GSL SYSTEM INTERFACE
+    target_include_directories(GSL SYSTEM INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>)
-        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
-        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
-    )
 endif()