json/integration/package_managers.md

# Package Managers

<p markdown style="text-align: center">
![Homebrew](../images/package_managers/homebrew.svg){: style="height:1em"}&nbsp;[**Homebrew**](#homebrew) `nlohmann-json` &emsp;
![Meson](../images/package_managers/meson.svg){: style="height:1em"}&nbsp;[**Meson**](#meson) `nlohmann_json` &emsp;
![Bazel](../images/package_managers/bazel.svg){: style="height:1em"}&nbsp;[**Bazel**](#bazel) `nlohmann_json`<br>
![Conan](../images/package_managers/conan.svg){: style="height:1em"}&nbsp;[**Conan**](#conan) `nlohmann_json` &emsp;
![Spack](../images/package_managers/spack.svg){: style="height:1em"}&nbsp;[**Spack**](#spack) `nlohmann-json` &emsp;
[**Hunter**](#hunter) `nlohmann_json`<br>
![vcpkg](../images/package_managers/vcpkg.png){: style="height:1em"}&nbsp;[**vcpkg**](#vcpkg) `nlohmann-json` &emsp;
[**cget**](#cget) `nlohmann/json` &emsp;
![Swift Package Manager](../images/package_managers/swift.svg){: style="height:1em"}&nbsp;[**Swift Package Manager**](#swift-package-manager) `nlohmann/json`<br>
![Nuget](../images/package_managers/nuget.svg){: style="height:1em"}&nbsp;[**NuGet**](#nuget) `nlohmann.json` &emsp;
![Conda](../images/package_managers/conda.svg){: style="height:1em"}&nbsp;[**Conda**](#conda) `nlohmann_json` &emsp;
![MacPorts](../images/package_managers/macports.svg){: style="height:1em"}&nbsp;[**MacPorts**](#macports) `nlohmann-json`<br>
![cpm.cmake](../images/package_managers/CPM.png){: style="height:1em"}&nbsp;[**CPM.cmake**](#cpmcmake) `gh:nlohmann/json` &emsp;
![xmake](../images/package_managers/xmake.svg){: style="height:1em"}&nbsp;[**xmake**](#xmake) `nlohmann_json`
</p>

## Running example

Throughout this page, we will describe how to compile the example file `example.cpp` below.

```cpp
--8<-- "integration/example.cpp"
```

When executed, this program should create output similar to

```json
--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://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
    - :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](http://brew.sh), you can install the library with

```sh
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](http://mesonbuild.com), add this source tree as a [meson subproject](https://mesonbuild.com/Subprojects.html#using-a-subproject). You may also use the
`include.zip` published in this project's [Releases](https://github.com/nlohmann/json/releases) to reduce the size of the vendored source tree. Alternatively,
you can get a wrap file by downloading it from [Meson WrapDB](https://mesonbuild.com/Wrapdb-projects.html), or use

```shell
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](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.

??? 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](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: Bazel module with `bazel_dep`"

    1. Create the following files:

        ```ini title="BUILD"
        --8<-- "integration/bazel/BUILD"
        ```

        ```ini title="MODULE.bazel"
        --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)

    - [![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
      [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](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: CMake with the Conan toolchain"

    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)

    - [![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.
    - :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](https://www.spack.io/) to manage your dependencies, you can use the
[`nlohmann-json` package](https://packages.spack.io/package.html?name=nlohmann-json) via

```shell
spack install nlohmann-json
```

Please see the [Spack project](https://github.com/spack/spack) for any issues regarding the packaging.

??? example "Example: CMake with a Spack-installed package"

    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](https://github.com/cpp-pm/hunter) on your project for external dependencies, then you can use
the [nlohmann_json package](https://hunter.readthedocs.io/en/latest/packages/pkg/nlohmann_json.html) via

```cmake
hunter_add_package(nlohmann_json)
```

Please see the Hunter project for any issues regarding the packaging.

??? example "Example: CMake with HunterGate"

    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)

    - [![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)
    - :octicons-question-24: [vcpkg website](https://vcpkg.io/)

If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project for external dependencies, then you can
install the [nlohmann-json package](https://github.com/Microsoft/vcpkg/tree/master/ports/nlohmann-json) with

```shell
vcpkg install nlohmann-json
```

and follow the then displayed descriptions. Please see the vcpkg project for any issues regarding the packaging.

??? example "Example: CMake with the vcpkg toolchain"

    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](http://cget.readthedocs.io/en/latest/), you can install the latest `master` version with

```shell
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: CMake with the cget toolchain"

    1. Create the following files:

        ```cmake title="CMakeLists.txt"
        --8<-- "integration/cget/CMakeLists.txt"
        ```
    
        ```cpp title="example.cpp"
        --8<-- "integration/cget/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)

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"

    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](https://www.nuget.org), you can use the package [nlohmann.json](https://www.nuget.org/packages/nlohmann.json/)
with

```shell
dotnet add package nlohmann.json
```

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.

??? example "Example: Visual Studio project"

    1. Right-click the project (any C++ project) in "Solution Explorer" and select "Manage NuGet Packages…"

        ![Right-clicking a project in Solution Explorer and selecting "Manage NuGet Packages…"](nuget/nuget-search-package.png)

    2. Switch to the "Browse" tab.

    3. Search for `nlohmann.json`, select it, and click "Install".

        ![Searching for and selecting the nlohmann.json package in the NuGet package manager](nuget/nuget-select-package.png)

    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.

For further details, see the [original discussion](https://github.com/nlohmann/json/issues/1132#issuecomment-452250255)
this section is based on.

## Conda

!!! abstract "Summary"

    package: [**`nlohmann_json`**](https://anaconda.org/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)
    - :octicons-question-24: [Conda documentation](https://docs.conda.io/projects/conda/en/stable/user-guide/getting-started.html)

If you are using [conda](https://conda.io/), you can use the package
[nlohmann_json](https://anaconda.org/conda-forge/nlohmann_json) from [conda-forge](https://conda-forge.org) executing

```shell
conda install -c conda-forge nlohmann_json
```

??? example "Example: Raw compilation"

    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

!!! abstract "Summary"

    package: [**`mingw-w64-nlohmann-json`**](https://packages.msys2.org/base/mingw-w64-nlohmann-json)

    - [![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

!!! abstract "Summary"

    port: [**`nlohmann-json`**](https://ports.macports.org/port/nlohmann-json/)

    - [![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)
    - :octicons-question-24: [MacPorts website](https://www.macports.org)

If you are using [MacPorts](https://ports.macports.org), execute 

```shell
sudo port install nlohmann-json
```

to install the [nlohmann-json](https://ports.macports.org/port/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`](https://build2.org) 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`](https://build2.org) project, the general steps are:

  1. <details><summary>Make the package available to download from a package repository that provides it.</summary>

      Your project's `repositories.manifest` specifies where the package manager will try to acquire packages by default. Make sure one of the repositories specified in this file provides `nlohmann-json` package.
      The recommended open-source repository is [`cppget.org`](https://cppget.org/).

      If the project has been created using [`bdep new`](https://build2.org/bdep/doc/bdep-new.xhtml), `cppget.org` is already specified in `repositories.manifest` but commented, just uncomment these lines:
      ```
      :
      role: prerequisite
      location: https://pkg.cppget.org/1/stable
      ```
      </details>

  2. <details><summary>Add this package as dependency of your project.</summary>

       In your project's `manifest` add the dependency to the package using `depends: nlohmann-json`. You could also add some [version constraints](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml#guide-add-remove-deps).
       For example, to depend on the latest version available:
       ```
       depends: nlohmann-json
       ```
       </details>


  3. <details><summary>Add this library as dependency of your target that uses it.</summary>

      In the `buildfile` defining the target that will use this library:
      
        - import the target `lib{json}` from the `nlohmann-json` package, 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
            ```
           
      </details>

  4. <details><summary>Use the library in your project's code and build it.</summary>

      At this point, assuming your project is initialized in a build-configuration, any `b` or `bdep update` command 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
        ```
      </details>

??? example "Example: from scratch, using `build2`'s [`bdep new` command](https://build2.org/bdep/doc/bdep-new.xhtml)"

    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`](https://github.com/TheLartians/CPM.cmake), add the
[CPM.cmake script](https://github.com/TheLartians/CPM.cmake#adding-cpm) and the following snippet to your CMake project:

```cmake
CPMAddPackage("gh:nlohmann/json@3.12.0")
```

??? example "Example: CMake with `CPMAddPackage`"

    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 "Example: xmake project"

    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; [Repology](https://repology.org/project/nlohmann-json/versions) tracks the packaged
versions across repositories.

* * *

## Buckaroo

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

    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](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
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

This project does not publish an official [npm](https://www.npmjs.com) package. The npm package
[`nlohmann-json`](https://www.npmjs.com/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](https://components.espressif.com) or the
[PlatformIO Registry](https://registry.platformio.org). A community-maintained fork,
[Johboh/nlohmann-json](https://github.com/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.