ceph/src/jaegertracing/opentelemetry-cpp/tools/vcpkg/docs/maintainers/vcpkg_check_features.md

   1 # vcpkg_check_features
   2
   3 The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_check_features.md).
   4 Check if one or more features are a part of a package installation.
   5
   6 ```cmake
   7 vcpkg_check_features(
   8     OUT_FEATURE_OPTIONS <out-var>
   9     [PREFIX <prefix>]
  10     [FEATURES
  11         [<feature-name> <feature-var>]...
  12         ]
  13     [INVERTED_FEATURES
  14         [<feature-name> <feature-var>]...
  15         ]
  16 )
  17 ```
  18
  19 The `<out-var>` should be set to `FEATURE_OPTIONS` by convention.
  20
  21 `vcpkg_check_features()` will:
  22
  23 - for each `<feature-name>` passed in `FEATURES`:
  24     - if the feature is set, add `-D<feature-var>=ON` to `<out-var>`,
  25       and set `<prefix>_<feature-var>` to ON.
  26     - if the feature is not set, add `-D<feature-var>=OFF` to `<out-var>`,
  27       and set `<prefix>_<feature-var>` to OFF.
  28 - for each `<feature-name>` passed in `INVERTED_FEATURES`:
  29     - if the feature is set, add `-D<feature-var>=OFF` to `<out-var>`,
  30       and set `<prefix>_<feature-var>` to OFF.
  31     - if the feature is not set, add `-D<feature-var>=ON` to `<out-var>`,
  32       and set `<prefix>_<feature-var>` to ON.
  33
  34 If `<prefix>` is not passed, then the feature vars set are simply `<feature-var>`,
  35 not `_<feature-var>`.
  36
  37 If `INVERTED_FEATURES` is not passed, then the `FEATURES` keyword is optional.
  38 This behavior is deprecated.
  39
  40 If the same `<feature-var>` is passed multiple times,
  41 then `vcpkg_check_features` will cause a fatal error,
  42 since that is a bug.
  43
  44 ## Examples
  45
  46 ### Example 1: Regular features
  47
  48 ```cmake
  49 $ ./vcpkg install mimalloc[asm,secure]
  50
  51 # ports/mimalloc/portfile.cmake
  52 vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
  53     FEATURES
  54         asm       MI_SEE_ASM
  55         override  MI_OVERRIDE
  56         secure    MI_SECURE
  57 )
  58
  59 vcpkg_configure_cmake(
  60     SOURCE_PATH ${SOURCE_PATH}
  61     PREFER_NINJA
  62     OPTIONS
  63         # Expands to "-DMI_SEE_ASM=ON;-DMI_OVERRIDE=OFF;-DMI_SECURE=ON"
  64         ${FEATURE_OPTIONS}
  65 )
  66 ```
  67
  68 ### Example 2: Inverted features
  69
  70 ```cmake
  71 $ ./vcpkg install cpprestsdk[websockets]
  72
  73 # ports/cpprestsdk/portfile.cmake
  74 vcpkg_check_features(
  75     INVERTED_FEATURES
  76         brotli      CPPREST_EXCLUDE_BROTLI
  77         websockets  CPPREST_EXCLUDE_WEBSOCKETS
  78 )
  79
  80 vcpkg_configure_cmake(
  81     SOURCE_PATH ${SOURCE_PATH}
  82     PREFER_NINJA
  83     OPTIONS
  84         # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON;-DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
  85         ${FEATURE_OPTIONS}
  86 )
  87 ```
  88
  89 ### Example 3: Set multiple options for same feature
  90
  91 ```cmake
  92 $ ./vcpkg install pcl[cuda]
  93
  94 # ports/pcl/portfile.cmake
  95 vcpkg_check_features(
  96     FEATURES
  97         cuda  WITH_CUDA
  98         cuda  BUILD_CUDA
  99         cuda  BUILD_GPU
 100 )
 101
 102 vcpkg_configure_cmake(
 103     SOURCE_PATH ${SOURCE_PATH}
 104     PREFER_NINJA
 105     OPTIONS
 106         # Expands to "-DWITH_CUDA=ON;-DBUILD_CUDA=ON;-DBUILD_GPU=ON"
 107         ${FEATURE_OPTIONS}
 108 )
 109 ```
 110
 111 ### Example 4: Use regular and inverted features
 112
 113 ```cmake
 114 $ ./vcpkg install rocksdb[tbb]
 115
 116 # ports/rocksdb/portfile.cmake
 117 vcpkg_check_features(
 118     FEATURES
 119         tbb   WITH_TBB
 120     INVERTED_FEATURES
 121         tbb   ROCKSDB_IGNORE_PACKAGE_TBB
 122 )
 123
 124 vcpkg_configure_cmake(
 125     SOURCE_PATH ${SOURCE_PATH}
 126     PREFER_NINJA
 127     OPTIONS
 128         # Expands to "-DWITH_TBB=ON;-DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
 129         ${FEATURE_OPTIONS}
 130 )
 131 ```
 132
 133 ## Examples in portfiles
 134
 135 * [cpprestsdk](https://github.com/microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
 136 * [pcl](https://github.com/microsoft/vcpkg/blob/master/ports/pcl/portfile.cmake)
 137 * [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
 138
 139 ## Source
 140 [scripts/cmake/vcpkg\_check\_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)