mirror of
https://github.com/microsoft/vcpkg.git
synced 2026-01-18 01:11:23 +01:00
[docs] Split integration.md per Build System. (#24737)
* Split integration.md per Build System. Centralize buildsystem configuration. * PR comment
This commit is contained in:
Robert Schumacher
committed by
GitHub
GitHub
parent
8de52b066f
commit
8639e65b88
@@ -212,8 +212,6 @@ You'll then be able to bootstrap vcpkg along with the [quick start guide](#quick
|
||||
|
||||
## Using vcpkg with CMake
|
||||
|
||||
If you're using vcpkg with CMake, the following may help!
|
||||
|
||||
### Visual Studio Code with CMake Tools
|
||||
|
||||
Adding the following to your workspace `settings.json` will make
|
||||
@@ -247,7 +245,7 @@ Finally, in `CMake options`, add the following line:
|
||||
-DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
|
||||
```
|
||||
|
||||
Unfortunately, you'll have to add this to each profile.
|
||||
You must add this line to each profile.
|
||||
|
||||
### Vcpkg as a Submodule
|
||||
|
||||
@@ -265,7 +263,7 @@ by passing the `CMAKE_TOOLCHAIN_FILE` directly,
|
||||
but it will make the configure-build step slightly easier.
|
||||
|
||||
[getting-started:using-a-package]: docs/examples/installing-and-using-packages.md
|
||||
[getting-started:integration]: docs/users/integration.md
|
||||
[getting-started:integration]: docs/users/buildsystems/integration.md
|
||||
[getting-started:git]: https://git-scm.com/downloads
|
||||
[getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
|
||||
[getting-started:linux-gcc]: #installing-linux-developer-tools
|
||||
|
||||
@@ -319,7 +319,7 @@ puede usar un simple `vcpkg install --feature-flags=manifests`
|
||||
Para más información, revise la especificación de [manifiesto][getting-started:manifest-spec]
|
||||
|
||||
[getting-started:using-a-package]: docs/examples/installing-and-using-packages.md
|
||||
[getting-started:integration]: docs/users/integration.md
|
||||
[getting-started:integration]: docs/users/buildsystems/integration.md
|
||||
[getting-started:git]: https://git-scm.com/downloads
|
||||
[getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
|
||||
[getting-started:linux-gcc]: #Instalando-Herramientas-de-desarrollo-en-Linux
|
||||
|
||||
@@ -245,7 +245,7 @@ set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems
|
||||
Cela permettra toujours aux gens de ne pas utiliser vcpkg, en passant directement le CMAKE_TOOLCHAIN_FILE, mais cela rendra l'étape de configuration-construction légèrement plus facile.
|
||||
|
||||
[getting-started:utiliser-un-paquet]: docs/examples/installing-and-using-packages.md
|
||||
[getting-started:integration]: docs/users/integration.md
|
||||
[getting-started:integration]: docs/users/buildsystems/integration.md
|
||||
[getting-started:git]: https://git-scm.com/downloads
|
||||
[getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
|
||||
[getting-started:linux-gcc]: #installing-linux-developer-tools
|
||||
|
||||
@@ -262,7 +262,7 @@ set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems
|
||||
vcpkg를 사용하지 않을 수 있습니다.
|
||||
|
||||
[getting-started:using-a-package]: docs/examples/installing-and-using-packages.md
|
||||
[getting-started:integration]: docs/users/integration.md
|
||||
[getting-started:integration]: docs/users/buildsystems/integration.md
|
||||
[getting-started:git]: https://git-scm.com/downloads
|
||||
[getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
|
||||
[getting-started:linux-gcc]: #installing-linux-developer-tools
|
||||
|
||||
@@ -245,7 +245,7 @@ set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems
|
||||
使用此种方式可无需设置 `CMAKE_TOOLCHAIN_FILE` 即可使用vcpkg，且更容易完成配置工作。
|
||||
|
||||
[getting-started:using-a-package]: docs/examples/installing-and-using-packages.md
|
||||
[getting-started:integration]: docs/users/integration.md
|
||||
[getting-started:integration]: docs/users/buildsystems/integration.md
|
||||
[getting-started:git]: https://git-scm.com/downloads
|
||||
[getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
|
||||
[getting-started:linux-gcc]: #installing-linux-developer-tools
|
||||
|
||||
@@ -14,7 +14,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
|
||||
|
||||
### User Help
|
||||
|
||||
- [Buildsystem Integration](users/integration.md)
|
||||
- [Buildsystem Integration](users/buildsystems/integration.md)
|
||||
- [Triplet files](users/triplets.md)
|
||||
- [Configuration and Environment](users/config-environment.md)
|
||||
- [Authentication](users/authentication.md)
|
||||
|
||||
@@ -6,7 +6,7 @@ If you want to contribute but don't have a particular library in mind then take
|
||||
of [new port requests](https://github.com/Microsoft/vcpkg/issues?q=is%3Aissue+is%3Aopen+label%3Acategory%3Anew-port).
|
||||
|
||||
## Can Vcpkg create pre-built binary packages? What is the binary format used by Vcpkg?
|
||||
Yes! See [the `export` command](../users/integration.md#export-command).
|
||||
Yes! See [the `export` command](../users/buildsystems/integration.md#export-command).
|
||||
|
||||
## How do I update libraries?
|
||||
The `vcpkg update` command lists all packages which are out-of-sync with your current portfiles. To update a package, follow the instructions in the command.
|
||||
@@ -36,7 +36,7 @@ Execute `git pull` to get the latest sources, then run `bootstrap-vcpkg.bat` (Wi
|
||||
## How do I use different versions of a library on one machine?
|
||||
Within a single instance of Vcpkg (e.g. one set of `installed\`, `packages\`, `ports\` and so forth), you can only have one version of a library installed (otherwise, the headers would conflict with each other!). For those with experience with system-wide package managers, packages in Vcpkg correspond to the `X-dev` or `X-devel` packages.
|
||||
|
||||
To use different versions of a library for different projects, we recommend making separate instances of Vcpkg and using the [per-project integration mechanisms](../users/integration.md). The versions of each library are specified by the files in `ports\`, so they are easily manipulated using standard `git` commands. This makes it very easy to roll back the entire set of libraries to a consistent set of older versions which all work with each other. If you need to then pin a specific library forward, that is as easy as checking out the appropriate version of `ports\<package>\`.
|
||||
To use different versions of a library for different projects, we recommend making separate instances of Vcpkg and using the [per-project integration mechanisms](../users/buildsystems/integration.md). The versions of each library are specified by the files in `ports\`, so they are easily manipulated using standard `git` commands. This makes it very easy to roll back the entire set of libraries to a consistent set of older versions which all work with each other. If you need to then pin a specific library forward, that is as easy as checking out the appropriate version of `ports\<package>\`.
|
||||
|
||||
If your application is very sensitive to the versions of libraries, we recommend checking in the specific set of portfiles you need into your source control along with your project sources and using the `--vcpkg-root` option to redirect the working directory of `vcpkg.exe`.
|
||||
|
||||
@@ -88,7 +88,7 @@ Vcpkg uses CMake internally as a build scripting language. This is because CMake
|
||||
## Will Vcpkg support downloading compiled binaries from a public or private server?
|
||||
We would like to eventually support downloading precompiled binaries, similar to other system package managers.
|
||||
|
||||
In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host. See the [`export`](../users/integration.md#export) command.
|
||||
In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host. See the [`export`](../users/buildsystems/integration.md#export) command.
|
||||
|
||||
## What Visual C++ toolsets are supported?
|
||||
We support Visual Studio 2015 Update 3 and above.
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
- [Step 2: Use](#use)
|
||||
- [VS/MSBuild Project (User-wide integration)](#msbuild)
|
||||
- [CMake (Toolchain file)](#cmake)
|
||||
- [Other integration options](../users/integration.md)
|
||||
- [Other integration options](../users/buildsystems/integration.md)
|
||||
|
||||
---
|
||||
<a name="install"></a>
|
||||
|
||||
224
docs/users/buildsystems/cmake-integration.md
Normal file
224
docs/users/buildsystems/cmake-integration.md
Normal file
@@ -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.
|
||||
20
docs/users/buildsystems/export-command.md
Normal file
20
docs/users/buildsystems/export-command.md
Normal file
@@ -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.
|
||||
10
docs/users/buildsystems/integration.md
Normal file
10
docs/users/buildsystems/integration.md
Normal file
@@ -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)
|
||||
- [`export` Command](#export-command)
|
||||
31
docs/users/buildsystems/manual-integration.md
Normal file
31
docs/users/buildsystems/manual-integration.md
Normal file
@@ -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.
|
||||
139
docs/users/buildsystems/msbuild-integration.md
Normal file
139
docs/users/buildsystems/msbuild-integration.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# 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)
|
||||
- [Classic Mode Configuration](#classic-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)**
|
||||
|
||||
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.
|
||||
@@ -1,177 +0,0 @@
|
||||
# Buildsystem Integration
|
||||
|
||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/integration.md).**
|
||||
## Table of Contents
|
||||
- [MSBuild Integration (Visual Studio)](#msbuild-integration-visual-studio)
|
||||
- [User-wide integration](#user-wide-integration)
|
||||
- [Per-project Integration](#per-project-integration)
|
||||
- [Changing the triplet](#msbuild-changing-the-triplet)
|
||||
- [CMake Integration](#cmake-integration)
|
||||
- [Using an environment variable instead of a command line option](#using-an-environment-variable-instead-of-a-command-line-option)
|
||||
- [Using multiple toolchain files](#using-multiple-toolchain-files)
|
||||
- [Changing the triplet](#cmake-changing-the-triplet)
|
||||
- [Manual Compiler Setup](#manual-compiler-setup)
|
||||
- [`export` Command](#export-command)
|
||||
|
||||
The buildsystem-specific integration styles have heuristics to deduce the correct [triplet][]. This can be overridden in a native way for [MSBuild](#msbuild-changing-the-triplet) and [CMake](#cmake-changing-the-triplet).
|
||||
|
||||
## MSBuild Integration (Visual Studio)
|
||||
|
||||
**If you are using manifest mode(`vcpkg.json`) see [here](manifests.md#msbuild-integration) for additional configuration options.**
|
||||
### 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`.
|
||||
|
||||
**If you are using manifest mode (`vcpkg.json`) see [here](manifests.md#msbuild-integration) for all available options.**
|
||||
|
||||
### Per-project integration
|
||||
|
||||
**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)**
|
||||
|
||||
We also provide individual VS project integration 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.*
|
||||
|
||||
<a name="msbuild-changing-the-triplet"></a>
|
||||
|
||||
### Changing the triplet
|
||||
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
|
||||
<PropertyGroup Label="Globals">
|
||||
<!-- .... -->
|
||||
<VcpkgTriplet Condition="'$(Platform)'=='Win32'">x86-windows-static</VcpkgTriplet>
|
||||
<VcpkgTriplet Condition="'$(Platform)'=='x64'">x64-windows-static</VcpkgTriplet>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
## CMake Integration
|
||||
```no-highlight
|
||||
cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=[vcpkg-root]/scripts/buildsystems/vcpkg.cmake
|
||||
```
|
||||
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 [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
|
||||
# To find and use catch
|
||||
find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
|
||||
include_directories(${CATCH_INCLUDE_DIR})
|
||||
```
|
||||
|
||||
**If you are using manifest mode (`vcpkg.json`) see [here](manifests.md#cmake-integration) for all available options.**
|
||||
|
||||
For different IDE integrations see [here](../../README.md#using-vcpkg-with-cmake).
|
||||
|
||||
### Using an environment variable instead of a command line option
|
||||
|
||||
The `CMAKE_TOOLCHAIN_FILE` setting simply must be set before the `project()` directive is first called. This means that you can easily read from an environment variable to avoid passing it on the configure line:
|
||||
|
||||
```cmake
|
||||
if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE)
|
||||
set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
|
||||
CACHE STRING "")
|
||||
endif()
|
||||
|
||||
project(myproject CXX)
|
||||
```
|
||||
|
||||
### Using multiple toolchain files
|
||||
|
||||
To use an external toolchain file with a project using vcpkg, you can set the cmake variable `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` on the configure line:
|
||||
```no-highlight
|
||||
cmake ../my/project \
|
||||
-DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \
|
||||
-DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/compiler-settings-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_ see the settings in your own triplets, such as your compiler or compilation flags. To change vcpkg's settings, you must make a [custom triplet file](triplets.md) (which can [share your own toolchain](triplets.md#VCPKG_CHAINLOAD_TOOLCHAIN_FILE))**
|
||||
|
||||
<a name="cmake-changing-the-triplet"></a>
|
||||
|
||||
### Changing the triplet
|
||||
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 control 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()
|
||||
```
|
||||
Finally, if you have your own toolchain file, you can set `VCPKG_TARGET_TRIPLET` there:
|
||||
```cmake
|
||||
# MyToolchain.cmake
|
||||
set(CMAKE_CXX_COMPILER ...)
|
||||
set(VCPKG_TARGET_TRIPLET x64-my-custom-triplet)
|
||||
```
|
||||
|
||||
## Manual Compiler Setup
|
||||
|
||||
Libraries are installed into the `installed\` subfolder in classic mode, partitioned by triplet (e.g. x86-windows):
|
||||
|
||||
* The header files are installed to `installed\x86-windows\include`
|
||||
* Release `.lib` files are installed to `installed\x86-windows\lib` or `installed\x86-windows\lib\manual-link`
|
||||
* Release `.dll` files are installed to `installed\x86-windows\bin`
|
||||
* Debug `.lib` files are installed to `installed\x86-windows\debug\lib` or `installed\x86-windows\debug\lib\manual-link`
|
||||
* Debug `.dll` files are installed to `installed\x86-windows\debug\bin`
|
||||
|
||||
See your build system specific documentation for how to use prebuilt binaries.
|
||||
|
||||
_On Windows dynamic triplets:_ 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.
|
||||
|
||||
## Export Command
|
||||
This 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.
|
||||
|
||||
- `--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 installed package files
|
||||
- `scripts\buildsystems\vcpkg.cmake` is a toolchain file suitable for use with CMake
|
||||
|
||||
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.
|
||||
|
||||
|
||||
[triplet]: triplets.md
|
||||
@@ -16,9 +16,6 @@ project directory or build directory. This mode acts more similarly to language
|
||||
recommend using this manifest mode whenever possible, because it allows one to encode a project's dependencies
|
||||
explicitly in a project file, rather than in the documentation, making your project much easier to consume.
|
||||
|
||||
Manifest mode is in beta, but it can be used from the CMake or MSBuild integration, which will be stable when used via
|
||||
things like `find_package`. This is the recommended way to use manifest mode.
|
||||
|
||||
Check out the [manifest cmake example](../examples/manifest-mode-cmake.md) for an example project using CMake and
|
||||
manifest mode.
|
||||
|
||||
@@ -27,8 +24,6 @@ manifest mode.
|
||||
- [Simple Example Manifest](#simple-example-manifest)
|
||||
- [Manifest Syntax Reference](#manifest-syntax-reference)
|
||||
- [Command Line Interface](#command-line-interface)
|
||||
- [CMake Integration](#cmake-integration)
|
||||
- [MSBuild Integration](#msbuild-integration)
|
||||
|
||||
See also [the original specification](../specifications/manifests.md) for more low-level details.
|
||||
|
||||
@@ -317,205 +312,3 @@ Disables automatic activation of all default features listed in the `vcpkg.json`
|
||||
Specifies the directory containing `vcpkg.json`.
|
||||
|
||||
Defaults to searching upwards from the current working directory.
|
||||
|
||||
## CMake Integration
|
||||
|
||||
Our [CMake Integration](integration.md#cmake) will automatically detect a `vcpkg.json` manifest file in the same
|
||||
directory as the top-level `CMakeLists.txt` (`${CMAKE_SOURCE_DIR}/vcpkg.json`) and activate manifest mode. Vcpkg will be
|
||||
automatically bootstrapped if missing and invoked to install your dependencies into your local build directory
|
||||
(`${CMAKE_BINARY_DIR}/vcpkg_installed`).
|
||||
|
||||
### Configuration
|
||||
|
||||
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 variable controls which triplet dependencies will be installed for.
|
||||
|
||||
If unset, vcpkg will automatically detect an appropriate default triplet given the current compiler settings.
|
||||
|
||||
#### `VCPKG_HOST_TRIPLET`
|
||||
|
||||
This variable controls which triplet 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 allows one to set the location of the `vcpkg_installed` directory.
|
||||
It defaults to `${CMAKE_BINARY_DIR}/vcpkg_installed`.
|
||||
|
||||
#### `VCPKG_MANIFEST_MODE`
|
||||
|
||||
This variable controls whether vcpkg operates in manifest mode or in classic mode. To disable manifest mode even with a
|
||||
`vcpkg.json`, set this to `OFF`.
|
||||
|
||||
Defaults to `ON` when `VCPKG_MANIFEST_DIR` is non-empty or `${CMAKE_SOURCE_DIR}/vcpkg.json` exists.
|
||||
|
||||
#### `VCPKG_MANIFEST_DIR`
|
||||
|
||||
This variable can be defined to specify an alternate folder containing your `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` (run in automatic restore mode
|
||||
if the vcpkg tool 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 treat as active 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 whether to automatically activate all 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 appends instead of prepends 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.
|
||||
|
||||
## MSBuild Integration
|
||||
|
||||
To use manifests with MSBuild, first you need to use an [existing integration method](integration.md#with-msbuild).
|
||||
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`.
|
||||
|
||||
As part of your project's build, vcpkg automatically be run and install any listed dependencies to `vcpkg_installed/$(VcpkgTriplet)/`
|
||||
adjacent to the `vcpkg.json` file; these files 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.
|
||||
|
||||
### MSBuild Properties
|
||||
|
||||
When using Visual Studio 2015 integration, these properties can be set in your project file before the
|
||||
|
||||
```xml
|
||||
<Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
|
||||
```
|
||||
|
||||
line, which unfortunately requires manual editing of the `.vcxproj` or passing on the msbuild command line with `/p:`.
|
||||
With 2017 or later integration, These properties can additionally be set via the Visual Studio GUI under
|
||||
`Project Properties -> Vcpkg` or via a common `.props` file imported between `Microsoft.Cpp.props` and
|
||||
`Microsoft.Cpp.targets`.
|
||||
|
||||
#### `VcpkgEnabled` (Use Vcpkg)
|
||||
|
||||
This can be set to "false" to explicitly disable vcpkg integration for the project
|
||||
|
||||
#### `VcpkgTriplet` (Triplet)
|
||||
|
||||
This can be set to a custom triplet to use for integration (such as x64-windows-static)
|
||||
|
||||
#### `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, x64-osx, x64-linux).
|
||||
|
||||
See also [Host Dependencies](host-dependencies.md).
|
||||
|
||||
#### `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.
|
||||
|
||||
#### `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 will default to true in the future.
|
||||
|
||||
#### `VcpkgManifestInstall` (Install Vcpkg Dependencies)
|
||||
|
||||
*(Requires `Use Vcpkg Manifest` set to `true`)*
|
||||
|
||||
This property can be set to "false" to disable automatic dependency restoration on project build. Dependencies can be
|
||||
manually restored via the vcpkg command line.
|
||||
|
||||
#### `VcpkgInstalledDir` (Installed Directory)
|
||||
|
||||
This property defines the location where headers and binaries are consumed from. In manifest mode, this directory is
|
||||
created and populated based on your manifest.
|
||||
|
||||
@@ -6,9 +6,9 @@ Triplet is a standard term used in cross compiling as a way to completely captur
|
||||
|
||||
In Vcpkg, we use triplets to describe an imaginary "target configuration set" for every library. Within a triplet, libraries are generally built with the same configuration, but it is not a requirement. For example, you could have one triplet that builds `openssl` statically and `zlib` dynamically, one that builds them both statically, and one that builds them both dynamically (all for the same target OS and architecture). A single build will consume files from a single triplet.
|
||||
|
||||
We currently provide many triplets by default (run `vcpkg help triplet`). However, you can easily customize or add your own by copying a built-in triplet from the `triplets\` directory into a project local location. Then, use overlay triplets (such as [`$VCPKG_OVERLAY_TRIPLETS`](config-environment.md#vcpkg_overlay_triplets), [CMake Manifest Mode](manifests.md#vcpkg_overlay_triplets), or [MSBuild Manifest Mode](manifests.md#vcpkgadditionalinstalloptions-additional-options)) to add that directory to vcpkg. See our [overlay triplets example](../examples/overlay-triplets-linux-dynamic.md) for a more detailed walkthrough.
|
||||
We currently provide many triplets by default (run `vcpkg help triplet`). However, you can easily customize or add your own by copying a built-in triplet from the `triplets\` directory into a project local location. Then, use `--overlay-triplets=` (or equivalent such as [`$VCPKG_OVERLAY_TRIPLETS`](config-environment.md#vcpkg_overlay_triplets), [CMake `VCPKG_OVERLAY_TRIPLETS`](buildsystems/cmake-integration.md#vcpkg_overlay_triplets), or [MSBuild Additional Options](buildsystems/msbuild-integration.md#vcpkg-additional-install-options)) to add that directory to vcpkg. See our [overlay triplets example](../examples/overlay-triplets-linux-dynamic.md) for a more detailed walkthrough.
|
||||
|
||||
To change the triplet used by your project away from the default, see our [Integration Document](integration.md#triplet-selection).
|
||||
To change the triplet used by your project away from the default, see our [Integration Document](buildsystems/integration.md#triplet-selection).
|
||||
|
||||
## Community triplets
|
||||
|
||||
|
||||
Reference in New Issue
Block a user