[docs] Split integration.md per Build System. #24737
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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: | ||
|
Contributor
There was a problem hiding this comment. Other important folders:
Contributor
There was a problem hiding this comment.
Contributor
Author
There was a problem hiding this comment.
I didn't document this because this particular document is aimed at non-CMake buildsystems (though I suppose meson users might care).
This is actually against vcpkg policy; it is our intent that all config files (
Are there any current ports you're aware of that take advantage of this? If so, I think we have some bugs in our various helpers that touch pkgconfig.
Contributor
There was a problem hiding this comment.
Where is this specified, explicitly?
Contributor
There was a problem hiding this comment.
This has 8 hits for x64-windows. I didn't check if they are valid or if they should go to
Contributor
There was a problem hiding this comment.
We had this discussion in microsoft/vcpkg-tool#171 (comment). |
||
|
|
||
| * 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]/` | ||
|
Contributor
There was a problem hiding this comment. Is this the right place for the missing filesystem layout specification (#17607)? In particular, the diversity in
Contributor
Author
There was a problem hiding this comment. I think that a full layout policy document should probably exist separately, but until that separate document exists this is a fine place to put that information. |
||
|
|
||
ras0219-msft marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I intentionally leave the
<triplet>off here, because in the Manifest Mode + MSBuild case it actually does double up the triplet:/path/to/project/vcpkg_installed/arm64-windows/x64-windows/tools/<host tools here>. This is because we got feedback from the IDE team that it was critical for MSBuild users to be able to switch platforms (x64 -> Win32 -> ARM64) without needing to reinstall dependencies.So in vcpkg terminology, header files for a given target are located at
[install root]/[target triplet]/include. Do you have a suggestion for how I can reword the sentence above to make this clearer?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
wasn't this fixed by @autoantwort ? I mean VS Code has the same problem if you switch triplets and have defined the same
VCPKG_INSTALLED_DIR. Manifest mode should never touch unrelated triplets.After rereading the sentence above and below it seems ok. Maybe line 5 and line 7 could have been swapped and slightly rewritten to accommodate the swap.
What really is missing here is a link on how to manipulate the default root.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Host dependencies & host triplets are what ruin it and require the extra partitioning :(. It's also conceivable that a user could have multiple MSBuild configurations that select different feature sets in the manifest, so different sets of dependencies get installed -- though I just realized that we aren't solving that problem... we may need to change this to
$(Platform)/$(Configuration), same as the output directories.