amorfo77/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-10-04 05:30:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

deploy: 63c10a51fc

Browse Source
This commit is contained in:
nlohmann
2026-10-03 05:43:12 +00:00
parent 2aaa1d24ef
commit a410b4f40f
741 changed files with 8115 additions and 2252 deletions
Download Patch File Download Diff File Expand all files Collapse all files
integration/package_managers.md
+130 -145
View File
@@ -31,13 +31,17 @@ When executed, this program should create output similar to
--8<-- "examples/meta.output"
```
Many of the package managers below install a CMake package configuration that exposes the same
`nlohmann_json::nlohmann_json` interface target described in [CMake](cmake.md); their CMake examples below link
against that target.
## Homebrew
!!! abstract "Summary"
formula: [**`nlohmann-json`**](https://formulae.brew.sh/formula/nlohmann-json)
- [![Homebrew package](https://repology.org/badge/version-for-repo/homebrew/nlohmann-json.svg)](https://repology.org/project/nlohmann-json/versions)
- [![Homebrew package](https://img.shields.io/homebrew/v/nlohmann-json)](https://formulae.brew.sh/formula/nlohmann-json)
- :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
@@ -121,8 +125,8 @@ 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
which case a [pkg-config](pkg-config.md) 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()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a subproject fallback, rather than
using the subproject directly.
@@ -165,7 +169,7 @@ using the subproject directly.
This repository provides a [Bazel](https://bazel.build/) `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
??? example "Example: Bazel module with `bazel_dep`"
1. Create the following files:
@@ -173,7 +177,7 @@ repository can be referenced within a `MODULE.bazel` by rules such as `archive_o
--8<-- "integration/bazel/BUILD"
```
```ini title="WORKSPACE"
```ini title="MODULE.bazel"
--8<-- "integration/bazel/MODULE.bazel"
```
@@ -194,7 +198,7 @@ repository can be referenced within a `MODULE.bazel` by rules such as `archive_o
recipe: [**`nlohmann_json`**](https://conan.io/center/recipes/nlohmann_json)
- [![ConanCenter package](https://repology.org/badge/version-for-repo/conancenter/nlohmann-json.svg)](https://repology.org/project/nlohmann-json/versions)
- [![ConanCenter package](https://img.shields.io/conan/v/nlohmann_json)](https://conan.io/center/recipes/nlohmann_json)
- :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
@@ -205,7 +209,7 @@ repository can be referenced within a `MODULE.bazel` by rules such as `archive_o
If you are using [Conan](https://www.conan.io/) 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
??? example "Example: CMake with the Conan toolchain"
1. Create the following files:
@@ -240,7 +244,7 @@ requires, where `x.y.z` is the release version you want to use.
package: [**`nlohmann-json`**](https://packages.spack.io/package.html?name=nlohmann-json)
- [![Spack package](https://repology.org/badge/version-for-repo/spack/nlohmann-json.svg)](https://repology.org/project/nlohmann-json/versions)
- [![Spack package](https://img.shields.io/spack/v/nlohmann-json)](https://packages.spack.io/package.html?name=nlohmann-json)
- :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.
@@ -257,7 +261,7 @@ spack install nlohmann-json
Please see the [Spack project](https://github.com/spack/spack) for any issues regarding the packaging.
??? example
??? example "Example: CMake with a Spack-installed package"
1. Create the following files:
@@ -309,7 +313,7 @@ hunter_add_package(nlohmann_json)
Please see the Hunter project for any issues regarding the packaging.
??? example
??? example "Example: CMake with HunterGate"
1. Create the following files:
@@ -341,7 +345,7 @@ Please see the Hunter project for any issues regarding the packaging.
package: [**`nlohmann-json`**](https://github.com/Microsoft/vcpkg/tree/master/ports/nlohmann-json)
- [![Vcpkg package](https://repology.org/badge/version-for-repo/vcpkg/nlohmann-json.svg)](https://repology.org/project/nlohmann-json/versions)
- [![vcpkg package](https://img.shields.io/vcpkg/v/nlohmann-json)](https://vcpkg.io/en/package/nlohmann-json)
- :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)
@@ -356,7 +360,7 @@ vcpkg install nlohmann-json
and follow the then displayed descriptions. Please see the vcpkg project for any issues regarding the packaging.
??? example
??? example "Example: CMake with the vcpkg toolchain"
1. Create the following files:
@@ -401,16 +405,16 @@ 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
??? example "Example: CMake with the cget toolchain"
1. Create the following files:
```cmake title="CMakeLists.txt"
--8<-- "integration/vcpkg/CMakeLists.txt"
--8<-- "integration/cget/CMakeLists.txt"
```
```cpp title="example.cpp"
--8<-- "integration/vcpkg/example.cpp"
--8<-- "integration/cget/example.cpp"
```
2. Initialize cget
@@ -443,6 +447,58 @@ installed by adding the `-DJSON_MultipleHeaders=ON` flag (i.e., `cget install nl
- :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)
If you are using the [Swift Package Manager](https://www.swift.org/documentation/package-manager/), add this
repository as a package dependency and depend on its `json` product:
```swift
dependencies: [
.package(url: "https://github.com/nlohmann/json", from: "3.12.0")
],
targets: [
.target(name: "MyTarget", dependencies: [.product(name: "json", package: "json")])
]
```
The library's own [`Package.swift`](https://github.com/nlohmann/json/blob/develop/Package.swift) publishes
`single_include/nlohmann` (not `single_include`) as the public headers directory, so include the header without the
`nlohmann/` prefix:
```cpp
#include <json.hpp>
```
??? example "Example: a minimal executable package"
1. Create the following files (the source file goes into `Sources/json_example/`, following Swift Package
Manager's directory layout convention):
```swift title="Package.swift"
--8<-- "integration/swift/Package.swift"
```
```cpp title="Sources/json_example/example.cpp"
--8<-- "integration/swift/example.cpp"
```
2. Build and run:
```shell
swift run --build-system native
```
!!! warning
On some toolchains, `swift run`/`swift build` fail to link an **executable** target against the header-only
`json` product with an error such as `Build input file cannot be found: '.../json.o'`, because the product
itself has no compiled sources; see [#4650](https://github.com/nlohmann/json/issues/4650) and the upstream
[Swift Package Manager issue](https://github.com/swiftlang/swift-package-manager/issues/5706). Passing
`--build-system native` (shown above) selects Swift Package Manager's legacy build system, which does not
have this problem; depending on the library from a *library* target instead of an executable is not affected
either.
You can also add the dependency from within Xcode via **File → Add Package Dependencies…** and the same repository
URL; see [Apple's documentation](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).
## NuGet
!!! abstract "Summary"
@@ -462,119 +518,28 @@ with
dotnet add package nlohmann.json
```
??? example
NuGet integrates with C++ projects through MSBuild, so it is mainly useful for Visual Studio/MSBuild projects; using
it as a dependency from other build systems, such as CMake, is possible but more cumbersome than the other package
managers on this page.
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…”
??? example "Example: Visual Studio project"
![](nuget/nuget-search-package.png)
1. Right-click the project (any C++ project) in "Solution Explorer" and select "Manage NuGet Packages…"
Now you can click on “Browse” tab and find the package you like to install.
![Right-clicking a project in Solution Explorer and selecting "Manage NuGet Packages…"](nuget/nuget-search-package.png)
![](nuget/nuget-select-package.png)
2. Switch to the "Browse" tab.
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.
3. Search for `nlohmann.json`, select it, and click "Install".
!!! note
![Searching for and selecting the nlohmann.json package in the NuGet package manager](nuget/nuget-select-package.png)
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.
4. `#include <nlohmann/json.hpp>` in your code and build the project. The package's
`build/native/nlohmann.json.targets` file adds `$(MSBuildThisFileDirectory)include` to the project's
`AdditionalIncludeDirectories`, so no further include path configuration is needed.
**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:
![](nuget/nuget-project-changes.png)
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`:
![](nuget/nuget-package-content.png)
!!! 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.
![](nuget/nuget-project-makefile.png)
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](https://github.com/nlohmann/json/issues/1132#issuecomment-452250255) for
more information.
For further details, see the [original discussion](https://github.com/nlohmann/json/issues/1132#issuecomment-452250255)
this section is based on.
## Conda
@@ -582,7 +547,7 @@ more information.
package: [**`nlohmann_json`**](https://anaconda.org/conda-forge/nlohmann_json)
- ![](https://img.shields.io/conda/v/conda-forge/nlohmann_json)
- [![Conda package](https://img.shields.io/conda/v/conda-forge/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)
@@ -595,7 +560,7 @@ If you are using [conda](https://conda.io/), you can use the package
conda install -c conda-forge nlohmann_json
```
??? example
??? example "Example: Raw compilation"
1. Create the following file:
@@ -624,14 +589,37 @@ conda install -c conda-forge nlohmann_json
## MSYS2
If you are using [MSYS2](http://www.msys2.org/), you can use the [mingw-w64-nlohmann-json](https://packages.msys2.org/base/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](https://github.com/msys2/MINGW-packages/issues/new?title=%5Bnlohmann-json%5D) if you experience problems with the packages.
!!! abstract "Summary"
[![MSYS2 clang64 package](https://repology.org/badge/version-for-repo/msys2_clang64/nlohmann-json.svg)](https://repology.org/project/nlohmann-json/versions)
[![MSYS2 clangarm64 package](https://repology.org/badge/version-for-repo/msys2_clangarm64/nlohmann-json.svg)](https://repology.org/project/nlohmann-json/versions)
[![MSYS2 mingw package](https://repology.org/badge/version-for-repo/msys2_mingw/nlohmann-json.svg)](https://repology.org/project/nlohmann-json/versions)
[![MSYS2 ucrt64 package](https://repology.org/badge/version-for-repo/msys2_ucrt64/nlohmann-json.svg)](https://repology.org/project/nlohmann-json/versions)
package: [**`mingw-w64-nlohmann-json`**](https://packages.msys2.org/base/mingw-w64-nlohmann-json)
:material-update: The [package](https://packages.msys2.org/base/mingw-w64-nlohmann-json) is updated automatically.
- [![MSYS2 package](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpackages.msys2.org%2Fapi%2Fsearch%3Fquery%3Dnlohmann-json%26qtype%3Dpkg&query=%24.results.exact.version&label=msys2&prefix=v)](https://packages.msys2.org/base/mingw-w64-nlohmann-json)
- :octicons-rocket-24: The [package](https://packages.msys2.org/base/mingw-w64-nlohmann-json) is updated automatically.
- :octicons-file-24: File issues at the [MINGW-packages issue tracker](https://github.com/msys2/MINGW-packages/issues/new?title=%5Bnlohmann-json%5D)
- :octicons-question-24: [MSYS2 website](http://www.msys2.org/)
If you are using [MSYS2](http://www.msys2.org/), you can use the [mingw-w64-nlohmann-json](https://packages.msys2.org/base/mingw-w64-nlohmann-json)
package; type `pacman -S mingw-w64-i686-nlohmann-json` or `pacman -S mingw-w64-x86_64-nlohmann-json` for installation.
??? example "Example: Raw compilation"
1. Create the following file:
```cpp title="example.cpp"
--8<-- "integration/msys2/example.cpp"
```
2. Install the package (from an MSYS2 MinGW 64-bit shell):
```shell
pacman -S mingw-w64-x86_64-nlohmann-json
```
3. Compile the code:
```shell
g++ example.cpp -std=c++11 -o example
```
## MacPorts
@@ -639,7 +627,7 @@ If you are using [MSYS2](http://www.msys2.org/), you can use the [mingw-w64-nloh
port: [**`nlohmann-json`**](https://ports.macports.org/port/nlohmann-json/)
- [![MacPorts package](https://repology.org/badge/version-for-repo/macports/nlohmann-json.svg)](https://repology.org/project/nlohmann-json/versions)
- [![MacPorts package](https://img.shields.io/macports/v/nlohmann-json)](https://ports.macports.org/port/nlohmann-json/)
- :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)
@@ -841,7 +829,7 @@ If you are using [`CPM.cmake`](https://github.com/TheLartians/CPM.cmake), add th
CPMAddPackage("gh:nlohmann/json@3.12.0")
```
??? example
??? example "Example: CMake with `CPMAddPackage`"
1. Create the following files:
@@ -878,7 +866,7 @@ CPMAddPackage("gh:nlohmann/json@3.12.0")
- :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
??? example "Example: xmake project"
1. Create the following files:
@@ -906,18 +894,14 @@ CPMAddPackage("gh:nlohmann/json@3.12.0")
## Other package managers
The library is also contained in many other package repositories: [![Packaging status](https://repology.org/badge/tiny-repos/nlohmann-json.svg)](https://repology.org/project/nlohmann-json/versions)
??? example "Package version overview"
[![Packaging status](https://repology.org/badge/vertical-allrepos/nlohmann-json.svg)](https://repology.org/project/nlohmann-json/versions)
The library is also contained in many other package repositories; [Repology](https://repology.org/project/nlohmann-json/versions) tracks the packaged
versions across repositories.
* * *
## Buckaroo
If you are using [Buckaroo](https://buckaroo.pm), you can install this library's module with `buckaroo add github.com/buckaroo-pm/nlohmann-json`. There is a demo repo [here](https://github.com/njlr/buckaroo-nholmann-json-example).
If you are using [Buckaroo](https://github.com/LoopPerfect/buckaroo), you can install this library's module with `buckaroo add github.com/buckaroo-pm/nlohmann-json`. There is a demo repo [here](https://github.com/njlr/buckaroo-nholmann-json-example).
!!! warning
@@ -928,7 +912,14 @@ If you are using [Buckaroo](https://buckaroo.pm), you can install this library's
If you are using [CocoaPods](https://cocoapods.org), you can use the library by adding pod `"nlohmann_json", '~>3.1.2'`
to your podfile (see [an example](https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/)). Please file issues
[here](https://bitbucket.org/benman/nlohmann_json-cocoapod/issues?status=new&status=open).
at [the repository](https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/), as its issue tracker is no longer
reachable.
[![CocoaPods package](https://img.shields.io/cocoapods/v/nlohmann_json)](https://cocoapods.org/pods/nlohmann_json)
!!! warning
The module is outdated as the respective [pod](https://cocoapods.org/pods/nlohmann_json) has not been updated in years.
## npm
@@ -944,9 +935,3 @@ There is no official package published to the [ESP-IDF Component Registry](https
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.
![](https://img.shields.io/cocoapods/v/nlohmann_json)
!!! warning
The module is outdated as the respective [pod](https://cocoapods.org/pods/nlohmann_json) has not been updated in years.