ceph/src/jaegertracing/opentelemetry-cpp/tools/vcpkg/docs/users/manifests.md

   1 # Manifest Mode
   2
   3 **The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/manifests.md).**
   4
   5 vcpkg has two modes of consuming dependencies - classic mode and manifest mode.
   6
   7 In classic mode, vcpkg produces an "installed" tree, whose contents are changed by explicit calls to `vcpkg install` or
   8 `vcpkg remove`. The installed tree is intended for consumption by any number of projects: for example, installing a
   9 bunch of libraries and then using those libraries from Visual Studio, without additional configuration. Because the
  10 installed tree is not associated with an individual project, it's similar to tools like `brew` or `apt`, except that the
  11 installed tree is vcpkg-installation-local, rather than global to a system or user.
  12
  13 In manifest mode, an installed tree is associated with a particular project rather than the vcpkg installation. The set
  14 of installed ports is controlled by editing the project's "manifest file", and the installed tree is placed in the
  15 project directory or build directory. This mode acts more similarly to language package managers like Cargo, or npm. We
  16 recommend using this manifest mode whenever possible, because it allows one to encode a project's dependencies
  17 explicitly in a project file, rather than in the documentation, making your project much easier to consume.
  18
  19 Manifest mode is in beta, but it can be used from the CMake or MSBuild integration, which will be stable when used via
  20 things like `find_package`. This is the recommended way to use manifest mode.
  21
  22 Check out the [manifest cmake example](../examples/manifest-mode-cmake.md) for an example project using CMake and
  23 manifest mode.
  24
  25 ## Table of Contents
  26
  27 - [Simple Example Manifest](#simple-example-manifest)
  28 - [Manifest Syntax Reference](#manifest-syntax-reference)
  29 - [Command Line Interface](#command-line-interface)
  30 - [CMake Integration](#cmake-integration)
  31 - [MSBuild Integration](#msbuild-integration)
  32
  33 See also [the original specification](../specifications/manifests.md) for more low-level details.
  34
  35 ## Simple Example Manifest
  36
  37 ```json
  38 {
  39   "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg/master/scripts/vcpkg.schema.json",
  40   "name": "my-application",
  41   "version": "0.15.2",
  42   "dependencies": [
  43     "boost-system",
  44     {
  45       "name": "cpprestsdk",
  46       "default-features": false
  47     },
  48     "libxml2",
  49     "yajl"
  50   ]
  51 }
  52 ```
  53
  54 ## Manifest Syntax Reference
  55
  56 A manifest is a JSON-formatted file named `vcpkg.json` which lies at the root of your project.
  57 It contains all the information a person needs to know to get dependencies for your project,
  58 as well as all the metadata about your project that a person who depends on you might be interested in.
  59
  60 Manifests follow strict JSON: they can't contain C++-style comments (`//`) nor trailing commas. However
  61 you can use field names that start with `$` to write your comments in any object that has a well-defined set of keys.
  62 These comment fields are not allowed in any objects which permit user-defined keys (such as `"features"`).
  63
  64 Each manifest contains a top level object with the fields documented below; the most important ones are
  65 [`"name"`](#name), the [version fields](#version-fields), and [`"dependencies"`](#dependencies):
  66
  67 ### `"name"`
  68
  69 This is the name of your project! It must be formatted in a way that vcpkg understands - in other words,
  70 it must be lowercase alphabetic characters, digits, and hyphens, and it must not start nor end with a hyphen.
  71 For example, `Boost.Asio` might be given the name `boost-asio`.
  72
  73 This is a required field.
  74
  75 ### Version fields
  76
  77 There is, at this point, only one version field - `"version-string"`. However, more will be added in the future.
  78 You must have one (and only one) version field. There are different reasons to use each version field:
  79
  80 * `"version-string"` - used for packages that don't have orderable versions. This is pretty uncommon,
  81   but since we don't have any versioning constraints yet, this is the only one that you can use.
  82
  83 Additionally, the `"port-version"` field is used by registries of packages,
  84 as a way to version "the package gotten from `vcpkg install`" differently from the upstream package version.
  85 You shouldn't need to worry about this at all.
  86
  87 #### Additional version fields
  88
  89 **Experimental behind the `versions` feature flag**
  90
  91 See [versioning](versioning.md#version-schemes) for additional version types.
  92
  93 ### `"description"`
  94
  95 This is where you describe your project. Give it a good description to help in searching for it!
  96 This can be a single string, or it can be an array of strings;
  97 in the latter case, the first string is treated as a summary,
  98 while the remaining strings are treated as the full description.
  99
 100 ### `"builtin-baseline"`
 101
 102 **Experimental behind the `versions` feature flag**
 103
 104 This field indicates the commit of vcpkg which provides global minimum version information for your manifest. It is required for top-level manifest files using versioning.
 105
 106 See also [versioning](versioning.md#builtin-baseline) for more semantic details.
 107
 108 ### `"dependencies"`
 109
 110 This field lists all the dependencies you'll need to build your library (as well as any your dependents might need,
 111 if they were to use you). It's an array of strings and objects:
 112
 113 * A string dependency (e.g., `"dependencies": [ "zlib" ]`) is the simplest way one can depend on a library;
 114   it means you don't depend on a single version, and don't need to write down any more information.
 115 * On the other hand, an object dependency (e.g., `"dependencies": [ { "name": "zlib" } ]`)
 116   allows you to add that extra information.
 117
 118 #### Example:
 119
 120 ```json
 121 "dependencies": [
 122   {
 123     "name": "arrow",
 124     "default-features": false,
 125     "features": [ "json" ]
 126   },
 127   "boost-asio",
 128   "openssl",
 129   {
 130     "name": "picosha2",
 131     "platform": "!windows"
 132   }
 133 ]
 134 ```
 135
 136 #### `"name"` Field
 137
 138 The name of the dependency. This follows the same restrictions as the [`"name"`](#name) property for a project.
 139
 140 #### `"features"` and `"default-features"` Fields
 141
 142 `"features"` is an array of feature names which tell you the set of features that the
 143 dependencies need to have at a minimum,
 144 while `"default-features"` is a boolean that tells vcpkg whether or not to
 145 install the features the package author thinks should be "most common for most people to use".
 146
 147 For example, `ffmpeg` is a library which supports many, many audio and video codecs;
 148 however, for your specific project, you may only need mp3 encoding.
 149 Then, you might just ask for:
 150
 151 ```json
 152 {
 153   "name": "ffmpeg",
 154   "default-features": false,
 155   "features": [ "mp3lame" ]
 156 }
 157 ```
 158
 159 #### `"platform"` Field
 160
 161 The `"platform"` field defines the platforms where the dependency should be installed - for example,
 162 you might need to use sha256, and so you use platform primitives on Windows, but `picosha2` on non-Windows platforms.
 163
 164 ```json
 165 {
 166   "name": "picosha2",
 167   "platform": "!windows"
 168 }
 169 ```
 170
 171 This is a string field which takes boolean expressions of the form `<identifier>`,
 172 `!expression`, `expression { & expression & expression...}`, and `expression { | expression | expression...}`,
 173 along with parentheses to denote precedence.
 174 For example, a dependency that's only installed on the Windows OS, for the ARM64 architecture,
 175 and on Linux on x64, would be written `(windows & arm64) | (linux & x64)`.
 176
 177 The common identifiers are:
 178
 179 - The operating system: `windows`, `uwp`, `linux`, `osx` (includes macOS), `android`, `emscripten`
 180 - The architecture: `x86`, `x64`, `wasm32`, `arm64`, `arm` (includes both arm32 and arm64 due to backwards compatibility)
 181
 182 although one can define their own.
 183
 184 #### `"version>="` Field
 185
 186 **Experimental behind the `versions` feature flag**
 187
 188 A minimum version constraint on the dependency.
 189
 190 This field specifies the minimum version of the dependency using a '#' suffix to denote port-version if non-zero.
 191
 192 See also [versioning](versioning.md#version-1) for more semantic details.
 193
 194 ### `"overrides"`
 195
 196 **Experimental behind the `versions` feature flag**
 197
 198 This field enables version resolution to be ignored for certain dependencies and to use specific versions instead.
 199
 200 See also [versioning](versioning.md#overrides) for more semantic details.
 201
 202 #### Example:
 203
 204 ```json
 205   "overrides": [
 206     {
 207       "name": "arrow", "version": "1.2.3", "port-version": 7
 208     }
 209   ]
 210 ```
 211
 212 ### `"supports"`
 213
 214 If your project doesn't support common platforms, you can tell your users this with the `"supports"` field.
 215 It uses the same platform expressions as [`"platform"`](#platform), from dependencies, as well as the
 216 `"supports"` field of features.
 217 For example, if your library doesn't support linux, you might write `{ "supports": "!linux" }`.
 218
 219
 220 ### `"features"` and `"default-features"`
 221
 222 The `"features"` field defines _your_ project's optional features, that others may either depend on or not.
 223 It's an object, where the keys are the names of the features, and the values are objects describing the feature.
 224 `"description"` is required,
 225 and acts exactly like the [`"description"`](#description) field on the global package,
 226 and `"dependencies"` are optional,
 227 and again act exactly like the [`"dependencies"`](#dependencies) field on the global package.
 228 There's also the `"supports"` field,
 229 which again acts exactly like the [`"supports"`](#supports) field on the global package.
 230
 231 You also have control over which features are default, if a person doesn't ask for anything specific,
 232 and that's the `"default-features"` field, which is an array of feature names.
 233
 234 #### Example:
 235
 236 ```json
 237 {
 238   "name": "libdb",
 239   "version": "1.0.0",
 240   "description": [
 241     "An example database library.",
 242     "Optionally can build with CBOR, JSON, or CSV as backends."
 243   ],
 244   "$default-features-explanation": "Users using this library transitively will get all backends automatically",
 245   "default-features": [ "cbor", "csv", "json" ],
 246   "features": {
 247     "cbor": {
 248       "description": "The CBOR backend",
 249       "dependencies": [
 250         {
 251           "$explanation": [
 252             "This is how you tell vcpkg that the cbor feature depends on the json feature of this package"
 253           ],
 254           "name": "libdb",
 255           "default-features": false,
 256           "features": [ "json" ]
 257         }
 258       ]
 259     },
 260     "csv": {
 261       "description": "The CSV backend",
 262       "dependencies": [
 263         "fast-cpp-csv-parser"
 264       ]
 265     },
 266     "json": {
 267       "description": "The JSON backend",
 268       "dependencies": [
 269         "jsoncons"
 270       ]
 271     }
 272   }
 273 }
 274 ```
 275
 276 ## Command Line Interface
 277
 278 **Experimental behind the `manifests` feature flag**
 279
 280 When invoked from any subdirectory of the directory containing `vcpkg.json`, `vcpkg install` with no package arguments
 281 will install all manifest dependencies into `<directory containing vcpkg.json>/vcpkg_installed/`. Most of `vcpkg
 282 install`'s classic mode parameters function the same in manifest mode.
 283
 284 ### `--x-install-root=<path>`
 285
 286 **Experimental and may change or be removed at any time**
 287
 288 Specifies an alternate install location than `<directory containing vcpkg.json>/vcpkg_installed/`.
 289
 290 ### `--triplet=<triplet>`
 291
 292 Specify the triplet to be used for installation.
 293
 294 Defaults to the same default triplet as in classic mode.
 295
 296 ### `--x-feature=<feature>`
 297
 298 **Experimental and may change or be removed at any time**
 299
 300 Specify an additional feature from the `vcpkg.json` to install dependencies from.
 301
 302 ### `--x-no-default-features`
 303
 304 **Experimental and may change or be removed at any time**
 305
 306 Disables automatic activation of all default features listed in the `vcpkg.json`.
 307
 308 ### `--x-manifest-root=<path>`
 309
 310 **Experimental and may change or be removed at any time**
 311
 312 Specifies the directory containing `vcpkg.json`.
 313
 314 Defaults to searching upwards from the current working directory.
 315
 316 ## CMake Integration
 317
 318 Our [CMake Integration](integration.md#cmake) will automatically detect a `vcpkg.json` manifest file in the same
 319 directory as the top-level `CMakeLists.txt` (`${CMAKE_SOURCE_DIR}/vcpkg.json`) and activate manifest mode. Vcpkg will be
 320 automatically bootstrapped if missing and invoked to install your dependencies into your local build directory
 321 (`${CMAKE_BINARY_DIR}/vcpkg_installed`).
 322
 323 ### Configuration
 324
 325 All vcpkg-affecting variables must be defined before the first `project()` directive, such as via the command line or
 326 `set()` statements.
 327
 328 #### `VCPKG_TARGET_TRIPLET`
 329
 330 This variable controls which triplet dependencies will be installed for.
 331
 332 If unset, vcpkg will automatically detect an appropriate default triplet given the current compiler settings.
 333
 334 #### `VCPKG_HOST_TRIPLET`
 335
 336 This variable controls which triplet host dependencies will be installed for.
 337
 338 If unset, vcpkg will automatically detect an appropriate native triplet (x64-windows, x64-osx, x64-linux).
 339
 340 See also [Host Dependencies](host-dependencies.md).
 341
 342 #### `VCPKG_MANIFEST_MODE`
 343
 344 This variable controls whether vcpkg operates in manifest mode or in classic mode. To disable manifest mode even with a
 345 `vcpkg.json`, set this to `OFF`.
 346
 347 Defaults to `ON` when `VCPKG_MANIFEST_DIR` is non-empty or `${CMAKE_SOURCE_DIR}/vcpkg.json` exists.
 348
 349 #### `VCPKG_MANIFEST_DIR`
 350
 351 This variable can be defined to specify an alternate folder containing your `vcpkg.json` manifest.
 352
 353 Defaults to `${CMAKE_SOURCE_DIR}` if `${CMAKE_SOURCE_DIR}/vcpkg.json` exists.
 354
 355 #### `VCPKG_MANIFEST_INSTALL`
 356
 357 This variable controls whether vcpkg will be automatically run to install your dependencies during your configure step.
 358
 359 Defaults to `ON` if `VCPKG_MANIFEST_MODE` is `ON`.
 360
 361 #### `VCPKG_BOOTSTRAP_OPTIONS`
 362
 363 This variable can be set to additional command parameters to pass to `./bootstrap-vcpkg` (run in automatic restore mode
 364 if the vcpkg tool does not exist).
 365
 366 #### `VCPKG_OVERLAY_TRIPLETS`
 367
 368 This variable can be set to a list of paths to be passed on the command line as `--overlay-triplets=...`
 369
 370 #### `VCPKG_OVERLAY_PORTS`
 371
 372 This variable can be set to a list of paths to be passed on the command line as `--overlay-ports=...`
 373
 374 #### `VCPKG_MANIFEST_FEATURES`
 375
 376 This variable can be set to a list of features to treat as active when installing from your manifest.
 377
 378 For example, Features can be used by projects to control building with additional dependencies to enable tests or
 379 samples:
 380
 381 ```json
 382 {
 383   "name": "mylibrary",
 384   "version": "1.0",
 385   "dependencies": [ "curl" ],
 386   "features": {
 387     "samples": {
 388       "description": "Build Samples",
 389       "dependencies": [ "fltk" ]
 390     },
 391     "tests": {
 392       "description": "Build Tests",
 393       "dependencies": [ "gtest" ]
 394     }
 395   }
 396 }
 397 ```
 398 ```cmake
 399 # CMakeLists.txt
 400
 401 option(BUILD_TESTING "Build tests" OFF)
 402 if(BUILD_TESTING)
 403   list(APPEND VCPKG_MANIFEST_FEATURES "tests")
 404 endif()
 405
 406 option(BUILD_SAMPLES "Build samples" OFF)
 407 if(BUILD_SAMPLES)
 408   list(APPEND VCPKG_MANIFEST_FEATURES "samples")
 409 endif()
 410
 411 project(myapp)
 412
 413 # ...
 414 ```
 415
 416 #### `VCPKG_MANIFEST_NO_DEFAULT_FEATURES`
 417
 418 This variable controls whether to automatically activate all default features in addition to those listed in
 419 `VCPKG_MANIFEST_FEATURES`. If set to `ON`, default features will not be automatically activated.
 420
 421 Defaults to `OFF`.
 422
 423 #### `VCPKG_INSTALL_OPTIONS`
 424
 425 This variable can be set to a list of additional command line parameters to pass to the vcpkg tool during automatic
 426 installation.
 427
 428 #### `VCPKG_FEATURE_FLAGS`
 429
 430 This variable can be set to a list of feature flags to pass to the vcpkg tool during automatic installation to opt-in to
 431 experimental behavior.
 432
 433 See the `--feature-flags=` command line option for more information.
 434
 435 ## MSBuild Integration
 436
 437 To use manifests with MSBuild, first you need to use an [existing integration method](integration.md#with-msbuild).
 438 Then, simply add a vcpkg.json above your project file (such as in the root of your source repository) and set the
 439 property `VcpkgEnableManifest` to `true`. You can set this property via the IDE in `Project Properties -> Vcpkg -> Use
 440 Vcpkg Manifest`.
 441
 442 As part of your project's build, vcpkg automatically be run and install any listed dependencies to `vcpkg_installed/`
 443 adjacent to the `vcpkg.json` file; these files will then automatically be included in and linked to your MSBuild
 444 projects.
 445
 446 Note: It is critical that all project files in a single build consuming the same `vcpkg.json` use the same triplet; if
 447 you need to use different triplets for different projects in your solution, they must consume from different
 448 `vcpkg.json` files.
 449
 450 ### MSBuild Properties
 451
 452 These properties can be defined via the VS GUI under `Project Properties -> Vcpkg` or via a common `.props` file.
 453
 454 #### `VcpkgEnabled` (Use Vcpkg)
 455
 456 This can be set to "false" to explicitly disable vcpkg integration for the project
 457
 458 #### `VcpkgTriplet` (Triplet)
 459
 460 This can be set to a custom triplet to use for integration (such as x64-windows-static)
 461
 462 #### `VcpkgHostTriplet` (Host Triplet)
 463
 464 This can be set to a custom triplet to use for resolving host dependencies.
 465
 466 If unset, this will default to the "native" triplet (x64-windows, x64-osx, x64-linux).
 467
 468 See also [Host Dependencies](host-dependencies.md).
 469
 470 #### `VcpkgAdditionalInstallOptions` (Additional Options)
 471
 472 When using a manifest, this option specifies additional command line flags to pass to the underlying vcpkg tool
 473 invocation. This can be used to access features that have not yet been exposed through another option.
 474
 475 #### `VcpkgConfiguration` (Vcpkg Configuration)
 476
 477 If your configuration names are too complex for vcpkg to guess correctly, you can assign this property to `Release` or
 478 `Debug` to explicitly tell vcpkg what variant of libraries you want to consume.
 479
 480 #### `VcpkgEnableManifest` (Use Vcpkg Manifest)
 481
 482 This property must be set to true in order to consume from a local vcpkg.json file. If set to false, any local
 483 vcpkg.json files will be ignored. This will default to true in the future.
 484
 485 #### `VcpkgManifestInstall` (Install Vcpkg Dependencies)
 486
 487 *(Requires `Use Vcpkg Manifest` set to `true`)*
 488
 489 This property can be set to "false" to disable automatic dependency restoration on project build. Dependencies can be
 490 manually restored via the vcpkg command line.
 491
 492 #### `VcpkgInstalledDirectory` (Installed Directory)
 493
 494 This property defines the location where headers and binaries are consumed from. In manifest mode, this directory is
 495 created and populated based on your manifest.