Introducing option NB_SUPPRESS_WARNINGS to nanobind_add_module (#868)

* Make public include directories SYSTEM-includes

With this change compile commands generated by cmake for targets consuming nanobind use `-isystem`  instead of `-I` for defining nanobind's header locations, which makes modern analysis tools (e.g. clang analyzer) ignore them.

* Header dirs as SYSTEM shall not be default but an opt-in

Using option `NB_SUPPRESS_WARNINGS` on function `add_nanobind_module` to
enable this behaviour.

* change NB_SUPPRESS_WARNINGS documentation as suggested

cmake/nanobind-config.cmake

@@ -104,6 +104,9 @@ endfunction()
 # ---------------------------------------------------------------------------
 
 function (nanobind_build_library TARGET_NAME)
+  cmake_parse_arguments(PARSE_ARGV 1 ARG
+    "AS_SYSINCLUDE" "" "")
+
   if (TARGET ${TARGET_NAME})
     return()
   endif()
@@ -114,6 +117,10 @@ function (nanobind_build_library TARGET_NAME)
     set (TARGET_TYPE SHARED)
   endif()
 
+  if (${ARG_AS_SYSINCLUDE})
+    set (AS_SYSINCLUDE SYSTEM)
+  endif()
+
   add_library(${TARGET_NAME} ${TARGET_TYPE}
     EXCLUDE_FROM_ALL
     ${NB_DIR}/include/nanobind/make_iterator.h
@@ -238,7 +245,7 @@ function (nanobind_build_library TARGET_NAME)
       ${NB_DIR}/ext/robin_map/include)
   endif()
 
-  target_include_directories(${TARGET_NAME} PUBLIC
+  target_include_directories(${TARGET_NAME} ${AS_SYSINCLUDE} PUBLIC
     ${Python_INCLUDE_DIRS}
     ${NB_DIR}/include)
 
@@ -312,7 +319,7 @@ endfunction()
 
 function(nanobind_add_module name)
   cmake_parse_arguments(PARSE_ARGV 1 ARG
-    "STABLE_ABI;FREE_THREADED;NB_STATIC;NB_SHARED;PROTECT_STACK;LTO;NOMINSIZE;NOSTRIP;MUSL_DYNAMIC_LIBCPP"
+    "STABLE_ABI;FREE_THREADED;NB_STATIC;NB_SHARED;PROTECT_STACK;LTO;NOMINSIZE;NOSTRIP;MUSL_DYNAMIC_LIBCPP;NB_SUPPRESS_WARNINGS"
     "NB_DOMAIN" "")
 
   add_library(${name} MODULE ${ARG_UNPARSED_ARGUMENTS})
@@ -357,7 +364,11 @@ function(nanobind_add_module name)
     set(libname ${libname}-${ARG_NB_DOMAIN})
   endif()
 
-  nanobind_build_library(${libname})
+  if (ARG_NB_SUPPRESS_WARNINGS)
+    set(EXTRA_LIBRARY_PARAMS AS_SYSINCLUDE)
+  endif()
+
+  nanobind_build_library(${libname} ${EXTRA_LIBRARY_PARAMS})
 
   if (ARG_NB_DOMAIN)
     target_compile_definitions(${name} PRIVATE NB_DOMAIN=${ARG_NB_DOMAIN})

docs/api_cmake.rst

@@ -83,6 +83,13 @@ The high-level interface consists of just one CMake command:
         - The opposite of ``NB_STATIC``: compile the core nanobind library
           as a shared library for use in projects that consist of multiple
           extensions.
+      * - ``NB_SUPPRESS_WARNINGS``
+        - Mark the include directories of nanobind and Python as
+          [SYSTEM](https://cmake.org/cmake/help/latest/command/include_directories.html)
+          include directories, which suppresses any potential warning messages
+          originating there. This is mainly of relevance if your project artificially
+          raises the warning level via flags like `-pedantic`, ``-Wcast-qual``,
+          ``-Wsign-conversion``.
       * - ``PROTECT_STACK``
         - Don't remove stack smashing-related protections.
       * - ``LTO``