ceph/src/jaegertracing/opentelemetry-cpp/tools/vcpkg/docs/examples/packaging-zipfiles.md

   1 ## Packaging Zipfiles Example: zlib
   2
   3 ### Bootstrap with `create`
   4 First, locate a globally accessible archive of the library's sources. Zip, gzip, and bzip are all supported. Strongly prefer official sources or mirrors over unofficial mirrors.
   5
   6 *Looking at zlib's website, the URL http://zlib.net/zlib-1.2.11.tar.gz looks appropriate.*
   7
   8 Second, determine a suitable package name. This should be ASCII, lowercase, and recognizable to someone who knows the library's "human name". If the library is already packaged in another package manager, prefer that name.
   9
  10 *Since zlib is already packaged as zlib, we will use the name zlib2 for this example.*
  11
  12 Finally, if the server's name for the archive is not very descriptive (such as downloading a zipped commit or branch from GitHub), choose a nice archive name of the form `<packagename>-<version>.zip`.
  13
  14 *`zlib1211.zip` is a fine name, so no change needed.*
  15
  16 All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports/<packagename>`.
  17
  18 ```no-highlight
  19 PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib-1.2.11.tar.gz zlib1211.tar.gz
  20 -- Generated portfile: D:/src/vcpkg/ports/zlib2/portfile.cmake
  21 ```
  22
  23 ### Create the manifest file
  24 In addition to the generated `ports/<package>/portfile.cmake`, we also need a `ports/<package>/vcpkg.json` file. This file is a simple set of fields describing the package's metadata.
  25
  26 *For zlib2, we'll create the file `ports/zlib2/vcpkg.json` with the following contents:*
  27 ```json
  28 {
  29   "name": "zlib2",
  30   "version-string": "1.2.11",
  31   "description": "A Massively Spiffy Yet Delicately Unobtrusive Compression Library"
  32 }
  33 ```
  34
  35 ### Tweak the generated portfile
  36 The generated `portfile.cmake` will need some editing to correctly package most libraries in the wild, however we can start by trying out the build.
  37
  38 ```no-highlight
  39 PS D:\src\vcpkg> .\vcpkg install zlib2
  40 Computing installation plan...
  41 The following packages will be built and installed:
  42     zlib2[core]:x64-uwp
  43 Starting package 1/1: zlib2:x64-uwp
  44 Building package zlib2[core]:x64-uwp...
  45 -- Using cached C:/src/vcpkg/downloads/zlib1211.tar.gz
  46 -- Cleaning sources at C:/src/vcpkg/buildtrees/zlib2/src/1.2.11-deec42f53b.clean. Pass --editable to vcpkg to reuse sources.
  47 -- Extracting source C:/src/vcpkg/downloads/zlib1211.tar.gz
  48 -- Applying patch cmake_dont_build_more_than_needed.patch
  49 -- Using source at C:/src/vcpkg/buildtrees/zlib2/src/1.2.11-deec42f53b.clean
  50 -- Configuring x64-uwp
  51 -- Building x64-uwp-dbg
  52 -- Building x64-uwp-rel
  53 -- Installing: C:/src/vcpkg/packages/zlib2_x64-uwp/share/zlib2/copyright
  54 -- Performing post-build validation
  55 Include files should not be duplicated into the /debug/include directory. If this cannot be disabled in the project cmake, use
  56     file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include)
  57 /debug/share should not exist. Please reorganize any important files, then use
  58     file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/share)
  59 The software license must be available at ${CURRENT_PACKAGES_DIR}/share/zlib2/copyright
  60 Found 3 error(s). Please correct the portfile:
  61     D:\src\vcpkg\ports\zlib2\portfile.cmake
  62 ```
  63
  64 At this point, it is a matter of reading the error messages and log files while steadily improving the quality of the portfile. Zlib required providing a discrete copy of the LICENSE to copy into the package, suppressing the build and installation of executables and headers, and removing the static libraries after they were installed.
  65
  66 ### Suggested example portfiles
  67 In the `ports/` directory are many libraries that can be used as examples, including many that are not based on CMake.
  68
  69 - Header only libraries
  70     - rapidjson
  71     - range-v3
  72 - MSBuild-based
  73     - mpg123
  74 - Non-CMake, custom buildsystem
  75     - openssl
  76     - ffmpeg