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

@@ -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

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`
 

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"