2018-12-13 01:22:16 +08:00
## Environment and Configuration
2021-03-12 08:37:49 +08:00
**The latest version of this documentation is available on [GitHub ](https://github.com/Microsoft/vcpkg/tree/master/docs/users/config-environment.md ).**
2018-12-13 01:22:16 +08:00
### Environment Variables
#### VCPKG_DOWNLOADS
This environment variable can be set to an existing directory to use for storing downloads instead of the internal
`downloads/` directory. It should always be set to an absolute path.
#### VCPKG_FEATURE_FLAGS
This environment variable can be set to a comma-separated list of off-by-default features in vcpkg. These features are
subject to change without notice and should be considered highly unstable.
Non-exhaustive list of off-by-default features:
[vcpkg manifest] Manifest Implementation (#11757)
==== Changes Related to manifests ====
* Add the `manifests` feature flag
* This only says whether we look for a `vcpkg.json` in the cwd, not
whether we support parsing manifests (for ports, for example)
* Changes to the manifests RFC
* `"authors"` -> `"maintainers"`
* `--x-classic-mode` -> `-manifests` \in `vcpkg_feature_flags`
* reserve `"core"` in addition to `"default"`, since that's already
reserved for features
* Add a small helper note about what identifiers must look like
* `<license-string>`: SPDX v3.8 -> v3.9
* `"feature"."description"` is allowed to be an array of strings as well
* `"version"` -> `"version-string"` for forward-compat with versions
RFC
* Add the `--feature-flags` option
* Add the ability to turn off feature flags via passing
`-<feature-flag>` to `VCPKG_FEATURE_FLAGS` or `--feature-flags`
* Add CMake toolchain support for manifests
* Requires either:
* a feature flag of `manifests` in either `Env{VCPKG_FEATURE_FLAGS}`
or `VCPKG_FEATURE_FLAGS`
* Passing the `VCPKG_ENABLE_MANIFESTS` option
* The toolchain will install your packages to
`${VCPKG_MANIFEST_DIR}/vcpkg_installed`.
* Add MSBuild `vcpkg integrate install` support for manifests
* Requires `VcpkgEnableManifest` to be true
* `vcpkg create` creates a port that has a `vcpkg.json` instead of a
`CONTROL`
* argparse, abseil, 3fd, and avisynthplus ports switched to manifest
from CONTROL
* Add support for `--x-manifest-root`, as well as code for finding it if
not passed
* Add support for parsing manifests!
* Add a filesystem lock!
==== Important Changes which are somewhat unrelated to manifests ====
* Rename `logicexpression.{h,cpp}` to `platform-expression.{h,cpp}`
* Add `PlatformExpression` type which takes the place of the old logic
expression
* Split the parsing of platform expressions from checking whether
they're true or not
* Eagerly parse PlatformExpressions as opposed to leaving them as
strings
* Add checking for feature flag consistency
* i.e., if `-binarycaching` is passed, you shouldn't be passing
`--binarysource`
* Add the `Json::Reader` type which, with the help of user-defined
visitors, converts JSON to your internal type
* VcpkgArgParser: place the switch names into a constant as opposed to
using magic constants
* In general update the parsing code so that this ^ works
* Add `Port-Version` fields to CONTROL files
* This replaces the existing practice of
`Version: <my-version>-<port-version>`
==== Smaller changes ====
* small drive-by cleanups to some CMake
* `${_VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}` ->
`${CURRENT_INSTALLED_DIR}`
* Remove `-analyze` when compiling with clang-cl, since that's not a
supported flag (vcpkg's build system)
* Add a message about which compiler is detected by vcpkg's build
system machinery
* Fix `Expected::then`
* Convert `""` to `{}` for `std::string` and `fs::path`, to avoid a
`strlen` (additionally, `.empty()` instead of `== ""`, and `.clear()`)
* Add `Strings::strto` which converts strings to numeric types
* Support built-in arrays and `StringView` for `Strings::join`
* Add `operator<` and friends to `StringView`
* Add `substr` to `StringView`
* SourceParagraphParser gets some new errors
2020-07-01 01:40:18 +08:00
- `manifest`
2018-12-13 01:22:16 +08:00
#### EDITOR
This environment variable can be set to the full path of an executable to be used for `vcpkg edit` . Please see
`vcpkg help edit` for command-specific help.
#### VCPKG_ROOT
This environment variable can be set to a directory to use as the root of the vcpkg instance. Note that mixing vcpkg
repo versions and executable versions can cause issues.
2019-02-26 05:25:27 +08:00
#### VCPKG_VISUAL_STUDIO_PATH
2018-12-13 01:22:16 +08:00
This environment variable can be set to the full path to a Visual Studio instance on the machine. This Visual Studio instance
2021-04-30 04:39:50 +08:00
will be used if the triplet does not override it via the [`VCPKG_VISUAL_STUDIO_PATH` ](triplets.md#VCPKG_VISUAL_STUDIO_PATH ) triplet setting.
2018-12-13 01:22:16 +08:00
Example: `D:\2017`
#### VCPKG_DEFAULT_TRIPLET
This environment variable can be set to a triplet name which will be used for unqualified triplet references in command lines.
2021-03-11 07:33:16 +08:00
#### VCPKG_DEFAULT_HOST_TRIPLET
2021-04-30 04:39:50 +08:00
This environment variable can be set to a triplet name which will be used for unqualified host port references in command lines and all host port references in dependency lists. See [the host-dependencies documentation ](host-dependencies.md ) for more information.
2021-03-11 07:33:16 +08:00
2020-08-06 02:21:42 +08:00
#### VCPKG_OVERLAY_PORTS
This environment variable allows users to override ports with alternate versions according to the
2021-03-11 07:33:16 +08:00
[ports overlay ](../specifications/ports-overlay.md ) specification. List paths to overlays using
2021-05-10 01:48:42 +08:00
the platform dependent PATH separator (Windows `;` | others `:` )
2020-08-06 02:21:42 +08:00
Example (Windows): `C:\custom-ports\boost;C:\custom-ports\sqlite3`
2020-09-28 22:51:16 +08:00
#### VCPKG_OVERLAY_TRIPLETS
This environment variable allows users to add directories to search for triplets.
[Example: overlay triplets ](../examples/overlay-triplets-linux-dynamic.md ).
2021-05-10 01:48:42 +08:00
List paths to overlays using the platform dependent PATH separator (Windows `;` , others `:` )
2020-09-28 22:51:16 +08:00
2018-12-13 01:22:16 +08:00
#### VCPKG_FORCE_SYSTEM_BINARIES
This environment variable, if set, suppresses the downloading of CMake and Ninja and forces the use of the system binaries.
2019-03-29 05:34:26 +08:00
2020-08-06 02:21:42 +08:00
#### VCPKG_KEEP_ENV_VARS
2019-03-29 05:34:26 +08:00
This environment variable can be set to a list of environment variables, separated by `;` , which will be propagated to
the build environment.
2021-11-16 01:33:53 +08:00
The values of the kept variables will not be tracked in package ABIs and will not cause rebuilds when they change. To
pass in environment variables that should cause rebuilds on change, see [`VCPKG_ENV_PASSTHROUGH` ](triplets.md#VCPKG_ENV_PASSTHROUGH ).
2019-03-29 05:34:26 +08:00
Example: `FOO_SDK_DIR;BAR_SDK_DIR`
2021-01-06 06:37:04 +08:00
#### VCPKG_MAX_CONCURRENCY
This environment variables limits the amount of concurrency requested by underlying buildsystems. If unspecified, this defaults to logical cores + 1.
#### VCPKG_DEFAULT_BINARY_CACHE
This environment variable redirects the default location to store binary packages. See [Binary Caching ](binarycaching.md#Configuration ) for more details.
#### VCPKG_BINARY_SOURCES
This environment variable adds or removes binary sources. See [Binary Caching ](binarycaching.md#Configuration ) for more details.
#### VCPKG_NUGET_REPOSITORY
This environment variable changes the metadata of produced NuGet packages. See [Binary Caching ](binarycaching.md#Configuration ) for more details.
2021-01-25 15:11:02 +08:00
#### VCPKG_USE_NUGET_CACHE
This environment variable allows using NuGet's cache for every nuget-based binary source. See [Binary Caching ](binarycaching.md#NuGets-cache ) for more details.
2021-06-05 07:48:26 +08:00
#### X_VCPKG_ASSET_SOURCES
> Note: This is an experimental feature and may change or be removed at any time
This environment variable allows using a private mirror for all SHA512-tagged assets. See [Asset Caching ](assetcaching.md ) for more details.
