Niels Lohmann
791cd88dfc
* Fix math formulas rendering as raw TeX in the published docs The privacy plugin self-hosts MathJax 2.7.0 but drops its ?config=TeX-MML-AM_CHTML query string, so the rehosted script loads no input jax and the 10 formulas across 6 pages render as raw TeX to readers. Remove pymdownx.arithmatex and the MathJax extra_javascript entry, and rewrite the formulas in plain HTML (<sup>, <i>) instead. This also drops a nine-year-old third-party script from every page. Part of #5718 Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix publish_documentation triggers and persist unneeded git credentials publish_documentation.yml only triggered on docs/mkdocs/** pushes, but the site also embeds .github/CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, cmake/{clang,gcc}_flags.cmake, .clang-tidy, tools/astyle/.astylerc and tests/fmt_formatter/project/main.cpp via pymdownx.snippets, so changes to those files never republished the site. Extend the path filter to cover them, and switch runs-on from the long-pinned ubuntu-22.04 to ubuntu-latest to match ci_test_documentation. Also add persist-credentials: false to the checkouts in ci_icpx and ci_nvhpc (ubuntu.yml) and msvc-vs2026/msvc-arm64 (windows.yml), none of which pushes with git, matching every other checkout in these workflows. Part of #5718 Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix example build: broken debug echo, deprecations hidden for everything docs/Makefile's debug echo used a space instead of a comma in $(call cxx_standard ...), so it always printed an empty standard. Every example was also compiled with -Wno-deprecated-declarations, which would silently hide an accidental deprecated-API call in any of them. Factor the duplicated compile flags into EXAMPLE_CPPFLAGS/ EXAMPLE_WARNFLAGS, build with -Werror=deprecated-declarations by default, and only allow the three examples that intentionally document deprecated API (the DEPRECATED_EXAMPLES list) to suppress it. Part of #5718 Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix check_structure.py NOLINT parsing and an off-by-one report line `line.strip("<!-- NOLINT")` followed by `.strip(" -->")` strips any of the characters in those sets from both ends, not a literal prefix; it only happened to work for "Examples". A NOLINT'd section name starting with N, O, L, I or T (e.g. "Notes", "Template parameters", "Iterator invalidation", "Literals") was silently mangled, so the suppression did not apply and the checker could report a spurious missing/misordered section. Parse the comment with a regex instead. The same fragile strip() pattern was used for heading text; replace it with a plain prefix slice. Also fix the admonition_title report, which used the 0-based line index while every other report in the file uses lineno+1. Part of #5718 Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix docset README's non-existent make target and stale fallback URL The README told readers to run `make nlohmann_json.docset`, but the Makefile's targets are `all`, `JSON_for_Modern_C++.docset` and `install_docset_zeal`; the documented command has failed with "No rule to make target" since #2967 (2021). Point the README at the real target and folder name. Info.plist's DashDocSetFallbackURL also still pointed at the old nlohmann.github.io/json/ URL instead of the canonical https://json.nlohmann.me/ from mkdocs.yml's site_url. Leave list_missing_pages/list_removed_paths alone: they may become redundant once #5638's check_docset() lands, which is a follow-up. Part of #5718 Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Remove two leftover Doxygen-era .link files from the examples directory parse__iterator_pair.link and parse__pointers.link each held only a Wandbox "online" permalink from the old Doxygen docs. #3071 deleted every other .link file in 2021; these two came in through a parallel PR (#3100) and were never referenced by any page, script or config. Part of #5718 Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix MacPorts CMake example to include its own snippet files The MacPorts "Example: CMake" block included integration/homebrew/example.cpp and integration/homebrew/CMakeLists.txt instead of the MacPorts files right next to it, a copy-paste slip from the Homebrew section. Nothing referenced integration/macports/CMakeLists.txt as a result. The page rendered correctly only because the homebrew, macports and vcpkg/CMakeLists.txt snippets are byte-identical, so a future edit to the MacPorts files would not have shown up on the page. Part of #5718 item 6 Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Do not persist git credentials in publish_documentation's checkout The checkout step in publish_documentation.yml left the default persist-credentials: true, so GITHUB_TOKEN stayed writable in .git/config for the rest of the job (zizmor's artipacked finding). The Deploy documentation step authenticates through its own github_token input to peaceiris/actions-gh-pages and does not push with the checked-out credentials, so persist-credentials: false is safe here, matching every other checkout in the workflow set. Overlaps #5638, which edits this same checkout step (adds fetch-depth: 0); expect a rebase conflict there. Part of #5718 item 2 Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Replace list_missing_pages/list_removed_paths with a comm(1)-based diff The docset Makefile's list_missing_pages ran one sqlite3 query per mkdocs page, and list_removed_paths nested a loop over all mkdocs pages inside a loop over all docset index paths (O(n*m) shell iteration). Issue #5718 item 5 suggested removing or reducing these targets once #5638's check_docset() lands, but that PR is still open and covers only API pages and macros, not the full page set these targets check. Replace the loops with two sorted path lists (DOCSET_PAGE_PATHS from mkdocs' markdown sources, DOCSET_INDEX_PATHS from the built docset index) compared with a single comm(1) call each, verified to produce output identical to the old loops against the current docSet.dsidx. The sed expression used '#' as its delimiter, which GNU Make reads as a comment character even inside a variable assignment, truncating the line and orphaning the closing paren of $(shell ...) ("unterminated call to function 'shell': missing ')'"). Use '@' as the delimiter instead. Part of #5718 item 5 Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
36 KiB
Package Managers
{: style="height:1em"} [**Homebrew**](#homebrew) `nlohmann-json`
{: style="height:1em"} [**Meson**](#meson) `nlohmann_json`
{: style="height:1em"} [**Bazel**](#bazel) `nlohmann_json`
{: style="height:1em"} [**Conan**](#conan) `nlohmann_json`
{: style="height:1em"} [**Spack**](#spack) `nlohmann-json`
[**Hunter**](#hunter) `nlohmann_json`
{: style="height:1em"} [**vcpkg**](#vcpkg) `nlohmann-json`
[**cget**](#cget) `nlohmann/json`
{: style="height:1em"} [**Swift Package Manager**](#swift-package-manager) `nlohmann/json`
{: style="height:1em"} [**NuGet**](#nuget) `nlohmann.json`
{: style="height:1em"} [**Conda**](#conda) `nlohmann_json`
{: style="height:1em"} [**MacPorts**](#macports) `nlohmann-json`
{: style="height:1em"} [**CPM.cmake**](#cpmcmake) `gh:nlohmann/json`
{: style="height:1em"} [**xmake**](#xmake) `nlohmann_json`
Running example
Throughout this page, we will describe how to compile the example file example.cpp below.
--8<-- "integration/example.cpp"
When executed, this program should create output similar to
--8<-- "examples/meta.output"
Homebrew
!!! abstract "Summary"
formula: [**`nlohmann-json`**](https://formulae.brew.sh/formula/nlohmann-json)
- [](https://repology.org/project/nlohmann-json/versions)
- :octicons-tag-24: Available versions: current version and development version (with `--HEAD` parameter)
- :octicons-rocket-24: The formula is updated with every release.
- :octicons-person-24: Maintainer: Niels Lohmann
- :octicons-file-24: File issues at the [Homebrew issue tracker](https://github.com/Homebrew/homebrew-core/issues)
- :octicons-question-24: [Homebrew website](https://brew.sh)
If you are using Homebrew, you can install the library with
brew install nlohmann-json
The header can be used directly in your code or via CMake.
??? example "Example: Raw compilation"
1. Create the following file:
```cpp title="example.cpp"
--8<-- "integration/homebrew/example.cpp"
```
2. Install the package:
```sh
brew install nlohmann-json
```
3. Compile the code and pass the Homebrew prefix to the include path such that the library can be found:
```sh
c++ example.cpp -I$(brew --prefix nlohmann-json)/include -std=c++11 -o example
```
??? example "Example: CMake"
1. Create the following files:
```cpp title="example.cpp"
--8<-- "integration/homebrew/example.cpp"
```
```cmake title="CMakeLists.txt"
--8<-- "integration/homebrew/CMakeLists.txt"
```
2. Install the package:
```sh
brew install nlohmann-json
```
3. Compile the code and pass the Homebrew prefix to CMake to find installed packages via `#!cmake find_package`:
```sh
CMAKE_PREFIX_PATH=$(brew --prefix) cmake -S . -B build
cmake --build build
```
Meson
!!! abstract "Summary"
wrap: **`nlohmann_json`**
- :octicons-tag-24: Available versions: current version and select older versions (see
[WrapDB](https://mesonbuild.com/Wrapdb-projects.html))
- :octicons-rocket-24: The package is updated automatically from file
[`meson.build`](https://github.com/nlohmann/json/blob/develop/meson.build).
- :octicons-file-24: File issues at the [library issue tracker](https://github.com/nlohmann/json/issues)
- :octicons-question-24: [Meson website](https://mesonbuild.com/index.html)
If you are using the Meson Build System, add this source tree as a meson subproject. You may also use the
include.zip published in this project's Releases to reduce the size of the vendored source tree. Alternatively,
you can get a wrap file by downloading it from Meson WrapDB, or use
meson wrap install nlohmann_json
Please see the Meson project for any issues regarding the packaging.
The provided meson.build can also be used as an alternative to CMake for installing nlohmann_json system-wide in
which case a pkg-config file is installed. To use it, have your build system require the nlohmann_json
pkg-config dependency. In Meson, it is preferred to use the
dependency() object with a subproject fallback, rather than
using the subproject directly.
??? example "Example: Wrap"
1. Create the following files:
```ini title="meson.build"
--8<-- "integration/meson/meson.build"
```
```cpp title="example.cpp"
--8<-- "integration/meson/example.cpp"
```
2. Use the Meson WrapDB to fetch the nlohmann/json wrap:
```shell
mkdir subprojects
meson wrap install nlohmann_json
```
3. Build:
```shell
meson setup build
meson compile -C build
```
Bazel
!!! abstract "Summary"
use `bazel_dep`, `git_override`, or `local_path_override`
- :octicons-tag-24: Any version, that is available via [Bazel Central Registry](https://registry.bazel.build/modules/nlohmann_json)
- :octicons-file-24: File issues at the [library issue tracker](https://github.com/nlohmann/json/issues)
- :octicons-question-24: [Bazel website](https://bazel.build)
This repository provides a Bazel MODULE.bazel and a corresponding BUILD.bazel file. Therefore, this
repository can be referenced within a MODULE.bazel by rules such as archive_override, git_override, or local_path_override. To use the library, you need to depend on the target @nlohmann_json//:json (i.e., via deps attribute).
??? example
1. Create the following files:
```ini title="BUILD"
--8<-- "integration/bazel/BUILD"
```
```ini title="WORKSPACE"
--8<-- "integration/bazel/MODULE.bazel"
```
```cpp title="example.cpp"
--8<-- "integration/bazel/example.cpp"
```
2. Build and run:
```shell
bazel build //:main
bazel run //:main
```
Conan
!!! abstract "Summary"
recipe: [**`nlohmann_json`**](https://conan.io/center/recipes/nlohmann_json)
- [](https://repology.org/project/nlohmann-json/versions)
- :octicons-tag-24: Available versions: current version and older versions (see
[Conan Center](https://conan.io/center/recipes/nlohmann_json))
- :octicons-rocket-24: The package is updated automatically via
[this recipe](https://github.com/conan-io/conan-center-index/tree/master/recipes/nlohmann_json).
- :octicons-file-24: File issues at the [Conan Center issue tracker](https://github.com/conan-io/conan-center-index/issues)
- :octicons-question-24: [Conan website](https://conan.io)
If you are using Conan to manage your dependencies, merely add nlohmann_json/x.y.z to your conanfile's
requires, where x.y.z is the release version you want to use.
??? example
1. Create the following files:
```ini title="Conanfile.txt"
--8<-- "integration/conan/Conanfile.txt"
```
```cmake title="CMakeLists.txt"
--8<-- "integration/conan/CMakeLists.txt"
```
```cpp title="example.cpp"
--8<-- "integration/conan/example.cpp"
```
2. Call Conan:
```sh
conan install . --output-folder=build --build=missing
```
3. Build:
```sh
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="conan_toolchain.cmake" -DCMAKE_BUILD_TYPE=Release
cmake --build build
```
Spack
!!! abstract "Summary"
package: [**`nlohmann-json`**](https://packages.spack.io/package.html?name=nlohmann-json)
- [](https://repology.org/project/nlohmann-json/versions)
- :octicons-tag-24: Available versions: current version and older versions (see
[Spack package](https://packages.spack.io/package.html?name=nlohmann-json))
- :octicons-rocket-24: The package is updated with every release.
- :octicons-person-24: Maintainer: [Axel Huebl](https://github.com/ax3l)
- :octicons-file-24: File issues at the [Spack issue tracker](https://github.com/spack/spack/issues)
- :octicons-question-24: [Spack website](https://spack.io)
If you are using Spack to manage your dependencies, you can use the
nlohmann-json package via
spack install nlohmann-json
Please see the Spack project for any issues regarding the packaging.
??? example
1. Create the following files:
```cmake title="CMakeLists.txt"
--8<-- "integration/spack/CMakeLists.txt"
```
```cpp title="example.cpp"
--8<-- "integration/spack/example.cpp"
```
2. Install the library:
```sh
spack install nlohmann-json
```
3. Load the environment for your Spack-installed packages:
```sh
spack load nlohmann-json
```
4. Build the project with CMake:
```sh
cmake -S . -B build -DCMAKE_PREFIX_PATH=$(spack location -i nlohmann-json)
cmake --build build
```
Hunter
!!! abstract "Summary"
package: [**`nlohmann_json`**](https://hunter.readthedocs.io/en/latest/packages/pkg/nlohmann_json.html)
- :octicons-tag-24: Available versions: current version and older versions (see
[Hunter package](https://hunter.readthedocs.io/en/latest/packages/pkg/nlohmann_json.html))
- :octicons-rocket-24: The package is updated with every release.
- :octicons-file-24: File issues at the [Hunter issue tracker](https://github.com/cpp-pm/hunter/issues)
- :octicons-question-24: [Hunter website](https://hunter.readthedocs.io/en/latest/)
If you are using Hunter on your project for external dependencies, then you can use the nlohmann_json package via
hunter_add_package(nlohmann_json)
Please see the Hunter project for any issues regarding the packaging.
??? example
1. Create the following files:
```cmake title="CMakeLists.txt"
--8<-- "integration/hunter/CMakeLists.txt"
```
```cpp title="example.cpp"
--8<-- "integration/hunter/example.cpp"
```
2. Download required files
```shell
mkdir cmake
wget https://raw.githubusercontent.com/cpp-pm/gate/master/cmake/HunterGate.cmake -O cmake/HunterGate.cmake
```
3. Build the project with CMake:
```shell
cmake -S . -B build
cmake --build build
```
vcpkg
!!! abstract "Summary"
package: [**`nlohmann-json`**](https://github.com/Microsoft/vcpkg/tree/master/ports/nlohmann-json)
- [](https://repology.org/project/nlohmann-json/versions)
- :octicons-tag-24: Available versions: current version
- :octicons-rocket-24: The package is updated with every release.
- :octicons-file-24: File issues at the [vcpkg issue tracker](https://github.com/microsoft/vcpkg/issues)
- :octicons-question-24: [vcpkg website](https://vcpkg.io/)
If you are using vcpkg on your project for external dependencies, then you can install the nlohmann-json package with
vcpkg install nlohmann-json
and follow the then displayed descriptions. Please see the vcpkg project for any issues regarding the packaging.
??? example
1. Create the following files:
```cmake title="CMakeLists.txt"
--8<-- "integration/vcpkg/CMakeLists.txt"
```
```cpp title="example.cpp"
--8<-- "integration/vcpkg/example.cpp"
```
2. Install package:
```sh
vcpkg install nlohmann-json
```
3. Build:
```sh
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build build
```
cget
!!! abstract "Summary"
package: [**`nlohmann/json`**](https://github.com/pfultz2/cget-recipes/blob/master/recipes/nlohmann/json/package.txt)
- :octicons-tag-24: Available versions: current version and older versions
- :octicons-rocket-24: The package is updated with every release.
- :octicons-file-24: File issues at the [cget issue tracker](https://github.com/pfultz2/cget-recipes/issues)
- :octicons-question-24: [cget website](https://cget.readthedocs.io/)
If you are using cget, you can install the latest master version with
cget install nlohmann/json
A specific version can be installed with cget install nlohmann/json@v3.12.0. Also, the multiple header version can be
installed by adding the -DJSON_MultipleHeaders=ON flag (i.e., cget install nlohmann/json -DJSON_MultipleHeaders=ON).
??? example
1. Create the following files:
```cmake title="CMakeLists.txt"
--8<-- "integration/vcpkg/CMakeLists.txt"
```
```cpp title="example.cpp"
--8<-- "integration/vcpkg/example.cpp"
```
2. Initialize cget
```shell
cget init
```
3. Install the library
```shell
cget install nlohmann/json
```
4. Build
```shell
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=cget/cget/cget.cmake
cmake --build build
```
Swift Package Manager
!!! abstract "Summary"
package: **`nlohmann/json`**
- :octicons-tag-24: Available versions: current version and older versions
- :octicons-rocket-24: The package is updated with every release.
- :octicons-file-24: File issues at the [library issue tracker](https://github.com/nlohmann/json/issues)
- :octicons-question-24: [Xcode documentation](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app)
NuGet
!!! abstract "Summary"
package: [**`nlohmann.json`**](https://www.nuget.org/packages/nlohmann.json/)
- :octicons-tag-24: Available versions: current and previous versions
- :octicons-rocket-24: The package is updated with every release.
- :octicons-person-24: Maintainer: [Hani Kaabi](https://github.com/hnkb)
- :octicons-file-24: File issues at the [maintainer's issue tracker](https://github.com/hnkb/nlohmann-json-nuget/issues)
- :octicons-question-24: [NuGet website](https://www.nuget.org)
If you are using NuGet, you can use the package nlohmann.json with
dotnet add package nlohmann.json
??? example
Probably the easiest way to use NuGet packages is through Visual Studio graphical interface. Right-click on a
project (any C++ project would do) in “Solution Explorer” and select “Manage NuGet Packages…”
Now you can click on “Browse” tab and find the package you like to install.
Most of the packages in NuGet gallery are .NET packages and would not be useful in a C++ project. Microsoft
recommends adding “native” and “nativepackage” tags to C++ NuGet packages to distinguish them, but even adding
“native” to search query would still show many .NET-only packages in the list.
Nevertheless, after finding the package you want, click on “Install” button and accept confirmation dialogs.
After the package is successfully added to the projects, you should be able to build and execute the project
without the need for making any more changes to build settings.
!!! note
A few notes:
- NuGet packages are installed per project and not system-wide. The header and binaries for the package are only
available to the project it is added to, and not other projects (obviously unless we add the package to those
projects as well)
- One of the many great things about your elegant work is that it is a header-only library, which makes
deployment very straightforward. In case of libraries which need binary deployment (`.lib`, `.dll` and `.pdb`
for debug info) the different binaries for each supported compiler version must be added to the NuGet package.
Some library creators cram binary versions for all supported Visual C++ compiler versions in the same package,
so a single package will support all compilers. Some others create a different package for each compiler
version (and you usually see things like “v140” or “vc141” in package name to clarify which VC++ compiler this
package supports).
- Packages can have dependency to other packages, and in this case, NuGet will install all dependencies as well
as the requested package recursively.
**What happens behind the scenes**
After you add a NuGet package, three changes occur in the project source directory. Of course, we could make these
changes manually instead of using GUI:
1. A `packages.config` file will be created (or updated to include the package name if one such file already
exists). This file contains a list of the packages required by this project (name and minimum version) and must
be added to the project source code repository, so if you move the source code to a new machine, MSBuild/NuGet
knows which packages it has to restore (which it does automatically before each build).
```xml
<?xml version="1.0" encoding="utf-8"?>
<packages>
<package id="nlohmann.json" version="3.5.0" targetFramework="native" />
</packages>
```
2. A `packages` folder which contains actual files in the packages (these are header and binary files required for
a successful build, plus a few metadata files). In case of this library for example, it contains `json.hpp`:
!!! note
This directory should not be added to the project source code repository, as it will be restored before each
build by MSBuild/NuGet. If you go ahead and delete this folder, then build the project again, it will
magically re-appear!
3. Project MSBuild makefile (which for Visual C++ projects has a .vcxproj extension) will be updated to include
settings from the package.
The important bit for us here is line 170, which tells MSBuild to import settings from
`packages\nlohmann.json.3.5.0\build\native\nlohmann.json.targets` file. This is a file the package creator
created and added to the package (you can see it is one of the two files I created in this repository, the other
just contains package attributes like name and version number). What does it contain?
For our header-only repository, the only setting we need is to add our include directory to the list of
`AdditionalIncludeDirectories`:
```xml
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<ItemDefinitionGroup>
<ClCompile>
<AdditionalIncludeDirectories>$(MSBuildThisFileDirectory)include;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
</ClCompile>
</ItemDefinitionGroup>
</Project>
```
For libraries with binary files, we will need to add `.lib` files to linker inputs and add settings to copy
`.dll` and other redistributable files to output directory, if needed.
There are other changes to the makefile as well:
- Lines 165-167 add the `packages.config` as one of project files (so it is shown in Solution Explorer tree
view). It is added as None (no build action) and removing it wouldn’t affect build.
- Lines 172-177 check to ensure the required packages are present. This will display a build error if package
directory is empty (for example when NuGet cannot restore packages because Internet connection is down).
Again, if you omit this section, the only change in build would be a more cryptic error message if build
fails.
!!! note
Changes to .vcxproj makefile should also be added to project source code repository.
As you can see, the mechanism NuGet uses to modify project settings is through MSBuild makefiles, so using NuGet
with other build systems and compilers (like CMake) as a dependency manager is either impossible or more problematic
than useful.
Please refer to this extensive description for more information.
Conda
!!! abstract "Summary"
package: [**`nlohmann_json`**](https://anaconda.org/conda-forge/nlohmann_json)
- 
- :octicons-tag-24: Available versions: current and previous versions
- :octicons-rocket-24: The package is updated with every release.
- :octicons-file-24: File issues at the [feedstock's issue tracker](https://github.com/conda-forge/nlohmann_json-feedstock/issues)
- :octicons-question-24: [Conda documentation](https://docs.conda.io/projects/conda/en/stable/user-guide/getting-started.html)
If you are using conda, you can use the package nlohmann_json from conda-forge executing
conda install -c conda-forge nlohmann_json
??? example
1. Create the following file:
```cpp title="example.cpp"
--8<-- "integration/conda/example.cpp"
```
2. Create and activate an environment `json`:
```shell
conda create -n json
conda activate json
```
3. Install the package:
```shell
conda install -c conda-forge nlohmann_json
```
4. Build the code:
```shell
g++ -std=c++11 -I$(conda info --base)/envs/json/include example.cpp -o example
```
MSYS2
If you are using MSYS2, you can use the mingw-w64-nlohmann-json package, type pacman -S mingw-w64-i686-nlohmann-json or pacman -S mingw-w64-x86_64-nlohmann-json for installation. Please file issues here if you experience problems with the packages.
:material-update: The package is updated automatically.
MacPorts
!!! abstract "Summary"
port: [**`nlohmann-json`**](https://ports.macports.org/port/nlohmann-json/)
- [](https://repology.org/project/nlohmann-json/versions)
- :octicons-tag-24: Available versions: current version
- :octicons-rocket-24: The port is updated with every release.
- :octicons-file-24: File issues at the [MacPorts issue tracker](https://trac.macports.org/newticket?port=nlohmann-json)
- :octicons-question-24: [MacPorts website](https://www.macports.org)
If you are using MacPorts, execute
sudo port install nlohmann-json
to install the nlohmann-json package.
??? example "Example: Raw compilation"
1. Create the following file:
```cpp title="example.cpp"
--8<-- "integration/macports/example.cpp"
```
2. Install the package:
```sh
sudo port install nlohmann-json
```
3. Compile the code and pass the MacPorts prefix to the include path such that the library can be found:
```sh
c++ example.cpp -I/opt/local/include -std=c++11 -o example
```
??? example "Example: CMake"
1. Create the following files:
```cpp title="example.cpp"
--8<-- "integration/macports/example.cpp"
```
```cmake title="CMakeLists.txt"
--8<-- "integration/macports/CMakeLists.txt"
```
2. Install the package:
```sh
sudo port install nlohmann-json
```
3. Compile the code:
```sh
cmake -S . -B build
cmake --build build
```
build2
!!! abstract "Summary"
package: **`nlohmann-json`**
library target: **`nlohmann-json%lib{json}`**
available in package repositories:
- [`cppget.org` (recommended)](https://cppget.org/nlohmann-json)
- [package's sources (for advanced users)](https://github.com/build2-packaging/nlohmann-json/)
- :octicons-tag-24: Available versions: current version and older versions since `3.7.3` (see [cppget.org](https://cppget.org/nlohmann-json))
- :octicons-rocket-24: The package is maintained and published by the `build2` community in [this repository](https://github.com/build2-packaging/nlohmann-json/).
- :octicons-file-24: File issues at the [package source repository](https://github.com/build2-packaging/nlohmann-json/issues/)
- :octicons-question-24: [`build2` website](https://build2.org)
Note: build2 should not be considered as a standalone package-manager. It is a build-system + package manager + project manager, a set of tools that work hand-in-hand. build2-based projects do not rely on existing CMake scripts and the build scripts defining the project's targets are specific to build2.
To use this package in an existing build2 project, the general steps are:
-
Make the package available to download from a package repository that provides it.
Your project's
repositories.manifestspecifies where the package manager will try to acquire packages by default. Make sure one of the repositories specified in this file providesnlohmann-jsonpackage. The recommended open-source repository iscppget.org.If the project has been created using
bdep new,cppget.orgis already specified inrepositories.manifestbut commented, just uncomment these lines:: role: prerequisite location: https://pkg.cppget.org/1/stable -
Add this package as dependency of your project.
In your project's
manifestadd the dependency to the package usingdepends: nlohmann-json. You could also add some version constraints. For example, to depend on the latest version available:depends: nlohmann-json -
Add this library as dependency of your target that uses it.
In the
buildfiledefining the target that will use this library:-
import the target
lib{json}from thenlohmann-jsonpackage, for example:import nljson = nlohmann-json%lib{json} -
then add the library's target as requirement for your target using it, for example:
exe{example} : ... $nljson
-
-
Use the library in your project's code and build it.
At this point, assuming your project is initialized in a build-configuration, any
borbdep updatecommand that will update/build the project will also acquire the missing dependency automatically, then build it and link it with your target.If you just want to synchronize dependencies for all your configurations to download the ones you just added:
bdep sync -af
??? example "Example: from scratch, using build2's bdep new command"
1. Create a new executable project "example" (see [`bdep new` command details](https://build2.org/bdep/doc/bdep-new.xhtml) for the various options to create a new project):
```shell
bdep new example
```
2. Edit these files by replacing their content:
- `example/repositories.manifest`: Enable acquiring packages from https://cppget.org by uncommenting the related lines:
```make title="project's `repositories.manifest`"
--8<-- "integration/build2/repositories.manifest"
```
- `example/manifest`: Add the latest version of the `nlohmann-json` package as dependency to the project:
```make title="project's `manifest`"
--8<-- "integration/build2/manifest"
```
- `example/example/buildfile`: import the library's target to be used as requirement for building the executable target `exe{example}`:
```make title="project's `buildfile`"
--8<-- "integration/build2/buildfile"
```
- `example/example/example.cxx`: `bdep new` generates a "hello world" by default, replace it by this:
```cpp title="example.cxx"
--8<-- "integration/build2/example.cpp"
```
- `example/example/testscript`: (optional) if you want to be able to test that executable's output is correct using `b test`:
```cpp title="`testscript` checking the output of the program"
--8<-- "integration/build2/testscript"
```
3. Initialize the project in a default C/C++ build configuration directory, then build and test:
```shell
cd example/
# create default C/C++ build configuration in ../example-myconfig/, initialize the project in it (downloads it's dependencies in it too)
bdep init -C @myconfig cc
# build only,
b
# or build and test the executable's output, will only work if the `testscript` is correct
b test
```
CPM.cmake
!!! abstract "Summary"
package: **`gh:nlohmann/json`**
- :octicons-tag-24: Available versions: current and previous versions
- :octicons-rocket-24: The package is updated with every release.
- :octicons-file-24: File issues at the [CPM.cmake issue tracker](https://github.com/cpm-cmake/CPM.cmake/issues)
- :octicons-question-24: [CPM.cmake website](https://github.com/cpm-cmake/CPM.cmake)
If you are using CPM.cmake, add the
CPM.cmake script and the following snippet to your CMake project:
CPMAddPackage("gh:nlohmann/json@3.12.0")
??? example
1. Create the following files:
```cpp title="example.cpp"
--8<-- "integration/cpm/example.cpp"
```
```cmake title="CMakeLists.txt"
--8<-- "integration/cpm/CMakeLists.txt"
```
2. Download CPM.cmake
```shell
mkdir -p cmake
wget -O cmake/CPM.cmake https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake
```
3. Build
```shell
cmake -S . -B build
cmake --build build
```
xmake
!!! abstract "Summary"
package: [**`nlohmann_json`**](https://github.com/xmake-io/xmake-repo/blob/master/packages/n/nlohmann_json/xmake.lua)
- :octicons-tag-24: Available versions: current and previous versions
- :octicons-rocket-24: The package is updated with every release.
- :octicons-file-24: File issues at the [xmake issue tracker](https://github.com/xmake-io/xmake-repo/issues)
- :octicons-question-24: [xmake website](https://xmake.io/#/)
??? example
1. Create the following files:
```cpp title="example.cpp"
--8<-- "integration/xmake/example.cpp"
```
```lua title="xmake.lua"
--8<-- "integration/xmake/xmake.lua"
```
2. Build
```shell
xmake
```
3. Run
```shell
xmake run
```
Other package managers
The library is also contained in many other package repositories: 
??? example "Package version overview"
[](https://repology.org/project/nlohmann-json/versions)
Buckaroo
If you are using Buckaroo, you can install this library's module with buckaroo add github.com/buckaroo-pm/nlohmann-json. There is a demo repo here.
!!! warning
The module is outdated as the respective [repository](https://github.com/buckaroo-pm/nlohmann-json) has not been
updated in years.
CocoaPods
If you are using CocoaPods, you can use the library by adding pod "nlohmann_json", '~>3.1.2'
to your podfile (see an example). Please file issues
here.
npm
This project does not publish an official npm package. The npm package
nlohmann-json (or similarly named packages) is not maintained or
endorsed by this project. Use one of the package managers listed above, or integrate the single header directly.
ESP-IDF and PlatformIO
There is no official package published to the ESP-IDF Component Registry or the
PlatformIO Registry. A community-maintained fork,
Johboh/nlohmann-json, publishes this library to both registries on each
new release and can be used as an unofficial component/package for ESP-IDF and PlatformIO projects. As the library
is header-only, it can otherwise be used directly by adding its include/ directory to your component's/project's
include paths, like any other integration method described on this page.
!!! warning
The module is outdated as the respective [pod](https://cocoapods.org/pods/nlohmann_json) has not been updated in years.