From 71b4eaf74349e7710fdf80efce498f00962c4c14 Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Sun, 27 Sep 2026 14:51:27 +0200
Subject: [PATCH] Document the Meson options and check them in CI

Describe the options of meson.build in FILES.md and in the Meson section
of the package manager documentation, which so far said that a Meson
installation always uses the default configuration.

The ci_meson_install job now also installs with non-default options and
checks that the headers of the multi-header version are installed, that
the definitions reach the pkg-config file and the CMake target, and that
find_package still works.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
---
 .github/workflows/ubuntu.yml                     | 14 ++++++++++++++
 FILES.md                                         |  9 ++++++---
 docs/mkdocs/docs/integration/package_managers.md | 14 +++++++++++---
 3 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/ubuntu.yml b/.github/workflows/ubuntu.yml
index 054118ab7..0d0e8259b 100644
--- a/.github/workflows/ubuntu.yml
+++ b/.github/workflows/ubuntu.yml
@@ -49,6 +49,20 @@ jobs:
         run: |
           cmake -S tests/cmake_import/project -B build-import -DCMAKE_PREFIX_PATH=${{ github.workspace }}/install
           cmake --build build-import
+      - name: Install with Meson and non-default options
+        run: |
+          meson setup build-meson-options --prefix=${{ github.workspace }}/install-options -DMultipleHeaders=true -DDiagnostics=true -DGlobalUDLs=false
+          meson install -C build-meson-options
+      - name: Check that the options reach the installed files
+        run: |
+          test -d install-options/include/nlohmann/detail
+          cflags=$(PKG_CONFIG_PATH=${{ github.workspace }}/install-options/share/pkgconfig pkg-config --cflags nlohmann_json)
+          echo "$cflags"
+          echo "$cflags" | grep -q -- '-DJSON_DIAGNOSTICS=1'
+          echo "$cflags" | grep -q -- '-DJSON_USE_GLOBAL_UDLS=0'
+          grep -q 'JSON_USE_GLOBAL_UDLS=0;JSON_DIAGNOSTICS=1' install-options/share/cmake/nlohmann_json/nlohmann_jsonTargets.cmake
+          cmake -S tests/cmake_import/project -B build-import-options -DCMAKE_PREFIX_PATH=${{ github.workspace }}/install-options
+          cmake --build build-import-options
 
   ci_infer:
     runs-on: ubuntu-latest
diff --git a/FILES.md b/FILES.md
index 5c5106f10..73cc3d699 100644
--- a/FILES.md
+++ b/FILES.md
@@ -277,9 +277,12 @@ meson setup builddir
 ninja -C builddir
 ```
 
-The build definition for the [Meson](https://mesonbuild.com) build system. When installing, it also installs the CMake package config
-files so that `find_package(nlohmann_json)` works. As Meson cannot generate `nlohmann_jsonTargets.cmake` itself, it is
-created from the template `cmake/nlohmann_jsonTargets.cmake.in`, which is only used by Meson.
+`meson_options.txt` defines the options, which mirror the CMake options that change the library's target (for example,
+`-DDiagnostics=true`). Meson requires this file next to `meson.build`, so it is also part of `include.zip`.
+
+When installing, `meson.build` installs the headers, a pkg-config file, and the CMake package config files, so that
+`find_package(nlohmann_json)` works. As Meson cannot generate `nlohmann_jsonTargets.cmake` itself, it is created from
+the template `cmake/nlohmann_jsonTargets.cmake.in`, which is only used by Meson.
 
 ### `Package.swift`
 
diff --git a/docs/mkdocs/docs/integration/package_managers.md b/docs/mkdocs/docs/integration/package_managers.md
index 1dee51cf1..7438b7ff7 100644
--- a/docs/mkdocs/docs/integration/package_managers.md
+++ b/docs/mkdocs/docs/integration/package_managers.md
@@ -126,10 +126,18 @@ the `nlohmann_json` pkg-config dependency, or use [`find_package(nlohmann_json)`
 it is preferred to use the [`dependency()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a
 subproject fallback, rather than using the subproject directly.
 
-!!! note
+The options that change the library's configuration are available in Meson as well, named like the
+[CMake options](cmake.md#cmake-options) without the `JSON_` prefix: `MultipleHeaders`, `GlobalUDLs`,
+`ImplicitConversions`, `DisableEnumSerialization`, `Diagnostics`, `Diagnostic_Positions`,
+`LegacyDiscardedValueComparison`, and `StrictNulHandling`. They have the same defaults as in CMake, except that
+`MultipleHeaders` is `false`. Set them with `-D` when setting up the build, or with the subproject name as prefix when
+the library is used as a subproject:
 
-    The `meson.build` does not expose the library's [CMake options](cmake.md#cmake-options), so a Meson installation
-    always uses the library's default configuration.
+```shell
+meson setup build -Dnlohmann_json:Diagnostics=true
+```
+
+The resulting compile definitions are part of the Meson dependency, the pkg-config file, and the CMake target.
 
 ??? example "Example: Wrap"