mirror of
https://github.com/nlohmann/json.git
synced 2026-11-17 09:01:28 +00:00
Documentation: - basic_json_view::contains: basic_json::contains(json_pointer) never throws either; drop the claim that it does. - std::format support is dated 3.13.0 in the serialization feature page; std::optional is supported since 3.12.0 and std::filesystem::path since 3.10.5 in type_recipes.md. - basic_json_view::source_offset: also -1 for values written by an edit and arrays/objects whose elements an edit added or removed. - basic_json_view::items: const auto& works (binds to the temporary); by value is recommended, non-const auto& does not compile. - basic_json_view::operator==/!=: document the overload that compares a read-only with an editable view. - basic_json_document::erase: out_of_range.404 also for a last token "-". - json_editable_document/json_editable_view: mention insert and erase. - basic_json::swap/std::swap: describe the conditional noexcept (only a throwing move of json_base_class_t can make it throw) and that the std::swap specialization is not provided with C++20 (ADL swap is). - exceptions.md: out_of_range.405 also from front/pop_front and from basic_json_document::erase with an empty pointer; other_error.502 also for non-empty binary values in UBJSON/BJData Draft 2, as the writer does. - Macro pages: fix highlighted lines. Tests: - unit-unicode.cpp: enable the "incorrect sequences" sections that were disabled with #if 0 since 2017 without a reason. They pass; the reason was the runtime of the quadratic high/low surrogate sweep (1024 * 64512 parses, not finished after 3 CPU minutes). That sweep is thinned to all high surrogates against boundary code units, plus one high surrogate against every code unit with accept(). The sections are merged into the existing "incorrect sequences" section of the same name. Repository: - labeler.yml: match the moved json_view feature docs folder. - check_amalgamation.yml: take config_json_view.json from develop's tools. - FILES.md: list json_view_benchmarks.yml. - cmake/ci.cmake: remove the unused targets ci_test_amalgamation (a duplicate of make check-amalgamation), ci_benchmarks and ci_clean, and the .gitignore entry of the first. - make clean and .gitignore cover all tests/*_fuzzer binaries. - hedley_undef.hpp: regenerate with make update_hedley_undef (one line moves into sorted order); regenerate the amalgamation. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
320 lines
13 KiB
Markdown
320 lines
13 KiB
Markdown
# Supporting files
|
|
|
|
This file describes the source for supporting files; that is, files that are not part of the library, but define the infrastructure and other aspects of the project.
|
|
|
|
- [Continuous Integration](#continuous-integration)
|
|
- [GitHub](#github)
|
|
- [REUSE](#reuse)
|
|
- [Package Managers](#package-managers)
|
|
- [Debugging](#debugging)
|
|
|
|
## Continuous Integration
|
|
|
|
### `.github/workflows`
|
|
|
|
The [GitHub Actions](https://docs.github.com/en/actions) workflows that build, test, and analyze the library. Each file in this folder defines one workflow:
|
|
|
|
- `ubuntu.yml`, `macos.yml`, `windows.yml` — build and run the test suite on Linux, macOS, and Windows.
|
|
- `check_amalgamation.yml` — verify on pull requests and pushes to `develop` that the generated files (the single-header amalgamation in `single_include`, `BUILD.bazel`, and `nlohmann_json.natvis`) are up to date.
|
|
- `comment_check_amalgamation.yml` — comment on a pull request when the amalgamation check failed.
|
|
- `cifuzz.yml` — run short fuzzing sessions via [OSS-Fuzz CIFuzz](https://google.github.io/oss-fuzz/getting-started/continuous-integration/) on pull requests.
|
|
- `codeql-analysis.yml` — run [CodeQL](https://codeql.github.com) code scanning.
|
|
- `flawfinder.yml` — run the [Flawfinder](https://dwheeler.com/flawfinder/) static analysis.
|
|
- `semgrep.yml` — run [Semgrep](https://semgrep.dev) static analysis.
|
|
- `scorecards.yml` — run the [OpenSSF Scorecard](https://securityscorecards.dev) supply-chain security checks.
|
|
- `dependency-review.yml` — scan dependency changes in pull requests for known vulnerabilities.
|
|
- `labeler.yml` — the "Pull Request Labeler" workflow (see `.github/labeler.yml`).
|
|
- `stale.yml` — comment on and close stale issues and pull requests.
|
|
- `publish_documentation.yml` — build and publish the documentation on pushes to the `develop` branch that touch the documentation sources (or the files it embeds).
|
|
- `check_docs_links.yml` — check the links of the documentation weekly, as external links can break without any change in this repository.
|
|
- `cancel_closed_pr_runs.yml` — cancel unfinished workflow runs of a pull request once it is closed or merged.
|
|
- `json_view_benchmarks.yml` — compare the performance of `json_view` with other JSON libraries on GitHub-hosted x86-64 and AArch64 Linux runners, on demand or when a pull request gets the label "benchmark".
|
|
|
|
Further documentation:
|
|
|
|
- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)
|
|
|
|
> [!IMPORTANT]
|
|
> The folder `.github/workflows` is predetermined by GitHub.
|
|
|
|
### `.github/external_ci/appveyor.yml`
|
|
|
|
Configuration for the pipelines at [AppVeyor](https://ci.appveyor.com/project/nlohmann/json).
|
|
|
|
Further documentation:
|
|
|
|
- [appveyor.yml reference](https://www.appveyor.com/docs/appveyor-yml/)
|
|
|
|
> [!NOTE]
|
|
> The filename can be freely configured in the AppVeyor project.
|
|
|
|
## GitHub
|
|
|
|
### `CITATION.cff`
|
|
|
|
A file to configure the citation for the repository which is displayed in the sidebar of the project.
|
|
|
|
Further documentation:
|
|
|
|
- [About CITATION files](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files)
|
|
|
|
> [!IMPORTANT]
|
|
> The filename `CITATION.cff` and position (root of the repository) are predetermined by GitHub.
|
|
|
|
### `.github/CODE_OF_CONDUCT.md`
|
|
|
|
The code of conduct for the project. This is the Markdown version of the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). The code of conduct is linked on the [Community Standards](https://github.com/nlohmann/json/community) page and is mentioned by the Sentiment Bot.
|
|
|
|
Further documentation:
|
|
|
|
- [Adding a code of conduct to your project](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)
|
|
|
|
> [!IMPORTANT]
|
|
> The filename `.github/CODE_OF_CONDUCT.md` is predetermined by GitHub.
|
|
|
|
> [!NOTE]
|
|
> The file is part of the documentation and is included in `docs/mkdocs/docs/community/code_of_conduct.md`.
|
|
|
|
### `.github/CODEOWNERS`
|
|
|
|
The code owners file for the project which is used to select reviewers for new pull requests.
|
|
|
|
Further documentation:
|
|
|
|
- [About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)
|
|
|
|
> [!IMPORTANT]
|
|
> The filename `.github/CODEOWNERS` is predetermined by GitHub.
|
|
|
|
### `.github/config.yml`
|
|
|
|
Configuration file for [probot](https://probot.github.io/apps/), in particular the [Sentiment Bot](https://probot.github.io/apps/sentiment-bot/) and the [Request Info](https://probot.github.io/apps/request-info/).
|
|
|
|
> [!IMPORTANT]
|
|
> The filename `.github/config.yml` is predetermined by probot.
|
|
|
|
### `.github/CONTRIBUTING.md`
|
|
|
|
The contribution guidelines which are linked in the [Community Standards](https://github.com/nlohmann/json/community) and at <https://github.com/nlohmann/json/contribute>.
|
|
|
|
Further documentation:
|
|
|
|
- [Setting guidelines for repository contributors](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors)
|
|
|
|
> [!IMPORTANT]
|
|
> The filename `.github/CONTRIBUTING.md` is predetermined by GitHub.
|
|
|
|
> [!NOTE]
|
|
> The file is part of the documentation and is included in `docs/mkdocs/docs/community/contribution_guidelines.md`.
|
|
|
|
### `.github/dependabot.yml`
|
|
|
|
The configuration of [dependabot](https://github.com/dependabot) which ensures the dependencies (GitHub actions and Python packages used in the CI) remain up to date.
|
|
|
|
Further documentation:
|
|
|
|
- [Configuring Dependabot security updates](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates)
|
|
|
|
> [!IMPORTANT]
|
|
> The filename `.github/dependabot.yml` is predetermined by GitHub.
|
|
|
|
### `.github/FUNDING.yml`
|
|
|
|
A file to configure the sponsor button of the repository which is displayed in the sidebar of the project.
|
|
|
|
Further documentation:
|
|
|
|
- [Displaying a sponsor button in your repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository)
|
|
|
|
> [!IMPORTANT]
|
|
> The filename `.github/FUNDING.yml` is predetermined by GitHub.
|
|
|
|
### `.github/ISSUE_TEMPLATE/bug.yaml`
|
|
|
|
Issue form template for bugs.
|
|
|
|
Further documentation:
|
|
|
|
- [Configuring issue templates for your repository](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)
|
|
|
|
> [!IMPORTANT]
|
|
> The folder `.github/ISSUE_TEMPLATE` is predetermined by GitHub.
|
|
|
|
### `.github/ISSUE_TEMPLATE/config.yml`
|
|
|
|
Issue template chooser configuration. The file is used to configure the dialog when a new issue is created.
|
|
|
|
Further documentation:
|
|
|
|
- [Configuring issue templates for your repository](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)
|
|
|
|
> [!IMPORTANT]
|
|
> The filename `.github/ISSUE_TEMPLATE/config.yml` is predetermined by GitHub.
|
|
|
|
### `.github/labeler.yml`
|
|
|
|
Configuration file for the "Pull Request Labeler" workflow defined in `workflows/labeler.yml`. This file defines rules how labels are assigned to pull requests based on which files are changed.
|
|
|
|
Further documentation:
|
|
|
|
- [Label manager for PRs and issues based on configurable conditions](https://github.com/srvaroa/labeler)
|
|
|
|
> [!NOTE]
|
|
> The filename defaults to `.github/labeler.yml` and can be configured in the workflow.
|
|
|
|
### `.github/PULL_REQUEST_TEMPLATE.md`
|
|
|
|
The pull request template which prefills new pull requests.
|
|
|
|
Further documentation:
|
|
|
|
- [Creating a pull request template for your repository](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository)
|
|
|
|
> [!IMPORTANT]
|
|
> The filename `.github/PULL_REQUEST_TEMPLATE.md` is predetermined by GitHub.
|
|
|
|
### `.github/SECURITY.md`
|
|
|
|
The goal is to describe how to securely report security vulnerabilities for this repository. The security policy is linked at <https://github.com/nlohmann/json/security/policy>.
|
|
|
|
Further documentation:
|
|
|
|
- [Adding a security policy to your repository](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository)
|
|
|
|
> [!IMPORTANT]
|
|
> The filename `.github/SECURITY.md` is predetermined by GitHub.
|
|
|
|
> [!NOTE]
|
|
> The file is part of the documentation and is included in `docs/mkdocs/docs/community/security_policy.md`.
|
|
|
|
### `LICENSE.MIT`
|
|
|
|
The license of the project.
|
|
|
|
Further documentation:
|
|
|
|
- [Adding a license to a repository](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository)
|
|
|
|
> [!IMPORTANT]
|
|
> The filename `LICENSE.MIT` is partly predetermined by GitHub. The root filename must be `LICENSE`.
|
|
|
|
## REUSE
|
|
|
|
### `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:
|
|
|
|
- [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.toml` is predetermined by REUSE. Alternatively, a `.reuse/dep5` file (deprecated) can be used.
|
|
|
|
### `.reuse/templates`
|
|
|
|
Copyright header templates for source files. The root `Makefile` contains a target `reuse` that updates copyright headers with the templates.
|
|
|
|
Further information:
|
|
|
|
- [reuse command-line tool](https://pypi.org/project/reuse/)
|
|
- [documentation on templates](https://reuse.readthedocs.io/en/stable/man/reuse-annotate.html#cmdoption-t)
|
|
- [REUSE](http://reuse.software)
|
|
|
|
> [!IMPORTANT]
|
|
> The folder name `.reuse/templates` is predetermined by REUSE.
|
|
|
|
### `LICENSES`
|
|
|
|
A folder that contains every license of all license files (library and third-party code).
|
|
|
|
Further documentation:
|
|
|
|
- [REUSE specification](https://reuse.software/spec-3.3/)
|
|
|
|
> [!IMPORTANT]
|
|
> The folder name `LICENSES` is predetermined by REUSE.
|
|
|
|
|
|
## Package Managers
|
|
|
|
### `BUILD.bazel`
|
|
|
|
The build definition for [Bazel](https://bazel.build). The file is generated by
|
|
`cmake/scripts/gen_bazel_build_file.cmake`, which derives the header list from the files in `include`; change the
|
|
script rather than editing the file by hand. The file can be updated by calling
|
|
|
|
```shell
|
|
make BUILD.bazel
|
|
```
|
|
|
|
The "Check amalgamation" workflow fails if the file is out of date.
|
|
|
|
### `meson.build` and `meson_options.txt`
|
|
|
|
Meson build definitions suitable for use as a subproject ("wrap" in Meson terminology).
|
|
|
|
Projects wishing to use the wrap can execute:
|
|
```sh
|
|
meson wrap install nlohmann_json
|
|
```
|
|
|
|
Which allows Meson to build from source when a system provided dependency isn't available.
|
|
|
|
To build directly:
|
|
```sh
|
|
meson setup builddir
|
|
ninja -C builddir
|
|
```
|
|
|
|
`meson_options.txt` defines the options, which mirror the names of the CMake options that change the library's target (for example,
|
|
`-DDiagnostics=true`); their defaults may differ (for example, `MultipleHeaders` defaults to `false` in Meson, while
|
|
`JSON_MultipleHeaders` is `ON` in CMake). Meson requires this file next to `meson.build`, so it is also part of `include.zip`. `make check_build_options`
|
|
([`tools/check_build_options`](tools/check_build_options/README.md)) checks in CI that both files and the pkg-config files
|
|
stay in sync with the CMake options.
|
|
|
|
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`
|
|
|
|
The package manifest for the [Swift Package Manager](https://www.swift.org/package-manager/).
|
|
|
|
### `MODULE.bazel`
|
|
|
|
The module definition for [Bazel](https://bazel.build)'s [Bzlmod](https://bazel.build/external/module) dependency system. It complements `BUILD.bazel` and replaces the previously used `WORKSPACE.bazel`.
|
|
|
|
Further documentation:
|
|
|
|
- [Bazel modules](https://bazel.build/external/module)
|
|
|
|
## Debugging
|
|
|
|
### `nlohmann_json.natvis`
|
|
|
|
The [Natvis](https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects) file that
|
|
gives `json` values a friendly view in the Visual Studio debugger. The file is generated by
|
|
`tools/generate_natvis/generate_natvis.py` from the template `tools/generate_natvis/nlohmann_json.natvis.j2` and the ABI
|
|
tags and version in `include/nlohmann/detail/abi_macros.hpp`; change the script or the template rather than editing
|
|
the file by hand. The file can be updated by calling
|
|
|
|
```shell
|
|
make natvis
|
|
```
|
|
|
|
The "Check amalgamation" workflow fails if the file is out of date.
|
|
|
|
The file covers the namespace variants with up to two ABI tags. A Natvis file for other configurations can be
|
|
generated with the `--abi-tags` or `--all` options, for example
|
|
`make natvis NATVIS_ARGS="--abi-tags _diag,_dp,_ns --output my_nlohmann_json.natvis"`; see
|
|
[`tools/generate_natvis`](tools/generate_natvis/README.md). With MSVC, CMake adds the file to the `nlohmann_json`
|
|
target and installs it.
|
|
|
|
Further documentation:
|
|
|
|
- [Create custom views of C++ objects in the debugger using the Natvis framework](https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects)
|