Reorganize directories (#3462)

* 🚚 move files * 🚚 rename doc folder to docs * 🚚 rename test folder to tests
2026-10-04 21:50:33 +00:00 · 2022-05-01 09:41:50 +02:00
parent 5352856f04
commit b21c345179
865 changed files with 52 additions and 51 deletions
@@ -0,0 +1,162 @@
+# CMake
+
+## 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.
+
+### External
+
+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:
+
+!!! example
+
+    ```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.
+
+!!! example
+
+    ```cmake title="CMakeLists.txt"
+    cmake_minimum_required(VERSION 3.1)
+    project(ExampleProject LANGUAGES CXX)
+
+    # 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)
+
+    add_executable(example example.cpp)
+    target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
+    ```
+
+!!! note
+
+    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.
+
+
+### 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.
+
+!!! example
+
+    ```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 a release 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 URL https://github.com/nlohmann/json/releases/download/v3.10.5/json.tar.xz)
+    FetchContent_MakeAvailable(json)
+    
+    add_executable(example example.cpp)
+    target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
+    ```
+
+!!! Note
+
+    It is recommended to use the URL approach described above which is supported as of version 3.10.0. It is also
+    possible to pass the Git repository like
+
+    ```cmake
+    FetchContent_Declare(json
+        GIT_REPOSITORY https://github.com/nlohmann/json
+        GIT_TAG v3.10.5
+    )
+    ```
+
+	However, 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
+
+### `JSON_BuildTests`
+
+Build the unit tests when [`BUILD_TESTING`](https://cmake.org/cmake/help/latest/command/enable_testing.html) is enabled. This option is `ON` by default if the library's CMake project is the top project. That is, when integrating the library as described above, the test suite is not built unless explicitly switched on with this option.
+
+### `JSON_CI`
+
+Enable CI build targets. The exact targets are used during the several CI steps and are subject to change without notice. This option is `OFF` by default.
+
+### `JSON_Diagnostics`
+
+Enable [extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) by defining macro [`JSON_DIAGNOSTICS`](../features/macros.md#json_diagnostics). This option is `OFF` by default.
+
+### `JSON_FastTests`
+
+Skip expensive/slow test suites. This option is `OFF` by default. Depends on `JSON_BuildTests`.
+
+### `JSON_ImplicitConversions`
+
+Enable implicit conversions by defining macro [`JSON_USE_IMPLICIT_CONVERSIONS`](../features/macros.md#json_use_implicit_conversions). This option is `ON` 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.
+
+### `JSON_MultipleHeaders`
+
+Use non-amalgamated version of the library. This option is `OFF` by default.
+
+### `JSON_SystemInclude`
+
+Treat the library headers like system headers (i.e., adding `SYSTEM` to the [`target_include_directories`](https://cmake.org/cmake/help/latest/command/target_include_directories.html) call) to checks for this library by tools like Clang-Tidy. This option is `OFF` by default.
+
+### `JSON_Valgrind`
+
+Execute test suite with [Valgrind](https://valgrind.org). This option is `OFF` by default. Depends on `JSON_BuildTests`.
@@ -0,0 +1,9 @@
+project(json_example)
+cmake_minimum_required(VERSION 2.8.12)
+add_definitions("-std=c++11")
+
+include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
+conan_basic_setup()
+
+add_executable(json_example example.cpp)
+target_link_libraries(json_example ${CONAN_LIBS})
@@ -0,0 +1,5 @@
+[requires]
+nlohmann_json/3.7.3
+
+[generators]
+cmake
@@ -0,0 +1,9 @@
+#include <nlohmann/json.hpp>
+#include <iostream>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << json::meta() << std::endl;
+}
@@ -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;
+}
@@ -0,0 +1,18 @@
+# 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
+
+```cpp
+#include <nlohmann/json.hpp>
+
+// for convenience
+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).
+
+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`.
@@ -0,0 +1,194 @@
+# Package Managers
+
+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"
+```
+
+## Homebrew
+
+If you are using OS X and [Homebrew](http://brew.sh), just type
+
+```sh
+brew install nlohmann-json
+```
+
+and you're set. If you want the bleeding edge rather than the latest release, use
+
+```sh
+brew install nlohmann-json --HEAD
+```
+
+instead. See [nlohmann-json](https://formulae.brew.sh/formula/nlohmann-json) for more information.
+
+??? example
+
+	1. Create the following file:
+
+        ```cpp title="example.cpp"
+        --8<-- "integration/example.cpp"
+        ```
+
+	2. Install the package
+
+		```sh
+		brew install nlohmann-json
+		```
+
+	3. Determine the include path, which defaults to `/usr/local/Cellar/nlohmann-json/$version/include`, where `$version` is the version of the library, e.g. `3.7.3`. The path of the library can be determined with
+
+		```sh
+		brew list nlohmann-json
+		```
+
+	4. Compile the code. For instance, the code can be compiled using Clang with
+
+		```sh
+		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.
+
+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, simply 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.
+
+## Conan
+
+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. Please file issues [here](https://github.com/conan-io/conan-center-index/issues) if you experience problems with the packages.
+
+??? example
+
+	1. Create the following files:
+
+        ```ini title="Conanfile.txt"
+        --8<-- "integration/conan/Conanfile.txt"
+        ```
+
+        ```cmake title="CMakeLists.txt"
+        --8<-- "integration/conan/CMakeLists.txt"
+        ```
+
+        ```cpp title="example.cpp"
+        --8<-- "integration/conan/example.cpp"
+        ```
+
+	2. Build:
+
+		```sh
+		mkdir build
+		cd build
+		conan install ..
+		cmake ..
+		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.
+
+## Hunter
+
+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). Please see the hunter project for any issues regarding the packaging.
+
+## 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`. Please file issues [here](https://github.com/buckaroo-pm/nlohmann-json). There is a demo repo [here](https://github.com/njlr/buckaroo-nholmann-json-example).
+
+## vcpkg
+
+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 `vcpkg install nlohmann-json` and follow the then displayed descriptions. Please see the vcpkg project for any issues regarding the packaging.
+
+??? example
+
+	1. Create the following files:
+
+        ```cmake title="CMakeLists.txt"
+        --8<-- "integration/vcpkg/CMakeLists.txt"
+        ```
+    
+        ```cpp title="example.cpp"
+        --8<-- "integration/vcpkg/example.cpp"
+        ```
+
+    2. Install package:
+
+        ```sh
+        vcpkg install nlohmann-json
+        ```
+
+	3. Build:
+
+		```sh
+		mkdir build
+		cd build
+		cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
+		cmake --build .
+		```
+
+    Note you need to adjust `/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake` to your system.
+
+## cget
+
+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).
+
+## NuGet
+
+If you are using [NuGet](https://www.nuget.org), you can use the package [nlohmann.json](https://www.nuget.org/packages/nlohmann.json/). Please check [this extensive description](https://github.com/nlohmann/json/issues/1132#issuecomment-452250255) on how to use the package. Please file issues [here](https://github.com/hnkb/nlohmann-json-nuget/issues).
+
+## Conda
+
+If you are using [conda](https://conda.io/), you can use the package [nlohmann_json](https://github.com/conda-forge/nlohmann_json-feedstock) from [conda-forge](https://conda-forge.org) executing `conda install -c conda-forge nlohmann_json`. Please file issues [here](https://github.com/conda-forge/nlohmann_json-feedstock/issues).
+
+## 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, 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).
+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:
+
+```cmake
+CPMAddPackage(
+    NAME nlohmann_json
+    GITHUB_REPOSITORY nlohmann/json
+    VERSION 3.9.1)
+```
@@ -0,0 +1,13 @@
+# Pkg-config
+
+If you are using bare Makefiles, you can use `pkg-config` to generate the include flags that point to where the library is installed:
+
+```sh
+pkg-config nlohmann_json --cflags
+```
+
+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
+json = dependency('nlohmann_json', required: true)
+```
@@ -0,0 +1,7 @@
+project(json_example)
+cmake_minimum_required(VERSION 2.8.12)
+
+find_package(nlohmann_json CONFIG REQUIRED)
+
+add_executable(json_example example.cpp)
+target_link_libraries(json_example PRIVATE nlohmann_json::nlohmann_json)
@@ -0,0 +1,9 @@
+#include <nlohmann/json.hpp>
+#include <iostream>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << json::meta() << std::endl;
+}