Migrate REUSE metadata from deprecated .reuse/dep5 to REUSE.toml

reuse==6.2.0 (pinned in cmake/requirements/requirements-reuse.txt) warns
"'.reuse/dep5' is deprecated. You are recommended to instead use
REUSE.toml. Use `reuse convert-dep5` to convert." on every
ci_reuse_compliance run. A later reuse release that drops DEP5 support
would break that CI job outright.

Generate REUSE.toml from the 9 Files: stanzas with `reuse convert-dep5`
and remove .reuse/dep5. `reuse lint` still reports full compliance with
spec 3.3 (1268/1268 files with copyright and license information,
unchanged), and `reuse spdx` produces the same per-file copyright and
license entries as before the conversion.

Update the three places that referenced the old file: FILES.md now
documents REUSE.toml with a spec 3.3 link, README.md's REUSE section
names REUSE.toml, and the comment in gen_hedley_undef_check.cmake now
refers to REUSE.toml's blanket path = "**" rule.

Overlaps #4663, which adds an entry to .reuse/dep5; that PR will need to
move its entry into REUSE.toml when rebased on this.

#5716 item 4

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

.github/workflows/macos.yml

@@ -71,3 +71,38 @@ jobs:
         run: cmake --build build --parallel 10
       - name: Test
         run: cd build ; ctest -j 10 --output-on-failure
+
+  swiftpm:
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Check that Package.swift resolves without a deprecation warning
+        run: swift package dump-package
+      - name: Build the SwiftPM documentation example against this checkout
+        run: |
+          mkdir -p /tmp/json-swiftpm-consumer/Sources/MyLibrary
+          cp docs/mkdocs/docs/integration/swift/example.cpp /tmp/json-swiftpm-consumer/Sources/MyLibrary/example.cpp
+          cat > /tmp/json-swiftpm-consumer/Package.swift << EOF
+          // swift-tools-version: 5.9
+          import PackageDescription
+
+          let package = Package(
+              name: "MyPackage",
+              dependencies: [
+                  .package(path: "${{ github.workspace }}")
+              ],
+              targets: [
+                  .target(
+                      name: "MyLibrary",
+                      dependencies: [
+                          .product(name: "json", package: "json")
+                      ],
+                      publicHeadersPath: "."
+                  )
+              ]
+          )
+          EOF
+          cd /tmp/json-swiftpm-consumer
+          swift build

.github/workflows/publish_documentation.yml

@@ -7,16 +7,6 @@ on:
       - develop
     paths:
       - docs/mkdocs/**
-      # the site also embeds these files via pymdownx.snippets
-      # (mkdocs.yml sets restrict_base_path: false for this)
-      - .clang-tidy
-      - .github/CODE_OF_CONDUCT.md
-      - .github/CONTRIBUTING.md
-      - .github/SECURITY.md
-      - cmake/clang_flags.cmake
-      - cmake/gcc_flags.cmake
-      - tests/fmt_formatter/project/main.cpp
-      - tools/astyle/.astylerc
   workflow_dispatch:
 
 # we don't want to have concurrent jobs, and we don't want to cancel running jobs to avoid broken publications
@@ -33,7 +23,7 @@ jobs:
       contents: write
 
     if: github.repository == 'nlohmann/json'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - name: Harden Runner
         uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
@@ -41,8 +31,6 @@ jobs:
           egress-policy: audit
 
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
 
       - name: Install virtual environment
         run: make install_venv -C docs/mkdocs

.github/workflows/ubuntu.yml

@@ -346,8 +346,6 @@ jobs:
     container: intel/oneapi-hpckit:latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
       - name: Get latest CMake and ninja
         uses: lukka/get-cmake@fffaaafeea488556c2c12dad60690008bc1caacb # v4.4.2
       - name: Run CMake
@@ -360,8 +358,6 @@ jobs:
     container: nvcr.io/nvidia/nvhpc:25.5-devel-cuda12.9-ubuntu22.04
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
       - name: Get latest CMake and ninja
         uses: lukka/get-cmake@fffaaafeea488556c2c12dad60690008bc1caacb # v4.4.2
       - name: Run CMake

.github/workflows/windows.yml

@@ -87,8 +87,6 @@ jobs:
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
       - name: Get latest CMake and ninja
         uses: lukka/get-cmake@fffaaafeea488556c2c12dad60690008bc1caacb # v4.4.2
       - name: Set extra CXX_FLAGS for latest std_version
@@ -125,8 +123,6 @@ jobs:
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
       - name: Run CMake (Release)
         run: cmake -S . -B build -G "Visual Studio 18 2026" -A ARM64 -DJSON_BuildTests=On -DCMAKE_CXX_FLAGS="/W4 /WX"
         if: matrix.build_type == 'Release'

.reuse/dep5

@@ -1,40 +0,0 @@
-Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
-Upstream-Name: json
-Upstream-Contact: Niels Lohmann <mail@nlohmann.me>
-Source: https://github.com/nlohmann/json
-
-Files: *
-Copyright: 2013-2026 Niels Lohmann <https://nlohmann.me>
-License: MIT
-
-Files: include/nlohmann/thirdparty/hedley.hpp
-Copyright: 2016-2021 Evan Nemerson <evan@nemerson.com>
-License: CC0
-
-Files: include/nlohmann/detail/meta/cpp_future.hpp
-Copyright: 2013-2026 Niels Lohmann <https://nlohmann.me> and 2018 The Abseil Authors
-License: MIT AND Apache-2.0
-
-Files: tests/thirdparty/doctest/*
-Copyright: 2016-2023 Viktor Kirilov
-License: MIT
-
-Files: tests/thirdparty/fifo_map/*
-Copyright: 2015-2017 Niels Lohmann
-License: MIT
-
-Files: tests/thirdparty/Fuzzer/*
-Copyright: 2003-2022 LLVM Project.
-License: Apache-2.0
-
-Files: tests/thirdparty/imapdl/*
-Copyright: 2017 Georg Sauthoff <mail@gms.tf>
-License: GPL-3.0-only
-
-Files: tools/amalgamate/*
-Copyright: 2012 Erik Edlund <erik.edlund@32767.se>
-License: BSD-3-Clause
-
-Files: tools/gdb_pretty_printer/*
-Copyright: 2020 Hannes Domani <https://github.com/ssbssa>
-License: MIT

BUILD.bazel

@@ -77,6 +77,7 @@ cc_library(
     name = "singleheader-json",
     hdrs = [
         "single_include/nlohmann/json.hpp",
+        "single_include/nlohmann/json_fwd.hpp",
     ],
     includes = ["single_include"],
     visibility = ["//visibility:public"],

CITATION.cff

@@ -10,5 +10,5 @@ title: "JSON for Modern C++"
 version: 3.12.0
 date-released: 2025-04-07
 license: MIT
-repository-code: "https://github.com/nlohmann"
+repository-code: "https://github.com/nlohmann/json"
 url: https://json.nlohmann.me

CMakeLists.txt

@@ -42,8 +42,11 @@ endif()
 ## OPTIONS
 ##
 
+# Build the tests by default only for the main project and only if the tests
+# directory exists (the release archive json.tar.xz does not contain it).
 # VERSION_GREATER_EQUAL is not available in older CMake (< 3.7)
-if(${MAIN_PROJECT} AND (${CMAKE_VERSION} VERSION_EQUAL 3.13 OR ${CMAKE_VERSION} VERSION_GREATER 3.13))
+if(${MAIN_PROJECT} AND (${CMAKE_VERSION} VERSION_EQUAL 3.13 OR ${CMAKE_VERSION} VERSION_GREATER 3.13)
+   AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/tests/CMakeLists.txt")
     set(JSON_BuildTests_INIT ON)
 else()
     set(JSON_BuildTests_INIT OFF)

FILES.md

@@ -207,19 +207,19 @@ Further documentation:
 
 ## REUSE
 
-### `.reuse/dep5`
+### `REUSE.toml`
 
 The file defines the licenses of certain third-party components in the repository. The root `Makefile` contains a target `reuse` that checks for compliance.
 
 Further documentation:
 
-- [DEP5](https://reuse.software/spec-3.2/#dep5-deprecated)
+- [REUSE.toml](https://reuse.software/spec-3.3/#reusetoml)
 - [reuse command-line tool](https://pypi.org/project/reuse/)
 - [documentation of linting](https://reuse.readthedocs.io/en/stable/man/reuse-lint.html)
 - [REUSE](http://reuse.software)
 
 > [!IMPORTANT]
-> The filename `.reuse/dep5` is predetermined by REUSE. Alternatively, a `REUSE.toml` file can be used.
+> The filename `REUSE.toml` is predetermined by REUSE. Alternatively, a `.reuse/dep5` file (deprecated) can be used.
 
 ### `.reuse/templates`
 

Makefile

@@ -7,6 +7,9 @@
 # find GNU sed to use `-i` parameter
 SED:=$(shell command -v gsed || which sed)
 
+# find GNU tar to use `--sort` and `--pax-option` parameters
+TAR:=$(shell command -v gtar || which tar)
+
 
 ##########################################################################
 # source files
@@ -215,8 +218,8 @@ ChangeLog.md:
 # archive is created according to the advices of <https://reproducible-builds.org/docs/archives/>.
 json.tar.xz:
 	mkdir json
-	rsync -R $(shell find LICENSE.MIT nlohmann_json.natvis CMakeLists.txt cmake/*.in include single_include -type f) json
-	gtar --sort=name --mtime="@$(shell git log -1 --pretty=%ct)" --owner=0 --group=0 --numeric-owner --pax-option=exthdr.name=%d/PaxHeaders/%f,delete=atime,delete=ctime --create --file - json | xz --compress -9e --threads=2 - > json.tar.xz
+	rsync -R $(shell find LICENSE.MIT nlohmann_json.natvis CMakeLists.txt cmake/*.in include single_include src/modules -type f) json
+	$(TAR) --sort=name --mtime="@$(shell git log -1 --pretty=%ct)" --owner=0 --group=0 --numeric-owner --pax-option=exthdr.name=%d/PaxHeaders/%f,delete=atime,delete=ctime --create --file - json | xz --compress -9e --threads=2 - > json.tar.xz
 	rm -fr json
 
 # We use `-X` to make the resulting ZIP file reproducible, see

Package.swift

@@ -6,7 +6,7 @@ import PackageDescription
 let package = Package(
     name: "nlohmann-json",
      platforms: [
-        .iOS(.v12), .macOS(.v10_13), .tvOS(.v12), .watchOS(.v4), .visionOS(.v1)
+        .iOS(.v12), .macOS(.v10_13), .tvOS(.v12), .watchOS(.v9), .visionOS(.v1)
     ],
     products: [
         .library(name: "json", targets: ["json"])

README.md

@@ -1204,15 +1204,18 @@ language bindings, format converters, and the like. See the curated [Ecosystem](
 
 Though it's 2026 already, the support for C++11 is still a bit sparse. Currently, the following compilers are known to work:
 
-- GCC 4.8 - 14.2 (and possibly later)
-- Clang 3.4 - 21.0 (and possibly later)
-- Apple Clang 9.1 - 16.0 (and possibly later)
-- Intel C++ Compiler 17.0.2 (and possibly later)
-- Nvidia CUDA Compiler 11.0.221 (and possibly later)
-- Microsoft Visual C++ 2015 / Build Tools 14.0.25123.0 (and possibly later)
-- Microsoft Visual C++ 2017 / Build Tools 15.5.180.51428 (and possibly later)
-- Microsoft Visual C++ 2019 / Build Tools 16.3.1+1def00d3d (and possibly later)
-- Microsoft Visual C++ 2022 / Build Tools 19.30.30709.0 (and possibly later)
+- GCC 4.8 - 16.2 (and possibly later)
+- Clang 3.4 - 22.1 (and possibly later)
+- Apple Clang 15.0 - 21.0 (and possibly later)
+- Intel C++ Compiler Classic (icpc) 2021.10
+- Intel oneAPI DPC++/C++ Compiler (icpx) 2025.3 (and possibly later)
+- NVIDIA CUDA Compiler (nvcc) 11.8 - 12.6 (and possibly later)
+- NVIDIA HPC SDK C++ Compiler (nvc++) 25.5 (and possibly later)
+- Microsoft Visual C++ 2015 / MSVC 19.0 (and possibly later)
+- Microsoft Visual C++ 2017 / MSVC 19.16 (and possibly later)
+- Microsoft Visual C++ 2019 / MSVC 19.29 (and possibly later)
+- Microsoft Visual C++ 2022 / MSVC 19.44 (and possibly later)
+- Microsoft Visual C++ 2026 / MSVC 19.51 (and possibly later)
 
 I would be happy to learn about other compilers/versions.
 
@@ -1402,7 +1405,7 @@ The library is compliant to version 3.3 of the [**REUSE specification**](https:/
 
 - Every source file contains an SPDX copyright header.
 - The full text of all licenses used in the repository can be found in the `LICENSES` folder.
-- File `.reuse/dep5` contains an overview of all files' copyrights and licenses.
+- File `REUSE.toml` contains an overview of all files' copyrights and licenses.
 - Run `pipx run reuse lint` to verify the project's REUSE compliance and `pipx run reuse spdx` to generate a SPDX SBOM.
 
 ## Contact

REUSE.toml

@@ -0,0 +1,58 @@
+version = 1
+SPDX-PackageName = "json"
+SPDX-PackageSupplier = "Niels Lohmann <mail@nlohmann.me>"
+SPDX-PackageDownloadLocation = "https://github.com/nlohmann/json"
+
+[[annotations]]
+path = "**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2013-2026 Niels Lohmann <https://nlohmann.me>"
+SPDX-License-Identifier = "MIT"
+
+[[annotations]]
+path = "include/nlohmann/thirdparty/hedley.hpp"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2016-2021 Evan Nemerson <evan@nemerson.com>"
+SPDX-License-Identifier = "CC0"
+
+[[annotations]]
+path = "include/nlohmann/detail/meta/cpp_future.hpp"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2013-2026 Niels Lohmann <https://nlohmann.me> and 2018 The Abseil Authors"
+SPDX-License-Identifier = "MIT AND Apache-2.0"
+
+[[annotations]]
+path = "tests/thirdparty/doctest/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2016-2023 Viktor Kirilov"
+SPDX-License-Identifier = "MIT"
+
+[[annotations]]
+path = "tests/thirdparty/fifo_map/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2015-2017 Niels Lohmann"
+SPDX-License-Identifier = "MIT"
+
+[[annotations]]
+path = "tests/thirdparty/Fuzzer/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2003-2022 LLVM Project."
+SPDX-License-Identifier = "Apache-2.0"
+
+[[annotations]]
+path = "tests/thirdparty/imapdl/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2017 Georg Sauthoff <mail@gms.tf>"
+SPDX-License-Identifier = "GPL-3.0-only"
+
+[[annotations]]
+path = "tools/amalgamate/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2012 Erik Edlund <erik.edlund@32767.se>"
+SPDX-License-Identifier = "BSD-3-Clause"
+
+[[annotations]]
+path = "tools/gdb_pretty_printer/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2020 Hannes Domani <https://github.com/ssbssa>"
+SPDX-License-Identifier = "MIT"

cmake/scripts/gen_bazel_build_file.cmake

@@ -48,6 +48,7 @@ cc_library(
     name = "singleheader-json",
     hdrs = [
         "single_include/nlohmann/json.hpp",
+        "single_include/nlohmann/json_fwd.hpp",
     ],
     includes = ["single_include"],
     visibility = ["//visibility:public"],

cmake/scripts/gen_hedley_undef_check.cmake

@@ -64,7 +64,7 @@ if(MODE STREQUAL "undef")
     # recipe is self-contained and its output is byte-stable across reruns.
     # The embedded SPDX tags below are part of the *generated* file's
     # content, not a REUSE header for this .cmake script itself (which is
-    # already covered by the blanket "Files: *" rule in .reuse/dep5) -- keep
+    # already covered by the blanket path = "**" rule in REUSE.toml) -- keep
     # them wrapped in REUSE-IgnoreStart/End so `reuse lint` does not try to
     # parse "MIT\n")" as this file's own SPDX-License-Identifier value.
     # REUSE-IgnoreStart

docs/Makefile

@@ -11,31 +11,20 @@ EXAMPLES = $(wildcard mkdocs/docs/examples/*.cpp)
 
 cxx_standard = $(lastword c++11 $(filter c++%, $(subst ., ,$1)))
 
-# common compile flags for the stand-alone example files
-EXAMPLE_CPPFLAGS = -I $(SRCDIR) -DJSON_USE_GLOBAL_UDLS=0
-EXAMPLE_WARNFLAGS = -Werror=deprecated-declarations
-
-# examples that document deprecated API and are allowed to use it
-DEPRECATED_EXAMPLES = $(addprefix mkdocs/docs/examples/, \
-	json_pointer__operator__equal_stringtype \
-	json_pointer__operator__notequal_stringtype \
-	json_pointer__operator_string_t)
-$(DEPRECATED_EXAMPLES:=.output) $(DEPRECATED_EXAMPLES:=.test): EXAMPLE_WARNFLAGS = -Wno-deprecated-declarations
-
 # create output from a stand-alone example file
 %.output: %.cpp
-	@echo "standard $(call cxx_standard,$(<:.cpp=))"
+	@echo "standard $(call cxx_standard $(<:.cpp=))"
 	$(MAKE) $(<:.cpp=) \
-		CPPFLAGS="$(EXAMPLE_CPPFLAGS)" \
-		CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) $(EXAMPLE_WARNFLAGS)"
+		CPPFLAGS="-I $(SRCDIR) -DJSON_USE_GLOBAL_UDLS=0" \
+		CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) -Wno-deprecated-declarations"
 	./$(<:.cpp=) > $@
 	rm $(<:.cpp=)
 
 # compare created output with current output of the example files
 %.test: %.cpp
 	$(MAKE) $(<:.cpp=) \
-		CPPFLAGS="$(EXAMPLE_CPPFLAGS)" \
-		CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) $(EXAMPLE_WARNFLAGS)"
+		CPPFLAGS="-I $(SRCDIR) -DJSON_USE_GLOBAL_UDLS=0" \
+		CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) -Wno-deprecated-declarations"
 	./$(<:.cpp=) > $@
 	diff $@ $(<:.cpp=.output)
 	rm $(<:.cpp=) $@

docs/docset/Info.plist

@@ -13,7 +13,7 @@
     <key>dashIndexFilePath</key>
     <string>index.html</string>
     <key>DashDocSetFallbackURL</key>
-    <string>https://json.nlohmann.me/</string>
+    <string>https://nlohmann.github.io/json/</string>
     <key>isJavaScriptEnabled</key>
     <true/>
 </dict>

docs/docset/Makefile

@@ -52,25 +52,35 @@ install_docset_zeal: JSON_for_Modern_C++.docset
 	mkdir -p $$docset_root; \
 	cp -r JSON_for_Modern_C++.docset $$docset_root/
 
-# both targets below compare the docset search index with the mkdocs page
-# set. They share the same normalization (docs/foo/index.md and
-# docs/foo.md both become foo/index.html, the URL mkdocs itself would
-# give the page; the top-level index.md is excluded, as it is not part
-# of the hand-curated docSet.sql) and use comm(1) on two sorted lists
-# instead of running a sqlite3 query, or an O(n*m) nested shell loop,
-# once per page.
-DOCSET_INDEX_PATHS=$(shell sqlite3 docSet.dsidx "SELECT DISTINCT path FROM searchIndex" | sort)
-DOCSET_PAGE_PATHS=$(shell echo '$(MKDOCS_PAGES)' | tr ' ' '\n' | grep -v '^index\.md$$' | $(SED) -E 's@/index\.md$$@/index.html@; s@\.md$$@/index.html@' | sort)
-
 # list mkdocs pages missing from the docset index
 .PHONY: list_missing_pages
 list_missing_pages: docSet.dsidx
-	@comm -23 <(echo '$(DOCSET_PAGE_PATHS)' | tr ' ' '\n') <(echo '$(DOCSET_INDEX_PATHS)' | tr ' ' '\n')
+	@for page in $(MKDOCS_PAGES); do \
+		case "$$page" in \
+			*/index.md) path=$${page/\/index.md/} ;; \
+			*)          path=$${page/.md/}        ;; \
+		esac; \
+		if [ "x$$page" != "xindex.md" -a "x$$(sqlite3 docSet.dsidx "SELECT COUNT(*) FROM searchIndex WHERE path='$$path/index.html'")" = "x0" ]; then \
+			echo $$page; \
+		fi \
+	done
 
 # list paths in the docset index without a corresponding mkdocs page
 .PHONY: list_removed_paths
 list_removed_paths: docSet.dsidx
-	@comm -13 <(echo '$(DOCSET_PAGE_PATHS)' | tr ' ' '\n') <(echo '$(DOCSET_INDEX_PATHS)' | tr ' ' '\n')
+	@for path in $$(sqlite3 docSet.dsidx "SELECT path FROM searchIndex"); do \
+		page=$${path/\/index.html/.md}; \
+		page_index=$${path/index.html/index.md}; \
+		page_found=0; \
+		for p in $(MKDOCS_PAGES); do \
+			if [ "x$$p" = "x$$page" -o "x$$p" = "x$$page_index" ]; then \
+				page_found=1; \
+			fi \
+		done; \
+		if [ "x$$page_found" = "x0" ]; then \
+			echo $$path; \
+		fi \
+	done
 
 .PHONY: clean
 clean:

docs/docset/README.md

@@ -7,11 +7,10 @@ documentation browsers like [Dash](https://kapeli.com/dash), [Velocity](https://
 The docset can be created with
 
 ```sh
-make JSON_for_Modern_C++.docset
+make nlohmann_json.docset
 ```
 
-The generated folder `JSON_for_Modern_C++.docset` can then be opened in the documentation browser. `make all` builds a
-`JSON_for_Modern_C++.tgz` archive instead, and `make install_docset_zeal` installs the docset for Zeal directly.
+The generated folder `nlohmann_json.docset` can then be opened in the documentation browser.
 
 A recent version is also part of the [Dash user contributions](https://github.com/Kapeli/Dash-User-Contributions/tree/master/docsets/JSON_for_Modern_C%2B%2B).
 

docs/mkdocs/docs/api/basic_json/number_integer_t.md

@@ -51,7 +51,7 @@ range will yield over/underflow when used in a constructor. During deserializati
 will automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) or [`number_float_t`](number_float_t.md).
 
 [RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
-> Note that when such software is used, numbers that are integers and are in the range [-2<sup>53</sup>+1, 2<sup>53</sup>-1] are
+> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are
 > interoperable in the sense that implementations will agree exactly on their numeric values.
 
 As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is

docs/mkdocs/docs/api/basic_json/number_unsigned_t.md

@@ -52,7 +52,7 @@ when used in a constructor. During deserialization, too large or small integer n
 as [`number_integer_t`](number_integer_t.md) or [`number_float_t`](number_float_t.md).
 
 [RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
-> Note that when such software is used, numbers that are integers and are in the range [-2<sup>53</sup>+1, 2<sup>53</sup>-1] are
+> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are
 > interoperable in the sense that implementations will agree exactly on their numeric values.
 
 As this range is a subrange (when considered in conjunction with the `number_integer_t` type) of the exactly supported

docs/mkdocs/docs/api/basic_json/parse_error.md

@@ -54,7 +54,7 @@ classDiagram
 
 ## Notes
 
-For an input with <i>n</i> bytes, 1 is the index of the first character and <i>n</i>+1 is the index of the terminating null byte
+For an input with $n$ bytes, 1 is the index of the first character and $n+1$ is the index of the terminating null byte
 or the end of file. This also holds true when reading a byte vector for binary formats.
 
 ## Examples

docs/mkdocs/docs/examples/parse__iterator_pair.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/hUJYo1HWmfTBLMGn"><b>online</b></a>

docs/mkdocs/docs/examples/parse__pointers.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/AWbpa8e1xRV3y4MM"><b>online</b></a>

docs/mkdocs/docs/features/binary_formats/bjdata.md

@@ -61,7 +61,7 @@ The library uses the following mapping from JSON values types to BJData types ac
 
     The following values can **not** be converted to a BJData value:
 
-      - strings with more than 18446744073709551615 bytes, i.e., 2<sup>64</sup>-1 bytes (theoretical)
+      - strings with more than 18446744073709551615 bytes, i.e., $2^{64}-1$ bytes (theoretical)
 
 !!! info "Unused BJData markers"
 

docs/mkdocs/docs/features/types/index.md

@@ -273,7 +273,7 @@ When the default type is used, the maximal unsigned integer number that can be s
 
 [RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
 
-> Note that when such software is used, numbers that are integers and are in the range [-2<sup>53</sup>+1, 2<sup>53</sup>-1] are interoperable in the sense that implementations will agree exactly on their numeric values.
+> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are interoperable in the sense that implementations will agree exactly on their numeric values.
 
 As this range is a subrange of the exactly supported range [`INT64_MIN`, `INT64_MAX`], this class's integer type is interoperable.
 

docs/mkdocs/docs/features/types/number_handling.md

@@ -48,7 +48,7 @@ On number interoperability, the following remarks are made:
     for numeric magnitude and precision than is widely available.
     
     Note that when such software is used, numbers that are integers and
-    are in the range [-2<sup>53</sup>+1, 2<sup>53</sup>-1] are interoperable in the
+    are in the range $[-2^{53}+1, 2^{53}-1]$ are interoperable in the
     sense that implementations will agree exactly on their numeric
     values.
 
@@ -95,9 +95,9 @@ This is the same behavior as the code `#!c double x = 3.141592653589793238462643
 
 !!! success "Interoperability"
 
-    - The library is interoperable with respect to the specification, because its supported range [-2<sup>63</sup>, 2<sup>64</sup>-1] is
-      larger than the described range [-2<sup>53</sup>+1, 2<sup>53</sup>-1].
-    - All integers outside the range [-2<sup>63</sup>, 2<sup>64</sup>-1], as well as floating-point numbers are stored as `double`.
+    - The library is interoperable with respect to the specification, because its supported range $[-2^{63}, 2^{64}-1]$ is
+      larger than the described range $[-2^{53}+1, 2^{53}-1]$.
+    - All integers outside the range $[-2^{63}, 2^{64}-1]$, as well as floating-point numbers are stored as `double`.
       This also concurs with the specification above.
 
 ### Zeros

docs/mkdocs/docs/integration/cmake.md

@@ -125,7 +125,7 @@ automatically download a release as a dependency at configure time.
 
 ### `JSON_BuildTests`
 
-Build the unit tests when [`BUILD_TESTING`](https://cmake.org/cmake/help/latest/command/enable_testing.html) is enabled. This option is `ON` by default if the library's CMake project is the top project. That is, when integrating the library as described above, the test suite is not built unless explicitly switched on with this option.
+Build the unit tests when [`BUILD_TESTING`](https://cmake.org/cmake/help/latest/command/enable_testing.html) is enabled. This option is `ON` by default if the library's CMake project is the top project and the `tests` directory exists (the release archive `json.tar.xz` does not contain it). That is, when integrating the library as described above, the test suite is not built unless explicitly switched on with this option.
 
 ### `JSON_CI`
 

docs/mkdocs/docs/integration/package_managers.md

@@ -443,6 +443,30 @@ installed by adding the `-DJSON_MultipleHeaders=ON` flag (i.e., `cget install nl
     - :octicons-file-24: File issues at the [library issue tracker](https://github.com/nlohmann/json/issues)
     - :octicons-question-24: [Xcode documentation](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app)
 
+The `json` target's public headers live at `single_include/nlohmann`, so a consumer must write `#include <json.hpp>` rather than the
+`#include <nlohmann/json.hpp>` form used elsewhere in this documentation. The `json` target also ships only headers, and SwiftPM/Xcode
+expect every library target to produce an object file to link against; without one, linking a consumer fails with a missing `json.o`
+([#4650](https://github.com/nlohmann/json/issues/4650)). The workaround is to add at least one `.cpp` file of your own to the target
+that depends on `json`.
+
+??? example
+
+    1. Create the following files:
+
+        ```swift title="Package.swift"
+        --8<-- "integration/swift/Package.swift"
+        ```
+
+        ```cpp title="Sources/MyLibrary/example.cpp"
+        --8<-- "integration/swift/example.cpp"
+        ```
+
+    2. Build
+
+        ```shell
+        swift build
+        ```
+
 ## NuGet
 
 !!! abstract "Summary"
@@ -678,11 +702,11 @@ to install the [nlohmann-json](https://ports.macports.org/port/nlohmann-json/) p
     1. Create the following files:
 
         ```cpp title="example.cpp"
-        --8<-- "integration/macports/example.cpp"
+        --8<-- "integration/homebrew/example.cpp"
         ```
 
         ```cmake title="CMakeLists.txt"
-        --8<-- "integration/macports/CMakeLists.txt"
+        --8<-- "integration/homebrew/CMakeLists.txt"
         ```
 
     2. Install the package:

docs/mkdocs/docs/integration/swift/Package.swift

@@ -0,0 +1,20 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "MyPackage",
+    dependencies: [
+        .package(url: "https://github.com/nlohmann/json.git", from: "3.12.0")
+    ],
+    targets: [
+        // the C++ target that uses nlohmann/json
+        .target(
+            name: "MyLibrary",
+            dependencies: [
+                .product(name: "json", package: "json")
+            ],
+            // works around missing public headers in MyLibrary; not related to nlohmann/json
+            publicHeadersPath: "."
+        )
+    ]
+)

docs/mkdocs/docs/integration/swift/example.cpp

@@ -0,0 +1,8 @@
+// MyLibrary must contain at least one .cpp file, or SwiftPM/Xcode will
+// not build a usable "json" library to link against (see nlohmann/json#4650)
+#include <json.hpp>
+
+nlohmann::json example()
+{
+    return nlohmann::json::meta();
+}

docs/mkdocs/mkdocs.yml

@@ -349,6 +349,7 @@ markdown_extensions:
   - toc:
       permalink: true
   - md_in_html
+  - pymdownx.arithmatex
   - pymdownx.betterem:
       smart_enable: all
   - pymdownx.caret
@@ -440,3 +441,6 @@ plugins:
 
 extra_css:
   - css/custom.css
+
+extra_javascript:
+  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML

docs/mkdocs/scripts/check_structure.py

@@ -79,9 +79,9 @@ def check_structure() -> None:
                     report("whitespace/line_length", f"{file}:{lineno+1} ({current_section})", f"line is too long ({len(line)} vs. 160 chars)")
 
                 # sections in `<!-- NOLINT -->` comments are treated as present
-                nolint_match = re.match(r"<!--\s*NOLINT\s+(.*?)\s*-->", line)
-                if nolint_match:
-                    current_section = nolint_match.group(1)
+                if line.startswith("<!-- NOLINT"):
+                    current_section = line.strip("<!-- NOLINT")
+                    current_section = current_section.strip(" -->")
                     existing_sections.append(current_section)
 
                 # check if sections are correct
@@ -97,7 +97,7 @@ def check_structure() -> None:
                             if len(unexpected):
                                 report("style/numbering", f"{file}:{lineno} ({current_section})", f'unexpected overloads: {", ".join([f"({x})" for x in unexpected])}')
 
-                    current_section = line[3:]
+                    current_section = line.strip("## ")
                     existing_sections.append(current_section)
 
                     if current_section in expected_sections:
@@ -141,7 +141,7 @@ def check_structure() -> None:
                 # check that non-example admonitions have titles
                 untitled_admonition = re.match(r"^(\?\?\?|!!!) ([^ ]+)$", line)
                 if untitled_admonition and untitled_admonition.group(2) != "example":
-                    report("style/admonition_title", f"{file}:{lineno+1} ({current_section})", f'"{untitled_admonition.group(2)}" admonitions should have a title')
+                    report("style/admonition_title", f"{file}:{lineno} ({current_section})", f'"{untitled_admonition.group(2)}" admonitions should have a title')
 
                 previous_line = line