| # 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. | |
| 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) |