ceph/src/jaegertracing/opentelemetry-cpp/third_party/nlohmann-json/doc/mkdocs/docs/integration/cmake.md

   1 # CMake
   2
   3 ## Integration
   4
   5 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.
   6
   7 ### External
   8
   9 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:
  10
  11 ```cmake
  12 # CMakeLists.txt
  13 find_package(nlohmann_json 3.2.0 REQUIRED)
  14 ...
  15 add_library(foo ...)
  16 ...
  17 target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
  18 ```
  19
  20 The package configuration file, `nlohmann_jsonConfig.cmake`, can be used either from an install tree or directly out of the build tree.
  21
  22 ### Embedded
  23
  24 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:
  25
  26 ```cmake
  27 # If you only include this third party in PRIVATE source files, you do not
  28 # need to install it when your main project gets installed.
  29 # set(JSON_Install OFF CACHE INTERNAL "")
  30
  31 # Don't use include(nlohmann_json/CMakeLists.txt) since that carries with it
  32 # unintended consequences that will break the build.  It's generally
  33 # discouraged (although not necessarily well documented as such) to use
  34 # include(...) for pulling in other CMake projects anyways.
  35 add_subdirectory(nlohmann_json)
  36 ...
  37 add_library(foo ...)
  38 ...
  39 target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
  40 ```
  41
  42 ### Embedded (FetchContent)
  43
  44 Since CMake v3.11,
  45 [FetchContent](https://cmake.org/cmake/help/v3.11/module/FetchContent.html) can
  46 be used to automatically download the repository as a dependency at configure type.
  47
  48 Example:
  49 ```cmake
  50 include(FetchContent)
  51
  52 FetchContent_Declare(json
  53   GIT_REPOSITORY https://github.com/nlohmann/json
  54   GIT_TAG v3.7.3)
  55
  56 FetchContent_GetProperties(json)
  57 if(NOT json_POPULATED)
  58   FetchContent_Populate(json)
  59   add_subdirectory(${json_SOURCE_DIR} ${json_BINARY_DIR} EXCLUDE_FROM_ALL)
  60 endif()
  61
  62 target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
  63 ```
  64
  65 !!! Note
  66         The repository <https://github.com/nlohmann/json> download size is quite large.
  67         You might want to depend on a smaller repository. For instance, you might want to replace the URL above by
  68         <https://github.com/ArthurSonzogni/nlohmann_json_cmake_fetchcontent>.
  69
  70 ### Supporting Both
  71
  72 To allow your project to support either an externally supplied or an embedded JSON library, you can use a pattern akin to the following:
  73
  74 ``` cmake
  75 # Top level CMakeLists.txt
  76 project(FOO)
  77 ...
  78 option(FOO_USE_EXTERNAL_JSON "Use an external JSON library" OFF)
  79 ...
  80 add_subdirectory(thirdparty)
  81 ...
  82 add_library(foo ...)
  83 ...
  84 # Note that the namespaced target will always be available regardless of the
  85 # import method
  86 target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
  87 ```
  88 ```cmake
  89 # thirdparty/CMakeLists.txt
  90 ...
  91 if(FOO_USE_EXTERNAL_JSON)
  92   find_package(nlohmann_json 3.2.0 REQUIRED)
  93 else()
  94   set(JSON_BuildTests OFF CACHE INTERNAL "")
  95   add_subdirectory(nlohmann_json)
  96 endif()
  97 ...
  98 ```
  99
 100 `thirdparty/nlohmann_json` is then a complete copy of this source tree.
 101
 102 ## CMake Options
 103
 104 ### `JSON_BuildTests`
 105
 106 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.
 107
 108 ### `JSON_CI`
 109
 110 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.
 111
 112 ### `JSON_Diagnostics`
 113
 114 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.
 115
 116 ### `JSON_FastTests`
 117
 118 Skip expensive/slow test suites. This option is `OFF` by default. Depends on `JSON_BuildTests`.
 119
 120 ### `JSON_ImplicitConversions`
 121
 122 Enable implicit conversions by defining macro [`JSON_USE_IMPLICIT_CONVERSIONS`](../features/macros.md#json_use_implicit_conversions). This option is `ON` by default.
 123
 124 ### `JSON_Install`
 125
 126 Install CMake targets during install step. This option is `ON` by default if the library's CMake project is the top project.
 127
 128 ### `JSON_MultipleHeaders`
 129
 130 Use non-amalgamated version of the library. This option is `OFF` by default.
 131
 132 ### `JSON_SystemInclude`
 133
 134 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.
 135
 136 ### `JSON_Valgrind`
 137
 138 Execute test suite with [Valgrind](https://valgrind.org). This option is `OFF` by default. Depends on `JSON_BuildTests`.