зеркало из https://github.com/microsoft/vcpkg.git
[docs] improve integrate documentation (#19700)
* [docs] improve integrate documentation * Small suggestions Co-authored-by: Robert Schumacher <roschuma@microsoft.com>
This commit is contained in:
autoantwort
GitHub
Родитель
69670b0a4a
Коммит
2777eada3f
|
|
@ -14,7 +14,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
|
||||||
|
|
||||||
### User Help
|
### User Help
|
||||||
|
|
||||||
- [Integration with build systems](users/integration.md)
|
- [Buildsystem Integration](users/integration.md)
|
||||||
- [Triplet files](users/triplets.md)
|
- [Triplet files](users/triplets.md)
|
||||||
- [Configuration and Environment](users/config-environment.md)
|
- [Configuration and Environment](users/config-environment.md)
|
||||||
- [Manifest Mode](users/manifests.md)
|
- [Manifest Mode](users/manifests.md)
|
||||||
|
|
|
||||||
|
|
@ -1,21 +1,24 @@
|
||||||
## Buildsystem Integration
|
# Buildsystem Integration
|
||||||
|
|
||||||
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/integration.md).**
|
**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)
|
||||||
|
|
||||||
Vcpkg offers many ways to integrate into your build so you can do what's right for your project. There are two main categories of integration:
|
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).
|
||||||
|
|
||||||
- [`integrate` command](#integrate)
|
## MSBuild Integration (Visual Studio)
|
||||||
- [`export` command](#export)
|
|
||||||
|
|
||||||
Each integration style has heuristics to deduce the correct [triplet][]. This can be overridden using [a common method](#triplet-selection) based on your buildsystem.
|
**If you are using manifest mode(`vcpkg.json`) see [here](manifests.md#msbuild-integration) for additional configuration options.**
|
||||||
|
### User-wide integration
|
||||||
<a name="integrate-command"></a>
|
|
||||||
### Integrate Command
|
|
||||||
|
|
||||||
These link your project(s) to a specific copy of Vcpkg on your machine so any updates or new package installations will be instantly available for the next build of your project.
|
|
||||||
|
|
||||||
<a name="user-wide-msbuild"></a>
|
|
||||||
#### User-wide for MSBuild (Recommended for Open Source MSBuild projects)
|
|
||||||
```no-highlight
|
```no-highlight
|
||||||
vcpkg integrate install
|
vcpkg integrate install
|
||||||
```
|
```
|
||||||
|
|
@ -32,45 +35,13 @@ Here are some examples, though this is not an exhaustive list:
|
||||||
|
|
||||||
To get a full list for all your installed packages, run `vcpkg owns manual-link`.
|
To get a full list for all your installed packages, run `vcpkg owns manual-link`.
|
||||||
|
|
||||||
<a name="cmake"></a>
|
**If you are using manifest mode (`vcpkg.json`) see [here](manifests.md#msbuild-integration) for all available options.**
|
||||||
#### CMake toolchain file (Recommended for Open Source CMake projects)
|
|
||||||
```no-highlight
|
|
||||||
cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\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.
|
### Per-project integration
|
||||||
|
|
||||||
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:
|
**Note: This approach is not recommended for new projects, since it makes them difficult to share with others.**
|
||||||
```cmake
|
|
||||||
# To find and use catch
|
|
||||||
find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
|
|
||||||
include_directories(${CATCH_INCLUDE_DIR})
|
|
||||||
```
|
|
||||||
|
|
||||||
##### Using an environment variable instead of a command line option
|
**For a portable, self-contained NuGet package, see the [`export command`](#export-command)**
|
||||||
|
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Linking NuGet file
|
|
||||||
|
|
||||||
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.
|
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
|
```no-highlight
|
||||||
|
|
@ -82,49 +53,9 @@ With a project open, go to Tools->NuGet Package Manager->Package Manager Console
|
||||||
```
|
```
|
||||||
*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.*
|
*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.*
|
||||||
|
|
||||||
#### Manual compiler settings
|
<a name="msbuild-changing-the-triplet"></a>
|
||||||
|
|
||||||
Libraries are installed into the `installed\` subfolder, partitioned by architecture (e.g. x86-windows):
|
### Changing the triplet
|
||||||
|
|
||||||
* 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.
|
|
||||||
|
|
||||||
Generally, 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.
|
|
||||||
|
|
||||||
<a name="export-command"></a>
|
|
||||||
### 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 (Recommended for MSBuild projects)
|
|
||||||
- `--zip`: Zip archive
|
|
||||||
- `--7zip`: 7Zip archive (Recommended for CMake projects)
|
|
||||||
- `--raw`: Raw, uncompressed folder
|
|
||||||
|
|
||||||
Each of these have the same layout, which mimics the layout of a full vcpkg:
|
|
||||||
|
|
||||||
- `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.
|
|
||||||
|
|
||||||
<a name="triplet-selection"></a>
|
|
||||||
### Triplet selection
|
|
||||||
Every integration mechanism besides manually adding the folders will deduce a [triplet][] for your project as one of:
|
|
||||||
|
|
||||||
- x86-windows
|
|
||||||
- x64-windows
|
|
||||||
- x86-uwp
|
|
||||||
- x64-uwp
|
|
||||||
- arm-uwp
|
|
||||||
|
|
||||||
#### With MSBuild
|
|
||||||
You can see the automatically deduced triplet by setting your MSBuild verbosity to Normal or higher:
|
You can see the automatically deduced triplet by setting your MSBuild verbosity to Normal or higher:
|
||||||
|
|
||||||
> *Shortcut: Ctrl+Q "build and run"*
|
> *Shortcut: Ctrl+Q "build and run"*
|
||||||
|
|
@ -140,7 +71,59 @@ To override the automatically chosen [triplet][], you can specify the MSBuild pr
|
||||||
</PropertyGroup>
|
</PropertyGroup>
|
||||||
```
|
```
|
||||||
|
|
||||||
#### With CMake
|
## 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:
|
You can set `VCPKG_TARGET_TRIPLET` on the configure line:
|
||||||
```no-highlight
|
```no-highlight
|
||||||
cmake ../my/project -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=...
|
cmake ../my/project -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=...
|
||||||
|
|
@ -152,5 +135,43 @@ if(DEFINED ENV{VCPKG_DEFAULT_TRIPLET} AND NOT DEFINED VCPKG_TARGET_TRIPLET)
|
||||||
set(VCPKG_TARGET_TRIPLET "$ENV{VCPKG_DEFAULT_TRIPLET}" CACHE STRING "")
|
set(VCPKG_TARGET_TRIPLET "$ENV{VCPKG_DEFAULT_TRIPLET}" CACHE STRING "")
|
||||||
endif()
|
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
|
[triplet]: triplets.md
|
||||||
|
|
|
||||||
Загрузка…
Ссылка в новой задаче