ceph/src/jaegertracing/opentelemetry-cpp/tools/vcpkg/docs/users/integration.md

   1 ## Buildsystem Integration
   2
   3 **The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/integration.md).**
   4
   5 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:
   6
   7 - [`integrate` command](#integrate)
   8 - [`export` command](#export)
   9
  10 Each integration style has heuristics to deduce the correct [triplet][]. This can be overridden using [a common method](#triplet-selection) based on your buildsystem.
  11
  12 <a name="integrate-command"></a>
  13 ### Integrate Command
  14
  15 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.
  16
  17 <a name="user-wide-msbuild"></a>
  18 #### User-wide for MSBuild (Recommended for Open Source MSBuild projects)
  19 ```no-highlight
  20 vcpkg integrate install
  21 ```
  22 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.
  23
  24 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.
  25
  26 Here are some examples, though this is not an exhaustive list:
  27
  28 - Gtest provides `gtest`, `gmock`, `gtest_main`, and `gmock_main`
  29 - SDL2 provides `SDL2main`
  30 - SFML provides `sfml-main`
  31 - Boost.Test provides `boost_test_exec_monitor`
  32
  33 To get a full list for all your installed packages, run `vcpkg owns manual-link`.
  34
  35 <a name="cmake"></a>
  36 #### CMake toolchain file (Recommended for Open Source CMake projects)
  37 ```no-highlight
  38 cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake
  39 ```
  40 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()`.
  41
  42 See [Installing and Using Packages Example: sqlite](../examples/installing-and-using-packages.md) for a fully worked example using our CMake toolchain.
  43
  44 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:
  45 ```cmake
  46 # To find and use catch
  47 find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
  48 include_directories(${CATCH_INCLUDE_DIR})
  49 ```
  50
  51 ##### Using an environment variable instead of a command line option
  52
  53 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:
  54
  55 ```cmake
  56 if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE)
  57   set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
  58       CACHE STRING "")
  59 endif()
  60
  61 project(myproject CXX)
  62 ```
  63
  64 ##### Using multiple toolchain files
  65
  66 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:
  67 ```no-highlight
  68 cmake ../my/project \
  69    -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \
  70    -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/compiler-settings-toolchain.cmake
  71 ```
  72
  73 #### Linking NuGet file
  74
  75 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.
  76 ```no-highlight
  77 PS D:\src\vcpkg> .\vcpkg integrate project
  78 Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg
  79
  80 With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste:
  81     Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems"
  82 ```
  83 *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.*
  84
  85 #### Manual compiler settings
  86
  87 Libraries are installed into the `installed\` subfolder, partitioned by architecture (e.g. x86-windows):
  88
  89 * The header files are installed to `installed\x86-windows\include`
  90 * Release `.lib` files are installed to `installed\x86-windows\lib` or `installed\x86-windows\lib\manual-link`
  91 * Release `.dll` files are installed to `installed\x86-windows\bin`
  92 * Debug `.lib` files are installed to `installed\x86-windows\debug\lib` or `installed\x86-windows\debug\lib\manual-link`
  93 * Debug `.dll` files are installed to `installed\x86-windows\debug\bin`
  94
  95 See your build system specific documentation for how to use prebuilt binaries.
  96
  97 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.
  98
  99 <a name="export-command"></a>
 100 ### Export Command
 101 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.
 102
 103 - `--nuget`: NuGet package (Recommended for MSBuild projects)
 104 - `--zip`: Zip archive
 105 - `--7zip`: 7Zip archive (Recommended for CMake projects)
 106 - `--raw`: Raw, uncompressed folder
 107
 108 Each of these have the same layout, which mimics the layout of a full vcpkg:
 109
 110 - `installed\` contains the installed package files
 111 - `scripts\buildsystems\vcpkg.cmake` is a toolchain file suitable for use with CMake
 112
 113 Additionally, NuGet packages will contain a `build\native\vcpkg.targets` that integrates with MSBuild projects.
 114
 115 Please also see our [blog post](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) for additional examples.
 116
 117 <a name="triplet-selection"></a>
 118 ### Triplet selection
 119 Every integration mechanism besides manually adding the folders will deduce a [triplet][] for your project as one of:
 120
 121 - x86-windows
 122 - x64-windows
 123 - x86-uwp
 124 - x64-uwp
 125 - arm-uwp
 126
 127 #### With MSBuild
 128 You can see the automatically deduced triplet by setting your MSBuild verbosity to Normal or higher:
 129
 130 > *Shortcut: Ctrl+Q "build and run"*
 131 >
 132 > Tools -> Options -> Projects and Solutions -> Build and Run -> MSBuild project build output verbosity
 133
 134 To override the automatically chosen [triplet][], you can specify the MSBuild property `VcpkgTriplet` in your `.vcxproj`. We recommend adding this to the `Globals` PropertyGroup.
 135 ```xml
 136 <PropertyGroup Label="Globals">
 137   <!-- .... -->
 138   <VcpkgTriplet Condition="'$(Platform)'=='Win32'">x86-windows-static</VcpkgTriplet>
 139   <VcpkgTriplet Condition="'$(Platform)'=='x64'">x64-windows-static</VcpkgTriplet>
 140 </PropertyGroup>
 141 ```
 142
 143 #### With CMake
 144 You can set `VCPKG_TARGET_TRIPLET` on the configure line:
 145 ```no-highlight
 146 cmake ../my/project -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=...
 147 ```
 148 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):
 149
 150 ```cmake
 151 if(DEFINED ENV{VCPKG_DEFAULT_TRIPLET} AND NOT DEFINED VCPKG_TARGET_TRIPLET)
 152   set(VCPKG_TARGET_TRIPLET "$ENV{VCPKG_DEFAULT_TRIPLET}" CACHE STRING "")
 153 endif()
 154 ```
 155
 156 [triplet]: triplets.md