From 56c94a81027dae14ea8adabcbda800d0f7c10d0b Mon Sep 17 00:00:00 2001 From: Simon Brand Date: Thu, 15 Nov 2018 11:18:48 +0000 Subject: Rename example documents The current names and titles of the examples put too much emphasis on the package which is being demonstrated rather than the concept. This can be jarring for newcomers. This patch renames them to put the emphasis on the concept instead. --- docs/users/integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/users') diff --git a/docs/users/integration.md b/docs/users/integration.md index ce52abe23..fbaea41d9 100644 --- a/docs/users/integration.md +++ b/docs/users/integration.md @@ -35,7 +35,7 @@ cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.c ``` Projects configured with the Vcpkg toolchain file will have the appropriate Vcpkg folders added to the cmake search paths. This makes all libraries available to be found through `find_package()`, `find_path()`, and `find_library()`. -See [Example: Using Sqlite](../examples/using-sqlite.md) for a fully worked example using our CMake toolchain. +See [Installing and Using Packages Example: sqlite](../examples/installing-and-using-packages.md) for a fully worked example using our CMake toolchain. Note that we do not automatically add ourselves to your compiler include paths. To use a header-only library, simply use `find_path()`, which will correctly work on all platforms: ```cmake -- cgit v1.2.3 From cf7e2f3906f78dcb89f320a642428b54c00e4e0b Mon Sep 17 00:00:00 2001 From: Billy O'Neal Date: Tue, 11 Dec 2018 11:48:41 -0800 Subject: Allow redirection of the downloads folder with an environment variable. (#4883) * Add detection for VCPKG_DOWNLOADS environment variable in vcpkgpaths.cpp. * Pass the downloads directory from VcpkgPaths to cmake. * Also fixup bootstrap on *nix. * Make error message a little prettier. * Make that bash script actually work :) * [vcpkg] Alter Optional<> usage style * [vcpkg-docs] Add section on Environment Variables to the docs --- docs/users/triplets.md | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) (limited to 'docs/users') diff --git a/docs/users/triplets.md b/docs/users/triplets.md index 9ff372aed..4f23c8e27 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -33,24 +33,6 @@ Valid options include any CMake system name, such as: - `Darwin` (Mac OSX) - `Linux` (Linux) -### VCPKG_PLATFORM_TOOLSET -Specifies the VS-based 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. - -Visual Studio 2015 platform toolset is `v140` -Visual Studio 2017 platform toolset is `v141` - -### VCPKG_VISUAL_STUDIO_PATH -Specifies the Visual Studio installation to use. - -When unspecified, a Visual Studio instance is selected automatically, preferring Stable 2017, then Preview 2017, then 2015. - -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") -``` - ### VCPKG_CHAINLOAD_TOOLCHAIN_FILE Specifies an alternate CMake Toolchain file to use. @@ -69,7 +51,28 @@ This option also has forms for configuration-specific and C flags: - `VCPKG_C_FLAGS_DEBUG` - `VCPKG_C_FLAGS_RELEASE` -## macOS Variables +## Windows Variables + +### VCPKG_PLATFORM_TOOLSET +Specifies the VS-based 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. + +Visual Studio 2015 platform toolset is `v140` +Visual Studio 2017 platform toolset is `v141` + + +### VCPKG_VISUAL_STUDIO_PATH +Specifies the Visual Studio installation to use. + +When unspecified, a Visual Studio instance is selected automatically, preferring Stable 2017, then Preview 2017, then 2015. + +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") +``` + +## MacOS Variables ### 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. -- cgit v1.2.3 From 1d5e22919fcfeba3fe513248e73395c42ac18ae4 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Wed, 12 Dec 2018 09:22:16 -0800 Subject: [docs] Add config-environment.md --- docs/users/config-environment.md | 42 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/users/config-environment.md (limited to 'docs/users') diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md new file mode 100644 index 000000000..103c1c547 --- /dev/null +++ b/docs/users/config-environment.md @@ -0,0 +1,42 @@ +## Environment and Configuration + +### 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: + +- `binarycaching` + +#### 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. + +#### VCPKG_DEFAULT_VS_PATH + +This environment variable can be set to the full path to a Visual Studio instance on the machine. This Visual Studio instance +will be used if the triplet does not override it via the [`VCPKG_VISUAL_STUDIO_PATH` triplet setting](triplets.md#VCPKG_VISUAL_STUDIO_PATH). + +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. + +#### VCPKG_FORCE_SYSTEM_BINARIES + +This environment variable, if set, suppresses the downloading of CMake and Ninja and forces the use of the system binaries. -- cgit v1.2.3 From 8ba6cbec0dfc6c8d692136d27c74f98387233641 Mon Sep 17 00:00:00 2001 From: myd7349 Date: Tue, 18 Dec 2018 08:41:17 +0800 Subject: [docs] Fix #4932 (#4982) --- docs/users/integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/users') diff --git a/docs/users/integration.md b/docs/users/integration.md index fbaea41d9..10f5574c1 100644 --- a/docs/users/integration.md +++ b/docs/users/integration.md @@ -50,7 +50,7 @@ The `CMAKE_TOOLCHAIN_FILE` setting simply must be set before the `project()` dir ```cmake if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE) - set(CMAKE_TOOLCHAIN_FILE "${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake" + set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake" CACHE STRING "") endif() -- cgit v1.2.3 From 36cb7592b18d261f87ef366f9271ca45eadffb88 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Wed, 30 Jan 2019 17:47:36 -0800 Subject: [vcpkg-docs] Improve documentation for Visual Studio 2019 --- docs/users/triplets.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) (limited to 'docs/users') diff --git a/docs/users/triplets.md b/docs/users/triplets.md index 4f23c8e27..87fa72fd3 100644 --- a/docs/users/triplets.md +++ b/docs/users/triplets.md @@ -53,25 +53,33 @@ This option also has forms for configuration-specific and C flags: ## Windows Variables -### VCPKG_PLATFORM_TOOLSET -Specifies the VS-based 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. - -Visual Studio 2015 platform toolset is `v140` -Visual Studio 2017 platform toolset is `v141` - ### VCPKG_VISUAL_STUDIO_PATH Specifies the Visual Studio installation to use. -When unspecified, a Visual Studio instance is selected automatically, preferring Stable 2017, then Preview 2017, then 2015. +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 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") ``` +### 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`. + ## MacOS Variables ### VCPKG_INSTALL_NAME_DIR -- cgit v1.2.3 From 4ad78224c989953cde21c77dd63345b9f722671b Mon Sep 17 00:00:00 2001 From: zhihaoy <43971430+zhihaoy@users.noreply.github.com> Date: Fri, 22 Feb 2019 18:29:05 -0600 Subject: [docs] Show how to default VCPKG_TARGET_TRIPLET (#5346) --- docs/users/integration.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs/users') diff --git a/docs/users/integration.md b/docs/users/integration.md index 10f5574c1..6d56c7c70 100644 --- a/docs/users/integration.md +++ b/docs/users/integration.md @@ -135,9 +135,16 @@ To override the automatically chosen [triplet][], you can specify the MSBuild pr ``` #### With CMake -Simply set `VCPKG_TARGET_TRIPLET` on the configure line. +You can set `VCPKG_TARGET_TRIPLET` on the configure line: ```no-highlight cmake ../my/project -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=... ``` +If you use `VCPKG_DEFAULT_TRIPLET` [environment variable](config-environment.md) to contoll the unqualified triplet in vcpkg command lines you can default `VCPKG_TARGET_TRIPLET` in CMake like [Using an environment variable instead of a command line option](#using-an-environment-variable-instead-of-a-command-line-option): + +```cmake +if(DEFINED ENV{VCPKG_DEFAULT_TRIPLET} AND NOT DEFINED VCPKG_TARGET_TRIPLET) + set(VCPKG_TARGET_TRIPLET "$ENV{VCPKG_DEFAULT_TRIPLET}" CACHE STRING "") +endif() +``` [triplet]: triplets.md -- cgit v1.2.3 From 9ef92a21a07a3f6685df08a6f8cfed2b0cb5ea9c Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Mon, 25 Feb 2019 13:25:27 -0800 Subject: [vcpkg-docs] Replace reference to VCPKG_DEFAULT_VS_PATH with VCPKG_VISUAL_STUDIO_PATH --- docs/users/config-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/users') diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md index 103c1c547..f25df89a3 100644 --- a/docs/users/config-environment.md +++ b/docs/users/config-environment.md @@ -26,7 +26,7 @@ This environment variable can be set to the full path of an executable to be use 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. -#### VCPKG_DEFAULT_VS_PATH +#### VCPKG_VISUAL_STUDIO_PATH This environment variable can be set to the full path to a Visual Studio instance on the machine. This Visual Studio instance will be used if the triplet does not override it via the [`VCPKG_VISUAL_STUDIO_PATH` triplet setting](triplets.md#VCPKG_VISUAL_STUDIO_PATH). -- cgit v1.2.3