ceph/src/jaegertracing/opentelemetry-cpp/tools/vcpkg/docs/specifications/export-command.md

   1 # Binary Export (Apr 28, 2017)
   2
   3 **Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
   4
   5 ## 1. Motivation
   6
   7 ### A. Build once and share
   8
   9 Customers want to be able to build their set of required libraries once, and then distribute the resulting binaries to all members of the "group". This has been brought up in
  10 - Enterprise environments, in which there are dedicated teams to acquire libraries and then share them with other teams to consume them
  11 - Academic environments, in which the professor/teacher wants to build the required libraries and then provide them to all the students
  12 - CI Systems, in which developers want to quickly distribute their exact set of dependencies to a cloud-based farm of build machines
  13
  14 Building once and sharing ensures that everyone gets exactly the same binaries, isolates the building effort to a small number of people and minimizes friction to obtain them. Therefore, there is value in enabling users to easily export ready-to-share binaries from `vcpkg`.
  15
  16 ### B. Very large libraries
  17
  18 Libraries like [Qt][] can take a very long time to build (5+ hours). Therefore, having the ability to build them and then distribute the binaries can save a lot of time.
  19
  20 ### C. Flexibility and uses without `vcpkg`
  21
  22 `vcpkg` currently handles cases where you have a `vcpkg` enlistment on your machine and use it for acquiring libraries and integrating into Visual Studio, CMake etc. However, users need the ability to build the libraries and then use them outside of and independently of `vcpkg`. For example:
  23 - Use `vcpkg` for the build, then host the binaries in a website (similarly to nuget)
  24 - Use `vcpkg` for the build, then put the binaries in an installer and distribute the installer
  25
  26 Consuming the libraries outside of `vcpkg` forfeits the ability to install new libraries or update existing ones, but this can be:
  27 - not a concern, like in a short term project or assignment
  28 - explicitly desired, like in the development of a game where libraries and their versions are sealed for a particular release, never to be modified
  29
  30 ### D. Easy consumption in Visual Studio for NuGet users
  31
  32 Customers have requested C++ NuGet packages to integrate into their project. This has come from:
  33 - Customers than have used NuGet (e.g. in C#) and find it very convenient
  34 - Customers who are working on a C# project that has a few dependencies on C++ and just want those dependencies to be satisfied in the most automatic way possible
  35
  36 Providing a way to create NuGet packages provides great value to those customers. In an enterprise environment which focuses on C#, the dedicated acquisition team can create the NuGet packages with `vcpkg` and provide them to the other developers. For the "end-developer", this makes the consumption of C++ libraries the same as C# ones.
  37
  38 [Qt]: https://www.qt.io/
  39
  40 ## 2. Other design concerns
  41
  42 - The `vcpkg` root may have a variety of packages built and many of them might be unrelated to the current task. Providing an easy way to export a subset of them will enhance user experience.
  43 - Since binary compatibility is not guaranteed, it is not safe to individually export packages. Therefore, when exporting a particular package, all of the dependencies that it was built against must also be present in the export format (e.g. zip file). When a `vcpkg export` command succeeds, there is a guarantee that all required headers/binaries are available in the target bundle.
  44
  45 ## 3. Proposed solution
  46
  47 This document proposes the `vcpkg export` command to pack the desired binaries in a convenient format. It is not the goal of this document to discuss binary distribution for C++ in a similar way that NuGet does for C#. It proposes exporting "library sets" instead of individual libraries as a solution to the C++ binary incompatibility problem.
  48
  49 From a user experience perspective, the user expresses interest in exporting a particular library (e.g. `vcpkg export cpprestsdk`). `vcpkg export` should then make sure that the output contains `cpprestsdk` along with all dependencies it was actually built against.
  50
  51 ## 4. Proposed User experience
  52
  53 ### i. User knows what libraries he needs and wants to export them to an archive format (zip)
  54 Developer Bob needs gtest and cpprestsdk and has been manually building them and their dependencies, then using the binaries in his project via applocal deployment. Bob has been experimenting with `vcpkg` and wants to use `vcpkg` for the building part only.
  55
  56 Bob tries to export the libraries:
  57 ```no-highlight
  58 > vcpkg export gtest cpprestsdk --zip
  59 The following packages are already built and will be exported:
  60   * boost:x86-windows
  61   * bzip2:x86-windows
  62     cpprestsdk:x86-windows
  63   * openssl:x86-windows
  64   * websocketpp:x86-windows
  65   * zlib:x86-windows
  66 The following packages need to be built:
  67     gtest:x86-windows
  68 Additional packages (*) need to be exported to complete this operation.
  69 There are packages that have not been built.
  70 To build them, run:
  71     vcpkg install gtest:x86-windows
  72 ```
  73
  74 Bob proceeds to install the missing libraries:
  75 ```no-highlight
  76 > vcpkg install gtest:x86-windows
  77 // -- omitted build information -- //
  78 Package gtest:x86-windows is installed.
  79 ```
  80
  81 Bob then returns to export the libraries:
  82 ```no-highlight
  83 > vcpkg export gtest cpprestsdk --zip
  84 The following packages are already built and will be exported:
  85   * boost:x86-windows
  86   * bzip2:x86-windows
  87     cpprestsdk:x86-windows
  88     gtest:x86-windows
  89   * openssl:x86-windows
  90   * websocketpp:x86-windows
  91   * zlib:x86-windows
  92 Additional packages (*) need to be exported to complete this operation.
  93 Exporting package zlib:x86-windows...
  94 Exporting package zlib:x86-windows... done
  95 Exporting package openssl:x86-windows...
  96 Exporting package openssl:x86-windows... done
  97 Exporting package bzip2:x86-windows...
  98 Exporting package bzip2:x86-windows... done
  99 Exporting package boost:x86-windows...
 100 Exporting package boost:x86-windows... done
 101 Exporting package websocketpp:x86-windows...
 102 Exporting package websocketpp:x86-windows... done
 103 Exporting package cpprestsdk:x86-windows...
 104 Exporting package cpprestsdk:x86-windows... done
 105 Exporting package gtest:x86-windows...
 106 Exporting package gtest:x86-windows... done
 107 Creating zip archive...
 108 Creating zip archive... done
 109 zip archive exported at: C:/vcpkg/vcpkg-export-20170428-155351.zip
 110 ```
 111
 112 Bob takes the zip file and extracts the contents next to his other dependencies. Bob can now proceed with building his own project as before.
 113
 114 ### ii. User has a vcpkg root that works and wants to share it
 115 Developer Alice has been using `vcpkg` and has a Visual Studio project that consumes libraries from it (via `vcpkg integrate`). The project is built for both 32-bit and 64-bit architectures. Alice wants to quickly share the dependencies with Bob so he can test the project.
 116 ```no-highlight
 117 > vcpkg export gtest zlib gtest:x64-windows zlib:x64-windows --nuget
 118 The following packages are already built and will be exported:
 119     gtest:x86-windows
 120     gtest:x64-windows
 121     zlib:x86-windows
 122     zlib:x64-windows
 123 Exporting package zlib:x86-windows...
 124 Exporting package zlib:x86-windows... done
 125 Exporting package zlib:x64-windows...
 126 Exporting package zlib:x64-windows... done
 127 Exporting package gtest:x86-windows...
 128 Exporting package gtest:x86-windows... done
 129 Exporting package gtest:x64-windows...
 130 Exporting package gtest:x64-windows... done
 131 Creating nuget package...
 132 Creating nuget package... done
 133 Nuget package exported at: C:/vcpkg/scripts/buildsystems/tmp/vcpkg-export-20170428-164312.nupkg
 134 ```
 135
 136 Alice gives to Bob: a) The link to her project and b) The NuGet package "vcpkg-export-20170428-164312.nupkg". Bob clones the project and then installs the NuGet package. Bob is now ready to build Alice's project.
 137
 138 ### iii. User has a vcpkg root that works and wants to share it #2
 139 Developer Alice has been using `vcpkg` and has a CMake project that consumes libraries from it (via CMake toolchain file). Alice wants to quickly share the dependencies with Bob so he can test the project.
 140 ```no-highlight
 141 > vcpkg export cpprestsdk zlib --zip
 142 The following packages are already built and will be exported:
 143   * boost:x86-windows
 144   * bzip2:x86-windows
 145     cpprestsdk:x86-windows
 146   * openssl:x86-windows
 147   * websocketpp:x86-windows
 148     zlib:x86-windows
 149 Additional packages (*) need to be exported to complete this operation.
 150 Exporting package zlib:x86-windows...
 151 Exporting package zlib:x86-windows... done
 152 Exporting package openssl:x86-windows...
 153 Exporting package openssl:x86-windows... done
 154 Exporting package bzip2:x86-windows...
 155 Exporting package bzip2:x86-windows... done
 156 Exporting package boost:x86-windows...
 157 Exporting package boost:x86-windows... done
 158 Exporting package websocketpp:x86-windows...
 159 Exporting package websocketpp:x86-windows... done
 160 Exporting package cpprestsdk:x86-windows...
 161 Exporting package cpprestsdk:x86-windows... done
 162 Creating zip archive...
 163 Creating zip archive... done
 164 zip archive exported at: C:/vcpkg/vcpkg-export-20170428-155351.zip
 165 ```
 166
 167 Alice gives to Bob: a) The links to her project and b) The zip file "vcpkg-export-20170428-155351.zip". Bob clones the project, extracts the zip file and uses the provided (in the zip) CMake toolchain file to make the dependencies available to CMake. Bob is now ready to build Alice's project.
 168
 169 ## 5. Technical model
 170
 171 - Each exported library, must be accompanied with all of its dependencies, even if they are not explicitly specified in the `vcpkg export` command.
 172 - When exporting a library, a dependency graph will be built, similarly to install, to figure out which packages need to be exported.
 173 - It is allowed to have packages from different triplets, so users can include 32/64-bit and dynamic/static binaries in the same export.
 174 - The exported archives also include the files needed to integrate with MSBuild and/or CMake.