2017-06-07 02:40:47 +08:00
# Triplet files
Triplet is a standard term used in cross compiling as a way to completely capture the target environment (cpu, os, compiler, runtime, etc) in a single convenient name.
2020-02-04 06:22:52 +08:00
In Vcpkg, we use triplets to describe an imaginary "target configuration set" for every library. Within a triplet, libraries are generally built with the same configuration, but it is not a requirement. For example, you could have one triplet that builds `openssl` statically and `zlib` dynamically, one that builds them both statically, and one that builds them both dynamically (all for the same target OS and architecture). A single build will consume files from a single triplet.
2017-06-07 02:40:47 +08:00
We currently provide many triplets by default (run `vcpkg help triplet` ). However, you can easily add your own by creating a new file in the `triplets\` directory. The new triplet will immediately be available for use in commands, such as `vcpkg install boost:x86-windows-custom` .
2017-06-08 08:08:13 +08:00
To change the triplet used by your project, such as to enable static linking, see our [Integration Document ](integration.md#triplet-selection ).
2020-01-18 06:21:19 +08:00
## Community triplets
2020-02-04 06:22:52 +08:00
Triplets contained in the `triplets\community` folder are not tested by continuous integration, but are commonly requested by the community.
2020-01-18 06:21:19 +08:00
2020-02-04 06:22:52 +08:00
Because we do not have continuous coverage, port updates may break compatibility with community triplets. Because of this, community involvement is paramount!
2020-01-18 06:21:19 +08:00
We will gladly accept and review contributions that aim to solve issues with these triplets.
### Usage
Community Triplets are enabled by default, when using a community triplet a message like the following one will be printed during a package install:
2020-02-04 06:22:52 +08:00
```no-highlight
2020-01-18 06:21:19 +08:00
-- Using community triplet x86-uwp. This triplet configuration is not guaranteed to succeed.
-- [COMMUNITY] Loading triplet configuration from: D:\src\viromer\vcpkg\triplets\community\x86-uwp.cmake
```
2017-06-07 02:40:47 +08:00
## Variables
### VCPKG_TARGET_ARCHITECTURE
Specifies the target machine architecture.
2020-06-03 07:07:41 +08:00
Valid options are `x86` , `x64` , `arm` , `arm64` and `wasm32` .
2017-06-07 02:40:47 +08:00
### VCPKG_CRT_LINKAGE
2018-06-26 13:14:07 +08:00
Specifies the desired CRT linkage (for MSVC).
2017-06-07 02:40:47 +08:00
Valid options are `dynamic` and `static` .
### VCPKG_LIBRARY_LINKAGE
Specifies the preferred library linkage.
Valid options are `dynamic` and `static` . Note that libraries can ignore this setting if they do not support the preferred linkage type.
### VCPKG_CMAKE_SYSTEM_NAME
Specifies the target platform.
2018-06-26 13:14:07 +08:00
Valid options include any CMake system name, such as:
- Empty (Windows Desktop for legacy reasons)
- `WindowsStore` (Universal Windows Platform)
2020-07-14 23:38:18 +08:00
- `MinGW` (Minimalist GNU for Windows)
2018-06-26 13:14:07 +08:00
- `Darwin` (Mac OSX)
2020-07-14 23:38:18 +08:00
- `iOS` (iOS)
2018-06-26 13:14:07 +08:00
- `Linux` (Linux)
2020-06-03 07:07:41 +08:00
- `Emscripten` (WebAssembly)
2017-06-07 02:40:47 +08:00
2019-04-12 08:54:53 +08:00
### VCPKG_CMAKE_SYSTEM_VERSION
Specifies the target platform system version.
This field is optional and, if present, will be passed into the build as `CMAKE_SYSTEM_VERSION` .
See also the CMake documentation for `CMAKE_SYSTEM_VERSION` : https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_VERSION.html.
2018-06-19 02:21:03 +08:00
### VCPKG_CHAINLOAD_TOOLCHAIN_FILE
Specifies an alternate CMake Toolchain file to use.
This (if set) will override all other compiler detection logic. By default, a toolchain file is selected from `scripts/toolchains/` appropriate to the platform.
See also the CMake documentation for toolchain files: https://cmake.org/cmake/help/v3.11/manual/cmake-toolchains.7.html.
2018-06-26 13:14:07 +08:00
### VCPKG_CXX_FLAGS
Sets additional compiler flags to be used when not using `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` .
This option also has forms for configuration-specific and C flags:
2018-10-13 07:30:30 +08:00
- `VCPKG_CXX_FLAGS`
2018-06-26 13:14:07 +08:00
- `VCPKG_CXX_FLAGS_DEBUG`
- `VCPKG_CXX_FLAGS_RELEASE`
- `VCPKG_C_FLAGS`
- `VCPKG_C_FLAGS_DEBUG`
- `VCPKG_C_FLAGS_RELEASE`
2020-09-04 02:00:35 +08:00
### VCPKG_LINKER_FLAGS
Sets additional linker flags to be used while building dynamic libraries and
executables in the absence of `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` .
This option also has forms for configuration-specific flags:
- `VCPKG_LINKER_FLAGS`
- `VCPKG_LINKER_FLAGS_DEBUG`
- `VCPKG_LINKER_FLAGS_RELEASE`
2020-02-04 06:22:52 +08:00
< a name = "VCPKG_DEP_INFO_OVERRIDE_VARS" > < / a >
### VCPKG_DEP_INFO_OVERRIDE_VARS
Replaces the default computed list of triplet "Supports" terms.
This option (if set) will override the default set of terms used for qualified dependency resolution and "Supports" field evaluation.
2020-09-15 06:07:02 +08:00
See the [`"supports"` ](../maintainers/manifest-files.md#supports ) manifest file field documentation for more details.
2020-02-04 06:22:52 +08:00
> Implementers' Note: this list is extracted via the `vcpkg_get_dep_info` mechanism.
2018-12-12 03:48:41 +08:00
## Windows Variables
2020-02-04 06:22:52 +08:00
### VCPKG_ENV_PASSTHROUGH
Instructs vcpkg to allow additional environment variables into the build process.
2020-12-18 03:35:08 +08:00
On Windows, vcpkg builds packages in a special clean environment that is isolated from the current command prompt to
ensure build reliability and consistency. This triplet option can be set to a list of additional environment variables
that will be added to the clean environment. The values of these environment variables will be hashed into the package
abi -- to pass through environment variables without abi tracking, see `VCPKG_ENV_PASSTHROUGH_UNTRACKED` .
2020-02-04 06:22:52 +08:00
See also the `vcpkg env` command for how you can inspect the precise environment that will be used.
> Implementers' Note: this list is extracted via the `vcpkg_get_tags` mechanism.
2020-12-18 03:35:08 +08:00
### VCPKG_ENV_PASSTHROUGH_UNTRACKED
Instructs vcpkg to allow additional environment variables into the build process without abi tracking.
See `VCPKG_ENV_PASSTHROUGH` .
2018-12-12 03:48:41 +08:00
< a name = "VCPKG_VISUAL_STUDIO_PATH" > < / a >
### VCPKG_VISUAL_STUDIO_PATH
Specifies the Visual Studio installation to use.
2019-01-31 09:47:36 +08:00
To select the precise combination of Visual Studio instance and toolset version, we walk through the following algorithm:
1. Determine the setting for `VCPKG_VISUAL_STUDIO_PATH` from the triplet, or the environment variable `VCPKG_VISUAL_STUDIO_PATH` , or consider it unset
2. Determine the setting for `VCPKG_PLATFORM_TOOLSET` from the triplet or consider it unset
3. Gather a list of all pairs of Visual Studio Instances with all toolsets available in those instances
1. This is ordered first by instance type (Stable, Prerelease, Legacy) and then by toolset version (v142, v141, v140)
4. Filter the list based on the settings for `VCPKG_VISUAL_STUDIO_PATH` and `VCPKG_PLATFORM_TOOLSET` .
5. Select the best remaining option
2018-12-12 03:48:41 +08:00
The path should be absolute, formatted with backslashes, and have no trailing slash:
```cmake
set(VCPKG_VISUAL_STUDIO_PATH "C:\\Program Files (x86)\\Microsoft Visual Studio\\Preview\\Community")
```
2019-01-31 09:47:36 +08:00
### VCPKG_PLATFORM_TOOLSET
Specifies the VS-based C/C++ compiler toolchain to use.
See [`VCPKG_VISUAL_STUDIO_PATH` ](#VCPKG_VISUAL_STUDIO_PATH ) for the full selection algorithm.
Valid settings:
* The Visual Studio 2019 platform toolset is `v142` .
* The Visual Studio 2017 platform toolset is `v141` .
* The Visual Studio 2015 platform toolset is `v140` .
2020-03-28 11:19:53 +08:00
### VCPKG_LOAD_VCVARS_ENV
2020-07-14 23:38:18 +08:00
If `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` is used, VCPKG will not setup the Visual Studio environment.
2020-03-28 11:19:53 +08:00
Setting `VCPKG_LOAD_VCVARS_ENV` to (true|1|on) changes this behavior so that the Visual Studio environment is setup following the same rules as if `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` was not set.
2018-12-12 03:48:41 +08:00
## MacOS Variables
2018-10-24 07:49:48 +08:00
### VCPKG_INSTALL_NAME_DIR
Sets the install name used when building macOS dynamic libraries. Default value is `@rpath` . See the CMake documentation for [CMAKE_INSTALL_NAME_DIR ](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_NAME_DIR.html ) for more information.
### VCPKG_OSX_DEPLOYMENT_TARGET
Sets the minimum macOS version for compiled binaries. This also changes what versions of the macOS platform SDK that CMake will search for. See the CMake documentation for [CMAKE_OSX_DEPLOYMENT_TARGET ](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_DEPLOYMENT_TARGET.html ) for more information.
### VCPKG_OSX_SYSROOT
Set the name or path of the macOS platform SDK that will be used by CMake. See the CMake documentation for [CMAKE_OSX_SYSROOT ](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_SYSROOT.html ) for more information.
Add initial iOS support (#6275)
* Add iOS community triplets and toolchain support
Added an iOS toolchain to enable building packages for iOS.
The toolchain is used when a triplet's VCPKG_CMAKE_SYSTEM_NAME is set
to iOS.
To configure which architecture should be built, as well as other
iOS specifics, the following triplet variables can be set:
- VCPKG_TARGET_ARCHITECTURE
- VCPKG_OSX_SYSROOT
- VCPKG_OSX_DEPLOYMENT_TARGET
- VCPKG_OSX_ARCHITECTURES
The following VCPKG_TARGET_ARCHITECTURE values are currently
supported:
- arm, arm64, x64, x86.
The following VCPKG_OSX_SYSROOT values are currently supported:
- iphoneos, iphonesimulator, or an absolute path to the device or
simulator Xcode SDK.
VCPKG_OSX_DEPLOYMENT_TARGET can be set to control the minimum iOS
delopyment target for the built libraries.
CMAKE_OSX_ARCHITECTURES is derived from VCPKG_TARGET_ARCHITECTURE,
so generally it should not be set. In case if someone needs to target
a more specific architecture (like armv7k or arm64e), it can
be set in the triplet via VCPKG_OSX_ARCHITECTURES.
Note that only certain combinations of the architecture and sysroot
will work: simulator SDKs only provide x86-based libraries, etc.
The toolchain also sets CMAKE_SYSTEM_PROCESSOR for certain
configurations, because certain packages (like libpng) depend on the
processor type.
Added 4 community iOS triplets that build static libraries:
- arm-ios, arm64-ios, x86-ios, x64-ios.
The non-arm triplets target the iOS simulator.
The triplets build static libraries because they are easiest to
integrate into an iOS project. Dynamic libraries or frameworks require
code signing on iOS, which complicates integration.
Added heuristics to try and automatically detect what iOS triplet to
use when building your own CMake project (so when a CMake project sets
CMAKE_TOOLCHAIN_FILE to buildsystems/vcpkg.cmake), if no explicit
triplet is provided (VCPKG_TARGET_TRIPLET is undefined).
The heuristic checks for the values of CMAKE_SYSTEM_NAME and
CMAKE_OSX_ARCHITECTURES. Note that for this to work,
CMAKE_OSX_ARCHITECTURES needs to be set before the first project()
call in your CMake project.
Added workaround so find_package finds vcpkg installed packages
when targeting iOS.
This is done by saving / restoring the value of CMAKE_FIND_ROOT_PATH
while also adding the vcpkg package root in the find_package override
macro.
The workaround can be removed once vcpkg upgrades to CMake 3.15.0
or higher where the issue is fixed.
Fixes: #6003
* Fix building libpng and pcre2 targetting iOS
Fixes: #6003
2020-04-16 04:06:55 +08:00
### VCPKG_OSX_ARCHITECTURES
Set the macOS / iOS target architecture which will be used by CMake. See the CMake documentation for [CMAKE_OSX_ARCHITECTURES ](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_ARCHITECTURES.html ) for more information.
2017-06-07 02:40:47 +08:00
## Per-port customization
The CMake Macro `PORT` will be set when interpreting the triplet file and can be used to change settings (such as `VCPKG_LIBRARY_LINKAGE` ) on a per-port basis.
Example:
```cmake
set(VCPKG_LIBRARY_LINKAGE static)
2018-02-20 02:04:02 +08:00
if(PORT MATCHES "qt5-")
2017-06-07 02:40:47 +08:00
set(VCPKG_LIBRARY_LINKAGE dynamic)
endif()
```
2018-06-26 13:14:07 +08:00
This will build all the `qt5-*` libraries as DLLs, but every other library as a static library.
2017-06-07 02:40:47 +08:00
For an example in a real project, see https://github.com/Intelight/vcpkg/blob/master/triplets/x86-windows-mixed.cmake.
## Additional Remarks
2018-06-26 13:14:07 +08:00
The default triplet when running any vcpkg command is `%VCPKG_DEFAULT_TRIPLET%` or a platform-specific choice if that environment variable is undefined.
- Windows: `x86-windows`
- Linux: `x64-linux`
- OSX: `x64-osx`
2017-06-07 02:40:47 +08:00
We recommend using a systematic naming scheme when creating new triplets. The Android toolchain naming scheme is a good source of inspiration: https://developer.android.com/ndk/guides/standalone_toolchain.html.
2020-05-14 07:42:13 +08:00
## Android triplets
See [android.md ](android.md )
