feat: add target_link_system_libraries

README.md

@@ -6,6 +6,8 @@ _NOTE_: It is planned to transfer this repository to [cpp-best-practices organiz
 
 ## Usage
 
+Here is a full example:
+
 ```cmake
 cmake_minimum_required(VERSION 3.16)
 
@@ -58,7 +60,9 @@ target_link_libraries(myprogram PRIVATE project_options project_warnings) # conn
 
 ```
 
-## `ProjectOptions` parameters
+## `ProjectOptions` function
+
+It accepts the following named flags:
 
 - `WARNINGS_AS_ERRORS`: Treat compiler warnings as errors
 - `ENABLE_CPPCHECK`: Enable static analysis with Cppcheck
@@ -78,15 +82,24 @@ target_link_libraries(myprogram PRIVATE project_options project_warnings) # conn
 - `ENABLE_SANITIZER_UNDEFINED_BEHAVIOR`: Enable undefined behavior sanitizer
 - `ENABLE_SANITIZER_THREAD`: Enable thread sanitizer
 - `ENABLE_SANITIZER_MEMORY`: Enable memory sanitizer
+
+It gets the following named parameters (each accepting multiple values):
+
 - `MSVC_WARNINGS`: Override the defaults for the MSVC warnings
 - `CLANG_WARNINGS`: Override the defaults for the CLANG warnings
 - `GCC_WARNINGS`: Override the defaults for the GCC warnings
 - `CONAN_OPTIONS`: Extra Conan options
 
-## `run_vcpkg` parameters
+## `run_vcpkg` function
 - `VCPKG_DIR`: (Defaults to `~/vcpkg`). You can provide the vcpkg installation directory using this optional parameter. 
 If the directory does not exist, it will automatically install vcpkg in this directory.
 
+
+## `target_link_system_libraries` function
+
+A very useful function that accepts the same arguments as `target_link_libraries` while marking their include directories as "SYSTEM", which suppresses their warnings. This helps in enabling `WARNINGS_AS_ERRORS` for your own source code.
+
+
 ## Using global CMake options (⚠️ **not recommended**)
 
 ⚠️ It is highly recommended to keep the build declarative and reproducible by using the function arguments as explained above.

src/Index.cmake

@@ -8,6 +8,8 @@ include("${ProjectOptions_SRC_DIR}/PreventInSourceBuilds.cmake")
 
 include("${ProjectOptions_SRC_DIR}/Vcpkg.cmake")
 
+include("${ProjectOptions_SRC_DIR}/SystemLink.cmake")
+
 #
 # Params:
 # - WARNINGS_AS_ERRORS: Treat compiler warnings as errors

src/SystemLink.cmake

@@ -0,0 +1,54 @@
+# Include the directories of a library target as system directories (which suppresses their warnings).
+function(
+  target_include_system_library
+  target
+  scope
+  lib)
+  get_target_property(lib_include_dirs ${lib} INTERFACE_INCLUDE_DIRECTORIES)
+  if(lib_include_dirs)
+    if(MSVC)
+      # system includes do not work in MSVC
+      # awaiting https://gitlab.kitware.com/cmake/cmake/-/issues/18272#
+      # awaiting https://gitlab.kitware.com/cmake/cmake/-/issues/17904
+      target_include_directories(${target} ${scope} ${lib_include_dirs})
+    else()
+      target_include_directories(
+        ${target}
+        SYSTEM
+        ${scope}
+        ${lib_include_dirs})
+    endif()
+  else()
+    message(WARNING "${lib} library does not have the INTERFACE_INCLUDE_DIRECTORIES property.")
+  endif()
+endfunction()
+
+# Link a library target as a system library (which suppresses its warnings).
+function(
+  target_link_system_library
+  target
+  scope
+  lib)
+  # Include the directories in the library
+  target_include_system_library(${target} ${scope} ${lib})
+
+  # Link the library
+  target_link_libraries(${target} ${scope} ${lib})
+endfunction()
+
+# Link multiple library targets as system libraries (which suppresses their warnings).
+function(target_link_system_libraries target)
+  set(multiValueArgs INTERFACE PUBLIC PRIVATE)
+  cmake_parse_arguments(
+    ARG
+    ""
+    ""
+    "${multiValueArgs}"
+    ${ARGN})
+
+  foreach(scope IN ITEMS INTERFACE PUBLIC PRIVATE)
+    foreach(lib IN LISTS ARG_${scope})
+      target_link_system_library(${target} ${scope} ${lib})
+    endforeach()
+  endforeach()
+endfunction()

test/CMakeLists.txt

@@ -23,12 +23,12 @@ ProjectOptions(
   # ENABLE_CPPCHECK
   ENABLE_CLANG_TIDY
   # ENABLE_INCLUDE_WHAT_YOU_USE
-  ENABLE_COVERAGE
+  # ENABLE_COVERAGE
   # ENABLE_PCH
   # ENABLE_DOXYGEN
   # ENABLE_IPO
   # ENABLE_USER_LINKER
-  ENABLE_BUILD_WITH_TIME_TRACE
+  # ENABLE_BUILD_WITH_TIME_TRACE
   ENABLE_UNITY
   # ENABLE_SANITIZER_ADDRESS
   # ENABLE_SANITIZER_LEAK
@@ -45,7 +45,7 @@ add_executable(escape escape.cpp)
 target_link_libraries(escape PRIVATE project_options project_warnings)
 
 find_package(fmt REQUIRED)
-target_link_libraries(escape PRIVATE fmt::fmt)
+target_link_system_libraries(escape PRIVATE fmt::fmt)
 
 enable_testing()
 add_test(NAME escape COMMAND escape)