mirror of
https://github.com/nlohmann/json.git
synced 2025-07-29 23:01:16 +03:00
📝 overwork documentation
This commit is contained in:
Niels Lohmann
@ -2,102 +2,124 @@
|
||||
|
||||
## Integration
|
||||
|
||||
You can also use the `nlohmann_json::nlohmann_json` interface target in CMake. This target populates the appropriate usage requirements for `INTERFACE_INCLUDE_DIRECTORIES` to point to the appropriate include directories and `INTERFACE_COMPILE_FEATURES` 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.
|
||||
|
||||
### External
|
||||
|
||||
To use this library from a CMake project, you can locate it directly with `find_package()` and use the namespaced imported target from the generated package configuration:
|
||||
To use this library from a CMake project, you can locate it directly with [`find_package()`](https://cmake.org/cmake/help/latest/command/find_package.html)
|
||||
and use the namespaced imported target from the generated package configuration:
|
||||
|
||||
```cmake
|
||||
# CMakeLists.txt
|
||||
find_package(nlohmann_json 3.2.0 REQUIRED)
|
||||
...
|
||||
add_library(foo ...)
|
||||
...
|
||||
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
|
||||
```
|
||||
!!! example
|
||||
|
||||
The package configuration file, `nlohmann_jsonConfig.cmake`, can be used either from an install tree or directly out of the build tree.
|
||||
```cmake title="CMakeLists.txt"
|
||||
cmake_minimum_required(VERSION 3.1)
|
||||
project(ExampleProject LANGUAGES CXX)
|
||||
|
||||
find_package(nlohmann_json 3.10.5 REQUIRED)
|
||||
|
||||
add_executable(example example.cpp)
|
||||
target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
|
||||
```
|
||||
|
||||
The package configuration file, `nlohmann_jsonConfig.cmake`, can be used either from an install tree or directly out of
|
||||
the build tree.
|
||||
|
||||
### Embedded
|
||||
|
||||
To embed the library directly into an existing CMake project, place the entire source tree in a subdirectory and call `add_subdirectory()` in your `CMakeLists.txt` file:
|
||||
To embed the library directly into an existing CMake project, place the entire source tree in a subdirectory and call
|
||||
`add_subdirectory()` in your `CMakeLists.txt` file.
|
||||
|
||||
```cmake
|
||||
# If you only include this third party in PRIVATE source files, you do not
|
||||
# need to install it when your main project gets installed.
|
||||
# set(JSON_Install OFF CACHE INTERNAL "")
|
||||
!!! example
|
||||
|
||||
# Don't use include(nlohmann_json/CMakeLists.txt) since that carries with it
|
||||
# unintended consequences that will break the build. It's generally
|
||||
# discouraged (although not necessarily well documented as such) to use
|
||||
# include(...) for pulling in other CMake projects anyways.
|
||||
add_subdirectory(nlohmann_json)
|
||||
...
|
||||
add_library(foo ...)
|
||||
...
|
||||
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
|
||||
```
|
||||
```cmake title="CMakeLists.txt"
|
||||
cmake_minimum_required(VERSION 3.1)
|
||||
project(ExampleProject LANGUAGES CXX)
|
||||
|
||||
### Embedded (FetchContent)
|
||||
# If you only include this third party in PRIVATE source files, you do not need to install it
|
||||
# when your main project gets installed.
|
||||
set(JSON_Install OFF CACHE INTERNAL "")
|
||||
|
||||
add_subdirectory(nlohmann_json)
|
||||
|
||||
Since CMake v3.11,
|
||||
[FetchContent](https://cmake.org/cmake/help/v3.11/module/FetchContent.html) can
|
||||
be used to automatically download the repository as a dependency at configure type.
|
||||
add_executable(example example.cpp)
|
||||
target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
|
||||
```
|
||||
|
||||
Example:
|
||||
```cmake
|
||||
include(FetchContent)
|
||||
!!! note
|
||||
|
||||
FetchContent_Declare(json
|
||||
GIT_REPOSITORY https://github.com/nlohmann/json
|
||||
GIT_TAG v3.7.3)
|
||||
Do not use `#!cmake include(nlohmann_json/CMakeLists.txt)`, since that carries with it unintended consequences that
|
||||
will break the build. It is generally discouraged (although not necessarily well documented as such) to use
|
||||
`#!cmake include(...)` for pulling in other CMake projects anyways.
|
||||
|
||||
FetchContent_GetProperties(json)
|
||||
if(NOT json_POPULATED)
|
||||
FetchContent_Populate(json)
|
||||
add_subdirectory(${json_SOURCE_DIR} ${json_BINARY_DIR} EXCLUDE_FROM_ALL)
|
||||
endif()
|
||||
|
||||
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
|
||||
```
|
||||
|
||||
!!! Note
|
||||
The repository <https://github.com/nlohmann/json> download size is quite large.
|
||||
You might want to depend on a smaller repository. For instance, you might want to replace the URL above by
|
||||
<https://github.com/ArthurSonzogni/nlohmann_json_cmake_fetchcontent>.
|
||||
|
||||
### Supporting Both
|
||||
|
||||
To allow your project to support either an externally supplied or an embedded JSON library, you can use a pattern akin to the following:
|
||||
To allow your project to support either an externally supplied or an embedded JSON library, you can use a pattern akin
|
||||
to the following.
|
||||
|
||||
``` cmake
|
||||
# Top level CMakeLists.txt
|
||||
project(FOO)
|
||||
...
|
||||
option(FOO_USE_EXTERNAL_JSON "Use an external JSON library" OFF)
|
||||
...
|
||||
add_subdirectory(thirdparty)
|
||||
...
|
||||
add_library(foo ...)
|
||||
...
|
||||
# Note that the namespaced target will always be available regardless of the
|
||||
# import method
|
||||
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
|
||||
```
|
||||
```cmake
|
||||
# thirdparty/CMakeLists.txt
|
||||
...
|
||||
if(FOO_USE_EXTERNAL_JSON)
|
||||
find_package(nlohmann_json 3.2.0 REQUIRED)
|
||||
else()
|
||||
set(JSON_BuildTests OFF CACHE INTERNAL "")
|
||||
add_subdirectory(nlohmann_json)
|
||||
endif()
|
||||
...
|
||||
```
|
||||
!!! example
|
||||
|
||||
`thirdparty/nlohmann_json` is then a complete copy of this source tree.
|
||||
```cmake title="CMakeLists.txt"
|
||||
project(ExampleProject LANGUAGES CXX)
|
||||
|
||||
option(EXAMPLE_USE_EXTERNAL_JSON "Use an external JSON library" OFF)
|
||||
|
||||
add_subdirectory(thirdparty)
|
||||
|
||||
add_executable(example example.cpp)
|
||||
|
||||
# Note that the namespaced target will always be available regardless of the import method
|
||||
target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
|
||||
```
|
||||
|
||||
```cmake title="thirdparty/CMakeLists.txt"
|
||||
if(EXAMPLE_USE_EXTERNAL_JSON)
|
||||
find_package(nlohmann_json 3.10.5 REQUIRED)
|
||||
else()
|
||||
set(JSON_BuildTests OFF CACHE INTERNAL "")
|
||||
add_subdirectory(nlohmann_json)
|
||||
endif()
|
||||
```
|
||||
|
||||
`thirdparty/nlohmann_json` is then a complete copy of this source tree.
|
||||
|
||||
|
||||
### FetchContent
|
||||
|
||||
Since CMake v3.11, [FetchContent](https://cmake.org/cmake/help/v3.11/module/FetchContent.html) can be used to
|
||||
automatically download the repository as a dependency at configure type.
|
||||
|
||||
!!! example
|
||||
|
||||
```cmake title="CMakeLists.txt"
|
||||
cmake_minimum_required(VERSION 3.11)
|
||||
project(ExampleProject LANGUAGES CXX)
|
||||
|
||||
include(FetchContent)
|
||||
|
||||
FetchContent_Declare(json
|
||||
GIT_REPOSITORY https://github.com/nlohmann/json
|
||||
GIT_TAG v3.10.5
|
||||
)
|
||||
|
||||
FetchContent_GetProperties(json)
|
||||
if(NOT json_POPULATED)
|
||||
FetchContent_Populate(json)
|
||||
add_subdirectory(${json_SOURCE_DIR} ${json_BINARY_DIR} EXCLUDE_FROM_ALL)
|
||||
endif()
|
||||
|
||||
add_executable(example example.cpp)
|
||||
target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
|
||||
```
|
||||
|
||||
!!! Note
|
||||
|
||||
The repository <https://github.com/nlohmann/json> download size is quite large. You might want to depend on a
|
||||
smaller repository. For instance, you might want to replace the URL in the example by
|
||||
<https://github.com/ArthurSonzogni/nlohmann_json_cmake_fetchcontent>.
|
||||
|
||||
## CMake Options
|
||||
|
||||
|
||||
@ -1,9 +1,10 @@
|
||||
#include <nlohmann/json.hpp>
|
||||
#include <iostream>
|
||||
#include <iomanip>
|
||||
|
||||
using json = nlohmann::json;
|
||||
|
||||
int main()
|
||||
{
|
||||
std::cout << json::meta() << std::endl;
|
||||
std::cout << std::setw(4) << json::meta() << std::endl;
|
||||
}
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
# 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
|
||||
[`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
|
||||
|
||||
```cpp
|
||||
#include <nlohmann/json.hpp>
|
||||
@ -9,6 +10,9 @@
|
||||
using json = nlohmann::json;
|
||||
```
|
||||
|
||||
to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., `-std=c++11` for GCC and Clang).
|
||||
to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., `-std=c++11` for GCC and
|
||||
Clang).
|
||||
|
||||
You can further use file [`include/nlohmann/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/json_fwd.hpp) for forward-declarations. The installation of `json_fwd.hpp` (as part of CMake's install step), can be achieved by setting `-DJSON_MultipleHeaders=ON`.
|
||||
You can further use file [`include/nlohmann/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/json_fwd.hpp)
|
||||
for forward-declarations. The installation of `json_fwd.hpp` (as part of CMake's install step), can be achieved by
|
||||
setting `-DJSON_MultipleHeaders=ON`.
|
||||
|
||||
@ -6,6 +6,12 @@ Throughout this page, we will describe how to compile the example file `example.
|
||||
--8<-- "integration/example.cpp"
|
||||
```
|
||||
|
||||
When executed, this program should create output similar to
|
||||
|
||||
```json
|
||||
--8<-- "../../examples/meta.output"
|
||||
```
|
||||
|
||||
## Homebrew
|
||||
|
||||
If you are using OS X and [Homebrew](http://brew.sh), just type
|
||||
@ -26,11 +32,9 @@ instead. See [nlohmann-json](https://formulae.brew.sh/formula/nlohmann-json) for
|
||||
|
||||
1. Create the following file:
|
||||
|
||||
=== "example.cpp"
|
||||
|
||||
```cpp
|
||||
--8<-- "integration/example.cpp"
|
||||
```
|
||||
```cpp title="example.cpp"
|
||||
--8<-- "integration/example.cpp"
|
||||
```
|
||||
|
||||
2. Install the package
|
||||
|
||||
@ -50,6 +54,8 @@ instead. See [nlohmann-json](https://formulae.brew.sh/formula/nlohmann-json) for
|
||||
clang++ example.cpp -I/usr/local/Cellar/nlohmann-json/3.7.3/include -std=c++11 -o example
|
||||
```
|
||||
|
||||
:material-update: The [formula](https://formulae.brew.sh/formula/nlohmann-json) is updated automatically.
|
||||
|
||||
## Meson
|
||||
|
||||
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://wrapdb.mesonbuild.com/nlohmann_json), or simply use `meson wrap install nlohmann_json`. Please see the meson project for any issues regarding the packaging.
|
||||
@ -64,24 +70,17 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer
|
||||
|
||||
1. Create the following files:
|
||||
|
||||
=== "Conanfile.txt"
|
||||
|
||||
```ini
|
||||
--8<-- "integration/conan/Conanfile.txt"
|
||||
```
|
||||
```ini title="Conanfile.txt"
|
||||
--8<-- "integration/conan/Conanfile.txt"
|
||||
```
|
||||
|
||||
=== "CMakeLists.txt"
|
||||
|
||||
```cmake
|
||||
--8<-- "integration/conan/CMakeLists.txt"
|
||||
```
|
||||
|
||||
=== "example.cpp"
|
||||
|
||||
```cpp
|
||||
--8<-- "integration/conan/example.cpp"
|
||||
```
|
||||
```cmake title="CMakeLists.txt"
|
||||
--8<-- "integration/conan/CMakeLists.txt"
|
||||
```
|
||||
|
||||
```cpp title="example.cpp"
|
||||
--8<-- "integration/conan/example.cpp"
|
||||
```
|
||||
|
||||
2. Build:
|
||||
|
||||
@ -93,6 +92,8 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer
|
||||
cmake --build .
|
||||
```
|
||||
|
||||
:material-update: The [package](https://conan.io/center/nlohmann_json) is updated automatically.
|
||||
|
||||
## Spack
|
||||
|
||||
If you are using [Spack](https://www.spack.io/) to manage your dependencies, you can use the [`nlohmann-json` package](https://spack.readthedocs.io/en/latest/package_list.html#nlohmann-json). Please see the [spack project](https://github.com/spack/spack) for any issues regarding the packaging.
|
||||
@ -113,17 +114,13 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo
|
||||
|
||||
1. Create the following files:
|
||||
|
||||
=== "CMakeLists.txt"
|
||||
|
||||
```cmake
|
||||
--8<-- "integration/vcpkg/CMakeLists.txt"
|
||||
```
|
||||
|
||||
=== "example.cpp"
|
||||
|
||||
```cpp
|
||||
--8<-- "integration/vcpkg/example.cpp"
|
||||
```
|
||||
```cmake title="CMakeLists.txt"
|
||||
--8<-- "integration/vcpkg/CMakeLists.txt"
|
||||
```
|
||||
|
||||
```cpp title="example.cpp"
|
||||
--8<-- "integration/vcpkg/example.cpp"
|
||||
```
|
||||
|
||||
2. Install package:
|
||||
|
||||
@ -146,6 +143,8 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo
|
||||
|
||||
If you are using [cget](http://cget.readthedocs.io/en/latest/), you can install the latest development version with `cget install nlohmann/json`. A specific version can be installed with `cget install nlohmann/json@v3.1.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`).
|
||||
|
||||
:material-update: cget reads directly from the [GitHub repository](https://github.com/nlohmann/json) and is always up-to-date.
|
||||
|
||||
## 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).
|
||||
@ -162,19 +161,27 @@ If you are using [conda](https://conda.io/), you can use the package [nlohmann_j
|
||||
|
||||
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, just 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.
|
||||
|
||||
:material-update: The [package](https://packages.msys2.org/base/mingw-w64-nlohmann-json) is updated automatically.
|
||||
|
||||
## MacPorts
|
||||
|
||||
If you are using [MacPorts](https://ports.macports.org), execute `sudo port install nlohmann-json` to install the [nlohmann-json](https://ports.macports.org/port/nlohmann-json/) package.
|
||||
|
||||
:material-update: The [package](https://ports.macports.org/port/nlohmann-json/) is updated automatically.
|
||||
|
||||
## build2
|
||||
|
||||
If you are using [`build2`](https://build2.org), you can use the [`nlohmann-json`](https://cppget.org/nlohmann-json) package from the public repository http://cppget.org or directly from the [package's sources repository](https://github.com/build2-packaging/nlohmann-json). In your project's `manifest` file, just add `depends: nlohmann-json` (probably with some [version constraints](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml#guide-add-remove-deps)). If you are not familiar with using dependencies in `build2`, [please read this introduction](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml).
|
||||
If you are using [`build2`](https://build2.org), you can use the [`nlohmann-json`](https://cppget.org/nlohmann-json) package from the public repository <http://cppget.org> or directly from the [package's sources repository](https://github.com/build2-packaging/nlohmann-json). In your project's `manifest` file, just add `depends: nlohmann-json` (probably with some [version constraints](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml#guide-add-remove-deps)). If you are not familiar with using dependencies in `build2`, [please read this introduction](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml).
|
||||
Please file issues [here](https://github.com/build2-packaging/nlohmann-json) if you experience problems with the packages.
|
||||
|
||||
:material-update: The [package](https://cppget.org/nlohmann-json) is updated automatically.
|
||||
|
||||
## wsjcpp
|
||||
|
||||
If you are using [`wsjcpp`](http://wsjcpp.org), you can use the command `wsjcpp install "https://github.com/nlohmann/json:develop"` to get the latest version. Note you can change the branch ":develop" to an existing tag or another branch.
|
||||
|
||||
:material-update: wsjcpp reads directly from the [GitHub repository](https://github.com/nlohmann/json) and is always up-to-date.
|
||||
|
||||
## CPM.cmake
|
||||
|
||||
If you are using [`CPM.cmake`](https://github.com/TheLartians/CPM.cmake), you can check this [`example`](https://github.com/TheLartians/CPM.cmake/tree/master/examples/json). After [adding CPM script](https://github.com/TheLartians/CPM.cmake#adding-cpm) to your project, implement the following snippet to your CMake:
|
||||
|
||||
Reference in New Issue
Block a user