early-access version 2853

externals/vcpkg/docs/users/buildsystems/cmake-integration.md

@@ -0,0 +1,224 @@
+# CMake Integration
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/cmake-integration.md).**
+
+See [Installing and Using Packages Example: sqlite](../../examples/installing-and-using-packages.md) for a fully worked example using CMake.
+
+## Table of Contents
+
+- [`CMAKE_TOOLCHAIN_FILE`](#cmake_toolchain_file)
+- [IDE Integration](#ide-integration)
+  - [Visual Studio Code (CMake Tools extension)](#visual-studio-code-cmake-tools-extension)
+  - [Visual Studio](#visual-studio)
+  - [CLion](#clion)
+- [Using Multiple Toolchain Files](#using-multiple-toolchain-files)
+- [Settings Reference](#settings-reference)
+
+## `CMAKE_TOOLCHAIN_FILE`
+
+Projects configured to use the vcpkg toolchain file (via the CMake setting `CMAKE_TOOLCHAIN_FILE`) can find libraries from vcpkg using the standard CMake functions: `find_package()`, `find_path()`, and `find_library()`.
+
+```no-highlight
+cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=[vcpkg-root]/scripts/buildsystems/vcpkg.cmake
+```
+
+Since version 3.21, CMake will use the environment variable `CMAKE_TOOLCHAIN_FILE`[1] as the default value for `CMAKE_TOOLCHAIN_FILE`.
+
+**cmd**
+```cmd
+set CMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
+```
+**Powershell**
+```powershell
+$env:CMAKE_TOOLCHAIN_FILE="[vcpkg root]/scripts/buildsystems/vcpkg.cmake"
+```
+**bash**
+```sh
+export CMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
+```
+
+vcpkg does not automatically add any include or links paths into your project. To use a header-only library you can use `find_path()` which will correctly work on all platforms:
+
+```cmake
+# To find and use catch2
+find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
+include_directories(${CATCH_INCLUDE_DIR})
+```
+
+[1]: https://cmake.org/cmake/help/latest/envvar/CMAKE_TOOLCHAIN_FILE.html
+
+## IDE Integration
+
+### Visual Studio Code (CMake Tools Extension)
+
+Adding the following to your workspace `settings.json` will make CMake Tools automatically use vcpkg for libraries:
+
+```json
+{
+  "cmake.configureSettings": {
+    "CMAKE_TOOLCHAIN_FILE": "[vcpkg root]/scripts/buildsystems/vcpkg.cmake"
+  }
+}
+```
+
+### Visual Studio
+
+In the CMake Settings Editor, add the path to the vcpkg toolchain file under `CMake toolchain file`:
+
+```
+[vcpkg root]/scripts/buildsystems/vcpkg.cmake
+```
+
+### CLion
+
+Open the Toolchains settings (`File > Settings` on Windows and Linux, `CLion > Preferences` on macOS), and go to the CMake settings (`Build, Execution, Deployment > CMake`). In `CMake options`, add the following line:
+
+```
+-DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
+```
+
+You must add this line to each profile separately.
+
+## Using Multiple Toolchain Files
+
+To combine vcpkg's toolchain file with another toolchain file, you can set the cmake variable `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`:
+
+```no-highlight
+cmake ../my/project \
+   -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \
+   -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/toolchain.cmake
+```
+
+Alternatively, you can include the vcpkg toolchain at the end of the primary toolchain file:
+
+```cmake
+# MyToolchain.cmake
+set(CMAKE_CXX_COMPILER ...)
+set(VCPKG_TARGET_TRIPLET x64-my-custom-windows-triplet)
+include(/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake)
+```
+
+**Note: vcpkg does not automatically apply your toolchain's settings, such as your compiler or compilation flags, while building libraries. To change vcpkg's library settings, you must make a [custom triplet file](../triplets.md) (which can [share your toolchain](../triplets.md#VCPKG_CHAINLOAD_TOOLCHAIN_FILE))**
+
+## Settings Reference
+
+All vcpkg-affecting variables must be defined before the first `project()` directive, such as via the command line or `set()` statements.
+
+### `VCPKG_TARGET_TRIPLET`
+
+This setting controls the [triplet](../triplets.md) vcpkg will install and consume libraries from.
+
+If unset, vcpkg will automatically detect an appropriate default triplet given the current compiler settings. If you change this CMake variable, you must delete your cache and reconfigure.
+
+### `VCPKG_HOST_TRIPLET`
+
+This variable controls which [triplet](../triplets.md) host dependencies will be installed for.
+
+If unset, vcpkg will automatically detect an appropriate native triplet (x64-windows, x64-osx, x64-linux).
+
+See also [Host Dependencies](../host-dependencies.md).
+
+### `VCPKG_INSTALLED_DIR`
+
+This variable sets the location where libraries will be installed and consumed from.
+
+In manifest mode, the default is `${CMAKE_BINARY_DIR}/vcpkg_installed`.
+
+In classic mode, the default is `${VCPKG_ROOT}/installed`.
+
+### `VCPKG_MANIFEST_MODE`
+
+This variable forces vcpkg to operate in either manifest mode or classic mode.
+
+Defaults to `ON` when `VCPKG_MANIFEST_DIR` is non-empty or `${CMAKE_SOURCE_DIR}/vcpkg.json` exists.
+
+To disable manifest mode while a `vcpkg.json` is detected, set this to `OFF`.
+
+### `VCPKG_MANIFEST_DIR`
+
+This variable specifies an alternate folder containing a `vcpkg.json` manifest.
+
+Defaults to `${CMAKE_SOURCE_DIR}` if `${CMAKE_SOURCE_DIR}/vcpkg.json` exists.
+
+### `VCPKG_MANIFEST_INSTALL`
+
+This variable controls whether vcpkg will be automatically run to install your dependencies during your configure step.
+
+Defaults to `ON` if `VCPKG_MANIFEST_MODE` is `ON`.
+
+### `VCPKG_BOOTSTRAP_OPTIONS`
+
+This variable can be set to additional command parameters to pass to `./bootstrap-vcpkg`.
+
+In manifest mode, vcpkg will be automatically bootstrapped if the executable does not exist.
+
+### `VCPKG_OVERLAY_TRIPLETS`
+
+This variable can be set to a list of paths to be passed on the command line as `--overlay-triplets=...`
+
+### `VCPKG_OVERLAY_PORTS`
+
+This variable can be set to a list of paths to be passed on the command line as `--overlay-ports=...`
+
+### `VCPKG_MANIFEST_FEATURES`
+
+This variable can be set to a list of features to activate when installing from your manifest.
+
+For example, features can be used by projects to control building with additional dependencies to enable tests or samples:
+
+```json
+{
+  "name": "mylibrary",
+  "version": "1.0",
+  "dependencies": [ "curl" ],
+  "features": {
+    "samples": {
+      "description": "Build Samples",
+      "dependencies": [ "fltk" ]
+    },
+    "tests": {
+      "description": "Build Tests",
+      "dependencies": [ "gtest" ]
+    }
+  }
+}
+```
+```cmake
+# CMakeLists.txt
+
+option(BUILD_TESTING "Build tests" OFF)
+if(BUILD_TESTING)
+  list(APPEND VCPKG_MANIFEST_FEATURES "tests")
+endif()
+
+option(BUILD_SAMPLES "Build samples" OFF)
+if(BUILD_SAMPLES)
+  list(APPEND VCPKG_MANIFEST_FEATURES "samples")
+endif()
+
+project(myapp)
+
+# ...
+```
+
+### `VCPKG_MANIFEST_NO_DEFAULT_FEATURES`
+
+This variable controls activation of default features in addition to those listed in `VCPKG_MANIFEST_FEATURES`. If set to `ON`, default features will not be automatically activated.
+
+Defaults to `OFF`.
+
+### `VCPKG_INSTALL_OPTIONS`
+
+This variable can be set to a list of additional command line parameters to pass to the vcpkg tool during automatic installation.
+
+### `VCPKG_PREFER_SYSTEM_LIBS`
+
+This variable controls whether vcpkg will append instead of prepend its paths to `CMAKE_PREFIX_PATH`, `CMAKE_LIBRARY_PATH` and `CMAKE_FIND_ROOT_PATH` so that vcpkg libraries/packages are found after toolchain/system libraries/packages.
+
+Defaults to `OFF`.
+
+### `VCPKG_FEATURE_FLAGS`
+
+This variable can be set to a list of feature flags to pass to the vcpkg tool during automatic installation to opt-in to experimental behavior.
+
+See the `--feature-flags=` command line option for more information.

externals/vcpkg/docs/users/buildsystems/export-command.md

@@ -0,0 +1,20 @@
+# `export` Command
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/export-command.md).**
+
+The `export` command creates a shrinkwrapped archive containing a specific set of libraries (and their dependencies) that can be quickly and reliably shared with build servers or other users in your organization. `export` only supports classic mode at this time.
+
+- `--nuget`: NuGet package
+- `--zip`: Zip archive
+- `--7zip`: 7Zip archive
+- `--raw`: Raw, uncompressed folder
+
+Each of these have the same internal layout which mimics the layout of a full vcpkg instance:
+
+- `installed/` contains the library files
+- `scripts/buildsystems/vcpkg.cmake` is the [CMake toolchain file](cmake-integration.md)
+- `scripts/buildsystems/msbuild/vcpkg.props` and `scripts/buildsystems/msbuild/vcpkg.targets` are the [MSBuild integration files](msbuild-integration.md)
+
+NuGet package exports will also contain a `build\native\vcpkg.targets` that integrates with MSBuild projects using the NuGet package manager.
+
+Please also see our [blog post](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) for additional examples.

externals/vcpkg/docs/users/buildsystems/integration.md

@@ -0,0 +1,10 @@
+# Buildsystem Integration
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/integration.md).**
+
+vcpkg supports use from any buildsystem and has specific native integration into MSBuild and CMake.
+
+- [MSBuild Integration (Visual Studio)](msbuild-integration.md)
+- [CMake Integration](cmake-integration.md)
+- [Manual Integration](manual-integration.md)
+- [`export` Command](export-command.md)

externals/vcpkg/docs/users/buildsystems/manual-integration.md

@@ -0,0 +1,31 @@
+# Manual Integration
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/manual-integration.md).**
+
+When installing libraries, vcpkg creates a single common layout partitioned by triplet. 
+
+The root of the tree in classic mode is `[vcpkg root]/installed`. The root of the tree in manifest mode is `[vcpkg.json directory]/vcpkg_installed`.
+
+Underneath this root, in a subfolder named after the triplet:
+
+* Header files: `include/`
+* Release `.lib`, `.a`, and `.so` files: `lib/` or `lib/manual-link/`
+* Release `.dll` files: `bin/`
+* Release `.pc` files: `lib/pkgconfig/`
+* Debug `.lib`, `.a`, and `.so` files: `debug/lib/` or `debug/lib/manual-link/`
+* Debug `.dll` files: `debug/bin/`
+* Debug `.pc` files: `debug/lib/pkgconfig/`
+* Tools: `tools/[portname]/`
+
+For example, `zlib.h` for `zlib:x64-windows` in classic mode is located at `[vcpkg root]/installed/x64-windows/include/zlib.h`.
+
+See your build system specific documentation for how to use prebuilt binaries. For example, `Makefile` projects often accept environment variables:
+
+```sh
+export CXXFLAGS=-I$(pwd)/installed/x64-linux/include
+export CFLAGS=-I$(pwd)/installed/x64-linux/include
+export LDFLAGS=-L$(pwd)/installed/x64-linux/lib
+export PKG_CONFIG_PATH=$(pwd)/installed/x64-linux/lib/pkgconfig:$PKG_CONFIG_PATH
+```
+
+_On Windows dynamic triplets, such as x64-windows:_ To run any produced executables you will also need to either copy the needed DLL files to the same folder as your executable or *prepend* the correct `bin\` directory to your path.

externals/vcpkg/docs/users/buildsystems/msbuild-integration.md

@@ -0,0 +1,138 @@
+# MSBuild Integration (Visual Studio)
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/msbuild-integration.md).**
+
+## Table of Contents
+
+- [Integration Methods](#integration-methods)
+  - [User-wide integration](#user-wide-integration)
+  - [Import `.props` and `.targets`](#import-props-and-targets)
+  - [Linked NuGet Package](#linked-nuget-package)
+- [Common Configuration](#common-configuration)
+- [Manifest Mode Configuration](#manifest-mode-configuration)
+
+## Integration Methods
+
+### User-wide integration
+
+```no-highlight
+vcpkg integrate install
+```
+This will implicitly add Include Directories, Link Directories, and Link Libraries for all packages installed with Vcpkg to all VS2015, VS2017 and VS2019 MSBuild projects. We also add a post-build action for executable projects that will analyze and copy any DLLs you need to the output folder, enabling a seamless F5 experience.
+
+For the vast majority of libraries, this is all you need to do -- just File -> New Project and write code! However, some libraries perform conflicting behaviors such as redefining `main()`. Since you need to choose per-project which of these conflicting options you want, you will need to add those libraries to your linker inputs manually.
+
+Here are some examples, though this is not an exhaustive list:
+
+- Gtest provides `gtest`, `gmock`, `gtest_main`, and `gmock_main`
+- SDL2 provides `SDL2main`
+- SFML provides `sfml-main`
+- Boost.Test provides `boost_test_exec_monitor`
+
+To get a full list for all your installed packages, run `vcpkg owns manual-link`.
+
+### Import `.props` and `.targets`
+
+vcpkg can also be integrated into MSBuild projects by explicitly importing the `scripts/buildsystems/vcpkg.props` and `scripts/buildsystems/vcpkg.targets` files into each `.vcxproj`. By using relative paths, this enables vcpkg to be consumed by a submodule and automatically acquired by users when they run `git clone`.
+
+The easiest way to add these to every project in your solution is to create `Directory.Build.props` and `Directory.Build.targets` files at the root of your repository.
+
+The following examples assume they are at the root of your repository with a submodule of `microsoft/vcpkg` at `vcpkg`.
+
+**Example `Directory.Build.props`**:
+```xml
+<Project>
+ <Import Project="$(MSBuildThisFileDirectory)vcpkg\scripts\buildsystems\vcpkg.props" />
+</Project>
+```
+
+**Example `Directory.Build.targets`**:
+```xml
+<Project>
+ <Import Project="$(MSBuildThisFileDirectory)vcpkg\scripts\buildsystems\vcpkg.targets" />
+</Project>
+```
+
+More information about `Directory.Build.targets` and `Directory.Build.props` can be found in the [Customize your build][1] section of the official MSBuild documentation.
+
+[1]: https://docs.microsoft.com/visualstudio/msbuild/customize-your-build#directorybuildprops-and-directorybuildtargets
+
+### Linked NuGet Package
+
+**Note: This approach is not recommended for new projects, since it makes them difficult to share with others. For a portable, self-contained NuGet package, see the [`export command`](export-command.md)**
+
+VS projects can also be integrated through a NuGet package. This will modify the project file, so we do not recommend this approach for open source projects.
+
+```no-highlight
+PS D:\src\vcpkg> .\vcpkg integrate project
+Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg
+
+With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste:
+    Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems"
+```
+
+*Note: The generated NuGet package does not contain the actual libraries. It instead acts like a shortcut (or symlink) to the vcpkg install and will "automatically" update with any changes (install/remove) to the libraries. You do not need to regenerate or update the NuGet package.*
+
+## Common Configuration
+
+### `VcpkgEnabled` (Use Vcpkg)
+
+This can be set to "false" to explicitly disable vcpkg integration for the project
+
+### `VcpkgConfiguration` (Vcpkg Configuration)
+
+If your configuration names are too complex for vcpkg to guess correctly, you can assign this property to `Release` or `Debug` to explicitly tell vcpkg what variant of libraries you want to consume.
+
+### `VcpkgEnableManifest` (Use Vcpkg Manifest)
+
+This property must be set to `true` in order to consume from a local `vcpkg.json` file. If set to `false`, any local `vcpkg.json` files will be ignored.
+
+This currently defaults to `false`, but will default to `true` in the future.
+
+### `VcpkgTriplet` (Triplet)
+
+This property controls the triplet to consume libraries from, such as `x64-windows-static` or `arm64-windows`.
+
+If this is not explicitly set, vcpkg will deduce the correct triplet based on your Visual Studio settings. vcpkg will only deduce triplets that use dynamic library linkage and dynamic CRT linkage; if you want static dependencies or to use the static CRT (`/MT`), you will need to set the triplet manually.
+
+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
+
+See also [Triplets](../triplets.md)
+
+### `VcpkgHostTriplet` (Host Triplet)
+
+This can be set to a custom triplet to use for resolving host dependencies.
+
+If unset, this will default to the "native" triplet (x64-windows).
+
+See also [Host Dependencies](../host-dependencies.md).
+
+### `VcpkgInstalledDir` (Installed Directory)
+
+This property defines the location vcpkg will install and consume libraries from.
+
+In manifest mode, this defaults to `$(VcpkgManifestRoot)\vcpkg_installed\$(VcpkgTriplet)\`. In classic mode, this defaults to `$(VcpkgRoot)\installed\`.
+
+## Manifest Mode Configuration
+
+To use manifests (`vcpkg.json`) with MSBuild, first you need to use one of the integration methods above. Then, add a vcpkg.json above your project file (such as in the root of your source repository) and set the property `VcpkgEnableManifest` to `true`. You can set this property via the IDE in `Project Properties -> Vcpkg -> Use Vcpkg Manifest` (note: you may need to reload the IDE to see the vcpkg Property Page).
+
+vcpkg will automatically run during your project's build and install any listed dependencies to `vcpkg_installed/$(VcpkgTriplet)/` adjacent to the `vcpkg.json` file; these libraries will then automatically be included in and linked to your MSBuild projects.
+
+**Known issues**
+
+* Visual Studio 2015 does not correctly track edits to the `vcpkg.json` and `vcpkg-configuration.json` files, and will not respond to changes unless a `.cpp` is edited.
+
+<a id="vcpkg-additional-install-options"></a>
+
+### `VcpkgAdditionalInstallOptions` (Additional Options)
+
+When using a manifest, this option specifies additional command line flags to pass to the underlying vcpkg tool invocation. This can be used to access features that have not yet been exposed through another option.
+
+### `VcpkgManifestInstall` (Install Vcpkg Dependencies)
+
+This property can be set to `false` to disable automatic dependency restoration during project build. Dependencies must be manually restored via the vcpkg command line separately.