From 94ec7c46a51b7bb1fe5f3e64a2f90fb8b3a0ade1 Mon Sep 17 00:00:00 2001 From: Roelf-Jilling Date: Mon, 19 Nov 2018 19:35:00 +0100 Subject: Add note, to delete the CMake cache, after editing a configuration. --- docs/examples/using-sqlite.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/examples/using-sqlite.md b/docs/examples/using-sqlite.md index 35da141d0..e622b9039 100644 --- a/docs/examples/using-sqlite.md +++ b/docs/examples/using-sqlite.md @@ -109,6 +109,7 @@ If you are using CMake through Open Folder with Visual Studio 2017 you can defin }] } ``` +*Note: It might be necessary to delete the CMake cache folder of each modified configuration, to force a full regeneration. In the `CMake` menu, under `Cache ()` you'll find `Delete Cache Folders`.* Now let's make a simple CMake project with a main file. ```cmake -- cgit v1.2.3 From 381e4c94af038bd0ff364ddec918ea077c405ecf Mon Sep 17 00:00:00 2001 From: Roelf-Jilling Date: Mon, 19 Nov 2018 19:47:31 +0100 Subject: Move -DCMAKE_... to a new line to prevent the line-break after the dash. --- docs/examples/using-sqlite.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/examples/using-sqlite.md b/docs/examples/using-sqlite.md index e622b9039..eb03d57d2 100644 --- a/docs/examples/using-sqlite.md +++ b/docs/examples/using-sqlite.md @@ -89,7 +89,8 @@ To remove the integration for your user, you can use `.\vcpkg integrate remove`. #### CMake (Toolchain File) -The best way to use installed libraries with cmake is via the toolchain file `scripts\buildsystems\vcpkg.cmake`. To use this file, you simply need to add it onto your CMake command line as `-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake`. +The best way to use installed libraries with cmake is via the toolchain file `scripts\buildsystems\vcpkg.cmake`. To use this file, you simply need to add it onto your CMake command line as: +`-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake`. If you are using CMake through Open Folder with Visual Studio 2017 you can define `CMAKE_TOOLCHAIN_FILE` by adding a "variables" section to each of your `CMakeSettings.json` configurations: -- 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/index.md | 4 ++-- docs/users/triplets.md | 41 ++++++++++++++++++++++------------------- 2 files changed, 24 insertions(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/index.md b/docs/index.md index 69dbdcd1e..cde241e92 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,8 +2,6 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This tool and ecosystem are constantly evolving; your involvement are vital to its success! -- [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md) - ### Examples - [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md) @@ -15,6 +13,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too - [Integration with build systems](users/integration.md) - [Triplet files](users/triplets.md) +- [Configuration and Environment](users/config-environment.md) ### Maintainer help @@ -24,6 +23,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too ### Specifications - [Export](specifications/export-command.md) +- [Feature Packages](specifications/feature-packages.md) ### Blog posts - [Announcing a single C++ library manager for Linux, macOS and Windows: Vcpkg](https://blogs.msdn.microsoft.com/vcblog/2018/04/24/announcing-a-single-c-library-manager-for-linux-macos-and-windows-vcpkg/) 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') 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') 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') 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 7a18088cf2c513863761200b0d01f20be8bfa2c2 Mon Sep 17 00:00:00 2001 From: Victor Romero Date: Fri, 15 Feb 2019 14:32:07 -0800 Subject: [vcpkg create, docs] Update create command's template and documentation on patching (#5370) --- docs/examples/patching.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/examples/patching.md b/docs/examples/patching.md index 98115400e..b152231e2 100644 --- a/docs/examples/patching.md +++ b/docs/examples/patching.md @@ -147,11 +147,11 @@ Finally, we need to apply the patch after extracting the source. ```cmake # ports\libpng\portfile.cmake ... -vcpkg_extract_source_archive(${ARCHIVE}) - -vcpkg_apply_patches( - SOURCE_PATH ${CURRENT_BUILDTREES_DIR}/src/libpng-1.6.24 - PATCHES "${CMAKE_CURRENT_LIST_DIR}/use-abort-on-all-platforms.patch" +vcpkg_extract_source_archive_ex( + OUT_SOURCE_PATH SOURCE_PATH + ARCHIVE ${ARCHIVE} + PATCHES + "use-abort-on-all-platforms.patch" ) vcpkg_configure_cmake( -- 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') 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') 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