[vcpkg-docs] Rework documentation for compatibility with readthedocs.io and MkDocs.

14 files changed, 514 insertions, 0 deletions

diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md
new file mode 100644
index 000000000..1cb444df3
--- /dev/null
+++ b/docs/maintainers/control-files.md
@@ -0,0 +1,51 @@
+## `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].
+
+Fields are case-sensitive.
+
+[debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html
+
+### Recognized fields
+
+#### Source
+The name of the port.
+
+#### 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.
+
+By convention, if a portfile is modified without incrementing the "upstream" version, a `-#` is appended to create a unique version string.
+
+Example:
+```no-highlight
+Version: 1.0.5-2
+```
+
+#### 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
+Reserved for future use.
+
+#### Build-Depends
+The list of dependencies required to build and use this library.
+
+Example:
+```no-highlight
+Build-Depends: zlib, libpng, libjpeg-turbo, tiff
+```
+
+Unlike dpkg, Vcpkg does not distinguish between build-only dependencies and runtime dependencies. The complete list of dependencies needed to successfully use the library should be specified.
+
+*For example: websocketpp is a header only library, and thus does not require any dependencies at install time. However, downstream users need boost and openssl to make use of the library. Therefore, websocketpp lists boost and openssl as dependencies*
+
+Dependencies can be filtered based on the target triplet to support different requirements on Windows Desktop versus the Universal Windows Platform. Currently, the string inside brackets is substring-compared against the triplet name. __This will change in a future version to not depend on the triplet name.__
+
+Example:
+```no-highlight
+Build-Depends: zlib [windows], openssl [windows], boost [windows], websocketpp [windows]
+```
+
diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
new file mode 100644
index 000000000..705d65b7e
--- /dev/null
+++ b/docs/maintainers/portfile-functions.md
@@ -0,0 +1,15 @@
+<!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->
+
+# Portfile helper functions

+- [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)

+- [vcpkg\_apply\_patches](vcpkg_apply_patches.md)

+- [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)

+- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)

+- [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)

+- [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)

+- [vcpkg\_download\_distfile](vcpkg_download_distfile.md)

+- [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)

+- [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)

+- [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)

+- [vcpkg\_from\_github](vcpkg_from_github.md)

+- [vcpkg\_install\_cmake](vcpkg_install_cmake.md)

diff --git a/docs/maintainers/vcpkg_acquire_msys.md b/docs/maintainers/vcpkg_acquire_msys.md
new file mode 100644
index 000000000..46cda81fd
--- /dev/null
+++ b/docs/maintainers/vcpkg_acquire_msys.md
@@ -0,0 +1,47 @@
+# vcpkg_acquire_msys
+
+Download and prepare an MSYS2 instance.
+
+## Usage
+```cmake
+vcpkg_acquire_msys(<MSYS_ROOT_VAR>)
+```
+
+## Parameters
+### MSYS_ROOT_VAR
+An out-variable that will be set to the path to MSYS2.
+
+## Notes
+A call to `vcpkg_acquire_msys` will usually be followed by a call to `bash.exe`:
+```cmake
+vcpkg_acquire_msys(MSYS_ROOT)
+set(BASH ${MSYS_ROOT}/usr/bin/bash.exe)
+
+vcpkg_execute_required_process(
+    COMMAND ${BASH} --noprofile --norc "${CMAKE_CURRENT_LIST_DIR}\\build.sh"
+    WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel
+    LOGNAME build-${TARGET_TRIPLET}-rel
+)
+```
+To ensure a package is available:
+```cmake
+vcpkg_acquire_msys(MSYS_ROOT)
+set(BASH ${MSYS_ROOT}/usr/bin/bash.exe)
+
+message(STATUS "Installing MSYS Packages")
+vcpkg_execute_required_process(
+    COMMAND
+        ${BASH} --noprofile --norc -c
+            "pacman -Sy --noconfirm --needed make"
+    WORKING_DIRECTORY ${MSYS_ROOT}
+    LOGNAME pacman-${TARGET_TRIPLET})
+```
+
+## Examples
+
+* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
+* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
+* [libvpx](https://github.com/Microsoft/vcpkg/blob/master/ports/libvpx/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_acquire_msys.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_acquire_msys.cmake)

diff --git a/docs/maintainers/vcpkg_apply_patches.md b/docs/maintainers/vcpkg_apply_patches.md
new file mode 100644
index 000000000..d4d8dbfec
--- /dev/null
+++ b/docs/maintainers/vcpkg_apply_patches.md
@@ -0,0 +1,35 @@
+# vcpkg_apply_patches
+
+Apply a set of patches to a source tree.
+
+## Usage
+```cmake
+vcpkg_apply_patches(
+    SOURCE_PATH <${SOURCE_PATH}>
+    [QUIET]
+    PATCHES <patch1.patch>...
+)
+```
+
+## Parameters
+### SOURCE_PATH
+The source path in which apply the patches. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+
+### PATCHES
+A list of patches that are applied to the source tree.
+
+Generally, these take the form of `${CMAKE_CURRENT_LIST_DIR}/some.patch` to select patches in the `port\<port>\` directory.
+
+### QUIET
+Disables the warning message upon failure.
+
+This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
+
+## Examples
+
+* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
+* [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)
+* [libpng](https://github.com/Microsoft/vcpkg/blob/master/ports/libpng/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_apply_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake)

diff --git a/docs/maintainers/vcpkg_build_msbuild.md b/docs/maintainers/vcpkg_build_msbuild.md
new file mode 100644
index 000000000..178964fcd
--- /dev/null
+++ b/docs/maintainers/vcpkg_build_msbuild.md
@@ -0,0 +1,59 @@
+# vcpkg_build_msbuild
+
+Build an msbuild-based project.
+
+## Usage
+```cmake
+vcpkg_build_msbuild(
+    PROJECT_PATH <${SOURCE_PATH}/port.sln>
+    [RELEASE_CONFIGURATION <Release>]
+    [DEBUG_CONFIGURATION <Debug>]
+    [TARGET <Build>]
+    [TARGET_PLATFORM_VERSION <10.0.15063.0>]
+    [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
+    [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
+    [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
+    [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
+    [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
+)
+```
+
+## Parameters
+### PROJECT_PATH
+The path to the solution (`.sln`) or project (`.vcxproj`) file.
+
+### RELEASE_CONFIGURATION
+The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
+
+### DEBUG_CONFIGURATION
+The configuration (``/p:Configuration`` msbuild parameter)
+used for Debug builds.
+
+### TARGET_PLATFORM_VERSION
+The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
+
+### TARGET
+The MSBuild target to build. (``/t:<TARGET>``)
+
+### PLATFORM
+The platform (``/p:Platform`` msbuild parameter) used for the build.
+
+### PLATFORM_TOOLSET
+The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build.
+
+### OPTIONS
+Additional options passed to msbuild for all builds.
+
+### OPTIONS_RELEASE
+Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`.
+
+### OPTIONS_DEBUG
+Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`.
+
+## Examples
+
+* [libuv](https://github.com/Microsoft/vcpkg/blob/master/ports/libuv/portfile.cmake)
+* [zeromq](https://github.com/Microsoft/vcpkg/blob/master/ports/zeromq/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_build_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake)

diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md
new file mode 100644
index 000000000..93f661767
--- /dev/null
+++ b/docs/maintainers/vcpkg_configure_cmake.md
@@ -0,0 +1,49 @@
+# vcpkg_configure_cmake
+
+Configure CMake for Debug and Release builds of a project.
+
+## Usage
+```cmake
+vcpkg_configure_cmake(
+    SOURCE_PATH <${SOURCE_PATH}>
+    [PREFER_NINJA]
+    [GENERATOR <"NMake Makefiles">]
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+    [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+)
+```
+
+## Parameters
+### SOURCE_PATH
+Specifies the directory containing the `CMakeLists.txt`. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+
+### PREFER_NINJA
+Indicates that, when available, Vcpkg should use Ninja to perform the build. This should be specified unless the port is known to not work under Ninja.
+
+### GENERATOR
+Specifies the precise generator to use.
+
+This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build. If used for this purpose, it should be set to "NMake Makefiles".
+
+### OPTIONS
+Additional options passed to CMake during the configuration.
+
+### OPTIONS_RELEASE
+Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`.
+
+### OPTIONS_DEBUG
+Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`.
+
+## Notes
+This command supplies many common arguments to CMake. To see the full list, examine the source.
+
+## Examples
+
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
+* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_configure_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_cmake.cmake)

diff --git a/docs/maintainers/vcpkg_copy_pdbs.md b/docs/maintainers/vcpkg_copy_pdbs.md
new file mode 100644
index 000000000..6bfa488db
--- /dev/null
+++ b/docs/maintainers/vcpkg_copy_pdbs.md
@@ -0,0 +1,19 @@
+# vcpkg_copy_pdbs
+
+Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
+
+## Usage
+```cmake
+vcpkg_copy_pdbs()
+```
+
+## Notes
+This command should always be called by portfiles after they have finished rearranging the binary output.
+
+## Examples
+
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_copy_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake)

diff --git a/docs/maintainers/vcpkg_copy_tool_dependencies.md b/docs/maintainers/vcpkg_copy_tool_dependencies.md
new file mode 100644
index 000000000..05d74f0b2
--- /dev/null
+++ b/docs/maintainers/vcpkg_copy_tool_dependencies.md
@@ -0,0 +1,21 @@
+# vcpkg_copy_tool_dependencies
+
+Copy all DLL dependencies of built tools into the tool folder.
+
+## Usage
+```cmake
+vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>)
+```
+## Parameters
+The path to the directory containing the tools.
+
+## Notes
+This command should always be called by portfiles after they have finished rearranging the binary output, if they have any tools.
+
+## Examples
+
+* [glib](https://github.com/Microsoft/vcpkg/blob/master/ports/glib/portfile.cmake)
+* [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_copy_tool_dependencies.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tool_dependencies.cmake)

diff --git a/docs/maintainers/vcpkg_download_distfile.md b/docs/maintainers/vcpkg_download_distfile.md
new file mode 100644
index 000000000..7897610e3
--- /dev/null
+++ b/docs/maintainers/vcpkg_download_distfile.md
@@ -0,0 +1,39 @@
+# vcpkg_download_distfile
+
+Download and cache a file needed for this port.
+
+## Usage
+```cmake
+vcpkg_download_distfile(
+    <OUT_VARIABLE>
+    URLS <http://mainUrl> <http://mirror1>...
+    FILENAME <output.zip>
+    SHA512 <5981de...>
+)
+```
+## Parameters
+### OUT_VARIABLE
+This variable will be set to the full path to the downloaded file. This can then immediately be passed in to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) for sources.
+
+### URLS
+A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given.
+
+### FILENAME
+The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.
+
+### SHA512
+The expected hash for the file.
+
+If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch.
+
+## Notes
+The command [`vcpkg_from_github`](vcpkg_from_github.md) should be used instead of this for downloading the main archive for GitHub projects.
+
+## Examples
+
+* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
+* [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)
+* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_download_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake)

diff --git a/docs/maintainers/vcpkg_execute_required_process.md b/docs/maintainers/vcpkg_execute_required_process.md
new file mode 100644
index 000000000..4b1a7e081
--- /dev/null
+++ b/docs/maintainers/vcpkg_execute_required_process.md
@@ -0,0 +1,33 @@
+# vcpkg_execute_required_process
+
+Execute a process with logging and fail the build if the command fails.
+
+## Usage
+```cmake
+vcpkg_execute_required_process(
+    COMMAND <${PERL}> [<arguments>...]
+    WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg>
+    LOGNAME <build-${TARGET_TRIPLET}-dbg>
+)
+```
+## Parameters
+### COMMAND
+The command to be executed, along with its arguments.
+
+### WORKING_DIRECTORY
+The directory to execute the command in.
+
+### LOGNAME
+The prefix to use for the log files.
+
+This should be a unique name for different triplets so that the logs don't conflict when building multiple at once.
+
+## Examples
+
+* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
+* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
+* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
+* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_execute_required_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake)

diff --git a/docs/maintainers/vcpkg_extract_source_archive.md b/docs/maintainers/vcpkg_extract_source_archive.md
new file mode 100644
index 000000000..104032ffc
--- /dev/null
+++ b/docs/maintainers/vcpkg_extract_source_archive.md
@@ -0,0 +1,32 @@
+# vcpkg_extract_source_archive
+
+Extract an archive into the source directory.
+
+## Usage
+```cmake
+vcpkg_extract_source_archive(
+    <${ARCHIVE}> [<${TARGET_DIRECTORY}>]
+)
+```
+## Parameters
+### ARCHIVE
+The full path to the archive to be extracted.
+
+This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md).
+
+### TARGET_DIRECTORY
+If specified, the archive will be extracted into the target directory instead of `${CURRENT_BUILDTREES_DIR}\src\`.
+
+This can be used to mimic git submodules, by extracting into a subdirectory of another archive.
+
+## Notes
+This command will also create a tracking file named <FILENAME>.extracted in the TARGET_DIRECTORY. This file, when present, will suppress the extraction of the archive.
+
+## Examples
+
+* [libraw](https://github.com/Microsoft/vcpkg/blob/master/ports/libraw/portfile.cmake)
+* [protobuf](https://github.com/Microsoft/vcpkg/blob/master/ports/protobuf/portfile.cmake)
+* [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_extract_source_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake)

diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md
new file mode 100644
index 000000000..209b4416e
--- /dev/null
+++ b/docs/maintainers/vcpkg_find_acquire_program.md
@@ -0,0 +1,37 @@
+# vcpkg_find_acquire_program
+
+Download or find a well-known tool.
+
+## Usage
+```cmake
+vcpkg_find_acquire_program(<VAR>)
+```
+## Parameters
+### VAR
+This variable specifies both the program to be acquired as well as the out parameter that will be set to the path of the program executable.
+
+## Notes
+The current list of programs includes:
+
+- 7Z
+- BISON
+- FLEX
+- PERL
+- PYTHON2
+- PYTHON3
+- JOM
+- MESON
+- NASM
+- NINJA
+- YASM
+
+Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
+
+## Examples
+
+* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
+* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
+* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_find_acquire_program.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_acquire_program.cmake)

diff --git a/docs/maintainers/vcpkg_from_github.md b/docs/maintainers/vcpkg_from_github.md
new file mode 100644
index 000000000..cb7849fcc
--- /dev/null
+++ b/docs/maintainers/vcpkg_from_github.md
@@ -0,0 +1,52 @@
+# vcpkg_from_github
+
+Download and extract a project from GitHub. Enables support for `install --head`.
+
+## Usage:
+```cmake
+vcpkg_from_github(
+    OUT_SOURCE_PATH <SOURCE_PATH>
+    REPO <Microsoft/cpprestsdk>
+    [REF <v2.0.0>]
+    [SHA512 <45d0d7f8cc350...>]
+    [HEAD_REF <master>]
+)
+```
+
+## Parameters:
+### OUT_SOURCE_PATH
+Specifies the out-variable that will contain the extracted location.
+
+This should be set to `SOURCE_PATH` by convention.
+
+### REPO
+The organization or user and repository on GitHub.
+
+### REF
+A stable git commit-ish (ideally a tag) that will not change contents.
+
+If `REF` is specified, `SHA512` must also be specified.
+
+### SHA512
+The SHA512 hash that should match the archive (https://github.com/${REPO}/archive/${REF}.tar.gz).
+
+This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
+
+### HEAD_REF
+The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
+
+For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
+
+## Notes:
+At least one of `REF` and `HEAD_REF` must be specified.
+
+This exports the `VCPKG_HEAD_VERSION` variable during head builds.
+
+## Examples:
+
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+* [ms-gsl](https://github.com/Microsoft/vcpkg/blob/master/ports/ms-gsl/portfile.cmake)
+* [beast](https://github.com/Microsoft/vcpkg/blob/master/ports/beast/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_from_github.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_github.cmake)

diff --git a/docs/maintainers/vcpkg_install_cmake.md b/docs/maintainers/vcpkg_install_cmake.md
new file mode 100644
index 000000000..e199d1292
--- /dev/null
+++ b/docs/maintainers/vcpkg_install_cmake.md
@@ -0,0 +1,25 @@
+# vcpkg_install_cmake
+
+Build and install a cmake project.
+
+## Usage:
+```cmake
+vcpkg_install_cmake([MSVC_64_TOOLSET])
+```
+
+## Parameters:
+### MSVC_64_TOOLSET
+This adds the `/p:PreferredToolArchitecture=x64` switch if the underlying buildsystem is MSBuild. Some large projects can run out of memory when linking if they use the 32-bit hosted tools.
+
+## Notes:
+This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
+
+## Examples:
+
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
+* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_install_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_cmake.cmake)