ceph/src/jaegertracing/opentelemetry-cpp/tools/vcpkg/docs/examples/installing-and-using-packages.md

   1 ## Installing and Using Packages Example: SQLite
   2
   3   - [Step 1: Install](#install)
   4   - [Step 2: Use](#use)
   5     - [VS/MSBuild Project (User-wide integration)](#msbuild)
   6     - [CMake (Toolchain file)](#cmake)
   7     - [Other integration options](../users/integration.md)
   8
   9 ---
  10 <a name="install"></a>
  11 ## Step 1: Install
  12
  13 First, we need to know what name [SQLite](https://sqlite.org) goes by in the ports tree. To do that, we'll run the `search` command and inspect the output:
  14 ```no-highlight
  15 PS D:\src\vcpkg> .\vcpkg search sqlite
  16 libodb-sqlite        2.4.0            Sqlite support for the ODB ORM library
  17 sqlite3              3.32.1           SQLite is a software library that implements a se...
  18
  19 If your library is not listed, please open an issue at:
  20     https://github.com/Microsoft/vcpkg/issues
  21 ```
  22 Looking at the list, we can see that the port is named "sqlite3". You can also run the `search` command without arguments to see the full list of packages.
  23
  24 Installing is then as simple as using the `install` command.
  25 ```no-highlight
  26 PS D:\src\vcpkg> .\vcpkg install sqlite3
  27 Computing installation plan...
  28 The following packages will be built and installed:
  29     sqlite3[core]:x86-windows
  30 Starting package 1/1: sqlite3:x86-windows
  31 Building package sqlite3[core]:x86-windows...
  32 -- Downloading https://sqlite.org/2020/sqlite-amalgamation-3320100.zip...
  33 -- Extracting source C:/src/vcpkg/downloads/sqlite-amalgamation-3320100.zip
  34 -- Applying patch fix-arm-uwp.patch
  35 -- Using source at C:/src/vcpkg/buildtrees/sqlite3/src/3320100-15aeda126a.clean
  36 -- Configuring x86-windows
  37 -- Building x86-windows-dbg
  38 -- Building x86-windows-rel
  39 -- Performing post-build validation
  40 -- Performing post-build validation done
  41 Building package sqlite3[core]:x86-windows... done
  42 Installing package sqlite3[core]:x86-windows...
  43 Installing package sqlite3[core]:x86-windows... done
  44 Elapsed time for package sqlite3:x86-windows: 12 s
  45
  46 Total elapsed time: 12.04 s
  47
  48 The package sqlite3:x86-windows provides CMake targets:
  49
  50     find_package(unofficial-sqlite3 CONFIG REQUIRED)
  51     target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3))
  52
  53 ```
  54
  55 We can check that sqlite3 was successfully installed for x86 Windows desktop by running the `list` command.
  56 ```no-highlight
  57 PS D:\src\vcpkg> .\vcpkg list
  58 sqlite3:x86-windows         3.32.1           SQLite is a software library that implements a se...
  59 ```
  60
  61 To install for other architectures and platforms such as Universal Windows Platform or x64 Desktop, you can suffix the package name with `:<target>`.
  62 ```no-highlight
  63 PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows
  64 ```
  65
  66 See `.\vcpkg help triplet` for all supported targets.
  67
  68 ---
  69 <a name="use"></a>
  70 ## Step 2: Use
  71 <a name="msbuild"></a>
  72 #### VS/MSBuild Project (User-wide integration)
  73
  74 The recommended and most productive way to use vcpkg is via user-wide integration, making the system available for all projects you build. The user-wide integration will prompt for administrator access the first time it is used on a given machine, but afterwards is no longer required and the integration is configured on a per-user basis.
  75 ```no-highlight
  76 PS D:\src\vcpkg> .\vcpkg integrate install
  77 Applied user-wide integration for this vcpkg root.
  78
  79 All C++ projects can now #include any installed libraries.
  80 Linking will be handled automatically.
  81 Installing new libraries will make them instantly available.
  82 ```
  83 *Note: You will need to restart Visual Studio or perform a Build to update intellisense with the changes.*
  84
  85 You can now simply use File -> New Project in Visual Studio and the library will be automatically available. For SQLite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html).
  86
  87 To remove the integration for your user, you can use `.\vcpkg integrate remove`.
  88
  89 <a name="cmake"></a>
  90 #### CMake (Toolchain File)
  91
  92 The best way to use installed libraries with cmake is via the toolchain file `scripts\buildsystems\vcpkg.cmake`. To use this file, you simply need to add it onto your CMake command line as:
  93 `-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake`.
  94
  95 If you are using CMake through Open Folder with Visual Studio you can define `CMAKE_TOOLCHAIN_FILE` by adding a "variables" section to each of your `CMakeSettings.json` configurations:
  96
  97 ```json
  98 {
  99   "configurations": [{
 100     "name": "x86-Debug",
 101     "generator": "Visual Studio 15 2017",
 102     "configurationType" : "Debug",
 103     "buildRoot":  "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}",
 104     "cmakeCommandArgs": "",
 105     "buildCommandArgs": "-m -v:minimal",
 106     "variables": [{
 107       "name": "CMAKE_TOOLCHAIN_FILE",
 108       "value": "D:\\src\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake"
 109     }]
 110   }]
 111 }
 112 ```
 113 *Note: It might be necessary to delete the CMake cache folder of each modified configuration, to force a full regeneration. In the `CMake` menu, under `Cache (<configuration name>)` you'll find `Delete Cache Folders`.*
 114
 115 Now let's make a simple CMake project with a main file.
 116 ```cmake
 117 # CMakeLists.txt
 118 cmake_minimum_required(VERSION 3.0)
 119 project(test)
 120
 121 find_package(unofficial-sqlite3 CONFIG REQUIRED)
 122
 123 add_executable(main main.cpp)
 124
 125 target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3)
 126 ```
 127 ```cpp
 128 // main.cpp
 129 #include <sqlite3.h>
 130 #include <stdio.h>
 131
 132 int main()
 133 {
 134     printf("%s\n", sqlite3_libversion());
 135     return 0;
 136 }
 137 ```
 138
 139 Then, we build our project in the normal CMake way:
 140 ```no-highlight
 141 PS D:\src\cmake-test> mkdir build
 142 PS D:\src\cmake-test> cd build
 143 PS D:\src\cmake-test\build> cmake .. "-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake"
 144     // omitted CMake output here //
 145 -- Build files have been written to: D:/src/cmake-test/build
 146 PS D:\src\cmake-test\build> cmake --build .
 147     // omitted MSBuild output here //
 148 Build succeeded.
 149     0 Warning(s)
 150     0 Error(s)
 151
 152 Time Elapsed 00:00:02.38
 153 PS D:\src\cmake-test\build> .\Debug\main.exe
 154 3.15.0
 155 ```
 156
 157 *Note: The correct sqlite3.dll is automatically copied to the output folder when building for x86-windows. You will need to distribute this along with your application.*
 158
 159 ##### Handling libraries without native cmake support
 160
 161 Unlike other platforms, we do not automatically add the `include\` directory to your compilation line by default. If you're using a library that does not provide CMake integration, you will need to explicitly search for the files and add them yourself using [`find_path()`][1] and [`find_library()`][2].
 162
 163 ```cmake
 164 # To find and use catch
 165 find_path(CATCH_INCLUDE_DIR catch.hpp)
 166 include_directories(${CATCH_INCLUDE_DIR})
 167
 168 # To find and use azure-storage-cpp
 169 find_path(WASTORAGE_INCLUDE_DIR was/blob.h)
 170 find_library(WASTORAGE_LIBRARY wastorage)
 171 include_directories(${WASTORAGE_INCLUDE_DIR})
 172 link_libraries(${WASTORAGE_LIBRARY})
 173
 174 # Note that we recommend using the target-specific directives for a cleaner cmake:
 175 #     target_include_directories(main ${LIBRARY})
 176 #     target_link_libraries(main PRIVATE ${LIBRARY})
 177 ```
 178
 179 [1]: https://cmake.org/cmake/help/latest/command/find_path.html
 180 [2]: https://cmake.org/cmake/help/latest/command/find_library.html