From 76b754e52ddcb2d2a6958e4a913d0371c00279d8 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Tue, 6 Jun 2017 11:40:47 -0700 Subject: [vcpkg-docs] Initial commit of triplets documentation --- docs/index.md | 1 + docs/maintainers/control-files.md | 18 ++++++------- docs/users/triplets.md | 54 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 64 insertions(+), 9 deletions(-) create mode 100644 docs/users/triplets.md (limited to 'docs') diff --git a/docs/index.md b/docs/index.md index 9b279baf0..3fa5784e9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,6 +13,7 @@ Vcpkg helps you get C and C++ libraries on Windows. This tool and ecosystem are ### User Help - [Integration with build systems](users/integration.md) +- [Triplet files](users/triplets.md) ### Maintainer help diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md index 1cb444df3..e446fe6fa 100644 --- a/docs/maintainers/control-files.md +++ b/docs/maintainers/control-files.md @@ -1,16 +1,16 @@ -## `CONTROL` files -Each port has some static metadata in the form of a `CONTROL` file. This file uses the same rough syntax as and a subset of the fields from [the Debian `control` format][debian]. +# CONTROL files +Each port has some static metadata in the form of a `CONTROL` file. This file uses the same syntax and a subset of the fields from [the Debian `control` format][debian]. -Fields are case-sensitive. +Field names are case-sensitive. [debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html -### Recognized fields +## Recognized fields -#### Source +### Source The name of the port. -#### Version +### Version The port version. This field should be an alphanumeric string which may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bitstrings and are only evaluated for equality. @@ -22,15 +22,15 @@ Example: Version: 1.0.5-2 ``` -#### Description +### Description A description of the library The first sentence of the description should concisely describe the purpose and contents of the library. Then, a larger description including the library's "proper name" should follow. -#### Maintainer +### Maintainer Reserved for future use. -#### Build-Depends +### Build-Depends The list of dependencies required to build and use this library. Example: diff --git a/docs/users/triplets.md b/docs/users/triplets.md new file mode 100644 index 000000000..2b0971da3 --- /dev/null +++ b/docs/users/triplets.md @@ -0,0 +1,54 @@ +# 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. + +In Vcpkg, we use triplets to describe self-consistent builds of library sets. This means every library will be built using the same target cpu, OS, and compiler toolchain, but also CRT linkage and preferred library type. + +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`. + +## Variables +### VCPKG_TARGET_ARCHITECTURE +Specifies the target machine architecture. + +Valid options are `x86`, `x64`, and `arm`. + +### VCPKG_CRT_LINKAGE +Specifies the desired MSVCRT linkage. + +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. + +Valid options are `WindowsStore` or empty. Empty corresponds to Windows Desktop and `WindowsStore` corresponds to UWP. +When setting this variable to `WindowsStore`, you must also set `VCPKG_CMAKE_SYSTEM_VERSION` to `10.0`. + +### VCPKG_PLATFORM_TOOLSET +Specifies the C/C++ compiler toolchain to use. + +This can be set to `v141`, `v140`, or left blank. If left blank, we select the latest compiler toolset available on your machine. + +## 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) +set(VCPKG_CRT_LINKAGE dynamic) +if(PORT STREQUAL "qt5") + set(VCPKG_LIBRARY_LINKAGE dynamic) +endif() +``` +This will build `qt5` as DLLs against the dynamic CRT, but every other library as a static library (still against the dynamic CRT). + +For an example in a real project, see https://github.com/Intelight/vcpkg/blob/master/triplets/x86-windows-mixed.cmake. + +## Additional Remarks +The default triplet when running any vcpkg command is `%VCPKG_DEFAULT_TRIPLET%` or `x86-windows` if that environment variable is undefined. + +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. -- cgit v1.2.3 From b90dbbc928d5880de690392f431d12321b337481 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Wed, 7 Jun 2017 17:08:13 -0700 Subject: [vcpkg-docs] Document how to change the deduced triplet for cmake and msbuild. Fixes #1185. --- docs/users/integration.md | 38 +++++++++++++++++++++++++++++++++++++- docs/users/triplets.md | 2 ++ 2 files changed, 39 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/users/integration.md b/docs/users/integration.md index 38332f1aa..1e52adb88 100644 --- a/docs/users/integration.md +++ b/docs/users/integration.md @@ -5,11 +5,14 @@ Vcpkg offers many ways to integrate into your build so you can do what's right f - [`integrate` command](#integrate) - [`export` command](#export) +Each integration style has heuristics to deduce the correct [triplet][]. This can be overridden using [a common method](#triplet-selection) based on your buildsystem. + ### Integrate Command These link your project(s) to a specific copy of Vcpkg on your machine so any updates or new package installations will be instantly available for the next build of your project. + #### User-wide for MSBuild (Recommended for Open Source MSBuild projects) ```no-highlight vcpkg integrate install @@ -82,4 +85,37 @@ Each of these have the same layout, which mimics the layout of a full vcpkg: Additionally, NuGet packages will contain a `build\native\vcpkg.targets` that integrates with MSBuild projects. -Please also see our [blog post](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) for additional examples. \ No newline at end of file +Please also see our [blog post](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) for additional examples. + + +### Triplet selection +Every integration mechanism besides manually adding the folders will deduce a [triplet][] for your project as one of: +- x86-windows +- x64-windows +- x86-uwp +- x64-uwp +- arm-uwp + +#### With MSBuild +You can see the automatically deduced triplet by setting your MSBuild verbosity to Normal or higher: + +> *Shortcut: Ctrl+Q "build and run"* +> +> Tools -> Options -> Projects and Solutions -> Build and Run -> MSBuild project build output verbosity + +To override the automatically chosen [triplet][], you can specify the MSBuild property `VcpkgTriplet` in your `.vcxproj`. We recommend adding this to the `Globals` PropertyGroup. +```xml + + + x86-windows-static + x64-windows-static + +``` + +#### With CMake +Simply set `VCPKG_TARGET_TRIPLET` on the configure line. +```no-highlight +cmake ../my/project -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=... +``` + +[triplet]: triplets.md diff --git a/docs/users/triplets.md b/docs/users/triplets.md index 2b0971da3..06f77e63f 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -6,6 +6,8 @@ In Vcpkg, we use triplets to describe self-consistent builds of library sets. Th 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`. +To change the triplet used by your project, such as to enable static linking, see our [Integration Document](integration.md#triplet-selection). + ## Variables ### VCPKG_TARGET_ARCHITECTURE Specifies the target machine architecture. -- cgit v1.2.3