mirror of
https://github.com/nlohmann/json.git
synced 2026-10-03 21:20:30 +00:00
deploy: 63c10a51fc
This commit is contained in:
nlohmann
@@ -1 +1 @@
|
||||
bazel_dep(name = "nlohmann_json", version = "3.11.3.bcr.1")
|
||||
bazel_dep(name = "nlohmann_json", version = "3.12.0.bcr.2")
|
||||
|
||||
+20
-5
@@ -5,7 +5,8 @@
|
||||
You can use the `nlohmann_json::nlohmann_json` interface target in CMake. This target populates the appropriate usage
|
||||
requirements for [`INTERFACE_INCLUDE_DIRECTORIES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.html)
|
||||
to point to the appropriate include directories and [`INTERFACE_COMPILE_FEATURES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_COMPILE_FEATURES.html)
|
||||
for the necessary C++11 flags.
|
||||
for the necessary C++11 flags. Most [package managers](package_managers.md) that provide a CMake package configuration
|
||||
for this library expose this same target.
|
||||
|
||||
### External
|
||||
|
||||
@@ -138,7 +139,7 @@ Enable [extended diagnostic messages](../home/exceptions.md#extended-diagnostic-
|
||||
!!! warning "Does not apply to a pre-installed package"
|
||||
|
||||
This option only takes effect when building nlohmann/json from source as part of your own
|
||||
CMake project (e.g. via [`FetchContent`](#fetchcontent) or [`add_subdirectory`](#external)).
|
||||
CMake project (e.g. via [`FetchContent`](#fetchcontent) or [`add_subdirectory`](#embedded)).
|
||||
It has **no effect** on a package that was already built and installed elsewhere (Homebrew,
|
||||
vcpkg, a system package, etc.) — the resulting compile definition is baked into the exported
|
||||
`nlohmann_jsonTargets.cmake` at install time, and `set(JSON_Diagnostics ON)` before
|
||||
@@ -182,15 +183,22 @@ Skip expensive/slow test suites. This option is `OFF` by default. Depends on `JS
|
||||
### `JSON_GlobalUDLs`
|
||||
|
||||
Place user-defined string literals in the global namespace by defining the macro
|
||||
[`JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md). This option is `OFF` by default.
|
||||
[`JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md). This option is `ON` by default; see the
|
||||
[migration guide](migration_guide.md#import-namespace-literals-for-udls) for how to prepare code for the next major
|
||||
release, where the literals are removed from the global namespace.
|
||||
|
||||
### `JSON_ImplicitConversions`
|
||||
|
||||
Enable implicit conversions by defining macro [`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md). This option is `ON` by default.
|
||||
Enable implicit conversions by defining macro
|
||||
[`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md). This option is `ON` by default; see
|
||||
the [migration guide](migration_guide.md#replace-implicit-conversions) for how to prepare code for the next major
|
||||
release, where implicit conversions are switched off by default.
|
||||
|
||||
### `JSON_Install`
|
||||
|
||||
Install CMake targets during install step. This option is `ON` by default if the library's CMake project is the top project.
|
||||
Install CMake targets during install step. This option is `ON` by default if the library's CMake project is the top
|
||||
project. Installing also generates a [pkg-config](pkg-config.md) file for tools that rely on `pkg-config` instead of
|
||||
CMake.
|
||||
|
||||
### `JSON_LegacyDiscardedValueComparison`
|
||||
|
||||
@@ -209,6 +217,13 @@ Treat the library headers like system headers (i.e., adding `SYSTEM` to the [`ta
|
||||
Reject a `'\0'` (NUL) byte in the input instead of treating it as end of input, by defining the macro
|
||||
[`JSON_STRICT_NUL_HANDLING`](../api/macros/json_strict_nul_handling.md). This option is `OFF` by default.
|
||||
|
||||
### `JSON_TestSimdutf`
|
||||
|
||||
Build the unit tests against the [simdutf](https://github.com/simdutf/simdutf) UTF-8 validation backend by defining
|
||||
[`JSON_USE_SIMDUTF`](../api/macros/json_use_simdutf.md) for every test target. simdutf is fetched during configuration;
|
||||
its version is set by the cache variable `JSON_SIMDUTF_VERSION`. This option is `OFF` by default. Depends on
|
||||
`JSON_BuildTests`.
|
||||
|
||||
### `JSON_Valgrind`
|
||||
|
||||
Execute the test suite with [Valgrind](https://valgrind.org). This option is `OFF` by default. Depends on `JSON_BuildTests`.
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -2,7 +2,7 @@
|
||||
|
||||
## Integration
|
||||
|
||||
You can use the `nlohmann_json::nlohmann_json` interface target in CMake. This target populates the appropriate usage requirements for [`INTERFACE_INCLUDE_DIRECTORIES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.html) to point to the appropriate include directories and [`INTERFACE_COMPILE_FEATURES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_COMPILE_FEATURES.html) for the necessary C++11 flags.
|
||||
You can use the `nlohmann_json::nlohmann_json` interface target in CMake. This target populates the appropriate usage requirements for [`INTERFACE_INCLUDE_DIRECTORIES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.html) to point to the appropriate include directories and [`INTERFACE_COMPILE_FEATURES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_COMPILE_FEATURES.html) for the necessary C++11 flags. Most [package managers](https://json.nlohmann.me/integration/package_managers/index.md) that provide a CMake package configuration for this library expose this same target.
|
||||
|
||||
### External
|
||||
|
||||
@@ -134,7 +134,7 @@ Enable [extended diagnostic messages](https://json.nlohmann.me/home/exceptions/#
|
||||
|
||||
Does not apply to a pre-installed package
|
||||
|
||||
This option only takes effect when building nlohmann/json from source as part of your own CMake project (e.g. via [`FetchContent`](#fetchcontent) or [`add_subdirectory`](#external)). It has **no effect** on a package that was already built and installed elsewhere (Homebrew, vcpkg, a system package, etc.) — the resulting compile definition is baked into the exported `nlohmann_jsonTargets.cmake` at install time, and `set(JSON_Diagnostics ON)` before `find_package()` does not change it (verified against the Homebrew-installed package: the exported target still carries a fixed `$<$<BOOL:OFF>:JSON_DIAGNOSTICS=1>`, regardless of any variable set in the consuming project).
|
||||
This option only takes effect when building nlohmann/json from source as part of your own CMake project (e.g. via [`FetchContent`](#fetchcontent) or [`add_subdirectory`](#embedded)). It has **no effect** on a package that was already built and installed elsewhere (Homebrew, vcpkg, a system package, etc.) — the resulting compile definition is baked into the exported `nlohmann_jsonTargets.cmake` at install time, and `set(JSON_Diagnostics ON)` before `find_package()` does not change it (verified against the Homebrew-installed package: the exported target still carries a fixed `$<$<BOOL:OFF>:JSON_DIAGNOSTICS=1>`, regardless of any variable set in the consuming project).
|
||||
|
||||
To enable extended diagnostics for a pre-installed package, override the imported target's property directly after `find_package()`:
|
||||
|
||||
@@ -164,15 +164,15 @@ Skip expensive/slow test suites. This option is `OFF` by default. Depends on `JS
|
||||
|
||||
### `JSON_GlobalUDLs`
|
||||
|
||||
Place user-defined string literals in the global namespace by defining the macro [`JSON_USE_GLOBAL_UDLS`](https://json.nlohmann.me/api/macros/json_use_global_udls/index.md). This option is `OFF` by default.
|
||||
Place user-defined string literals in the global namespace by defining the macro [`JSON_USE_GLOBAL_UDLS`](https://json.nlohmann.me/api/macros/json_use_global_udls/index.md). This option is `ON` by default; see the [migration guide](https://json.nlohmann.me/integration/migration_guide/#import-namespace-literals-for-udls) for how to prepare code for the next major release, where the literals are removed from the global namespace.
|
||||
|
||||
### `JSON_ImplicitConversions`
|
||||
|
||||
Enable implicit conversions by defining macro [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/index.md). This option is `ON` by default.
|
||||
Enable implicit conversions by defining macro [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/index.md). This option is `ON` by default; see the [migration guide](https://json.nlohmann.me/integration/migration_guide/#replace-implicit-conversions) for how to prepare code for the next major release, where implicit conversions are switched off by default.
|
||||
|
||||
### `JSON_Install`
|
||||
|
||||
Install CMake targets during install step. This option is `ON` by default if the library's CMake project is the top project.
|
||||
Install CMake targets during install step. This option is `ON` by default if the library's CMake project is the top project. Installing also generates a [pkg-config](https://json.nlohmann.me/integration/pkg-config/index.md) file for tools that rely on `pkg-config` instead of CMake.
|
||||
|
||||
### `JSON_LegacyDiscardedValueComparison`
|
||||
|
||||
@@ -190,6 +190,10 @@ Treat the library headers like system headers (i.e., adding `SYSTEM` to the [`ta
|
||||
|
||||
Reject a `'\0'` (NUL) byte in the input instead of treating it as end of input, by defining the macro [`JSON_STRICT_NUL_HANDLING`](https://json.nlohmann.me/api/macros/json_strict_nul_handling/index.md). This option is `OFF` by default.
|
||||
|
||||
### `JSON_TestSimdutf`
|
||||
|
||||
Build the unit tests against the [simdutf](https://github.com/simdutf/simdutf) UTF-8 validation backend by defining [`JSON_USE_SIMDUTF`](https://json.nlohmann.me/api/macros/json_use_simdutf/index.md) for every test target. simdutf is fetched during configuration; its version is set by the cache variable `JSON_SIMDUTF_VERSION`. This option is `OFF` by default. Depends on `JSON_BuildTests`.
|
||||
|
||||
### `JSON_Valgrind`
|
||||
|
||||
Execute the test suite with [Valgrind](https://valgrind.org). This option is `OFF` by default. Depends on `JSON_BuildTests`.
|
||||
|
||||
+11
-2
File diff suppressed because one or more lines are too long
+25
-1
@@ -1,4 +1,28 @@
|
||||
# Header only
|
||||
# Integration
|
||||
|
||||
There are several ways to add this header-only library to a C++ project. The following flowchart summarizes how to pick one:
|
||||
|
||||
```
|
||||
flowchart TD
|
||||
A[Add the library to a C++ project] --> B{Already using CMake?}
|
||||
B -- no --> C{Using pkg-config or plain Makefiles?}
|
||||
C -- yes --> D[pkg-config]
|
||||
C -- no --> E[Copy the single header]
|
||||
B -- yes --> F{Library installed system-wide?}
|
||||
F -- yes --> G["find_package()"]
|
||||
F -- no --> H{Use a package manager?}
|
||||
H -- yes --> I[Package manager]
|
||||
H -- no --> J["add_subdirectory() or FetchContent"]
|
||||
```
|
||||
|
||||
- **Copy the single header**, as described [below](#header-only) — no build-system integration required.
|
||||
- **CMake**: use [`find_package()`](https://json.nlohmann.me/integration/cmake/#external) if the library is already installed, [`add_subdirectory()`](https://json.nlohmann.me/integration/cmake/#embedded) to embed the source tree, or [`FetchContent`](https://json.nlohmann.me/integration/cmake/#fetchcontent) to download it at configure time; see [CMake](https://json.nlohmann.me/integration/cmake/index.md).
|
||||
- **Package managers**: install the library with a package manager such as Homebrew, Conan, or vcpkg; see [Package Managers](https://json.nlohmann.me/integration/package_managers/index.md).
|
||||
- **pkg-config**: if you use bare Makefiles instead of CMake, [pkg-config](https://json.nlohmann.me/integration/pkg-config/index.md) can supply the include flags for an already-installed library.
|
||||
|
||||
Once the library is integrated, see the [Migration Guide](https://json.nlohmann.me/integration/migration_guide/index.md) for how to keep your code future-proof across releases.
|
||||
|
||||
## Header only
|
||||
|
||||
[`json.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp) is the single required file in `single_include/nlohmann` or [released here](https://github.com/nlohmann/json/releases). You need to add
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# Migration Guide
|
||||
|
||||
This page collects some guidelines on how to future-proof your code for future versions of this library.
|
||||
This page collects some guidelines on how to future-proof your code for future versions of this library. For how to
|
||||
add the library to your project in the first place, see [Integration](index.md), [CMake](cmake.md), or
|
||||
[Package Managers](package_managers.md).
|
||||
|
||||
## Replace deprecated functions
|
||||
|
||||
@@ -9,7 +11,7 @@ deprecations are annotated with
|
||||
[`HEDLEY_DEPRECATED_FOR`](https://nemequ.github.io/hedley/api-reference.html#HEDLEY_DEPRECATED_FOR) to report which
|
||||
function to use instead.
|
||||
|
||||
#### Parsing
|
||||
### Parsing
|
||||
|
||||
- Function `friend std::istream& operator<<(basic_json&, std::istream&)` is deprecated since 3.0.0. Please use
|
||||
[`friend std::istream& operator>>(std::istream&, basic_json&)`](../api/operator_gtgt.md) instead.
|
||||
@@ -33,9 +35,11 @@ function to use instead.
|
||||
- Passing iterator pairs or pointer/length pairs to parsing functions ([`parse`](../api/basic_json/parse.md),
|
||||
[`accept`](../api/basic_json/accept.md), [`sax_parse`](../api/basic_json/sax_parse.md),
|
||||
[`from_cbor`](../api/basic_json/from_cbor.md), [`from_msgpack`](../api/basic_json/from_msgpack.md),
|
||||
[`from_ubjson`](../api/basic_json/from_ubjson.md), and [`from_bson`](../api/basic_json/from_bson.md) via initializer
|
||||
[`from_ubjson`](../api/basic_json/from_ubjson.md), and [`from_bson`](../api/basic_json/from_bson.md)) via initializer
|
||||
lists is deprecated since 3.8.0. Instead, pass two iterators; for instance, call `from_cbor(ptr, ptr+len)` instead of
|
||||
`from_cbor({ptr, len})`.
|
||||
`from_cbor({ptr, len})`. Likewise, passing a pointer and a length as two separate arguments to `from_cbor`,
|
||||
`from_msgpack`, `from_ubjson`, and `from_bson` is deprecated since 3.8.0; call `from_cbor(ptr, ptr+len)` instead of
|
||||
`from_cbor(ptr, len)`.
|
||||
|
||||
=== "Deprecated"
|
||||
|
||||
@@ -51,7 +55,7 @@ function to use instead.
|
||||
bool ok = nlohmann::json::accept(s, s + std::strlen(s));
|
||||
```
|
||||
|
||||
#### JSON Pointers
|
||||
### JSON Pointers
|
||||
|
||||
- Comparing JSON Pointers with strings via [`operator==`](../api/json_pointer/operator_eq.md) and
|
||||
[`operator!=`](../api/json_pointer/operator_ne.md) is deprecated since 3.11.2. To compare a
|
||||
@@ -93,7 +97,9 @@ function to use instead.
|
||||
|
||||
- Passing a `basic_json` specialization as template parameter `RefStringType` to
|
||||
[`json_pointer`](../api/json_pointer/index.md) is deprecated since 3.11.0. The string type can now be directly
|
||||
provided.
|
||||
provided. This also applies to passing such a JSON pointer to [`at`](../api/basic_json/at.md),
|
||||
[`contains`](../api/basic_json/contains.md), [`operator[]`](../api/basic_json/operator%5B%5D.md), and
|
||||
[`value`](../api/basic_json/value.md).
|
||||
|
||||
=== "Deprecated"
|
||||
|
||||
@@ -108,10 +114,11 @@ function to use instead.
|
||||
nlohmann::json_pointer<my_string_type> ptr("/foo/bar/1");
|
||||
```
|
||||
|
||||
Thereby, `nlohmann::my_json::json_pointer` is an alias for `nlohmann::json_pointer<my_string_type>` and is always an
|
||||
alias to the `json_pointer` with the appropriate string type for all specializations of `basic_json`.
|
||||
Thereby, `my_json::json_pointer` is an alias for `nlohmann::json_pointer<my_string_type>`; in general,
|
||||
`basic_json::json_pointer` is always an alias to the `json_pointer` with the appropriate string type for all
|
||||
specializations of `basic_json`.
|
||||
|
||||
#### Miscellaneous functions
|
||||
### Miscellaneous functions
|
||||
|
||||
- The function `iterator_wrapper` is deprecated since 3.1.0. Please use the member function
|
||||
[`items`](../api/basic_json/items.md) instead.
|
||||
@@ -260,7 +267,7 @@ exact version and configuration is relevant, use macro
|
||||
}
|
||||
```
|
||||
|
||||
## Do not use the `details` namespace
|
||||
## Do not use the `detail` namespace
|
||||
|
||||
The `details` namespace is not part of the public API of the library and can change in any version without an
|
||||
announcement. Do not rely on any function or type in the `details` namespace.
|
||||
The `nlohmann::detail` namespace is not part of the public API of the library and can change in any version without
|
||||
an announcement. Do not rely on any function or type in the `detail` namespace.
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -1,12 +1,12 @@
|
||||
# Migration Guide
|
||||
|
||||
This page collects some guidelines on how to future-proof your code for future versions of this library.
|
||||
This page collects some guidelines on how to future-proof your code for future versions of this library. For how to add the library to your project in the first place, see [Integration](https://json.nlohmann.me/integration/index.md), [CMake](https://json.nlohmann.me/integration/cmake/index.md), or [Package Managers](https://json.nlohmann.me/integration/package_managers/index.md).
|
||||
|
||||
## Replace deprecated functions
|
||||
|
||||
The following functions have been deprecated and will be removed in the next major version (i.e., 4.0.0). All deprecations are annotated with [`HEDLEY_DEPRECATED_FOR`](https://nemequ.github.io/hedley/api-reference.html#HEDLEY_DEPRECATED_FOR) to report which function to use instead.
|
||||
|
||||
#### Parsing
|
||||
### Parsing
|
||||
|
||||
- Function `friend std::istream& operator<<(basic_json&, std::istream&)` is deprecated since 3.0.0. Please use [`friend std::istream& operator>>(std::istream&, basic_json&)`](https://json.nlohmann.me/api/operator_gtgt/index.md) instead.
|
||||
|
||||
@@ -22,7 +22,7 @@ The following functions have been deprecated and will be removed in the next maj
|
||||
ss >> j;
|
||||
```
|
||||
|
||||
- Passing iterator pairs or pointer/length pairs to parsing functions ([`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md), [`accept`](https://json.nlohmann.me/api/basic_json/accept/index.md), [`sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md), [`from_cbor`](https://json.nlohmann.me/api/basic_json/from_cbor/index.md), [`from_msgpack`](https://json.nlohmann.me/api/basic_json/from_msgpack/index.md), [`from_ubjson`](https://json.nlohmann.me/api/basic_json/from_ubjson/index.md), and [`from_bson`](https://json.nlohmann.me/api/basic_json/from_bson/index.md) via initializer lists is deprecated since 3.8.0. Instead, pass two iterators; for instance, call `from_cbor(ptr, ptr+len)` instead of `from_cbor({ptr, len})`.
|
||||
- Passing iterator pairs or pointer/length pairs to parsing functions ([`parse`](https://json.nlohmann.me/api/basic_json/parse/index.md), [`accept`](https://json.nlohmann.me/api/basic_json/accept/index.md), [`sax_parse`](https://json.nlohmann.me/api/basic_json/sax_parse/index.md), [`from_cbor`](https://json.nlohmann.me/api/basic_json/from_cbor/index.md), [`from_msgpack`](https://json.nlohmann.me/api/basic_json/from_msgpack/index.md), [`from_ubjson`](https://json.nlohmann.me/api/basic_json/from_ubjson/index.md), and [`from_bson`](https://json.nlohmann.me/api/basic_json/from_bson/index.md)) via initializer lists is deprecated since 3.8.0. Instead, pass two iterators; for instance, call `from_cbor(ptr, ptr+len)` instead of `from_cbor({ptr, len})`. Likewise, passing a pointer and a length as two separate arguments to `from_cbor`, `from_msgpack`, `from_ubjson`, and `from_bson` is deprecated since 3.8.0; call `from_cbor(ptr, ptr+len)` instead of `from_cbor(ptr, len)`.
|
||||
|
||||
```
|
||||
const char* s = "[1,2,3]";
|
||||
@@ -34,7 +34,7 @@ The following functions have been deprecated and will be removed in the next maj
|
||||
bool ok = nlohmann::json::accept(s, s + std::strlen(s));
|
||||
```
|
||||
|
||||
#### JSON Pointers
|
||||
### JSON Pointers
|
||||
|
||||
- Comparing JSON Pointers with strings via [`operator==`](https://json.nlohmann.me/api/json_pointer/operator_eq/index.md) and [`operator!=`](https://json.nlohmann.me/api/json_pointer/operator_ne/index.md) is deprecated since 3.11.2. To compare a [`json_pointer`](https://json.nlohmann.me/api/json_pointer/index.md) `p` with a string `s`, convert `s` to a `json_pointer` first and use [`json_pointer::operator==`](https://json.nlohmann.me/api/json_pointer/operator_eq/index.md) or [`json_pointer::operator!=`](https://json.nlohmann.me/api/json_pointer/operator_ne/index.md).
|
||||
|
||||
@@ -60,7 +60,7 @@ The following functions have been deprecated and will be removed in the next maj
|
||||
std::string s = ptr.to_string();
|
||||
```
|
||||
|
||||
- Passing a `basic_json` specialization as template parameter `RefStringType` to [`json_pointer`](https://json.nlohmann.me/api/json_pointer/index.md) is deprecated since 3.11.0. The string type can now be directly provided.
|
||||
- Passing a `basic_json` specialization as template parameter `RefStringType` to [`json_pointer`](https://json.nlohmann.me/api/json_pointer/index.md) is deprecated since 3.11.0. The string type can now be directly provided. This also applies to passing such a JSON pointer to [`at`](https://json.nlohmann.me/api/basic_json/at/index.md), [`contains`](https://json.nlohmann.me/api/basic_json/contains/index.md), [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), and [`value`](https://json.nlohmann.me/api/basic_json/value/index.md).
|
||||
|
||||
```
|
||||
using my_json = nlohmann::basic_json<std::map, std::vector, my_string_type>;
|
||||
@@ -71,9 +71,9 @@ The following functions have been deprecated and will be removed in the next maj
|
||||
nlohmann::json_pointer<my_string_type> ptr("/foo/bar/1");
|
||||
```
|
||||
|
||||
Thereby, `nlohmann::my_json::json_pointer` is an alias for `nlohmann::json_pointer<my_string_type>` and is always an alias to the `json_pointer` with the appropriate string type for all specializations of `basic_json`.
|
||||
Thereby, `my_json::json_pointer` is an alias for `nlohmann::json_pointer<my_string_type>`; in general, `basic_json::json_pointer` is always an alias to the `json_pointer` with the appropriate string type for all specializations of `basic_json`.
|
||||
|
||||
#### Miscellaneous functions
|
||||
### Miscellaneous functions
|
||||
|
||||
- The function `iterator_wrapper` is deprecated since 3.1.0. Please use the member function [`items`](https://json.nlohmann.me/api/basic_json/items/index.md) instead.
|
||||
|
||||
@@ -178,6 +178,6 @@ void to_json(NLOHMANN_JSON_NAMESPACE::json& j, const person& p)
|
||||
}
|
||||
```
|
||||
|
||||
## Do not use the `details` namespace
|
||||
## Do not use the `detail` namespace
|
||||
|
||||
The `details` namespace is not part of the public API of the library and can change in any version without an announcement. Do not rely on any function or type in the `details` namespace.
|
||||
The `nlohmann::detail` namespace is not part of the public API of the library and can change in any version without an announcement. Do not rely on any function or type in the `detail` namespace.
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
#include <nlohmann/json.hpp>
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << std::setw(4) << json::meta() << std::endl;
|
||||
}
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 54 KiB |
+130
-145
@@ -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)
|
||||
|
||||
- [](https://repology.org/project/nlohmann-json/versions)
|
||||
- [](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)
|
||||
|
||||
- [](https://repology.org/project/nlohmann-json/versions)
|
||||
- [](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)
|
||||
|
||||
- [](https://repology.org/project/nlohmann-json/versions)
|
||||
- [](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)
|
||||
|
||||
- [](https://repology.org/project/nlohmann-json/versions)
|
||||
- [](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"
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
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](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://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"
|
||||
|
||||
[](https://repology.org/project/nlohmann-json/versions)
|
||||
[](https://repology.org/project/nlohmann-json/versions)
|
||||
[](https://repology.org/project/nlohmann-json/versions)
|
||||
[](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.
|
||||
- [](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/)
|
||||
|
||||
- [](https://repology.org/project/nlohmann-json/versions)
|
||||
- [](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: [](https://repology.org/project/nlohmann-json/versions)
|
||||
|
||||
??? example "Package version overview"
|
||||
|
||||
[](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.
|
||||
|
||||
[](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.
|
||||
|
||||
|
||||
|
||||
!!! warning
|
||||
|
||||
The module is outdated as the respective [pod](https://cocoapods.org/pods/nlohmann_json) has not been updated in years.
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -45,6 +45,8 @@ When executed, this program should create output similar to
|
||||
}
|
||||
```
|
||||
|
||||
Many of the package managers below install a CMake package configuration that exposes the same `nlohmann_json::nlohmann_json` interface target described in [CMake](https://json.nlohmann.me/integration/cmake/index.md); their CMake examples below link against that target.
|
||||
|
||||
## Homebrew
|
||||
|
||||
Summary
|
||||
@@ -159,7 +161,7 @@ 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()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a subproject fallback, rather than using the subproject directly.
|
||||
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](https://json.nlohmann.me/integration/pkg-config/index.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: Wrap
|
||||
|
||||
@@ -223,7 +225,7 @@ use `bazel_dep`, `git_override`, or `local_path_override`
|
||||
|
||||
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:
|
||||
|
||||
@@ -237,10 +239,10 @@ Example
|
||||
)
|
||||
```
|
||||
|
||||
WORKSPACE
|
||||
MODULE.bazel
|
||||
|
||||
```
|
||||
bazel_dep(name = "nlohmann_json", version = "3.11.3.bcr.1")
|
||||
bazel_dep(name = "nlohmann_json", version = "3.12.0.bcr.2")
|
||||
```
|
||||
|
||||
example.cpp
|
||||
@@ -278,7 +280,7 @@ recipe: [**`nlohmann_json`**](https://conan.io/center/recipes/nlohmann_json)
|
||||
|
||||
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:
|
||||
|
||||
@@ -353,7 +355,7 @@ 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:
|
||||
|
||||
@@ -422,7 +424,7 @@ 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:
|
||||
|
||||
@@ -494,7 +496,7 @@ 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:
|
||||
|
||||
@@ -557,7 +559,7 @@ 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:
|
||||
|
||||
@@ -567,7 +569,7 @@ Example
|
||||
cmake_minimum_required(VERSION 3.15)
|
||||
project(json_example)
|
||||
|
||||
find_package(nlohmann_json CONFIG REQUIRED)
|
||||
find_package(nlohmann_json REQUIRED)
|
||||
|
||||
add_executable(json_example example.cpp)
|
||||
target_link_libraries(json_example PRIVATE nlohmann_json::nlohmann_json)
|
||||
@@ -618,6 +620,76 @@ package: **`nlohmann/json`**
|
||||
- File issues at the [library issue tracker](https://github.com/nlohmann/json/issues)
|
||||
- [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:
|
||||
|
||||
```
|
||||
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:
|
||||
|
||||
```
|
||||
#include <json.hpp>
|
||||
```
|
||||
|
||||
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):
|
||||
|
||||
Package.swift
|
||||
|
||||
```
|
||||
// swift-tools-version: 5.9
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "json_example",
|
||||
dependencies: [
|
||||
.package(url: "https://github.com/nlohmann/json", from: "3.12.0")
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "json_example",
|
||||
dependencies: [
|
||||
.product(name: "json", package: "json")
|
||||
]
|
||||
)
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
Sources/json_example/example.cpp
|
||||
|
||||
```
|
||||
#include <json.hpp>
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << std::setw(4) << json::meta() << std::endl;
|
||||
}
|
||||
```
|
||||
|
||||
1. Build and run:
|
||||
|
||||
```
|
||||
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
|
||||
|
||||
Summary
|
||||
@@ -636,74 +708,16 @@ If you are using [NuGet](https://www.nuget.org), you can use the package [nlohma
|
||||
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: Visual Studio project
|
||||
|
||||
Now you can click on “Browse” tab and find the package you like to install.
|
||||
1. Right-click the project (any C++ project) in "Solution Explorer" and select "Manage NuGet Packages…"
|
||||
1. Switch to the "Browse" tab.
|
||||
1. Search for `nlohmann.json`, select it, and click "Install".
|
||||
1. `#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.
|
||||
|
||||
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 version="1.0" encoding="utf-8"?>
|
||||
<packages>
|
||||
<package id="nlohmann.json" version="3.5.0" targetFramework="native" />
|
||||
</packages>
|
||||
```
|
||||
|
||||
1. 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!
|
||||
|
||||
1. 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 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
|
||||
|
||||
@@ -722,7 +736,7 @@ If you are using [conda](https://conda.io/), you can use the package [nlohmann_j
|
||||
conda install -c conda-forge nlohmann_json
|
||||
```
|
||||
|
||||
Example
|
||||
Example: Raw compilation
|
||||
|
||||
1. Create the following file:
|
||||
|
||||
@@ -762,9 +776,46 @@ Example
|
||||
|
||||
## 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.
|
||||
Summary
|
||||
|
||||
The [package](https://packages.msys2.org/base/mingw-w64-nlohmann-json) is updated automatically.
|
||||
package: [**`mingw-w64-nlohmann-json`**](https://packages.msys2.org/base/mingw-w64-nlohmann-json)
|
||||
|
||||
- The [package](https://packages.msys2.org/base/mingw-w64-nlohmann-json) is updated automatically.
|
||||
- File issues at the [MINGW-packages issue tracker](https://github.com/msys2/MINGW-packages/issues/new?title=%5Bnlohmann-json%5D)
|
||||
- [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: Raw compilation
|
||||
|
||||
1. Create the following file:
|
||||
|
||||
example.cpp
|
||||
|
||||
```
|
||||
#include <nlohmann/json.hpp>
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << std::setw(4) << json::meta() << std::endl;
|
||||
}
|
||||
```
|
||||
|
||||
1. Install the package (from an MSYS2 MinGW 64-bit shell):
|
||||
|
||||
```
|
||||
pacman -S mingw-w64-x86_64-nlohmann-json
|
||||
```
|
||||
|
||||
1. Compile the code:
|
||||
|
||||
```
|
||||
g++ example.cpp -std=c++11 -o example
|
||||
```
|
||||
|
||||
## MacPorts
|
||||
|
||||
@@ -1067,7 +1118,7 @@ If you are using [`CPM.cmake`](https://github.com/TheLartians/CPM.cmake), add th
|
||||
CPMAddPackage("gh:nlohmann/json@3.12.0")
|
||||
```
|
||||
|
||||
Example
|
||||
Example: CMake with `CPMAddPackage`
|
||||
|
||||
1. Create the following files:
|
||||
|
||||
@@ -1125,7 +1176,7 @@ package: [**`nlohmann_json`**](https://github.com/xmake-io/xmake-repo/blob/maste
|
||||
- File issues at the [xmake issue tracker](https://github.com/xmake-io/xmake-repo/issues)
|
||||
- [xmake website](https://xmake.io/#/)
|
||||
|
||||
Example
|
||||
Example: xmake project
|
||||
|
||||
1. Create the following files:
|
||||
|
||||
@@ -1173,15 +1224,13 @@ ______________________________________________________________________
|
||||
|
||||
## Other package managers
|
||||
|
||||
The library is also contained in many other package repositories:
|
||||
|
||||
Package version overview
|
||||
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
|
||||
|
||||
@@ -1189,7 +1238,11 @@ The module is outdated as the respective [repository](https://github.com/buckaro
|
||||
|
||||
## 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 [here](https://bitbucket.org/benman/nlohmann_json-cocoapod/issues?status=new&status=open).
|
||||
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.
|
||||
|
||||
Warning
|
||||
|
||||
The module is outdated as the respective [pod](https://cocoapods.org/pods/nlohmann_json) has not been updated in years.
|
||||
|
||||
## npm
|
||||
|
||||
@@ -1198,7 +1251,3 @@ This project does not publish an official [npm](https://www.npmjs.com) package.
|
||||
## 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.
|
||||
|
||||
Warning
|
||||
|
||||
The module is outdated as the respective [pod](https://cocoapods.org/pods/nlohmann_json) has not been updated in years.
|
||||
|
||||
@@ -6,6 +6,9 @@ If you are using bare Makefiles, you can use `pkg-config` to generate the includ
|
||||
pkg-config nlohmann_json --cflags
|
||||
```
|
||||
|
||||
A pkg-config file is installed by [CMake](cmake.md#json_install) (when the `JSON_Install` option is enabled, which is
|
||||
the default for a top-level build) as well as by several [package managers](package_managers.md).
|
||||
|
||||
Users of the [Meson build system](package_managers.md#meson) will also be able to use a system-wide library, which will be found by `pkg-config`:
|
||||
|
||||
```meson
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -6,6 +6,8 @@ If you are using bare Makefiles, you can use `pkg-config` to generate the includ
|
||||
pkg-config nlohmann_json --cflags
|
||||
```
|
||||
|
||||
A pkg-config file is installed by [CMake](https://json.nlohmann.me/integration/cmake/#json_install) (when the `JSON_Install` option is enabled, which is the default for a top-level build) as well as by several [package managers](https://json.nlohmann.me/integration/package_managers/index.md).
|
||||
|
||||
Users of the [Meson build system](https://json.nlohmann.me/integration/package_managers/#meson) will also be able to use a system-wide library, which will be found by `pkg-config`:
|
||||
|
||||
```
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
// swift-tools-version: 5.9
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "json_example",
|
||||
dependencies: [
|
||||
.package(url: "https://github.com/nlohmann/json", from: "3.12.0")
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "json_example",
|
||||
dependencies: [
|
||||
.product(name: "json", package: "json")
|
||||
]
|
||||
)
|
||||
]
|
||||
)
|
||||
@@ -0,0 +1,10 @@
|
||||
#include <json.hpp>
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << std::setw(4) << json::meta() << std::endl;
|
||||
}
|
||||
Reference in New Issue
Block a user