Skip to content

FILES.md

Latest commit

 

History

History
318 lines (194 loc) · 13.2 KB

FILES.md

File metadata and controls

318 lines (194 loc) · 13.2 KB
Raw

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

.github/workflows

The GitHub 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 on pull requests.
  • codeql-analysis.yml — run CodeQL code scanning.
  • flawfinder.yml — run the Flawfinder static analysis.
  • semgrep.yml — run Semgrep static analysis.
  • scorecards.yml — run the OpenSSF Scorecard 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:

Important

The folder .github/workflows is predetermined by GitHub.

.github/external_ci/appveyor.yml

Configuration for the pipelines at AppVeyor.

Further documentation:

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:

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. The code of conduct is linked on the Community Standards page and is mentioned by the Sentiment Bot.

Further documentation:

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:

Important

The filename .github/CODEOWNERS is predetermined by GitHub.

.github/config.yml

Configuration file for probot, in particular the Sentiment Bot and the 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 and at https://github.com/nlohmann/json/contribute.

Further documentation:

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 which ensures the dependencies (GitHub actions and Python packages used in the CI) remain up to date.

Further documentation:

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:

Important

The filename .github/FUNDING.yml is predetermined by GitHub.

.github/ISSUE_TEMPLATE/bug.yaml

Issue form template for bugs.

Further documentation:

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:

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:

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:

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:

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:

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:

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:

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:

Important

The folder name LICENSES is predetermined by REUSE.

Package Managers

BUILD.bazel

The build definition for Bazel. 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

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:

meson wrap install nlohmann_json

Which allows Meson to build from source when a system provided dependency isn't available.

To build directly:

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

MODULE.bazel

The module definition for Bazel's Bzlmod dependency system. It complements BUILD.bazel and replaces the previously used WORKSPACE.bazel.

Further documentation:

Debugging

nlohmann_json.natvis

The Natvis 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

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,_vns --output my_nlohmann_json.natvis"; see tools/generate_natvis. With MSVC, CMake adds the file to the nlohmann_json target and installs it.

Further documentation: