From ca91678af1d6a81116fedf0ae5b14196814cb4b1 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Thu, 9 Jul 2026 17:15:57 +0200 Subject: [PATCH] Document compiler/stdlib exclusions in macro_scope.hpp (#5252) * :memo: Document compiler/stdlib exclusions in macro_scope.hpp Add "Known compiler/stdlib exclusions" subsections to the public documentation for JSON_HAS_FILESYSTEM and JSON_HAS_RANGES, listing the exact compiler/stdlib versions that are silently excluded even when feature-test macros indicate support. Each exclusion references the originating issue. Also add a pointer note in the compiler compatibility section linking to these details. Signed-off-by: Niels Lohmann Co-Authored-By: Claude Code * :green_heart: fix build Signed-off-by: Niels Lohmann --------- Signed-off-by: Niels Lohmann Co-authored-by: Claude Code --- docs/mkdocs/docs/api/macros/json_has_filesystem.md | 14 ++++++++++++++ docs/mkdocs/docs/api/macros/json_has_ranges.md | 12 ++++++++++++ docs/mkdocs/docs/community/quality_assurance.md | 2 ++ 3 files changed, 28 insertions(+) diff --git a/docs/mkdocs/docs/api/macros/json_has_filesystem.md b/docs/mkdocs/docs/api/macros/json_has_filesystem.md index 15c87b636..68eb3089b 100644 --- a/docs/mkdocs/docs/api/macros/json_has_filesystem.md +++ b/docs/mkdocs/docs/api/macros/json_has_filesystem.md @@ -19,6 +19,20 @@ The default value is detected based on the preprocessor macros `#!cpp __cpp_lib_ `#!cpp __cpp_lib_experimental_filesystem`, `#!cpp __has_include()`, or `#!cpp __has_include()`. +!!! info "Known compiler/stdlib exclusions" + + Even when the feature-test macro indicates filesystem support is available, the library disables it on the following broken toolchains: + + - **MinGW + GCC 8** — disabled entirely (broken `std::filesystem` implementation; [MinGW-w64 bug 737](https://sourceforge.net/p/mingw-w64/bugs/737/)) + - **GCC (non-Clang) < 8** — disabled (no filesystem support) + - **Clang < 7** — disabled (no filesystem support) + - **MSVC < 19.14** — disabled (no filesystem support) + - **iOS < 13** — disabled (no filesystem support) + - **macOS < Catalina (10.15)** — disabled (no filesystem support) + + If `JSON_HAS_FILESYSTEM` or `JSON_HAS_EXPERIMENTAL_FILESYSTEM` is `0` despite `__cpp_lib_filesystem` being defined, one + of the exclusions above likely applies to your toolchain. + ## Notes - Note that older compilers or older versions of libstdc++ also require the library `stdc++fs` to be linked to for diff --git a/docs/mkdocs/docs/api/macros/json_has_ranges.md b/docs/mkdocs/docs/api/macros/json_has_ranges.md index 96d51052d..287ba69eb 100644 --- a/docs/mkdocs/docs/api/macros/json_has_ranges.md +++ b/docs/mkdocs/docs/api/macros/json_has_ranges.md @@ -13,6 +13,18 @@ The default value is detected based on the preprocessor macro `#!cpp __cpp_lib_r When the macro is not defined, the library will define it to its default value. +!!! info "Known compiler/stdlib exclusions" + + Even when the feature-test macro `__cpp_lib_ranges` indicates ranges support is available, the library disables it on + the following incomplete or broken toolchains: + + - **GCC 11.1.0** — disabled (the shipped `` header has a syntax error; [issue #4440](https://github.com/nlohmann/json/issues/4440)) + - **libstdc++ < 11** — disabled (incomplete C++20 ranges support; [issue #4440](https://github.com/nlohmann/json/issues/4440)) + - **Clang < 16 with libstdc++** — disabled (incomplete ranges support; [issue #4440](https://github.com/nlohmann/json/issues/4440)) + - **libc++ < 160000** — disabled (incomplete C++20 ranges support; [issue #4440](https://github.com/nlohmann/json/issues/4440)) + + If `JSON_HAS_RANGES` is `0` despite `__cpp_lib_ranges` being defined, one of the exclusions above likely applies to your toolchain. + ## Examples ??? example diff --git a/docs/mkdocs/docs/community/quality_assurance.md b/docs/mkdocs/docs/community/quality_assurance.md index 31990fa83..492fcfe5a 100644 --- a/docs/mkdocs/docs/community/quality_assurance.md +++ b/docs/mkdocs/docs/community/quality_assurance.md @@ -10,6 +10,8 @@ violations will result in a failed build. Any compiler with complete C++11 support can compile the library without warnings. +Note: Some modern features (like C++20 ranges or filesystem support) may be disabled on specific broken or incomplete toolchains even when standard feature-test macros indicate support. See [`JSON_HAS_RANGES`](../api/macros/json_has_ranges.md) and [`JSON_HAS_FILESYSTEM`](../api/macros/json_has_filesystem.md) for details on known exclusions. + - [x] The library is compiled with 50+ different C++ compilers with different operating systems and platforms, including the oldest versions known to compile the library.