Techt3o commited on
Commit
49de253
·
verified ·
1 Parent(s): 9847acb

34bad85e8f4867cc4aae63614ab916b258f738b7d991cec1f2cecea7c449afc7

Browse files
Files changed (50) hide show
  1. third-party/DPVO/Pangolin/scripts/vcpkg/docs/README.md +76 -0
  2. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_configure_make.md +93 -0
  3. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_configure_meson.md +44 -0
  4. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_configure_qmake.md +29 -0
  5. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_copy_pdbs.md +29 -0
  6. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_copy_tool_dependencies.md +23 -0
  7. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_copy_tools.md +36 -0
  8. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_download_distfile.md +62 -0
  9. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_execute_build_process.md +38 -0
  10. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_execute_in_download_mode.md +21 -0
  11. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_execute_required_process.md +51 -0
  12. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_execute_required_process_repeat.md +19 -0
  13. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_extract_source_archive.md +86 -0
  14. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_extract_source_archive_ex.md +26 -0
  15. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_fail_port_install.md +45 -0
  16. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_find_acquire_program.md +51 -0
  17. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_find_fortran.md +25 -0
  18. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_fixup_cmake_targets.md +62 -0
  19. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_fixup_pkgconfig.md +49 -0
  20. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_bitbucket.md +60 -0
  21. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_git.md +53 -0
  22. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_github.md +78 -0
  23. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_gitlab.md +71 -0
  24. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_sourceforge.md +73 -0
  25. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_get_program_files_platform_bitness.md +15 -0
  26. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_get_windows_sdk.md +13 -0
  27. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_host_path_list.md +29 -0
  28. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_cmake.md +29 -0
  29. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_gn.md +31 -0
  30. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_make.md +26 -0
  31. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_meson.md +22 -0
  32. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_msbuild.md +95 -0
  33. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_nmake.md +68 -0
  34. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_qmake.md +26 -0
  35. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_list.md +94 -0
  36. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_minimum_required.md +17 -0
  37. third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_replace_string.md +12 -0
  38. third-party/DPVO/Pangolin/scripts/vcpkg/docs/regenerate.ps1 +353 -0
  39. third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/binarycaching.md +159 -0
  40. third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/export-command.md +174 -0
  41. third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/feature-packages.md +291 -0
  42. third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/manifests.md +302 -0
  43. third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/ports-overlay.md +183 -0
  44. third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/prefab.md +160 -0
  45. third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/registries-2.md +559 -0
  46. third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/registries.md +287 -0
  47. third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/scripts-extraction.md +66 -0
  48. third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/versioning.md +357 -0
  49. third-party/DPVO/Pangolin/scripts/vcpkg/docs/users/android.md +224 -0
  50. third-party/DPVO/Pangolin/scripts/vcpkg/docs/users/assetcaching.md +58 -0
third-party/DPVO/Pangolin/scripts/vcpkg/docs/README.md ADDED
@@ -0,0 +1,76 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Quick Start
2
+
3
+ **The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/README.md).**
4
+
5
+ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This tool and ecosystem are constantly evolving; your involvement is vital to its success!
6
+
7
+ ### Examples
8
+
9
+ - [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md)
10
+ - [Packaging Zipfiles Example: zlib](examples/packaging-zipfiles.md)
11
+ - [Packaging GitHub Repositories Example: libogg](examples/packaging-github-repos.md)
12
+ - [Patching Example: Patching libpng to work for x64-uwp](examples/patching.md)
13
+ - [Getting Started with Versioning](examples/versioning.getting-started.md)
14
+
15
+ ### User Help
16
+
17
+ - [Buildsystem Integration](users/integration.md)
18
+ - [Triplet files](users/triplets.md)
19
+ - [Configuration and Environment](users/config-environment.md)
20
+ - [Authentication](users/authentication.md)
21
+ - [Manifest Mode](users/manifests.md)
22
+ - [Binary Caching](users/binarycaching.md)
23
+ - [Asset Caching](users/assetcaching.md)
24
+ - [Versioning](users/versioning.md)
25
+ - [Usage with Android](users/android.md)
26
+ - [Usage with Mingw-w64](users/mingw.md)
27
+ - [Host Dependencies](users/host-dependencies.md)
28
+ - [Using Registries](users/registries.md)
29
+
30
+ ### Maintainer Help
31
+
32
+ - [Manifest Files - vcpkg.json](maintainers/manifest-files.md)
33
+ - [Control Files](maintainers/control-files.md)
34
+ - [Portfile Functions](maintainers/portfile-functions.md)
35
+ - [Authoring Script Ports](maintainers/authoring-script-ports.md)
36
+ - [Common CMake Definitions](maintainers/vcpkg_common_definitions.md)
37
+ - [Maintainer Guidelines](maintainers/maintainer-guide.md)
38
+ - [Creating Registries](maintainers/registries.md)
39
+ - [CMake Guidelines](maintainers/cmake-guidelines.md)
40
+
41
+ ### [Vcpkg-Tool](https://github.com/microsoft/vcpkg-tool) Maintainer Help
42
+
43
+ - [Testing](https://github.com/microsoft/vcpkg-tool/tree/main/docs/testing.md)
44
+ - [Benchmarking](https://github.com/microsoft/vcpkg-tool/tree/main/docs/benchmarking.md)
45
+ - [Layout of the vcpkg source tree](https://github.com/microsoft/vcpkg-tool/tree/main/docs/layout.md)
46
+
47
+ ### Community Resources (not directly affiliated with vcpkg)
48
+
49
+ - [vcpkg.info](https://vcpkg.info/) - Package index + search
50
+ - [vcpkgx](https://vcpkgx.com/) - Package index + search
51
+ - [vcpkg index](https://vcpkg.dev/) - Package index + search
52
+
53
+ ### Specifications
54
+
55
+ - [Export](specifications/export-command.md)
56
+ - [Feature Packages](specifications/feature-packages.md)
57
+
58
+ ### Blog posts
59
+
60
+ - [Vcpkg Host Dependencies for Cross-Compilation](https://devblogs.microsoft.com/cppblog/vcpkg-host-dependencies/)
61
+ - [Registries: Bring your own libraries to vcpkg](https://devblogs.microsoft.com/cppblog/registries-bring-your-own-libraries-to-vcpkg/)
62
+ - [Vcpkg: Accelerate your team development environment with binary caching and manifests](https://devblogs.microsoft.com/cppblog/vcpkg-accelerate-your-team-development-environment-with-binary-caching-and-manifests/)
63
+ - [Vcpkg: 2019.06 Update (overlay ports, overlay triplets, `vcpkg_check_features`)](https://devblogs.microsoft.com/cppblog/vcpkg-2019-06-update/)
64
+ - [Announcing a single C++ library manager for Linux, macOS and Windows: Vcpkg](https://blogs.msdn.microsoft.com/vcblog/2018/04/24/announcing-a-single-c-library-manager-for-linux-macos-and-windows-vcpkg/)
65
+ - [Vcpkg: Using multiple enlistments to handle multiple versions of a library](https://blogs.msdn.microsoft.com/vcblog/2017/10/23/vcpkg-using-multiple-enlistments/)
66
+ - [Vcpkg: introducing the export command](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/)
67
+ - [Binary Compatibility and Pain-free Upgrade Why Moving to Visual Studio 2017 is almost "too easy"](https://blogs.msdn.microsoft.com/vcblog/2017/03/07/binary-compatibility-and-pain-free-upgrade-why-moving-to-visual-studio-2017-is-almost-too-easy/)
68
+ - [Vcpkg recent enhancements](https://blogs.msdn.microsoft.com/vcblog/2017/02/14/vcpkg-recent-enhancements/)
69
+ - [Vcpkg 3 Months Anniversary, Survey](https://blogs.msdn.microsoft.com/vcblog/2017/01/11/vcpkg-3-months-anniversary-survey/)
70
+ - [Vcpkg updates: Static linking is now available](https://blogs.msdn.microsoft.com/vcblog/2016/11/01/vcpkg-updates-static-linking-is-now-available/)
71
+ - [Vcpkg: a tool to acquire and build C++ open source libraries on Windows](https://blogs.msdn.microsoft.com/vcblog/2016/09/19/vcpkg-a-tool-to-acquire-and-build-c-open-source-libraries-on-windows/)
72
+
73
+ ### Other
74
+
75
+ - [FAQ](about/faq.md)
76
+ - [Privacy](about/privacy.md)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_configure_make.md ADDED
@@ -0,0 +1,93 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_configure_make
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_make.md).
4
+
5
+ Configure configure for Debug and Release builds of a project.
6
+
7
+ ## Usage
8
+ ```cmake
9
+ vcpkg_configure_make(
10
+ SOURCE_PATH <${SOURCE_PATH}>
11
+ [AUTOCONFIG]
12
+ [USE_WRAPPERS]
13
+ [DETERMINE_BUILD_TRIPLET]
14
+ [BUILD_TRIPLET "--host=x64 --build=i686-unknown-pc"]
15
+ [NO_ADDITIONAL_PATHS]
16
+ [CONFIG_DEPENDENT_ENVIRONMENT <SOME_VAR>...]
17
+ [CONFIGURE_ENVIRONMENT_VARIABLES <SOME_ENVVAR>...]
18
+ [ADD_BIN_TO_PATH]
19
+ [NO_DEBUG]
20
+ [SKIP_CONFIGURE]
21
+ [PROJECT_SUBPATH <${PROJ_SUBPATH}>]
22
+ [PRERUN_SHELL <${SHELL_PATH}>]
23
+ [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
24
+ [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
25
+ [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
26
+ )
27
+ ```
28
+
29
+ ## Parameters
30
+ ### SOURCE_PATH
31
+ Specifies the directory containing the `configure`/`configure.ac`.
32
+ By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
33
+
34
+ ### PROJECT_SUBPATH
35
+ Specifies the directory containing the ``configure`/`configure.ac`.
36
+ By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
37
+
38
+ ### SKIP_CONFIGURE
39
+ Skip configure process
40
+
41
+ ### USE_WRAPPERS
42
+ Use autotools ar-lib and compile wrappers (only applies to windows cl and lib)
43
+
44
+ ### BUILD_TRIPLET
45
+ Used to pass custom --build/--target/--host to configure. Can be globally overwritten by VCPKG_MAKE_BUILD_TRIPLET
46
+
47
+ ### DETERMINE_BUILD_TRIPLET
48
+ For ports having a configure script following the autotools rules for selecting the triplet
49
+
50
+ ### NO_ADDITIONAL_PATHS
51
+ Don't pass any additional paths except for --prefix to the configure call
52
+
53
+ ### AUTOCONFIG
54
+ Need to use autoconfig to generate configure file.
55
+
56
+ ### PRERUN_SHELL
57
+ Script that needs to be called before configuration (do not use for batch files which simply call autoconf or configure)
58
+
59
+ ### ADD_BIN_TO_PATH
60
+ Adds the appropriate Release and Debug `bin\` directories to the path during configure such that executables can run against the in-tree DLLs.
61
+
62
+ ## DISABLE_VERBOSE_FLAGS
63
+ do not pass '--disable-silent-rules --verbose' to configure
64
+
65
+ ### OPTIONS
66
+ Additional options passed to configure during the configuration.
67
+
68
+ ### OPTIONS_RELEASE
69
+ Additional options passed to configure during the Release configuration. These are in addition to `OPTIONS`.
70
+
71
+ ### OPTIONS_DEBUG
72
+ Additional options passed to configure during the Debug configuration. These are in addition to `OPTIONS`.
73
+
74
+ ### CONFIG_DEPENDENT_ENVIRONMENT
75
+ List of additional configuration dependent environment variables to set.
76
+ Pass SOMEVAR to set the environment and have SOMEVAR_(DEBUG|RELEASE) set in the portfile to the appropriate values
77
+ General environment variables can be set from within the portfile itself.
78
+
79
+ ### CONFIGURE_ENVIRONMENT_VARIABLES
80
+ List of additional environment variables to pass via the configure call.
81
+
82
+ ## Notes
83
+ This command supplies many common arguments to configure. To see the full list, examine the source.
84
+
85
+ ## Examples
86
+
87
+ * [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake)
88
+ * [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
89
+ * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
90
+ * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
91
+
92
+ ## Source
93
+ [scripts/cmake/vcpkg\_configure\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_configure_meson.md ADDED
@@ -0,0 +1,44 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_configure_meson
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_meson.md).
4
+
5
+ Configure Meson for Debug and Release builds of a project.
6
+
7
+ ## Usage
8
+ ```cmake
9
+ vcpkg_configure_meson(
10
+ SOURCE_PATH <${SOURCE_PATH}>
11
+ [NO_PKG_CONFIG]
12
+ [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
13
+ [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
14
+ [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
15
+ )
16
+ ```
17
+
18
+ ## Parameters
19
+ ### SOURCE_PATH
20
+ Specifies the directory containing the `meson.build`.
21
+ By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
22
+
23
+ ### OPTIONS
24
+ Additional options passed to Meson during the configuration.
25
+
26
+ ### OPTIONS_RELEASE
27
+ Additional options passed to Meson during the Release configuration. These are in addition to `OPTIONS`.
28
+
29
+ ### OPTIONS_DEBUG
30
+ Additional options passed to Meson during the Debug configuration. These are in addition to `OPTIONS`.
31
+
32
+ ### NO_PKG_CONFIG
33
+ Disable pkg-config setup
34
+
35
+ ## Notes
36
+ This command supplies many common arguments to Meson. To see the full list, examine the source.
37
+
38
+ ## Examples
39
+
40
+ * [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake)
41
+ * [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
42
+
43
+ ## Source
44
+ [scripts/cmake/vcpkg\_configure\_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_meson.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_configure_qmake.md ADDED
@@ -0,0 +1,29 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_configure_qmake
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_qmake.md).
4
+
5
+ Configure a qmake-based project.
6
+
7
+ ```cmake
8
+ vcpkg_configure_qmake(
9
+ SOURCE_PATH <pro_file_path>
10
+ [OPTIONS arg1 [arg2 ...]]
11
+ [OPTIONS_RELEASE arg1 [arg2 ...]]
12
+ [OPTIONS_DEBUG arg1 [arg2 ...]]
13
+ [BUILD_OPTIONS arg1 [arg2 ...]]
14
+ [BUILD_OPTIONS_RELEASE arg1 [arg2 ...]]
15
+ [BUILD_OPTIONS_DEBUG arg1 [arg2 ...]]
16
+ )
17
+ ```
18
+
19
+ ### SOURCE_PATH
20
+ The path to the *.pro qmake project file.
21
+
22
+ ### OPTIONS, OPTIONS\_RELEASE, OPTIONS\_DEBUG
23
+ The options passed to qmake to the configure step.
24
+
25
+ ### BUILD\_OPTIONS, BUILD\_OPTIONS\_RELEASE, BUILD\_OPTIONS\_DEBUG
26
+ The options passed to qmake to the build step.
27
+
28
+ ## Source
29
+ [scripts/cmake/vcpkg\_configure\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_qmake.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_copy_pdbs.md ADDED
@@ -0,0 +1,29 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_copy_pdbs
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_copy_pdbs.md).
4
+
5
+ Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
6
+
7
+ ```cmake
8
+ vcpkg_copy_pdbs(
9
+ [BUILD_PATHS <glob>...])
10
+ ```
11
+
12
+ The `<glob>`s are patterns which will be passed to `file(GLOB_RECURSE)`,
13
+ for locating DLLs. It defaults to using:
14
+
15
+ - `${CURRENT_PACKAGES_DIR}/bin/*.dll`
16
+ - `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`
17
+
18
+ since that is generally where DLLs are located.
19
+
20
+ ## Notes
21
+ This command should always be called by portfiles after they have finished rearranging the binary output.
22
+
23
+ ## Examples
24
+
25
+ * [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
26
+ * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
27
+
28
+ ## Source
29
+ [scripts/cmake/vcpkg\_copy\_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_copy_tool_dependencies.md ADDED
@@ -0,0 +1,23 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_copy_tool_dependencies
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_copy_tool_dependencies.md).
4
+
5
+ Copy all DLL dependencies of built tools into the tool folder.
6
+
7
+ ## Usage
8
+ ```cmake
9
+ vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>)
10
+ ```
11
+ ## Parameters
12
+ The path to the directory containing the tools.
13
+
14
+ ## Notes
15
+ This command should always be called by portfiles after they have finished rearranging the binary output, if they have any tools.
16
+
17
+ ## Examples
18
+
19
+ * [glib](https://github.com/Microsoft/vcpkg/blob/master/ports/glib/portfile.cmake)
20
+ * [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake)
21
+
22
+ ## Source
23
+ [scripts/cmake/vcpkg\_copy\_tool\_dependencies.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tool_dependencies.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_copy_tools.md ADDED
@@ -0,0 +1,36 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_copy_tools
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_copy_tools.md).
4
+
5
+ Copy tools and all their DLL dependencies into the `tools` folder.
6
+
7
+ ## Usage
8
+ ```cmake
9
+ vcpkg_copy_tools(
10
+ TOOL_NAMES <tool1>...
11
+ [SEARCH_DIR <${CURRENT_PACKAGES_DIR}/bin>]
12
+ [DESTINATION <${CURRENT_PACKAGES_DIR}/tools/${PORT}>]
13
+ [AUTO_CLEAN]
14
+ )
15
+ ```
16
+ ## Parameters
17
+ ### TOOL_NAMES
18
+ A list of tool filenames without extension.
19
+
20
+ ### SEARCH_DIR
21
+ The path to the directory containing the tools. This will be set to `${CURRENT_PACKAGES_DIR}/bin` if omitted.
22
+
23
+ ### DESTINATION
24
+ Destination to copy the tools to. This will be set to `${CURRENT_PACKAGES_DIR}/tools/${PORT}` if omitted.
25
+
26
+ ### AUTO_CLEAN
27
+ Auto clean the copied executables from `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`.
28
+
29
+ ## Examples
30
+
31
+ * [cpuinfo](https://github.com/microsoft/vcpkg/blob/master/ports/cpuinfo/portfile.cmake)
32
+ * [nanomsg](https://github.com/microsoft/vcpkg/blob/master/ports/nanomsg/portfile.cmake)
33
+ * [uriparser](https://github.com/microsoft/vcpkg/blob/master/ports/uriparser/portfile.cmake)
34
+
35
+ ## Source
36
+ [scripts/cmake/vcpkg\_copy\_tools.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tools.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_download_distfile.md ADDED
@@ -0,0 +1,62 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_download_distfile
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_download_distfile.md).
4
+
5
+ Download and cache a file needed for this port.
6
+
7
+ This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.
8
+
9
+ ## Usage
10
+ ```cmake
11
+ vcpkg_download_distfile(
12
+ <OUT_VARIABLE>
13
+ URLS <http://mainUrl> <http://mirror1>...
14
+ FILENAME <output.zip>
15
+ SHA512 <5981de...>
16
+ [ALWAYS_REDOWNLOAD]
17
+ )
18
+ ```
19
+ ## Parameters
20
+ ### OUT_VARIABLE
21
+ This variable will be set to the full path to the downloaded file. This can then immediately be passed in to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) for sources.
22
+
23
+ ### URLS
24
+ A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given.
25
+
26
+ ### FILENAME
27
+ The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.
28
+
29
+ ### SHA512
30
+ The expected hash for the file.
31
+
32
+ If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch.
33
+
34
+ ### QUIET
35
+ Suppress output on cache hit
36
+
37
+ ### SKIP_SHA512
38
+ Skip SHA512 hash check for file.
39
+
40
+ This switch is only valid when building with the `--head` command line flag.
41
+
42
+ ### ALWAYS_REDOWNLOAD
43
+ Avoid caching; this is a REST call or otherwise unstable.
44
+
45
+ Requires `SKIP_SHA512`.
46
+
47
+ ### HEADERS
48
+ A list of headers to append to the download request. This can be used for authentication during a download.
49
+
50
+ Headers should be specified as "<header-name>: <header-value>".
51
+
52
+ ## Notes
53
+ The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects.
54
+
55
+ ## Examples
56
+
57
+ * [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake)
58
+ * [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)
59
+ * [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)
60
+
61
+ ## Source
62
+ [scripts/cmake/vcpkg\_download\_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_execute_build_process.md ADDED
@@ -0,0 +1,38 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_execute_build_process
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_execute_build_process.md).
4
+
5
+ Execute a required build process
6
+
7
+ ## Usage
8
+ ```cmake
9
+ vcpkg_execute_build_process(
10
+ COMMAND <cmd> [<args>...]
11
+ [NO_PARALLEL_COMMAND <cmd> [<args>...]]
12
+ WORKING_DIRECTORY </path/to/dir>
13
+ LOGNAME <log_name>
14
+ )
15
+ ```
16
+ ## Parameters
17
+ ### COMMAND
18
+ The command to be executed, along with its arguments.
19
+
20
+ ### NO_PARALLEL_COMMAND
21
+ Optional parameter which specifies a non-parallel command to attempt if a
22
+ failure potentially due to parallelism is detected.
23
+
24
+ ### WORKING_DIRECTORY
25
+ The directory to execute the command in.
26
+
27
+ ### LOGNAME
28
+ The prefix to use for the log files.
29
+
30
+ This should be a unique name for different triplets so that the logs don't
31
+ conflict when building multiple at once.
32
+
33
+ ## Examples
34
+
35
+ * [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
36
+
37
+ ## Source
38
+ [scripts/cmake/vcpkg\_execute\_build\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_execute_in_download_mode.md ADDED
@@ -0,0 +1,21 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_execute_in_download_mode
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_execute_in_download_mode.md).
4
+
5
+ Execute a process even in download mode.
6
+
7
+ ## Usage
8
+ ```cmake
9
+ vcpkg_execute_in_download_mode(
10
+ ...
11
+ )
12
+ ```
13
+
14
+ The signature of this function is identical to `execute_process()`.
15
+
16
+ See [`execute_process()`] for more details.
17
+
18
+ [`execute_process()`]: https://cmake.org/cmake/help/latest/command/execute_process.html
19
+
20
+ ## Source
21
+ [scripts/cmake/vcpkg\_execute\_in\_download\_mode.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_in_download_mode.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_execute_required_process.md ADDED
@@ -0,0 +1,51 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_execute_required_process
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_execute_required_process.md).
4
+
5
+ Execute a process with logging and fail the build if the command fails.
6
+
7
+ ## Usage
8
+ ```cmake
9
+ vcpkg_execute_required_process(
10
+ COMMAND <${PERL}> [<arguments>...]
11
+ WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg>
12
+ LOGNAME <build-${TARGET_TRIPLET}-dbg>
13
+ [TIMEOUT <seconds>]
14
+ [OUTPUT_VARIABLE <var>]
15
+ [ERROR_VARIABLE <var>]
16
+ )
17
+ ```
18
+ ## Parameters
19
+ ### ALLOW_IN_DOWNLOAD_MODE
20
+ Allows the command to execute in Download Mode.
21
+ [See execute_process() override](../../scripts/cmake/execute_process.cmake).
22
+
23
+ ### COMMAND
24
+ The command to be executed, along with its arguments.
25
+
26
+ ### WORKING_DIRECTORY
27
+ The directory to execute the command in.
28
+
29
+ ### LOGNAME
30
+ The prefix to use for the log files.
31
+
32
+ ### TIMEOUT
33
+ Optional timeout after which to terminate the command.
34
+
35
+ ### OUTPUT_VARIABLE
36
+ Optional variable to receive stdout of the command.
37
+
38
+ ### ERROR_VARIABLE
39
+ Optional variable to receive stderr of the command.
40
+
41
+ This should be a unique name for different triplets so that the logs don't conflict when building multiple at once.
42
+
43
+ ## Examples
44
+
45
+ * [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
46
+ * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
47
+ * [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
48
+ * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
49
+
50
+ ## Source
51
+ [scripts/cmake/vcpkg\_execute\_required\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_execute_required_process_repeat.md ADDED
@@ -0,0 +1,19 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_execute_required_process_repeat
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_execute_required_process_repeat.md).
4
+
5
+ Execute a process until the command succeeds, or until the COUNT is reached.
6
+
7
+ ## Usage
8
+ ```cmake
9
+ vcpkg_execute_required_process_repeat(
10
+ COMMAND <cmd> [<arguments>]
11
+ COUNT <num>
12
+ WORKING_DIRECTORY <directory>
13
+ LOGNAME <name>
14
+ [ALLOW_IN_DOWNLOAD_MODE]
15
+ )
16
+ ```
17
+
18
+ ## Source
19
+ [scripts/cmake/vcpkg\_execute\_required\_process\_repeat.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process_repeat.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_extract_source_archive.md ADDED
@@ -0,0 +1,86 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_extract_source_archive
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_extract_source_archive.md).
4
+
5
+ Extract an archive into the source directory.
6
+
7
+ ## Usage
8
+ There are two "overloads" of this function. The first is deprecated:
9
+
10
+ ```cmake
11
+ vcpkg_extract_source_archive(<${ARCHIVE}> [<${TARGET_DIRECTORY}>])
12
+ ```
13
+
14
+ This overload should not be used.
15
+
16
+ The latter is suggested to use for all future `vcpkg_extract_source_archive`s.
17
+
18
+ ```cmake
19
+ vcpkg_extract_source_archive(<out-var>
20
+ ARCHIVE <path>
21
+ [NO_REMOVE_ONE_LEVEL]
22
+ [SKIP_PATCH_CHECK]
23
+ [PATCHES <patch>...]
24
+ [SOURCE_BASE <base>]
25
+ [BASE_DIRECTORY <relative-path> | WORKING_DIRECTORY <absolute-path>]
26
+ )
27
+ ```
28
+
29
+ `vcpkg_extract_source_archive` takes an archive and extracts it.
30
+ It replaces existing uses of `vcpkg_extract_source_archive_ex`.
31
+ The simplest use of it is:
32
+
33
+ ```cmake
34
+ vcpkg_download_distfile(archive ...)
35
+ vcpkg_extract_source_archive(source_path ARCHIVE "${archive}")
36
+ ```
37
+
38
+ The general expectation is that an archives are laid out with a base directory,
39
+ and all the actual files underneath that directory; in other words, if you
40
+ extract the archive, you'll get something that looks like:
41
+
42
+ ```
43
+ zlib-1.2.11/
44
+ doc/
45
+ ...
46
+ examples/
47
+ ...
48
+ ChangeLog
49
+ CMakeLists.txt
50
+ README
51
+ zlib.h
52
+ ...
53
+ ```
54
+
55
+ `vcpkg_extract_source_archive` automatically removes this directory,
56
+ and gives you the items under it directly. However, this only works
57
+ when there is exactly one item in the top level of an archive.
58
+ Otherwise, you'll have to pass the `NO_REMOVE_ONE_LEVEL` argument to
59
+ prevent `vcpkg_extract_source_archive` from performing this transformation.
60
+
61
+ If the source needs to be patched in some way, the `PATCHES` argument
62
+ allows one to do this, just like other `vcpkg_from_*` functions.
63
+ Additionally, the `SKIP_PATCH_CHECK` is provided for `--head` mode -
64
+ this allows patches to fail to apply silently.
65
+ This argument should _only_ be used when installing a `--head` library,
66
+ since otherwise we want a patch failing to appply to be a hard error.
67
+
68
+ `vcpkg_extract_source_archive` extracts the files to
69
+ `${CURRENT_BUILDTREES_DIR}/<base-directory>/<source-base>-<hash>.clean`.
70
+ When in editable mode, no `.clean` is appended,
71
+ to allow for a user to modify the sources.
72
+ `base-directory` defaults to `src`,
73
+ and `source-base` defaults to the stem of `<archive>`.
74
+ You can change these via the `BASE_DIRECTORY` and `SOURCE_BASE` arguments
75
+ respectively.
76
+ If you need to extract to a location that is not based in `CURRENT_BUILDTREES_DIR`,
77
+ you can use the `WORKING_DIRECTORY` argument to do the same.
78
+
79
+ ## Examples
80
+
81
+ * [libraw](https://github.com/Microsoft/vcpkg/blob/master/ports/libraw/portfile.cmake)
82
+ * [protobuf](https://github.com/Microsoft/vcpkg/blob/master/ports/protobuf/portfile.cmake)
83
+ * [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake)
84
+
85
+ ## Source
86
+ [scripts/cmake/vcpkg\_extract\_source\_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_extract_source_archive_ex.md ADDED
@@ -0,0 +1,26 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_extract_source_archive_ex
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_extract_source_archive_ex.md).
4
+
5
+ Extract an archive into the source directory.
6
+ Originally replaced [`vcpkg_extract_source_archive()`],
7
+ but new ports should instead use the second overload of
8
+ [`vcpkg_extract_source_archive()`].
9
+
10
+ ## Usage
11
+ ```cmake
12
+ vcpkg_extract_source_archive_ex(
13
+ [OUT_SOURCE_PATH <source_path>]
14
+ ...
15
+ )
16
+ ```
17
+
18
+ See the documentation for [`vcpkg_extract_source_archive()`] for other parameters.
19
+ Additionally, `vcpkg_extract_source_archive_ex()` adds the `REF` and `WORKING_DIRECTORY`
20
+ parameters, which are wrappers around `SOURCE_BASE` and `BASE_DIRECTORY`
21
+ respectively.
22
+
23
+ [`vcpkg_extract_source_archive()`]: vcpkg_extract_source_archive.md
24
+
25
+ ## Source
26
+ [scripts/cmake/vcpkg\_extract\_source\_archive\_ex.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_fail_port_install.md ADDED
@@ -0,0 +1,45 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_fail_port_install
2
+
3
+ **This function has been deprecated in favor of the `supports` field in [`manifest file`](manifest-files.md#supports) et al.**
4
+
5
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_fail_port_install.md).
6
+
7
+ Checks common requirements and fails the current portfile with a (default) error message
8
+
9
+ ## Usage
10
+ ```cmake
11
+ vcpkg_fail_port_install(
12
+ [ALWAYS]
13
+ [MESSAGE <"Reason for failure">]
14
+ [ON_TARGET <Windows> [<OSX> ...]]
15
+ [ON_ARCH <x64> [<arm> ...]]
16
+ [ON_CRT_LINKAGE <static> [<dynamic> ...]])
17
+ [ON_LIBRARY_LINKAGE <static> [<dynamic> ...]]
18
+ )
19
+ ```
20
+
21
+ ## Parameters
22
+ ### MESSAGE
23
+ Additional failure message. If none is given, a default message will be displayed depending on the failure condition.
24
+
25
+ ### ALWAYS
26
+ Will always fail early
27
+
28
+ ### ON_TARGET
29
+ Targets for which the build should fail early. Valid targets are `<target>` from `VCPKG_IS_TARGET_<target>` (see `vcpkg_common_definitions.cmake`).
30
+
31
+ ### ON_ARCH
32
+ Architecture for which the build should fail early.
33
+
34
+ ### ON_CRT_LINKAGE
35
+ CRT linkage for which the build should fail early.
36
+
37
+ ### ON_LIBRARY_LINKAGE
38
+ Library linkage for which the build should fail early.
39
+
40
+ ## Examples
41
+
42
+ * [aws-lambda-cpp](https://github.com/Microsoft/vcpkg/blob/master/ports/aws-lambda-cpp/portfile.cmake)
43
+
44
+ ## Source
45
+ [scripts/cmake/vcpkg\_fail\_port\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_find_acquire_program.md ADDED
@@ -0,0 +1,51 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_find_acquire_program
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_find_acquire_program.md).
4
+
5
+ Download or find a well-known tool.
6
+
7
+ ## Usage
8
+ ```cmake
9
+ vcpkg_find_acquire_program(<program>)
10
+ ```
11
+ ## Parameters
12
+ ### program
13
+ This variable specifies both the program to be acquired as well as the out parameter that will be set to the path of the program executable.
14
+
15
+ ## Notes
16
+ The current list of programs includes:
17
+
18
+ * 7Z
19
+ * ARIA2 (Downloader)
20
+ * BISON
21
+ * CLANG
22
+ * DARK
23
+ * DOXYGEN
24
+ * FLEX
25
+ * GASPREPROCESSOR
26
+ * GPERF
27
+ * PERL
28
+ * PYTHON2
29
+ * PYTHON3
30
+ * GIT
31
+ * GN
32
+ * GO
33
+ * JOM
34
+ * MESON
35
+ * NASM
36
+ * NINJA
37
+ * NUGET
38
+ * SCONS
39
+ * SWIG
40
+ * YASM
41
+
42
+ Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
43
+
44
+ ## Examples
45
+
46
+ * [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
47
+ * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
48
+ * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
49
+
50
+ ## Source
51
+ [scripts/cmake/vcpkg\_find\_acquire\_program.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_acquire_program.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_find_fortran.md ADDED
@@ -0,0 +1,25 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_find_fortran
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_find_fortran.md).
4
+
5
+ Checks if a Fortran compiler can be found.
6
+ Windows(x86/x64) Only: If not it will switch/enable MinGW gfortran
7
+ and return required cmake args for building.
8
+
9
+ ## Usage
10
+ ```cmake
11
+ vcpkg_find_fortran(<out_var>)
12
+ ```
13
+
14
+ ## Example
15
+ ```cmake
16
+ vcpkg_find_fortran(fortran_args)
17
+ # ...
18
+ vcpkg_cmake_configure(...
19
+ OPTIONS
20
+ ${fortran_args}
21
+ )
22
+ ```
23
+
24
+ ## Source
25
+ [scripts/cmake/vcpkg\_find\_fortran.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_fortran.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_fixup_cmake_targets.md ADDED
@@ -0,0 +1,62 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_fixup_cmake_targets
2
+
3
+ **This function has been deprecated in favor of [`vcpkg_cmake_config_fixup`](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md) from the vcpkg-cmake-config port.**
4
+
5
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_fixup_cmake_targets.md).
6
+
7
+ Merge release and debug CMake targets and configs to support multiconfig generators.
8
+
9
+ Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries.
10
+
11
+ ## Usage
12
+ ```cmake
13
+ vcpkg_fixup_cmake_targets([CONFIG_PATH <share/${PORT}>]
14
+ [TARGET_PATH <share/${PORT}>]
15
+ [TOOLS_PATH <tools/${PORT}>]
16
+ [DO_NOT_DELETE_PARENT_CONFIG_PATH])
17
+ ```
18
+
19
+ ## Parameters
20
+
21
+ ### CONFIG_PATH
22
+ Subpath currently containing `*.cmake` files subdirectory (like `lib/cmake/${PORT}`). Should be relative to `${CURRENT_PACKAGES_DIR}`.
23
+
24
+ Defaults to `share/${PORT}`.
25
+
26
+ ### TARGET_PATH
27
+ Subpath to which the above `*.cmake` files should be moved. Should be relative to `${CURRENT_PACKAGES_DIR}`.
28
+ This needs to be specified if the port name differs from the `find_package()` name.
29
+
30
+ Defaults to `share/${PORT}`.
31
+
32
+ ### DO_NOT_DELETE_PARENT_CONFIG_PATH
33
+ By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
34
+ Passing this option disable such behavior, as it is convenient for ports that install
35
+ more than one CMake package configuration file.
36
+
37
+ ### NO_PREFIX_CORRECTION
38
+ Disables the correction of_IMPORT_PREFIX done by vcpkg due to moving the targets.
39
+ Currently the correction does not take into account how the files are moved and applies
40
+ I rather simply correction which in some cases will yield the wrong results.
41
+
42
+ ### TOOLS_PATH
43
+ Define the base path to tools. Default: `tools/<PORT>`
44
+
45
+ ## Notes
46
+ Transform all `/debug/<CONFIG_PATH>/*targets-debug.cmake` files and move them to `/<TARGET_PATH>`.
47
+ Removes all `/debug/<CONFIG_PATH>/*targets.cmake` and `/debug/<CONFIG_PATH>/*config.cmake`.
48
+
49
+ Transform all references matching `/bin/*.exe` to `/${TOOLS_PATH}/*.exe` on Windows.
50
+ Transform all references matching `/bin/*` to `/${TOOLS_PATH}/*` on other platforms.
51
+
52
+ Fix `${_IMPORT_PREFIX}` in auto generated targets to be one folder deeper.
53
+ Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targets.
54
+
55
+ ## Examples
56
+
57
+ * [concurrentqueue](https://github.com/Microsoft/vcpkg/blob/master/ports/concurrentqueue/portfile.cmake)
58
+ * [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake)
59
+ * [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake)
60
+
61
+ ## Source
62
+ [scripts/cmake/vcpkg\_fixup\_cmake\_targets.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_fixup_pkgconfig.md ADDED
@@ -0,0 +1,49 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_fixup_pkgconfig
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_fixup_pkgconfig.md).
4
+
5
+ Fix common paths in *.pc files and make everything relative to $(prefix).
6
+ Additionally, on static triplets, private entries are merged with their non-private counterparts,
7
+ allowing pkg-config to be called without the ``--static`` flag.
8
+ Note that vcpkg is designed to never have to call pkg-config with the ``--static`` flag,
9
+ since a consumer cannot know if a dependent library has been built statically or not.
10
+
11
+ ## Usage
12
+ ```cmake
13
+ vcpkg_fixup_pkgconfig(
14
+ [RELEASE_FILES <PATHS>...]
15
+ [DEBUG_FILES <PATHS>...]
16
+ [SKIP_CHECK]
17
+ )
18
+ ```
19
+
20
+ ## Parameters
21
+ ### RELEASE_FILES
22
+ Specifies a list of files to apply the fixes for release paths.
23
+ Defaults to every *.pc file in the folder ${CURRENT_PACKAGES_DIR} without ${CURRENT_PACKAGES_DIR}/debug/
24
+
25
+ ### DEBUG_FILES
26
+ Specifies a list of files to apply the fixes for debug paths.
27
+ Defaults to every *.pc file in the folder ${CURRENT_PACKAGES_DIR}/debug/
28
+
29
+ ### SKIP_CHECK
30
+ Skips the library checks in vcpkg_fixup_pkgconfig. Only use if the script itself has unhandled cases.
31
+
32
+ ### SYSTEM_PACKAGES (deprecated)
33
+ This argument has been deprecated and has no effect.
34
+
35
+ ### SYSTEM_LIBRARIES (deprecated)
36
+ This argument has been deprecated and has no effect.
37
+
38
+ ### IGNORE_FLAGS (deprecated)
39
+ This argument has been deprecated and has no effect.
40
+
41
+ ## Notes
42
+ Still work in progress. If there are more cases which can be handled here feel free to add them
43
+
44
+ ## Examples
45
+
46
+ * [brotli](https://github.com/Microsoft/vcpkg/blob/master/ports/brotli/portfile.cmake)
47
+
48
+ ## Source
49
+ [scripts/cmake/vcpkg\_fixup\_pkgconfig.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_pkgconfig.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_bitbucket.md ADDED
@@ -0,0 +1,60 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_from_bitbucket
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_bitbucket.md).
4
+
5
+ Download and extract a project from Bitbucket.
6
+
7
+ ## Usage:
8
+ ```cmake
9
+ vcpkg_from_bitbucket(
10
+ OUT_SOURCE_PATH <SOURCE_PATH>
11
+ REPO <Microsoft/cpprestsdk>
12
+ [REF <v2.0.0>]
13
+ [SHA512 <45d0d7f8cc350...>]
14
+ [HEAD_REF <master>]
15
+ [PATCHES <patch1.patch> <patch2.patch>...]
16
+ )
17
+ ```
18
+
19
+ ## Parameters:
20
+ ### OUT_SOURCE_PATH
21
+ Specifies the out-variable that will contain the extracted location.
22
+
23
+ This should be set to `SOURCE_PATH` by convention.
24
+
25
+ ### REPO
26
+ The organization or user and repository on GitHub.
27
+
28
+ ### REF
29
+ A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**
30
+
31
+ For repositories without official releases, this can be set to the full commit id of the current latest master.
32
+
33
+ If `REF` is specified, `SHA512` must also be specified.
34
+
35
+ ### SHA512
36
+ The SHA512 hash that should match the archive (https://bitbucket.com/${REPO}/get/${REF}.tar.gz).
37
+
38
+ This is most easily determined by first setting it to `0`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
39
+
40
+ ### HEAD_REF
41
+ The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
42
+
43
+ For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
44
+
45
+ ### PATCHES
46
+ A list of patches to be applied to the extracted sources.
47
+
48
+ Relative paths are based on the port directory.
49
+
50
+ ## Notes:
51
+ At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
52
+
53
+ This exports the `VCPKG_HEAD_VERSION` variable during head builds.
54
+
55
+ ## Examples:
56
+
57
+ * [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake)
58
+
59
+ ## Source
60
+ [scripts/cmake/vcpkg\_from\_bitbucket.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_bitbucket.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_git.md ADDED
@@ -0,0 +1,53 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_from_git
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_git.md).
4
+
5
+ Download and extract a project from git
6
+
7
+ ## Usage:
8
+ ```cmake
9
+ vcpkg_from_git(
10
+ OUT_SOURCE_PATH <SOURCE_PATH>
11
+ URL <https://android.googlesource.com/platform/external/fdlibm>
12
+ REF <59f7335e4d...>
13
+ [HEAD_REF <ref>]
14
+ [PATCHES <patch1.patch> <patch2.patch>...]
15
+ )
16
+ ```
17
+
18
+ ## Parameters:
19
+ ### OUT_SOURCE_PATH
20
+ Specifies the out-variable that will contain the extracted location.
21
+
22
+ This should be set to `SOURCE_PATH` by convention.
23
+
24
+ ### URL
25
+ The url of the git repository.
26
+
27
+ ### REF
28
+ The git sha of the commit to download.
29
+
30
+ ### FETCH_REF
31
+ The git branch to fetch in non-HEAD mode. After this is fetched,
32
+ then `REF` is checked out. This is useful in cases where the git server
33
+ does not allow checking out non-advertised objects.
34
+
35
+ ### HEAD_REF
36
+ The git branch to use when the package is requested to be built from the latest sources.
37
+
38
+ Example: `main`, `develop`, `HEAD`
39
+
40
+ ### PATCHES
41
+ A list of patches to be applied to the extracted sources.
42
+
43
+ Relative paths are based on the port directory.
44
+
45
+ ## Notes:
46
+ `OUT_SOURCE_PATH`, `REF`, and `URL` must be specified.
47
+
48
+ ## Examples:
49
+
50
+ * [fdlibm](https://github.com/Microsoft/vcpkg/blob/master/ports/fdlibm/portfile.cmake)
51
+
52
+ ## Source
53
+ [scripts/cmake/vcpkg\_from\_git.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_git.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_github.md ADDED
@@ -0,0 +1,78 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_from_github
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_github.md).
4
+
5
+ Download and extract a project from GitHub. Enables support for `install --head`.
6
+
7
+ This also works with Gitea by specifying the Gitea server with the `GITHUB_HOST` option.
8
+
9
+ ## Usage:
10
+ ```cmake
11
+ vcpkg_from_github(
12
+ OUT_SOURCE_PATH <SOURCE_PATH>
13
+ REPO <Microsoft/cpprestsdk>
14
+ [REF <v2.0.0>]
15
+ [SHA512 <45d0d7f8cc350...>]
16
+ [HEAD_REF <master>]
17
+ [PATCHES <patch1.patch> <patch2.patch>...]
18
+ [GITHUB_HOST <https://github.com>]
19
+ [AUTHORIZATION_TOKEN <${SECRET_FROM_FILE}>]
20
+ [FILE_DISAMBIGUATOR <N>]
21
+ )
22
+ ```
23
+
24
+ ## Parameters:
25
+ ### OUT_SOURCE_PATH
26
+ Specifies the out-variable that will contain the extracted location.
27
+
28
+ This should be set to `SOURCE_PATH` by convention.
29
+
30
+ ### REPO
31
+ The organization or user and repository on GitHub.
32
+
33
+ ### REF
34
+ A stable git commit-ish (ideally a tag or commit) that will not change contents. **This should not be a branch.**
35
+
36
+ For repositories without official releases, this can be set to the full commit id of the current latest master.
37
+
38
+ If `REF` is specified, `SHA512` must also be specified.
39
+
40
+ ### SHA512
41
+ The SHA512 hash that should match the archive (https://github.com/${REPO}/archive/${REF}.tar.gz).
42
+
43
+ This is most easily determined by first setting it to `0`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
44
+
45
+ ### HEAD_REF
46
+ The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
47
+
48
+ For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
49
+
50
+ ### PATCHES
51
+ A list of patches to be applied to the extracted sources.
52
+
53
+ Relative paths are based on the port directory.
54
+
55
+ ### GITHUB_HOST
56
+ A replacement host for enterprise GitHub instances.
57
+
58
+ This field should contain the scheme, host, and port of the desired URL without a trailing slash.
59
+
60
+ ### AUTHORIZATION_TOKEN
61
+ A token to be passed via the Authorization HTTP header as "token ${AUTHORIZATION_TOKEN}".
62
+
63
+ ### FILE_DISAMBIGUATOR
64
+ A token to uniquely identify the resulting filename if the SHA512 changes even though a git ref does not, to avoid stepping on the same file name.
65
+
66
+ ## Notes:
67
+ At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
68
+
69
+ This exports the `VCPKG_HEAD_VERSION` variable during head builds.
70
+
71
+ ## Examples:
72
+
73
+ * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
74
+ * [ms-gsl](https://github.com/Microsoft/vcpkg/blob/master/ports/ms-gsl/portfile.cmake)
75
+ * [boost-beast](https://github.com/Microsoft/vcpkg/blob/master/ports/boost-beast/portfile.cmake)
76
+
77
+ ## Source
78
+ [scripts/cmake/vcpkg\_from\_github.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_github.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_gitlab.md ADDED
@@ -0,0 +1,71 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_from_gitlab
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_gitlab.md).
4
+
5
+ Download and extract a project from Gitlab instances. Enables support for `install --head`.
6
+
7
+ ## Usage:
8
+ ```cmake
9
+ vcpkg_from_gitlab(
10
+ GITLAB_URL <https://gitlab.com>
11
+ OUT_SOURCE_PATH <SOURCE_PATH>
12
+ REPO <gitlab-org/gitlab-ce>
13
+ [REF <v10.7.3>]
14
+ [SHA512 <45d0d7f8cc350...>]
15
+ [HEAD_REF <master>]
16
+ [PATCHES <patch1.patch> <patch2.patch>...]
17
+ [FILE_DISAMBIGUATOR <N>]
18
+ )
19
+ ```
20
+
21
+ ## Parameters:
22
+
23
+ ### GITLAB_URL
24
+ The URL of the Gitlab instance to use.
25
+
26
+ ### OUT_SOURCE_PATH
27
+ Specifies the out-variable that will contain the extracted location.
28
+
29
+ This should be set to `SOURCE_PATH` by convention.
30
+
31
+ ### REPO
32
+ The organization or user plus the repository name on the Gitlab instance.
33
+
34
+ ### REF
35
+ A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**
36
+
37
+ For repositories without official releases, this can be set to the full commit id of the current latest master.
38
+
39
+ If `REF` is specified, `SHA512` must also be specified.
40
+
41
+ ### SHA512
42
+ The SHA512 hash that should match the archive (${GITLAB_URL}/${REPO}/-/archive/${REF}/${REPO_NAME}-${REF}.tar.gz).
43
+ The REPO_NAME variable is parsed from the value of REPO.
44
+
45
+ This is most easily determined by first setting it to `0`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
46
+
47
+ ### HEAD_REF
48
+ The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
49
+
50
+ For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
51
+
52
+ ### PATCHES
53
+ A list of patches to be applied to the extracted sources.
54
+
55
+ Relative paths are based on the port directory.
56
+
57
+ ### FILE_DISAMBIGUATOR
58
+ A token to uniquely identify the resulting filename if the SHA512 changes even though a git ref does not, to avoid stepping on the same file name.
59
+
60
+ ## Notes:
61
+ At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
62
+
63
+ This exports the `VCPKG_HEAD_VERSION` variable during head builds.
64
+
65
+ ## Examples:
66
+ * [curl][https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75]
67
+ * [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
68
+ * [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
69
+
70
+ ## Source
71
+ [scripts/cmake/vcpkg\_from\_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_sourceforge.md ADDED
@@ -0,0 +1,73 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_from_sourceforge
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_sourceforge.md).
4
+
5
+ Download and extract a project from sourceforge.
6
+
7
+ This function automatically checks a set of sourceforge mirrors.
8
+ Additional mirrors can be injected through the `VCPKG_SOURCEFORGE_EXTRA_MIRRORS`
9
+ list variable in the triplet.
10
+
11
+ ## Usage:
12
+ ```cmake
13
+ vcpkg_from_sourceforge(
14
+ OUT_SOURCE_PATH SOURCE_PATH
15
+ REPO <cunit/CUnit>
16
+ [REF <2.1-3>]
17
+ SHA512 <547b417109332...>
18
+ FILENAME <CUnit-2.1-3.tar.bz2>
19
+ [DISABLE_SSL]
20
+ [NO_REMOVE_ONE_LEVEL]
21
+ [PATCHES <patch1.patch> <patch2.patch>...]
22
+ )
23
+ ```
24
+
25
+ ## Parameters:
26
+ ### OUT_SOURCE_PATH
27
+ Specifies the out-variable that will contain the extracted location.
28
+
29
+ This should be set to `SOURCE_PATH` by convention.
30
+
31
+ ### REPO
32
+ The organization or user and repository (optional) on sourceforge.
33
+
34
+ ### REF
35
+ A stable version number that will not change contents.
36
+
37
+ ### FILENAME
38
+ The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.
39
+
40
+ For example, we can get the download link:
41
+ https://sourceforge.net/settings/mirror_choices?projectname=mad&filename=libmad/0.15.1b/libmad-0.15.1b.tar.gz&selected=nchc
42
+ So the REPO is `mad/libmad`, the REF is `0.15.1b`, and the FILENAME is `libmad-0.15.1b.tar.gz`
43
+
44
+ For some special links:
45
+ https://sourceforge.net/settings/mirror_choices?projectname=soxr&filename=soxr-0.1.3-Source.tar.xz&selected=nchc
46
+ The REPO is `soxr`, REF is not exist, and the FILENAME is `soxr-0.1.3-Source.tar.xz`
47
+
48
+ ### SHA512
49
+ The SHA512 hash that should match the archive.
50
+
51
+ This is most easily determined by first setting it to `0`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
52
+
53
+ ### WORKING_DIRECTORY
54
+ If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`.
55
+
56
+ Note that the archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`).
57
+
58
+ ### PATCHES
59
+ A list of patches to be applied to the extracted sources.
60
+
61
+ Relative paths are based on the port directory.
62
+
63
+ ### NO_REMOVE_ONE_LEVEL
64
+ Specifies that the default removal of the top level folder should not occur.
65
+
66
+ ## Examples:
67
+
68
+ * [cunit](https://github.com/Microsoft/vcpkg/blob/master/ports/cunit/portfile.cmake)
69
+ * [polyclipping](https://github.com/Microsoft/vcpkg/blob/master/ports/polyclipping/portfile.cmake)
70
+ * [tinyfiledialogs](https://github.com/Microsoft/vcpkg/blob/master/ports/tinyfiledialogs/portfile.cmake)
71
+
72
+ ## Source
73
+ [scripts/cmake/vcpkg\_from\_sourceforge.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_sourceforge.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_get_program_files_platform_bitness.md ADDED
@@ -0,0 +1,15 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_get_program_files_platform_bitness
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_get_program_files_platform_bitness.md).
4
+
5
+ Get the Program Files directory of the current platform's bitness:
6
+ either `$ENV{ProgramW6432}` on 64-bit windows,
7
+ or `$ENV{PROGRAMFILES}` on 32-bit windows.
8
+
9
+ ## Usage:
10
+ ```cmake
11
+ vcpkg_get_program_files_platform_bitness(<variable>)
12
+ ```
13
+
14
+ ## Source
15
+ [scripts/cmake/vcpkg\_get\_program\_files\_platform\_bitness.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_get_windows_sdk.md ADDED
@@ -0,0 +1,13 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_get_windows_sdk
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_get_windows_sdk.md).
4
+
5
+ Get the Windows SDK number.
6
+
7
+ ## Usage:
8
+ ```cmake
9
+ vcpkg_get_windows_sdk(<variable>)
10
+ ```
11
+
12
+ ## Source
13
+ [scripts/cmake/vcpkg\_get\_windows\_sdk.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_windows_sdk.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_host_path_list.md ADDED
@@ -0,0 +1,29 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_host_path_list
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_host_path_list.md).
4
+
5
+ Modify a host path list variable (PATH, INCLUDE, LIBPATH, etc.)
6
+
7
+ ```cmake
8
+ vcpkg_host_path_list(PREPEND <list-var> [<path>...])
9
+ vcpkg_host_path_list(APPEND <list-var> [<path>...])
10
+ vcpkg_host_path_list(SET <list-var> [<path>...])
11
+ ```
12
+
13
+ `<list-var>` may be either a regular variable name, or `ENV{variable-name}`,
14
+ in which case `vcpkg_host_path_list` will modify the environment.
15
+
16
+ `vcpkg_host_path_list` adds all of the paths passed to it to `<list-var>`;
17
+ `PREPEND` puts them before the existing list, so that they are searched first;
18
+ `APPEND` places them after the existing list,
19
+ so they would be searched after the paths which are already in the variable,
20
+ and `SET` replaces the value of the existing list.
21
+
22
+ For all of `APPEND`, `PREPEND`, and `SET`,
23
+ the paths are added (and thus searched) in the order received.
24
+
25
+ If no paths are passed to `APPEND` or `PREPEND`, nothing will be done;
26
+ for `SET`, the variable will be set to the empty string.
27
+
28
+ ## Source
29
+ [scripts/cmake/vcpkg\_host\_path\_list.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_host_path_list.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_cmake.md ADDED
@@ -0,0 +1,29 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_install_cmake
2
+
3
+ **This function has been deprecated in favor of [`vcpkg_cmake_install`](ports/vcpkg-cmake/vcpkg_cmake_install.md) from the vcpkg-cmake port.**
4
+
5
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_cmake.md).
6
+
7
+ Build and install a cmake project.
8
+
9
+ ## Usage:
10
+ ```cmake
11
+ vcpkg_install_cmake(...)
12
+ ```
13
+
14
+ ## Parameters:
15
+ See [`vcpkg_build_cmake()`](vcpkg_build_cmake.md).
16
+
17
+ ## Notes:
18
+ This command transparently forwards to [`vcpkg_build_cmake()`](vcpkg_build_cmake.md), adding a `TARGET install`
19
+ parameter.
20
+
21
+ ## Examples:
22
+
23
+ * [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
24
+ * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
25
+ * [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
26
+ * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
27
+
28
+ ## Source
29
+ [scripts/cmake/vcpkg\_install\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_cmake.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_gn.md ADDED
@@ -0,0 +1,31 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_install_gn
2
+
3
+ **This function has been deprecated in favor of [`vcpkg_gn_install`](ports/vcpkg-gn/vcpkg_gn_install.md) from the vcpkg-gn port.**
4
+
5
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_gn.md).
6
+
7
+ Installs a GN project.
8
+
9
+ In order to build a GN project without installing, use [`vcpkg_build_ninja()`].
10
+
11
+ ## Usage:
12
+ ```cmake
13
+ vcpkg_install_gn(
14
+ SOURCE_PATH <SOURCE_PATH>
15
+ [TARGETS <target>...]
16
+ )
17
+ ```
18
+
19
+ ## Parameters:
20
+ ### SOURCE_PATH
21
+ The path to the source directory
22
+
23
+ ### TARGETS
24
+ Only install the specified targets.
25
+
26
+ Note: includes must be handled separately
27
+
28
+ [`vcpkg_build_ninja()`]: vcpkg_build_ninja.md
29
+
30
+ ## Source
31
+ [scripts/cmake/vcpkg\_install\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_gn.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_make.md ADDED
@@ -0,0 +1,26 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_install_make
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_make.md).
4
+
5
+ Build and install a make project.
6
+
7
+ ## Usage:
8
+ ```cmake
9
+ vcpkg_install_make(...)
10
+ ```
11
+
12
+ ## Parameters:
13
+ See [`vcpkg_build_make()`](vcpkg_build_make.md).
14
+
15
+ ## Notes:
16
+ This command transparently forwards to [`vcpkg_build_make()`](vcpkg_build_make.md), adding `ENABLE_INSTALL`
17
+
18
+ ## Examples
19
+
20
+ * [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake)
21
+ * [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
22
+ * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
23
+ * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
24
+
25
+ ## Source
26
+ [scripts/cmake/vcpkg\_install\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_make.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_meson.md ADDED
@@ -0,0 +1,22 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_install_meson
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_meson.md).
4
+
5
+ Builds a meson project previously configured with `vcpkg_configure_meson()`.
6
+
7
+ ## Usage
8
+ ```cmake
9
+ vcpkg_install_meson([ADD_BIN_TO_PATH])
10
+ ```
11
+
12
+ ## Parameters:
13
+ ### ADD_BIN_TO_PATH
14
+ Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs.
15
+
16
+ ## Examples
17
+
18
+ * [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake)
19
+ * [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
20
+
21
+ ## Source
22
+ [scripts/cmake/vcpkg\_install\_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_meson.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_msbuild.md ADDED
@@ -0,0 +1,95 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_install_msbuild
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_msbuild.md).
4
+
5
+ Build and install a msbuild-based project. This replaces `vcpkg_build_msbuild()`.
6
+
7
+ ## Usage
8
+ ```cmake
9
+ vcpkg_install_msbuild(
10
+ SOURCE_PATH <${SOURCE_PATH}>
11
+ PROJECT_SUBPATH <port.sln>
12
+ [INCLUDES_SUBPATH <include>]
13
+ [LICENSE_SUBPATH <LICENSE>]
14
+ [RELEASE_CONFIGURATION <Release>]
15
+ [DEBUG_CONFIGURATION <Debug>]
16
+ [TARGET <Build>]
17
+ [TARGET_PLATFORM_VERSION <10.0.15063.0>]
18
+ [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
19
+ [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
20
+ [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
21
+ [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
22
+ [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
23
+ [USE_VCPKG_INTEGRATION]
24
+ [ALLOW_ROOT_INCLUDES | REMOVE_ROOT_INCLUDES]
25
+ )
26
+ ```
27
+
28
+ ## Parameters
29
+ ### SOURCE_PATH
30
+ The path to the root of the source tree.
31
+
32
+ Because MSBuild uses in-source builds, the source tree will be copied into a temporary location for the build. This
33
+ parameter is the base for that copy and forms the base for all XYZ_SUBPATH options.
34
+
35
+ ### USE_VCPKG_INTEGRATION
36
+ Apply the normal `integrate install` integration for building the project.
37
+
38
+ By default, projects built with this command will not automatically link libraries or have header paths set.
39
+
40
+ ### PROJECT_SUBPATH
41
+ The subpath to the solution (`.sln`) or project (`.vcxproj`) file relative to `SOURCE_PATH`.
42
+
43
+ ### LICENSE_SUBPATH
44
+ The subpath to the license file relative to `SOURCE_PATH`.
45
+
46
+ ### INCLUDES_SUBPATH
47
+ The subpath to the includes directory relative to `SOURCE_PATH`.
48
+
49
+ This parameter should be a directory and should not end in a trailing slash.
50
+
51
+ ### ALLOW_ROOT_INCLUDES
52
+ Indicates that top-level include files (e.g. `include/zlib.h`) should be allowed.
53
+
54
+ ### REMOVE_ROOT_INCLUDES
55
+ Indicates that top-level include files (e.g. `include/Makefile.am`) should be removed.
56
+
57
+ ### SKIP_CLEAN
58
+ Indicates that the intermediate files should not be removed.
59
+
60
+ Ports using this option should later call [`vcpkg_clean_msbuild()`](vcpkg_clean_msbuild.md) to manually clean up.
61
+
62
+ ### RELEASE_CONFIGURATION
63
+ The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
64
+
65
+ ### DEBUG_CONFIGURATION
66
+ The configuration (``/p:Configuration`` msbuild parameter) used for Debug builds.
67
+
68
+ ### TARGET_PLATFORM_VERSION
69
+ The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
70
+
71
+ ### TARGET
72
+ The MSBuild target to build. (``/t:<TARGET>``)
73
+
74
+ ### PLATFORM
75
+ The platform (``/p:Platform`` msbuild parameter) used for the build.
76
+
77
+ ### PLATFORM_TOOLSET
78
+ The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build.
79
+
80
+ ### OPTIONS
81
+ Additional options passed to msbuild for all builds.
82
+
83
+ ### OPTIONS_RELEASE
84
+ Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`.
85
+
86
+ ### OPTIONS_DEBUG
87
+ Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`.
88
+
89
+ ## Examples
90
+
91
+ * [libirecovery](https://github.com/Microsoft/vcpkg/blob/master/ports/libirecovery/portfile.cmake)
92
+ * [libfabric](https://github.com/Microsoft/vcpkg/blob/master/ports/libfabric/portfile.cmake)
93
+
94
+ ## Source
95
+ [scripts/cmake/vcpkg\_install\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_msbuild.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_nmake.md ADDED
@@ -0,0 +1,68 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_install_nmake
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_nmake.md).
4
+
5
+ Build and install a msvc makefile project.
6
+
7
+ ## Usage:
8
+ ```cmake
9
+ vcpkg_install_nmake(
10
+ SOURCE_PATH <${SOURCE_PATH}>
11
+ [NO_DEBUG]
12
+ [TARGET <all>]
13
+ PROJECT_SUBPATH <${SUBPATH}>
14
+ PROJECT_NAME <${MAKEFILE_NAME}>
15
+ [PRERUN_SHELL <${SHELL_PATH}>]
16
+ [PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
17
+ [PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
18
+ [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
19
+ [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
20
+ [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
21
+ ```
22
+
23
+ ## Parameters
24
+ ### SOURCE_PATH
25
+ Specifies the directory containing the source files.
26
+ By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
27
+
28
+ ### PROJECT_SUBPATH
29
+ Specifies the sub directory containing the `makefile.vc`/`makefile.mak`/`makefile.msvc` or other msvc makefile.
30
+
31
+ ### PROJECT_NAME
32
+ Specifies the name of msvc makefile name.
33
+ Default is makefile.vc
34
+
35
+ ### NO_DEBUG
36
+ This port doesn't support debug mode.
37
+
38
+ ### PRERUN_SHELL
39
+ Script that needs to be called before build
40
+
41
+ ### PRERUN_SHELL_DEBUG
42
+ Script that needs to be called before debug build
43
+
44
+ ### PRERUN_SHELL_RELEASE
45
+ Script that needs to be called before release build
46
+
47
+ ### OPTIONS
48
+ Additional options passed to generate during the generation.
49
+
50
+ ### OPTIONS_RELEASE
51
+ Additional options passed to generate during the Release generation. These are in addition to `OPTIONS`.
52
+
53
+ ### OPTIONS_DEBUG
54
+ Additional options passed to generate during the Debug generation. These are in addition to `OPTIONS`.
55
+
56
+ ## Parameters:
57
+ See [`vcpkg_build_nmake()`](vcpkg_build_nmake.md).
58
+
59
+ ## Notes:
60
+ This command transparently forwards to [`vcpkg_build_nmake()`](vcpkg_build_nmake.md), adding `ENABLE_INSTALL`
61
+
62
+ ## Examples
63
+
64
+ * [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
65
+ * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
66
+
67
+ ## Source
68
+ [scripts/cmake/vcpkg\_install\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_nmake.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_qmake.md ADDED
@@ -0,0 +1,26 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_install_qmake
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_qmake.md).
4
+
5
+ Build and install a qmake project.
6
+
7
+ ## Usage:
8
+ ```cmake
9
+ vcpkg_install_qmake(...)
10
+ ```
11
+
12
+ ## Parameters:
13
+ See [`vcpkg_build_qmake()`](vcpkg_build_qmake.md).
14
+
15
+ ## Notes:
16
+ This command transparently forwards to [`vcpkg_build_qmake()`](vcpkg_build_qmake.md).
17
+
18
+ Additionally, this command will copy produced .libs/.dlls/.as/.dylibs/.sos to the appropriate
19
+ staging directories.
20
+
21
+ ## Examples
22
+
23
+ * [libqglviewer](https://github.com/Microsoft/vcpkg/blob/master/ports/libqglviewer/portfile.cmake)
24
+
25
+ ## Source
26
+ [scripts/cmake/vcpkg\_install\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_qmake.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_list.md ADDED
@@ -0,0 +1,94 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_list
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_list.md).
4
+
5
+ A replacement for CMake's `list()` function, which correctly handles elements
6
+ with internal semicolons (in other words, escaped semicolons).
7
+ Use `vcpkg_list()` instead of `list()` whenever possible.
8
+
9
+ ```cmake
10
+ vcpkg_list(SET <out-var> [<element>...])
11
+ vcpkg_list(<COMMAND> <list-var> [<other-arguments>...])
12
+ ```
13
+
14
+ In addition to all of the commands from `list()`, `vcpkg_list` adds
15
+ a `vcpkg_list(SET)` command.
16
+ This command takes its arguments, escapes them, and then concatenates
17
+ them into a list; this should be used instead of `set()` for setting any
18
+ list variable.
19
+
20
+ Otherwise, the `vcpkg_list()` function is the same as the built-in
21
+ `list()` function, with the following restrictions:
22
+
23
+ - `GET`, `REMOVE_ITEM`, and `REMOVE_AT` support only one index/value
24
+ - `POP_BACK` and `POP_FRONT` do not support getting the value into
25
+ another out variable. Use C++ style `GET` then `POP_(BACK|FRONT)`.
26
+ - `FILTER` and `TRANSFORM` are unsupported.
27
+
28
+ See the [CMake documentation for `list()`](https://cmake.org/cmake/help/latest/command/list.html)
29
+ for more information.
30
+
31
+ ## Notes: Some Weirdnesses
32
+
33
+ The most major weirdness is due to `""` pulling double-duty as "list of zero elements",
34
+ and "list of one element, which is empty". `vcpkg_list` always uses the former understanding.
35
+ This can cause weird behavior, for example:
36
+
37
+ ```cmake
38
+ set(lst "")
39
+ vcpkg_list(APPEND lst "" "")
40
+ # lst = ";"
41
+ ```
42
+
43
+ This is because you're appending two elements to the empty list.
44
+ One very weird behavior that comes out of this would be:
45
+
46
+ ```cmake
47
+ set(lst "")
48
+ vcpkg_list(APPEND lst "")
49
+ # lst = ""
50
+ ```
51
+
52
+ since `""` is the empty list, we append the empty element and end up with a list
53
+ of one element, which is empty. This does not happen for non-empty lists;
54
+ for example:
55
+
56
+ ```cmake
57
+ set(lst "a")
58
+ vcpkg_list(APPEND lst "")
59
+ # lst = "a;"
60
+ ```
61
+
62
+ only the empty list has this odd behavior.
63
+
64
+ ## Examples
65
+
66
+ ### Creating a list
67
+
68
+ ```cmake
69
+ vcpkg_list(SET foo_param)
70
+ if(DEFINED arg_FOO)
71
+ vcpkg_list(SET foo_param FOO "${arg_FOO}")
72
+ endif()
73
+ ```
74
+
75
+ ### Appending to a list
76
+
77
+ ```cmake
78
+ set(OPTIONS -DFOO=BAR)
79
+ if(VCPKG_TARGET_IS_WINDOWS)
80
+ vcpkg_list(APPEND OPTIONS "-DOS=WINDOWS;FOO")
81
+ endif()
82
+ ```
83
+
84
+ ### Popping the end off a list
85
+
86
+ ```cmake
87
+ if(NOT list STREQUAL "")
88
+ vcpkg_list(GET list end -1)
89
+ vcpkg_list(POP_BACK list)
90
+ endif()
91
+ ```
92
+
93
+ ## Source
94
+ [scripts/cmake/vcpkg\_list.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_list.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_minimum_required.md ADDED
@@ -0,0 +1,17 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_minimum_required
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_minimum_required.md).
4
+
5
+ Asserts that the version of the vcpkg program being used to build a port is later than the supplied date, inclusive.
6
+
7
+ ## Usage
8
+ ```cmake
9
+ vcpkg_minimum_required(VERSION 2021-01-13)
10
+ ```
11
+
12
+ ## Parameters
13
+ ### VERSION
14
+ The date-version to check against.
15
+
16
+ ## Source
17
+ [scripts/cmake/vcpkg\_minimum\_required.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_minimum_required.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_replace_string.md ADDED
@@ -0,0 +1,12 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vcpkg_replace_string
2
+
3
+ The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_replace_string.md).
4
+
5
+ Replace a string in a file.
6
+
7
+ ```cmake
8
+ vcpkg_replace_string(<filename> <match> <replace>)
9
+ ```
10
+
11
+ ## Source
12
+ [scripts/cmake/vcpkg\_replace\_string.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_replace_string.cmake)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/regenerate.ps1 ADDED
@@ -0,0 +1,353 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #! /usr/bin/env pwsh
2
+
3
+ [CmdletBinding()]
4
+ Param(
5
+ [String]$VcpkgRoot = ''
6
+ )
7
+
8
+ if ([String]::IsNullOrEmpty($VcpkgRoot)) {
9
+ $VcpkgRoot = "${PSScriptRoot}/.."
10
+ }
11
+
12
+ $VcpkgRoot = Resolve-Path $VcpkgRoot
13
+
14
+ if (-not (Test-Path "$VcpkgRoot/.vcpkg-root")) {
15
+ throw "Invalid vcpkg instance, did you forget -VcpkgRoot?"
16
+ }
17
+
18
+ class CMakeDocumentation {
19
+ [String]$Filename
20
+ [String[]]$ActualDocumentation
21
+ [Bool]$IsDeprecated
22
+ [String]$DeprecationMessage
23
+ [String]$DeprecatedByName
24
+ [String]$DeprecatedByPath
25
+ [Bool]$HasError
26
+ }
27
+
28
+ [String[]]$cmakeScriptsPorts = @(
29
+ 'vcpkg-cmake'
30
+ 'vcpkg-cmake-config'
31
+ 'vcpkg-pkgconfig-get-modules'
32
+ )
33
+
34
+ [CMakeDocumentation[]]$tableOfContents = @()
35
+ [CMakeDocumentation[]]$internalTableOfContents = @()
36
+ $portTableOfContents = [ordered]@{}
37
+
38
+ function RelativeUnixPathTo
39
+ {
40
+ Param(
41
+ [Parameter(Mandatory)]
42
+ [String]$Path,
43
+ [Parameter(Mandatory)]
44
+ [String]$Base
45
+ )
46
+
47
+ $Path = Resolve-Path -LiteralPath $Path
48
+ $Base = Resolve-Path -LiteralPath $Base
49
+
50
+ if ($IsWindows)
51
+ {
52
+ if ((Split-Path -Qualifier $Path) -ne (Split-Path -Qualifier $Base))
53
+ {
54
+ throw "It is not possible to get the relative unix path from $Base to $Path"
55
+ }
56
+ }
57
+
58
+ $Path = $Path -replace '\\','/'
59
+ $Base = $Base -replace '\\','/'
60
+
61
+ [String[]]$PathArray = $Path -split '/'
62
+ [String[]]$BaseArray = $Base -split '/'
63
+
64
+ [String[]]$Result = @()
65
+
66
+ $Idx = 0
67
+
68
+ while ($Idx -lt $PathArray.Length -and $Idx -lt $BaseArray.Length)
69
+ {
70
+ if ($PathArray[$Idx] -ne $BaseArray[$Idx])
71
+ {
72
+ break
73
+ }
74
+ ++$Idx
75
+ }
76
+
77
+ for ($BaseIdx = $Idx; $BaseIdx -lt $BaseArray.Length; ++$BaseIdx)
78
+ {
79
+ $Result += '..'
80
+ }
81
+ for ($PathIdx = $Idx; $PathIdx -lt $PathArray.Length; ++$PathIdx)
82
+ {
83
+ $Result += $PathArray[$PathIdx]
84
+ }
85
+
86
+ $Result -join '/'
87
+ }
88
+ function WriteFile
89
+ {
90
+ Param(
91
+ [String[]]$Value,
92
+ [String]$Path
93
+ )
94
+ # note that we use this method of getting the utf-8 bytes in order to:
95
+ # - have no final `r`n, which happens when Set-Content does the thing automatically on Windows
96
+ # - have no BOM, which happens when one uses [System.Text.Encoding]::UTF8
97
+ [byte[]]$ValueAsBytes = (New-Object -TypeName 'System.Text.UTF8Encoding').GetBytes($Value -join "`n")
98
+ Set-Content -Path $Path -Value $ValueAsBytes -AsByteStream
99
+ }
100
+ function FinalDocFile
101
+ {
102
+ Param(
103
+ [CMakeDocumentation]$Docs,
104
+ [String]$PathToFile # something like docs/maintainers/blah.md
105
+ )
106
+ [String[]]$documentation = @()
107
+
108
+ if ($Docs.ActualDocumentation.Length -eq 0)
109
+ {
110
+ throw "Invalid documentation: empty docs"
111
+ }
112
+
113
+ $documentation += $Docs.ActualDocumentation[0] # name line
114
+ if ($Docs.IsDeprecated)
115
+ {
116
+ if ($null -eq $Docs.DeprecationMessage -or $Docs.DeprecationMessage -match '^ *$')
117
+ {
118
+ if(![string]::IsNullOrEmpty($Docs.DeprecatedByName))
119
+ {
120
+ $message = " in favor of [``$($Docs.DeprecatedByName)``]($($Docs.DeprecatedByPath)$($Docs.DeprecatedByName).md)"
121
+ $Docs.DeprecatedByPath -match '^ports/([a-z\-]+)/$' | Out-Null
122
+ $port = $matches[1]
123
+ if(![string]::IsNullOrEmpty($port))
124
+ {
125
+ $message += " from the $port port."
126
+ }
127
+ }
128
+ $documentation += @("", "**This function has been deprecated$message**")
129
+ }
130
+ else
131
+ {
132
+ $documentation += @("", "**This function has been deprecated $($Docs.DeprecationMessage)**")
133
+ }
134
+ }
135
+ $documentation += @("", "The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/$PathToFile).")
136
+
137
+ $documentation += $Docs.ActualDocumentation[1..$Docs.ActualDocumentation.Length]
138
+
139
+ $relativePath = RelativeUnixPathTo $Docs.Filename $VcpkgRoot
140
+ $documentation += @(
141
+ "",
142
+ "## Source",
143
+ "[$($relativePath -replace '_','\_')](https://github.com/Microsoft/vcpkg/blob/master/$relativePath)",
144
+ ""
145
+ )
146
+
147
+ $documentation
148
+ }
149
+
150
+ function ParseCmakeDocComment
151
+ {
152
+ Param(
153
+ [Parameter(Mandatory)]
154
+ [System.IO.FileSystemInfo]$Filename
155
+ )
156
+
157
+ $Docs = New-Object 'CMakeDocumentation'
158
+ $Docs.HasError = $False
159
+ $Docs.IsDeprecated = $False
160
+ $Docs.Filename = $Filename.FullName
161
+
162
+ [String[]]$contents = Get-Content $Filename
163
+
164
+ if ($contents[0] -eq '# DEPRECATED')
165
+ {
166
+ $Docs.IsDeprecated = $True
167
+ }
168
+ elseif($contents[0] -match '^# DEPRECATED( BY (([^/]+/)+)(.+))?((: *)(.*))?$')
169
+ {
170
+ $Docs.IsDeprecated = $True
171
+ $Docs.DeprecatedByPath = $matches[2]
172
+ $Docs.DeprecatedByName = $matches[4]
173
+ $Docs.DeprecationMessage = $matches[7]
174
+ }
175
+
176
+ [String]$startCommentRegex = '#\[(=*)\['
177
+ [String]$endCommentRegex = ''
178
+ [Bool]$inComment = $False
179
+
180
+ $contents = $contents | ForEach-Object {
181
+ if (-not $inComment) {
182
+ if ($_ -match "^\s*${startCommentRegex}(\.[a-z]*)?:?\s*$") {
183
+ if (-not [String]::IsNullOrEmpty($matches[2]) -and $matches[2] -ne '.md') {
184
+ Write-Warning "The documentation in $($Filename.FullName) doesn't seem to be markdown (extension: $($matches[2])). Only markdown is supported; please rewrite the documentation in markdown."
185
+ }
186
+ $inComment = $True
187
+ $endCommentRegex = "\]$($matches[1])\]"
188
+ } elseif ($_ -match $startCommentRegex) {
189
+ $Docs.HasError = $True
190
+ Write-Warning "Invalid start of comment -- the comment start must be at the beginning of the line.
191
+ (on line: `"$_`")"
192
+ } else {
193
+ # do nothing -- we're outside a comment, so cmake code
194
+ }
195
+ } else {
196
+ if ($_ -match "^\s*#?${endCommentRegex}\s*$") {
197
+ $inComment = $False
198
+ $endCommentRegex = ''
199
+ } elseif ($_ -match $endCommentRegex) {
200
+ $Docs.HasError = $True
201
+ Write-Warning "Invalid end of comment -- the comment end must be on it's own on a line.
202
+ (on line: `"$_`")"
203
+ } else {
204
+ # regular documentation line
205
+ $_
206
+ }
207
+ }
208
+ }
209
+
210
+ if ($inComment) {
211
+ Write-Warning "File $($Filename.FullName) has an unclosed comment."
212
+ $Docs.HasError = $True
213
+ }
214
+
215
+ if (-not [String]::IsNullOrEmpty($contents))
216
+ {
217
+ $Docs.ActualDocumentation = $contents
218
+ }
219
+
220
+ $Docs
221
+ }
222
+
223
+ Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
224
+ $docs = ParseCmakeDocComment $_
225
+ [Bool]$isInternalFunction = $_.Name.StartsWith("z_vcpkg")
226
+
227
+ if ($docs.IsDeprecated -and $null -eq $docs.ActualDocumentation)
228
+ {
229
+ return
230
+ }
231
+ if ($docs.HasError)
232
+ {
233
+ return
234
+ }
235
+
236
+ if ($null -ne $docs.ActualDocumentation)
237
+ {
238
+ if ($isInternalFunction)
239
+ {
240
+ $pathToFile = "maintainers/internal/$($_.BaseName).md"
241
+ WriteFile `
242
+ -Path "$PSScriptRoot/$pathToFile" `
243
+ -Value (FinalDocFile $docs)
244
+
245
+ $internalTableOfContents += $docs
246
+ }
247
+ else
248
+ {
249
+ $pathToFile = "maintainers/$($_.BaseName).md"
250
+ WriteFile `
251
+ -Path "$PSScriptRoot/$pathToFile" `
252
+ -Value (FinalDocFile $docs $pathToFile)
253
+
254
+ $tableOfContents += $docs
255
+ }
256
+ }
257
+ elseif (-not $isInternalFunction)
258
+ {
259
+ # don't worry about undocumented internal functions
260
+ Write-Warning "The cmake function in file $($_.FullName) doesn't seem to have any documentation. Make sure the documentation comments are correctly written."
261
+ }
262
+ }
263
+
264
+ $cmakeScriptsPorts | ForEach-Object {
265
+ $portName = $_
266
+
267
+ Copy-Item "$VcpkgRoot/ports/$portName/README.md" "$PSScriptRoot/maintainers/ports/$portName.md"
268
+ New-Item -Path "$PSScriptRoot/maintainers/ports/$portName" -Force -ItemType 'Directory' | Out-Null
269
+
270
+ $portTableOfContents[$portName] = @()
271
+
272
+ Get-ChildItem "$VcpkgRoot/ports/$portName" -Filter '*.cmake' | ForEach-Object {
273
+ if ($_.Name -eq 'vcpkg-port-config.cmake' -or $_.Name -eq 'portfile.cmake')
274
+ {
275
+ return
276
+ }
277
+
278
+ $docs = ParseCmakeDocComment $_
279
+
280
+ if ($docs.IsDeprecated -and $null -eq $docs.ActualDocumentation)
281
+ {
282
+ return
283
+ }
284
+ if ($docs.HasError)
285
+ {
286
+ return
287
+ }
288
+
289
+ if ($null -ne $docs.ActualDocumentation)
290
+ {
291
+ $pathToFile = "maintainers/ports/$portName/$($_.BaseName).md"
292
+ WriteFile `
293
+ -Path "$PSScriptRoot/$pathToFile" `
294
+ -Value (FinalDocFile $docs $pathToFile)
295
+ $portTableOfContents[$portName] += $docs
296
+ }
297
+ else
298
+ {
299
+ Write-Warning "The cmake function in file $($_.FullName) doesn't seem to have any documentation. Make sure the documentation comments are correctly written."
300
+ }
301
+ }
302
+ }
303
+
304
+ $portfileFunctionsContent = @(
305
+ '<!-- Run regenerate.ps1 to extract scripts documentation -->',
306
+ '',
307
+ '# Portfile helper functions')
308
+
309
+ function GetDeprecationMessage
310
+ {
311
+ Param(
312
+ [CMakeDocumentation]$Doc
313
+ )
314
+ $message = ''
315
+ if ($Doc.IsDeprecated)
316
+ {
317
+ $message = " (deprecated"
318
+ if(![string]::IsNullOrEmpty($Doc.DeprecatedByName))
319
+ {
320
+ $message += ", use [$($($Doc.DeprecatedByName) -replace '_','\_')]($($Doc.DeprecatedByPath)$($Doc.DeprecatedByName).md)"
321
+ }
322
+ $message += ")"
323
+ }
324
+ $message
325
+ }
326
+
327
+ $DocsName = @{ expression = { Split-Path -LeafBase $_.Filename } }
328
+ $tableOfContents | Sort-Object -Property $DocsName -Culture '' | ForEach-Object {
329
+ $name = Split-Path -LeafBase $_.Filename
330
+ $portfileFunctionsContent += "- [$($name -replace '_','\_')]($name.md)" + $(GetDeprecationMessage $_)
331
+ }
332
+ $portfileFunctionsContent += @("", "## Internal Functions", "")
333
+ $internalTableOfContents | Sort-Object -Property $DocsName -Culture '' | ForEach-Object {
334
+ $name = Split-Path -LeafBase $_.Filename
335
+ $portfileFunctionsContent += "- [$($name -replace '_','\_')](internal/$name.md)" + $(GetDeprecationMessage $_)
336
+ }
337
+
338
+ $portfileFunctionsContent += @("", "## Scripts from Ports")
339
+ $portTableOfContents.GetEnumerator() | ForEach-Object {
340
+ $portName = $_.Name
341
+ $cmakeDocs = $_.Value
342
+ $portfileFunctionsContent += @("", "### [$portName](ports/$portName.md)", "")
343
+ $cmakeDocs | ForEach-Object {
344
+ $name = Split-Path -LeafBase $_.Filename
345
+ $portfileFunctionsContent += "- [$($name -replace '_','\_')](ports/$portName/$name.md)" + $(GetDeprecationMessage $_)
346
+ }
347
+ }
348
+
349
+ $portfileFunctionsContent += "" # final newline
350
+
351
+ WriteFile `
352
+ -Path "$PSScriptRoot/maintainers/portfile-functions.md" `
353
+ -Value $portfileFunctionsContent
third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/binarycaching.md ADDED
@@ -0,0 +1,159 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Binary Caching v1.1 (Jul 14, 2020)
2
+
3
+ **Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
4
+
5
+ **Up-to-date documentation is available at [Binarycaching](../users/binarycaching.md).**
6
+
7
+ ## Motivation
8
+
9
+ The primary motivation of binary caching is to accelerate two broad scenarios in an easily accessible way
10
+
11
+ - Continuous Integration
12
+
13
+ - Developer Environment Changes (first-time or branch change)
14
+
15
+ We generally believe both of these scenarios are addressed with the same feature set, however when differences arise they will be discussed in the individual scenarios.
16
+
17
+ It should also be explicitly noted that this specification does not intend to propose a "Microsoft Sanctioned Public Binaries Service" such as nuget.org – we only intend to enable users to leverage services they already have access to, such as GitHub, local file shares, Azure Artifacts, etc.
18
+
19
+ ## Key User Stories
20
+
21
+ ### CI -> CI
22
+
23
+ In this story, a CI build using either persistent or non-persistent machines wants to potentially reuse binaries built in a previous run of the pipeline. This is partially covered by the Cache tasks in GitHub Actions or Azure DevOps Pipelines, however the Cache task is all-or-nothing: a single package change will prevent restoration and require rebuilding the entire graph which is unacceptable in many scenarios (such as if actively developing one of the packages).
24
+
25
+ ### CI -> Developer
26
+
27
+ In this story, the developer wants to reuse binaries built during a CI run. Given appropriate CI coverage, most developers will always have any needed dependencies pre-built by the CI system.
28
+
29
+ Notably, this scenario indicates a need for Read/Write access granularity on the remote storage solution. Developers should not need write access to the output from the CI system for security reasons.
30
+
31
+ ### Single Developer (same machine reuse)
32
+
33
+ With the introduction of manifest files, each project will have separate instances of Vcpkg. The performance costs of rebuilding binaries across each cloned project can be debilitating for those working in micro-repos or open source; for the monolithic enterprise developer it is simply frustrating.
34
+
35
+ User-wide binary caching alleviates the pain of this scenario by ensuring the same binaries aren’t built multiple times (as long as the projects truly overlap with respect to versions/packages/etc).
36
+
37
+ ### Developer <-> Developer (multi-machine / team scenario)
38
+
39
+ In a small team scenario, it's reasonable that multiple developer machines can trust each other enough to share binaries. This also applies to developers that have multiple machines and wish to share binaries between them (given a similar enough environment).
40
+
41
+ ## Solution Aspects
42
+
43
+ ### Tracking Compilers
44
+
45
+ In order to provide reliable binary caching, vcpkg must determine if the produced binaries are appropriate for the current context. Currently, we consider many factors, including:
46
+
47
+ - All files in the port directory
48
+
49
+ - The toolchain file contents
50
+
51
+ - The triplet contents
52
+
53
+ - All dependency binaries
54
+
55
+ - The version of the CMake tool used to build
56
+
57
+ and a few others.
58
+
59
+ However, we notably do not currently track the compiler used. This is critical for all cross-machine scenarios, as the environment is likely to change incompatibly from machine to machine. We propose hashing the compiler that will used by CMake. This can be accomplished either by reimplementing the logic of CMake or running some partial project and extracting the results. For performance reasons, we will prefer first using heuristics to approximate the CMake logic with accompanying documentation for users that fall outside those bounds.
60
+
61
+ Another aspect of the environment we don't currently track is the CRT version on Linux systems. Currently, we believe this will not cause as many problems in most practices (thus not suitable for an MVP), since the compiler will (generally) link against the system CRT and should sufficiently reflect any differences. This can also be easily worked around by the user with documentation – the toolchain file can simply have a comment such as "# this uses muslc", which will cause it to hash differently.
62
+
63
+ ### Better control over source modifications
64
+
65
+ Currently, vcpkg caches sources inside `buildtrees/$PORT/src/`. The built-in helpers, such as `vcpkg_extract_archive_ex()` assume that if the appropriately named source folder exists, it is true, accurate, and without modification.
66
+
67
+ However, the basic workflow for working on ports (specifically, developing patches) breaks this assumption by directly editing whatever extracted source directory the tool is currently using until a successful build is achieved. The user then usually builds a patch file from their changes, then checks it in to the port directory (adding the changes to one of the tracked locations above) and everything is restored to normal.
68
+
69
+ However, this causes serious issues with the current tracking system, because modifications to this cached source are not detected and tracked into the binary package.
70
+
71
+ Our proposed solution is to force source re-extraction each time during builds that have uploading to any protocol enabled. Uploading/downloading can then be disabled on the command line via the --editable switch to reuse extracted sources and enable the current workflow.
72
+
73
+ ### Protocols
74
+
75
+ To service different scenarios and user requirements, we need to support multiple backends. Currently, our CI system uses our only implemented backend: file-based archives.
76
+
77
+ #### Backend #1: File-Based Archives
78
+
79
+ This backend simply stores .zip files in a hierarchy similar to git objects: `$VCPKG_ROOT/archives/$XX/$YYYY.zip` with `$XX` being the first two characters of the computed package hash, and `$YYYY` being the full expanded hash. It also supports storing failure logs as `$VCPKG_ROOT/archives/fail/$XX/$YYYY.zip`, however we consider this an internal feature that is not relevant to the key User Stories.
80
+
81
+ Our CI system uses this backend by symlinking this directory to an Azure Files share, enabling built binaries and failure logs to be shared by all machines in the pool. Credentials are handled at the time of mounting the Azure Files share, so this does not require interactive authentication.
82
+
83
+ This protocol is ideal due to simplicity for same-machine reuse and simple serverless scenarios such as using networked SMB folders across multiple machines for very small teams. However, it has three significant limitations in the current incarnation:
84
+
85
+ - It uses the hardcoded directory `$VCPKG_ROOT/archives` (redirectable using symlinks, but unwieldy)
86
+
87
+ - It cannot use multiple directories
88
+
89
+ - There is no ability to treat directories as "read-only"/immutable
90
+
91
+ These second two points are required to implement the very useful concept of "fallback" folders (see https://github.com/NuGet/Home/wiki/%5BSpec%5D-Fallback-package-folders for NuGet’s spec on this topic).
92
+
93
+ #### Backend #2: NuGet (Azure DevOps Artifacts, GitHub Packages, etc)
94
+
95
+ This backend packages binaries into a "raw" NuGet package (not suitable for direct import by MSBuild projects) and uploads them to supported NuGet servers such as Azure DevOps Artifacts and GitHub Packages. We believe this will best satisfy the CI scenarios – both CI -> CI as well as CI -> Developer by relying on powerful, centralized, managed hosting.
96
+
97
+ There is a difference in this case between the developer and CI scenarios. The developer generally wants to configure their remotes for the project and then be able to run vcpkg commands as normal, with packages automatically being downloaded and uploaded to optimize the experience. This is similar to File-Based Archives.
98
+
99
+ While a CI system could use the same workflow as a developer, there are a few key differences. First, a CI system must use a stored secret for authentication, because it cannot interactively authenticate. Second, to enable more complex interactions with systems such as package signing and task-based restores, we must also support a 4-step workflow:
100
+
101
+ 1. Vcpkg computes hashes of any potentially required packages and writes them to a file
102
+
103
+ 2. An unspecified service/task/etc can parse this file and download any appropriate packages
104
+
105
+ 3. vcpkg is then invoked a second time, with any downloaded packages. This consumes the packages, performs any installations and builds, and potentially produces new packages to an output folder.
106
+
107
+ 4. Finally, another unspecified service/task/etc can take these output packages, sign them, and upload them.
108
+
109
+ This flow enables arbitrarily complex, user-defined authentication and signing schemes, such as the tasks provided by GitHub Actions and Azure DevOps Pipelines or manual signing as documented in the NuGet documentation: https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package.
110
+
111
+ #### Configuration
112
+
113
+ Currently, our file-based backend is enabled by passing the undocumented `--binarycaching` flag to any Vcpkg command or setting the undocumented environment variable `VCPKG_FEATURE_FLAGS` to `binarycaching`. We will replace this feature flag with an on-by-default user-wide behavior, plus command line and environment-based configurability.
114
+
115
+ The on-by-default configuration will specify the file-based archive protocol on either `%LOCALAPPDATA%/vcpkg/archives` (Windows) or `$XDG_CACHE_HOME/vcpkg/archives` (Unix). If `XDG_CACHE_HOME` is not defined on Unix, we will fall back to `$HOME/.cache/vcpkg/archives` based on the [XDG Base Directory Specification][1]. This can be redirected with a symlink, or completely overridden with the command line or environment. In the future we can also consider having a user-wide configuration file, however we do not believe this is important for any of our key scenarios.
116
+
117
+ On the command line, a backend can be specified via `--binarysource=<config>`. Multiple backends can be specified by passing the option multiple times and the order of evaluation is determined by the order on the command line. Writes will be performed on all upload backends, but only for packages that were built as part of this build (the tool will not repackage/reupload binaries downloaded from other sources).
118
+
119
+ The environment variable `VCPKG_BINARY_SOURCES` can be set to a semicolon-delimited list of `<config>`. Empty `<config>` strings are valid and ignored, to support appending like `set VCPKG_BINARY_SOURCES=%VCPKG_BINARY_SOURCES%;foo` or `export VCPKG_BINARY_SOURCES="$VCPKG_BINARY_SOURCES;foo"`
120
+
121
+ `<config>` can be any of:
122
+
123
+ - `clear` - ignore all lower priority sources (lowest priority is default, then env, then command line)
124
+
125
+ - `default[,<readwrite>]` - Reintroduce the default ~/.vcpkg/packages (as read-only or with uploading)
126
+
127
+ - `files,<path>[,<readwrite>]` - Add a file-based archive at `<path>`
128
+
129
+ - `nuget,<url>[,<readwrite>]` - Add a nuget-based source at `<url>`. This url has a similar semantic as `nuget.exe restore -source <url>` for reads and `nuget.exe push -source <url>` for writes; notably it can also be a local path.
130
+
131
+ - `nugetconfig,<path>[,<readwrite>]` - Add a nuget-based source using the NuGet.config file at `<path>`. This enables users to fully control NuGet's execution in combination with the documented NuGet environment variables. This has similar semantics to `nuget.exe push -ConfigFile <path>` and `nuget.exe restore -ConfigFile <path>`.
132
+
133
+ - `interactive` - Enables interactive mode (such as manual credential entry) for all other configured backends.
134
+
135
+ `<readwrite>` can be any of `read`, `write`, or `readwrite` to control whether packages will be consumed or published.
136
+
137
+ Backtick (`) can be used as an escape character within config strings, with double backtick (``) inserting a single backtick. All paths must be absolute.
138
+
139
+ For all backends, noninteractive operation will be the default and the vcpkg tool will take a `--interactive` parameter to enable prompting for user credentials (if needed by the backend).
140
+
141
+ To enable the 4-step flow, `vcpkg install` will take a command `--write-nuget-packages-config=<path>` which can be used in combination with `--dry-run`. This path can be relative and will resolve with respect to the current working directory.
142
+
143
+ [1]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
144
+
145
+ #### Example 4-step flow
146
+
147
+ ```
148
+ PS> vcpkg install --dry-run pkg1 pkg2 pkg3 --write-nuget-packages-config=packages.config
149
+ ```
150
+
151
+ An unspecified process, such as `nuget.exe restore packages.config -packagedirectory $packages` or the [ADO task][2], restores the packages to `$packages`.
152
+
153
+ ```
154
+ PS> vcpkg install pkg1 pkg2 pkg3 --binarysource=clear --binarysource=nuget,$outpkgs,upload --binarysource=nuget,$packages
155
+ ```
156
+
157
+ Another unspecified process such as `nuget.exe sign $outpkgs/*.nupkg` and `nuget.exe push $outpkgs/*.nupkg` or the ADO task uploads the packages for use in future CI runs.
158
+
159
+ [2]: https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/package/nuget?view=azure-devops
third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/export-command.md ADDED
@@ -0,0 +1,174 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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.
third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/feature-packages.md ADDED
@@ -0,0 +1,291 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Proposal: Features / Feature packages (Feb 23 2017)
2
+
3
+ **Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
4
+
5
+ **Up-to-date documentation is available at [Selecting Library Features](../users/selecting-library-features.md).**
6
+
7
+ ## 1. Motivation
8
+
9
+ ### A. OpenCV + CUDA
10
+
11
+ [OpenCV][] is a computer vision library that can optionally be built with CUDA support to massively accelerate certain tasks when using computers with NVidia GPUs. For users without NVidia GPUs, building with CUDA support provides no benefit. [CUDA][] is provided only via a 1.3 GB installer (at the time of this authoring), which requires administrator access to install and modifies the global system state.
12
+
13
+ Therefore, there is significant value in enabling users to choose whether they find CUDA support valuable for their particular scenario.
14
+
15
+ ### B. OpenCV + OpenCV\_contrib
16
+
17
+ The community around [OpenCV][] has built up a library of extensions called [OpenCV_contrib][]. However, these extensions are a source-level patch onto the main OpenCV codebase and therefore must be applied _during_ the core OpenCV build. Further confounding the problem, it is the author's understanding that these community extensions have only been developed with [CUDA][] enabled and cannot be built without that dependency.
18
+
19
+ Therefore, if CUDA is disabled, OpenCV\_contrib must also be disabled. Likewise, when a user requests OpenCV\_contrib, CUDA must be enabled. It would be convenient, but not a requirement, to enable CUDA without enabling the community extensions.
20
+
21
+ Finally, these extensions add additional exports and headers which could be depended upon by other libraries. For maintainers, there must be a way to specify this requirement such that `vcpkg install mylib-depends-ocv-contrib` will verify/build/rebuild OpenCV with the community extensions enabled.
22
+
23
+ ### C. C++ REST SDK + SignalR
24
+
25
+ The [C++ REST SDK][cpprestsdk] is a networking library that provides (among other features) HTTP and Websockets clients. To implement the HTTP client functionality on Windows Desktop, only the core Win32 platform APIs are needed (`zlib` is optional).
26
+
27
+ However, the websockets client is based on [Websockets++][], which adds mandatory dependencies on `boost`, `openssl`, and `zlib`. Many users of the C++ REST SDK do not use the websockets component, so to minimize their overall dependency footprint it can be disabled at build time. Ideally, these kinds of options would be easily accessible to users in Vcpkg who are concerned about the final size or licensing of their deployment.
28
+
29
+ [SignalR-Client-Cpp][SignalR] depends on the websockets functionality provided by the C++ REST SDK. Therefore, the maintainers of the `signalrclient` port would ideally like to express this dependency such that `cpprestsdk` will be automatically correctly built for their needs. Note that `signalrclient` does not _inherently_ care about `boost`, `websocketspp` or `openssl` -- it depends only on the public websocket client APIs provided by `cpprestsdk`. It would be much more maintainable to declare dependencies based on the public APIs rather than the dependencies themselves.
30
+
31
+ [OpenCV]: http://opencv.org/
32
+ [CUDA]: http://www.nvidia.com/object/cuda_home_new.html
33
+ [OpenCV_contrib]: https://github.com/opencv/opencv_contrib
34
+ [cpprestsdk]: https://github.com/Microsoft/cpprestsdk
35
+ [Websockets++]: https://www.zaphoyd.com/websocketpp/
36
+ [SignalR]: https://github.com/aspnet/SignalR-Client-Cpp
37
+
38
+ ## 2. Other design concerns
39
+
40
+ - General-purpose Open Source projects must be able to easily and succinctly describe their build dependencies inside Vcpkg. This should be no more verbose than a single `vcpkg install` line and, when that command succeeds, there is a strong expectation that all required functionality/headers/imports are available.
41
+
42
+ - The internal state of the Vcpkg enlistment must be either extremely transparent OR managed by version control (git). This enables larger projects to efficiently transfer the entire state of their customized Vcpkg system between machines (and onto build servers) by having the destination clone and then run a single `vcpkg install` line for the subset of dependencies required. The results of this operation should be as repeatable as reasonably achievable given the current limits of the underlying toolchain.
43
+
44
+ ## 3. Proposed solution
45
+
46
+ A key summary of the above motivations is that they are all scenarios surrounding APIs that are not independently buildable from each other. We have an existing solution for APIs that are independently buildable: separate packages. Therefore, we seek to extend the user-facing notion of "packages" to include capabilities and contracts that cannot be made into independent builds.
47
+
48
+ This document proposes "features" (also called feature packages). These features are intended to model semi-independently toggleable API sets/contracts such that they can be sanely depended upon by other packages. It is not a goal to model exclusive alternatives (such as implementation choices that are not directly user-observable) through this mechanism.
49
+
50
+ - Individual libraries within `boost` may be reasonably represented as features.
51
+ - Whether a graphics library is built on DirectX xor OpenGL (where one but not both must be chosen) is not representable as a feature.
52
+
53
+ From a user experience perspective (i.e. from `vcpkg install`) feature packages act as much as possible like completely independent packages. However, internally, any change to a package's features will result in a rebuild of the associated "parent" package. This will invoke a package rebuild experience similar to upgrading.
54
+
55
+ When using `vcpkg install <package>`, some features will be enabled by default. These default features can be avoided by referring to the packages as `<package>[core]` and features can be added by supplying them on the same installation line.
56
+
57
+ ### A. Proposed User experience
58
+
59
+ #### i. User with no preference about options
60
+ Install of a library with default features:
61
+ ```no-highlight
62
+ > vcpkg install cpprestsdk
63
+ // -- omitted build information -- //
64
+ Package cpprestsdk[core]:x86-windows is installed.
65
+ Package cpprestsdk[compression]:x86-windows is installed.
66
+ Package cpprestsdk[ws-client]:x86-windows is installed.
67
+ ```
68
+
69
+ Removal of that library:
70
+ ```no-highlight
71
+ > vcpkg remove cpprestsdk
72
+ The following packages will be removed:
73
+ cpprestsdk:x86-windows
74
+ Removing package cpprestsdk:x86-windows...
75
+ Removing package cpprestsdk:x86-windows... done
76
+ Purging package cpprestsdk:x86-windows...
77
+ Cleaned up D:\src\vcpkg\packages\cpprestsdk_x64-windows
78
+ Purging package cpprestsdk:x86-windows... done
79
+ ```
80
+
81
+ Installation of a library with optional features:
82
+ ```no-highlight
83
+ > vcpkg install opencv
84
+ // -- omitted build information -- //
85
+ Package opencv[core]:x86-windows is installed.
86
+ ```
87
+
88
+ #### ii. User desires CUDA support for OpenCV directly, and is unfamiliar with feature packages
89
+ Developer Bob knows he wants OpenCV, so he guesses what the package is called
90
+ ```no-highlight
91
+ > vcpkg install opencv
92
+ // -- omitted build information -- //
93
+ Package opencv[core]:x86-windows is installed.
94
+ ```
95
+
96
+ Bob attempts to build his application against OpenCV (assuming CUDA), which fails at runtime or compile time indicating that OpenCV wasn't built with CUDA.
97
+ Bob comes back to vcpkg, not knowing about the "feature packages" feature. The primary inquiry tools for Vcpkg are `search` and `list`, so he runs `vcpkg search`:
98
+ ```no-highlight
99
+ > vcpkg search opencv
100
+ opencv 3.2.0 computer vision library
101
+ opencv[cuda] support for NVidia CUDA
102
+ opencv[contrib] community supported extensions for OpenCV
103
+
104
+ If your library is not listed, please open an issue at:
105
+ https://github.com/Microsoft/vcpkg/issues
106
+ ```
107
+ He isn't immediately sure what the lack of a version number means, but anything in `vcpkg search` can be applied to `vcpkg install`, so he runs:
108
+ ```no-highlight
109
+ > vcpkg install opencv[cuda]
110
+ The following packages will be rebuilt:
111
+ opencv:x86-windows
112
+
113
+ To rebuild with this feature, use:
114
+ vcpkg remove opencv:x86-windows
115
+ vcpkg install opencv[core,cuda]:x86-windows
116
+ ```
117
+ Bob follows the instructions...
118
+ ```no-highlight
119
+ > vcpkg remove opencv:x86-windows
120
+ // -- omitted results as above -- //
121
+ > vcpkg install opencv[core,cuda]:x86-windows
122
+ // -- omitted build information -- //
123
+ Package opencv[core]:x86-windows is installed.
124
+ Package opencv[cuda]:x86-windows is installed.
125
+ ```
126
+ and he can now use OpenCV's CUDA support in his application.
127
+
128
+ #### iii. User is familiar with feature packages, and wants to opt-out of a feature
129
+ Developer Alice has used `cpprestsdk`, built it from source, and she knows about the option to disable websockets. She uses `search` to find the complete list of features:
130
+ ```
131
+ > vcpkg search cpprestsdk
132
+ cpprestsdk 2.9.0-2 C++11 JSON, REST, and OAuth library The C++ RES...
133
+ cpprestsdk[compression] Gzip compression support in the HTTP client.
134
+ cpprestsdk[ws-client] Websocket client support based on websocketspp.
135
+
136
+ If your library is not listed, please open an issue at:
137
+ https://github.com/Microsoft/vcpkg/issues
138
+ ```
139
+
140
+ She decided she only wants `cpprestsdk[compression]`, so she installs only that feature:
141
+ ```no-highlight
142
+ > vcpkg install cpprestsdk[compression]
143
+ // -- omitted build information -- //
144
+ Package cpprestsdk[core]:x86-windows is installed.
145
+ Package cpprestsdk[compression]:x86-windows is installed.
146
+ ```
147
+ She receives a quick recursive build that only depends on `zlib`.
148
+
149
+ She's now interested in some additional libraries built on top of cpprestsdk: `azure-storage-cpp` and `signalrclient`.
150
+ ```no-highlight
151
+ > vcpkg install azure-storage-cpp
152
+ // -- omitted build information -- //
153
+ Package azure-storage-cpp[core]:x86-windows is installed.
154
+
155
+ > vcpkg install signalrclient
156
+ Package signalrclient:x86-windows depends on cpprestsdk[ws-client]:x86-windows.
157
+
158
+ The following packages will be rebuilt:
159
+ * azure-storage-cpp:x86-windows
160
+ * cpprestsdk:x86-windows
161
+
162
+ To rebuild the current package graph with this feature, use:
163
+ vcpkg remove cpprestsdk:x86-windows azure-storage-cpp:x86-windows
164
+ vcpkg install cpprestsdk[core,compression,ws-client]:x86-windows
165
+ vcpkg install azure-storage-cpp[core]:x86-windows
166
+ vcpkg install signalrclient[core]:x86-windows
167
+ ```
168
+ She follows the above script and can use both `azure-storage-cpp` and `signalrclient` in her code.
169
+
170
+ Some time has passed, she decided not to use `signalrclient`, and she's interested in shipping her application. She wants to minimize her final install size, so she'd like to remove all unneeded packages like `boost` and `openssl`.
171
+ ```no-highlight
172
+ > vcpkg remove boost openssl
173
+ The following packages and features will be removed:
174
+ * signalrclient[core]:x86-windows
175
+ * cpprestsdk[ws-client]:x86-windows
176
+ boost[core]:x86-windows
177
+ openssl[core]:x86-windows
178
+
179
+ The following packages will be rebuilt:
180
+ * azure-storage-cpp:x86-windows
181
+ * cpprestsdk:x86-windows
182
+
183
+ Removing features requires rebuilding packages.
184
+ To rebuild the current package graph without these features, use:
185
+ vcpkg remove cpprestsdk:x86-windows azure-storage-cpp:x86-windows signalrclient:x86-windows openssl:x86-windows boost:x86-windows
186
+ vcpkg install cpprestsdk[core,compression]:x86-windows
187
+ vcpkg install azure-storage-cpp[core]:x86-windows
188
+ ```
189
+ In the end, her final `vcpkg list` outputs:
190
+ ```no-highlight
191
+ > vcpkg list
192
+ zlib[core]:x86-windows 1.2.11 A compression library
193
+ azure-storage-cpp[core]:x86-windows 2.6.0 Microsoft Azure Storage Client SDK for ...
194
+ cpprestsdk[core]:x86-windows 2.9.0-2 C++11 JSON, REST, and OAuth library
195
+ cpprestsdk[compression]:x86-windows Gzip compression support in the HTTP client.
196
+ ```
197
+
198
+ ### B. Technical model
199
+
200
+ - Each package can have any number "features".
201
+ - Features follow the same naming conventions as packages, but when referenced are always "namespaced" by the parent package.
202
+ - `cpprestsdk[ws-client]` is a completely orthogonal feature from `poco[ws-client]`.
203
+ - Features are valid dependencies.
204
+ - `signalrclient` depends on `cpprestsdk[ws-client]`
205
+ - Features can have dependencies (including other features).
206
+ - `cpprestsdk[ws-client]` depends on `boost`, `openssl`, and `websocketspp`
207
+ - `opencv[cuda]` depends on `cuda`
208
+ - `opencv[contrib]` depends on `opencv[cuda]`
209
+ - `boost[python]` depends on `libpython`
210
+ - Every package has an implicit feature called `core`, which covers the core library with a minimum set of features. All features implicitly depend on the `core` feature of their parent package
211
+ - `azure-storage-cpp` depends on `cpprestsdk[core]`
212
+ - `cpprestsdk[ws-client]` implicitly depends on `cpprestsdk[core]`
213
+ - Each package declares a list of default features that are enabled when the package is referred to by its raw name, and `core` is always a default feature.
214
+ - `cpprestsdk` declares `ws-client` and `compression` to be default features. Any unqualified reference `cpprestsdk` implicitly means `cpprestsdk[core]` _and_ `cpprestsdk[ws-client]` _and_ `cpprestsdk[compression]`.
215
+ - `opencv` does not declare `cuda` nor `contrib` to be default features.
216
+
217
+ As a conclusion of the above, it is expected that all packages will be buildable with all features disabled (just the `core` feature) and with all features enabled.
218
+
219
+ ### C. Proposed Control File Syntax
220
+
221
+ #### OpenCV and CUDA
222
+ To add the feature CUDA to OpenCV, we will adopt the following syntax in the CONTROL file:
223
+ ```no-highlight
224
+ # opencv/CONTROL
225
+ Source: opencv
226
+ Version: 3.2.0-1
227
+ Build-Depends: zlib, libpng, libjpeg-turbo, tiff
228
+ Description: computer vision library
229
+ Default-Features:
230
+
231
+ Feature: cuda
232
+ Build-Depends: cuda
233
+ Description: parallel computing platform
234
+
235
+ Feature: contrib
236
+ Build-Depends: opencv[cuda]
237
+ Description: library of OpenCV Extensions
238
+ ```
239
+
240
+ #### Signalrclient
241
+ ```no-highlight
242
+ # signalrclient/CONTROL
243
+ Source: signalrclient
244
+ Version: 1.0.0-beta1
245
+ Build-Depends: cpprestsdk[ws-client]
246
+ Description: C++ client for SignalR.
247
+ ```
248
+ ```no-highlight
249
+ # cpprestsdk/CONTROL
250
+ Source: cpprestsdk
251
+ Version: 2.9.0-2
252
+ Build-Depends:
253
+ Description: C++11 JSON, REST, and OAuth library ...
254
+ Default-Features: compression, ws-client
255
+
256
+ Feature: compression
257
+ Build-Depends: zlib (windows)
258
+ Description: Gzip compression support in the HTTP client.
259
+
260
+ Feature: ws-client
261
+ Build-Depends: boost (windows), openssl (windows), websocketpp (windows)
262
+ Description: Websocket client support based on websocketspp
263
+ ```
264
+
265
+ ### D. Additional Control File Technical Details
266
+
267
+ - If any feature paragraphs exist, the field `Default-Features` must be present.
268
+
269
+ ## 4. Related Work
270
+
271
+ ### Cargo's Features (from Rust): <http://doc.crates.io/manifest.html#the-features-section>
272
+ The proposed feature packages are exceedingly similar to Cargo's Features, with the following changes:
273
+
274
+ - We avoid any collision problems because features are always namespaced by the owning package
275
+ - We do not have a concept of "feature groups", instead we allow dependencies from one feature to another within the same package (Note: This may be how "feature groups" are implemented internally to Cargo -- it was not clear from the documentation).
276
+ - Because of the nature of C and C++, it is extremely commonplace that large software packages can have features disabled to remove their dependencies upon other libraries. Changing this configuration requires a rebuild of the package and potentially rippling ABI changes to any downstream dependencies. Therefore, we expect significantly more use of this feature to manage optional API contracts instead of the intended use in Cargo (curation).
277
+ - We do not intend feature packages to be used to express the curation relationship, beyond the notion of a "default" set within a package.
278
+
279
+ ### Gentoo's USE flags: <https://wiki.gentoo.org/wiki/Handbook:X86/Working/USE>
280
+ Gentoo's USE flags can be shortly summarized as a global set of keywords that is used to make cross-cutting changes to the entire package graph's build configuration. This system standardizes many common settings such that they can be simultaneously toggled for the entire graph.
281
+
282
+ The most common example of this would be using KDE vs Gnome. A user who knows that, given the choice, they would prefer the KDE/Qt interface can manage the massive space of package configuration efficiently without learning the particular term that each package has decided to call "build using Qt instead of GTK".
283
+
284
+ USE flags can be customized hierarchically when needed, including at the per-package level. They can be depended upon by other packages, both positively and negatively. USE flags themselves can be used in any boolean expression to determine the complete set of package dependencies, including removing dependencies when flags are enabled.
285
+
286
+ Problems with USE flags:
287
+
288
+ - They require coordination from package maintainers to achieve the goal of "portable" flags. This increases the burden of adding a package -- to author a good package, I need to be aware of every uncommon USE flag and evaluate how those could map onto my local configuration space.
289
+ - Based on research online, it seems extremely common that users need to tweak flags at a per-package level. This calls into question how valuable the cross-cutting power above is.
290
+ - The vast majority of common USE flags are essentially a list of all the common packages and focus on giving the user a view of dependencies (which a package manager is designed to abstract when possible) instead of APIs (which is what users code against).
291
+ - Dependency analysis with USE flags becomes a SAT problem with an enormous state space -- P*F bits -- which compounds with any versioning relations. This may work acceptably in practice via heuristics, but it implies that a) there is a looming performance wall which could suddenly create a poor user experience and b) the heuristics may incorrectly model the user's needs, causing a disconnect in desire vs practice, which again leads to a poor user experience.
third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/manifests.md ADDED
@@ -0,0 +1,302 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Manifests -- `vcpkg.json`
2
+
3
+ **Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
4
+
5
+ **Up-to-date documentation is available at [Manifests](../users/manifests.md).**
6
+
7
+ For many other language package managers, there exists a way of writing one's dependencies in a declarative
8
+ manifest format; we want something similar for vcpkg. What follows is the specification of that feature;
9
+ this should mean that vcpkg becomes far more user and enterprise-friendly, and is additionally an important
10
+ first step for versioning and package federation. Our primary concern, beyond implementability, is ease-of-use;
11
+ it is important that using this feature is all of:
12
+
13
+ * Easy for existing users
14
+ * Easy for new users to set up
15
+ * Easy to extend later for new features like versioning and federation
16
+ * _Declarative_, not _Imperative_.
17
+
18
+ ## Reasoning
19
+
20
+ ### Why JSON?
21
+
22
+ We choose JSON for five main reasons:
23
+
24
+ * Everybody knows JSON, and if one doesn't, it's really easy to learn
25
+ * Every tool supports JSON in the standard library, or in a commonly used support library
26
+ * This means writing tooling should be trivial in any language one is comfortable with
27
+ * Most configuration formats don't have a COBOL implementation 😉
28
+ * Specified in an international standard
29
+ * There is _one_ right way to parse JSON
30
+ * There are no ambiguities of what the parse tree _should_ be
31
+ * Simple and secure
32
+ * Unlike YAML, for example, there's no weird ACE issues
33
+ * Easy to write a parser -- important since we can't depend on external libraries
34
+ * Schemas are almost a necessity
35
+
36
+ Some have suggested allowing comments or commas in our parser; we chose to use JSON proper
37
+ rather than JSON5 or JSON with comments because JSON is the everywhere-supported international
38
+ standard. That is not necessarily true of JSON with comments. Additionally, if one needs
39
+ to write a comment, they can do so via `"$reason"` or `"$comment"` fields.
40
+
41
+ ## Specification
42
+
43
+ A manifest file shall have the name `vcpkg.json`, and shall be in the root directory of a package.
44
+ It also replaces CONTROL files, though existing CONTROL files will still be
45
+ supported; there will be no difference between ports and packages, except
46
+ that packages do not need to supply portfile.cmake (eventually we would like
47
+ to remove the requirement of portfile.cmake for ports that already use
48
+ CMake).
49
+
50
+ The specification uses definitions from the [Definitions](#definitions) section in order
51
+ to specify the shape of a value. Note that any object may contain any directives, written as
52
+ a field key that starts with a `$`; these directives shall be ignored by `vcpkg`. Common
53
+ directives may include `"$schema"`, `"$comment"`, `"$reason"`.
54
+
55
+ A manifest must be a top-level object, and must have at least:
56
+
57
+ * `"name"`: a `<package-name>`
58
+ * One (and only one) of the following version fields:
59
+ * `"version-string"`: A `string`. Has no semantic meaning.
60
+ Equivalent to `CONTROL`'s `Version:` field.
61
+ * Other version fields will be defined by the Versions RFC
62
+
63
+ The simplest vcpkg.json looks like this:
64
+
65
+ ```json
66
+ {
67
+ "name": "mypackage",
68
+ "version-string": "0.1.0-dev"
69
+ }
70
+ ```
71
+
72
+ Additionally, it may contain the following properties:
73
+ * `"port-version"`: A non-negative integer. If this field doesn't exist, it's assumed to be `0`.
74
+ * Note that this is a change from existing CONTROL files, where versions were a part of the version string
75
+ * `"maintainers"`: An array of `string`s which contain the authors of a package
76
+ * `"maintainers": [ "Nicole Mazzuca <[email protected]>", "שלום עליכם <[email protected]>" ]`
77
+ * `"description"`: A string or array of strings containing the description of a package
78
+ * `"description": "mypackage is a package of mine"`
79
+ * `"homepage"`: A url which points to the homepage of a package
80
+ * `"homepage": "https://github.com/strega-nil/mypackage"`
81
+ * `"documentation"`: A url which points to the documentation of a package
82
+ * `"documentation": "https://readthedocs.io/strega-nil/mypackage"`
83
+ * `"license"`: A `<license-string>`
84
+ * `"license": "MIT"`
85
+ * `"dependencies"`: An array of `<dependency>`s
86
+ * `"dev-dependencies"`: An array of `<dependency>`s which are required only for developers (testing and the like)
87
+ * `"features"`: An array of `<feature>`s that the package supports
88
+ * `"default-features"`: An array of `<identifier>`s that correspond to features, which will be used by default.
89
+ * `"supports"`: A `<platform-expression>`
90
+ * `"supports": "windows & !arm"`
91
+
92
+ Any properties which are not listed, and which do not start with a `$`,
93
+ will be warned against and are reserved for future use.
94
+
95
+ The following is an example of an existing port CONTROL file rewritten as a vcpkg.json file:
96
+
97
+ ```
98
+ Source: pango
99
+ Version: 1.40.11-6
100
+ Homepage: https://ftp.gnome.org/pub/GNOME/sources/pango/
101
+ Description: Text and font handling library.
102
+ Build-Depends: glib, gettext, cairo, fontconfig, freetype, harfbuzz[glib] (!(windows&static)&!osx)
103
+ ```
104
+
105
+ ```json
106
+ {
107
+ "name": "pango",
108
+ "version-string": "1.40.11",
109
+ "port-version": 6,
110
+ "homepage": "https://ftp.gnome.org/pub/GNOME/sources/pango/",
111
+ "description": "Text and font handling library.",
112
+ "dependencies": [
113
+ "glib",
114
+ "gettext",
115
+ "cairo",
116
+ "fontconfig",
117
+ "freetype",
118
+ {
119
+ "name": "harfbuzz",
120
+ "features": [ "glib" ],
121
+ "platform": "!(windows & static) & !osx"
122
+ }
123
+ ]
124
+ }
125
+ ```
126
+
127
+ ## Behavior of the Tool
128
+
129
+ There will be two "modes" for vcpkg from this point forward: "classic", and "manifest".
130
+ The former will act exactly like the existing vcpkg workflow, so as to avoid breaking
131
+ anyone. The latter will be the mode only when the user either:
132
+
133
+ * Passes `--manifest-root=<directory>` (initially, `x-manifest-root`)
134
+ * Runs `vcpkg` in a directory that contains a file named `vcpkg.json`, or in a
135
+ child directory of a directory containing `vcpkg.json`.
136
+ * For this, initially vcpkg will warn that the behavior will change in the
137
+ future, and simply run in classic mode, unless the feature flag `manifests` is
138
+ passed via:
139
+ * The environment variable `VCPKG_FEATURE_FLAGS`
140
+ * The option `--feature-flags`
141
+ * (e.g., `--feature-flags=binarycaching,manifests`)
142
+ * If someone wants to use classic mode and silence the warning, they can add the
143
+ `-manifests` feature flag to disable the mode.
144
+
145
+ When in "manifest" mode, the `installed` directory will be changed to
146
+ `<manifest-root>/vcpkg_installed` (name up for bikeshedding).
147
+ The following commands will change behavior:
148
+
149
+ * `vcpkg install` without any port arguments will install the dependencies listed in
150
+ the manifest file, and will remove any dependencies
151
+ which are no longer in the dependency tree implied by the manifest file.
152
+ * `vcpkg install` with port arguments will give an error.
153
+
154
+ The following commands will not work in manifest mode, at least initially:
155
+
156
+ * `vcpkg x-set-installed`: `vcpkg install` serves the same function
157
+ * `vcpkg remove`
158
+ * `vcpkg export`
159
+
160
+ We may add these features back for manifest mode once we understand how best to
161
+ implement them.
162
+
163
+ ### Behavior of the Toolchain
164
+
165
+ Mostly, the toolchain file stays the same; however, we shall add
166
+ two public options:
167
+
168
+ ```cmake
169
+ VCPKG_MANIFEST_MODE:BOOL=<we found a manifest>
170
+ VCPKG_MANIFEST_INSTALL:BOOL=ON
171
+ ```
172
+
173
+ The first option either explicitly turns on, or off, manifest mode;
174
+ otherwise, we default to looking for a manifest file in the directory
175
+ tree upwards from the source directory.
176
+
177
+ The `VCPKG_MANIFEST_INSTALL` option tells the toolchain whether to
178
+ install the packages or not -- if you wish to install the manifest
179
+ dependencies manually, you can set this to off, and we also turn it
180
+ off for packages installed by vcpkg.
181
+
182
+ Additionally, if `-manifests` is set in the feature flags environment
183
+ variable, we turn off manifest mode in the toolchain, and we act like
184
+ the classic toolchain.
185
+
186
+ ### Example - CMake Integration
187
+
188
+ An example of using the new vcpkg manifests feature for a new
189
+ project follows:
190
+
191
+ The filesystem structure should look something like:
192
+
193
+ ```
194
+ example/
195
+ src/
196
+ main.cxx
197
+ CMakeLists.txt
198
+ vcpkg.json
199
+ ```
200
+
201
+ Then, `main.cxx` might look like:
202
+
203
+ ```cpp
204
+ #include <fmt/format.h>
205
+
206
+ int main() {
207
+ fmt::print("Hello, {}!", "world");
208
+ }
209
+ ```
210
+
211
+ Therefore, in `vcpkg.json`, we'll need to depend on `fmt`:
212
+
213
+ ```json
214
+ {
215
+ "name": "example",
216
+ "version-string": "0.0.1",
217
+ "dependencies": [
218
+ "fmt"
219
+ ]
220
+ }
221
+ ```
222
+
223
+ Then, let's write our `CMakeLists.txt`:
224
+
225
+ ```cmake
226
+ cmake_minimum_required(VERSION 3.14)
227
+
228
+ project(example CXX)
229
+
230
+ add_executable(example src/main.cxx)
231
+
232
+ find_package(fmt REQUIRED)
233
+
234
+ target_link_libraries(example
235
+ PRIVATE
236
+ fmt::fmt)
237
+ ```
238
+
239
+ And finally, to configure and build:
240
+
241
+ ```sh
242
+ $ cd example
243
+ $ cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
244
+ ... configuring and installing...
245
+ $ cmake --build build
246
+ ```
247
+
248
+ and we're done! `fmt` will get installed into
249
+ `example/build/vcpkg_installed`, and we can run our executable with:
250
+
251
+ ```sh
252
+ $ build/example
253
+ Hello, world!
254
+ ```
255
+
256
+ ## Definitions
257
+
258
+ * `<identifier>`: A `string` which:
259
+ * Is entirely ASCII
260
+ * Contains only lowercase alphabetic characters, digits, and hyphen-minus
261
+ * Does not have multiple consecutive hyphens
262
+ * Does not begin nor end with a hyphen
263
+ * Is not a Windows filesystem reserved name
264
+ * Is not a vcpkg reserved name: "default" or "core".
265
+ * In other words, it must follow the regex `[a-z0-9]+(-[a-z0-9]+)*`, and must not be any of:
266
+ * `{ prn, aux, nul, con, lpt[1-9], com[1-9], core, default }`
267
+ * `<package-name>`: A `string` consisting of a non-zero number of `<identifier>`s, separated by `.`.
268
+ * `a.b.c` is valid
269
+ * `a` is valid
270
+ * `a/b` is not valid
271
+ * `Boost.Beast` is not valid, but `boost.beast` is
272
+ * `<dependency>`: Either a `<package-name>`, or an object:
273
+ * A dependency always contains the following:
274
+ * `"name"`: A `<package-name>`
275
+ * Optionally, `"features"`: an array of `<identifier>`s corresponding to features in the package.
276
+ * Optionally, `"default-features"`: a `boolean`. If this is false, then don't use the default features of the package; equivalent to core in existing CONTROL files. If this is true, do the default thing of including the default features.
277
+ * Optionally, `"platform"`: a `<platform-expression>`
278
+ * `<dependency.port>`: No extra fields are required.
279
+ * `<license-string>`: An SPDX license expression at version 3.9.
280
+ * `<platform-expression>`: A specification of a set of platforms; used in platform-specific dependencies and supports fields. A string that is parsed as follows:
281
+ * `<platform-expression>`:
282
+ * `<platform-expression.not>`
283
+ * `<platform-expression.and>`
284
+ * `<platform-expression.or>`
285
+ * `<platform-expression.simple>`:
286
+ * `( <platform-expression> )`
287
+ * `<platform-expression.identifier>`
288
+ * `<platform-expression.identifier>`:
289
+ * regex: `/^[a-z0-9]+$/`
290
+ * `<platform-expression.not>`:
291
+ * `<platform-expression.simple>`
292
+ * `! <platform-expression.simple>`
293
+ * `<platform-expression.and>`
294
+ * `<platform-expression.not>`
295
+ * `<platform-expression.and> & <platform-expression.not>`
296
+ * `<platform-expression.or>`
297
+ * `<platform-expression.not>`
298
+ * `<platform-expression.or> | <platform-expression.not>`
299
+ * `<feature>`: An object containing the following:
300
+ * `"name"`: An `<identifier>`, the name of the feature
301
+ * `"description"`: A `string` or array of `string`s, the description of the feature
302
+ * Optionally, `"dependencies"`: An array of `<dependency>`s, the dependencies used by this feature
third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/ports-overlay.md ADDED
@@ -0,0 +1,183 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Ports Overlay (Jun 19, 2019)
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. Allow users to override ports with alternate versions
8
+
9
+ It's a common scenario for `vcpkg` users to keep specific versions of libraries to use in their own projects. The current recommendation for users is to fork `vcpkg`'s repository and create tags for commits containing the specific versions of the ports they want to use.
10
+
11
+ This proposal adds an alternative to solve this problem. By allowing `vcpkg` users to specify additional locations in their file system containing ports for:
12
+
13
+ * older or newer versions of libraries,
14
+ * modified libraries, or
15
+ * libraries not available in `vcpkg`.
16
+
17
+ These locations will be searched when resolving port names during package installation, and override ports in `<vcpkg-root>/ports`.
18
+
19
+ ### B. Allow users to keep unmodified upstream ports
20
+
21
+ Users will be able to keep unmodified versions of the ports shipped with `vcpkg` and update them via `vcpkg update` and `vcpkg upgrade` without having to solve merge conflicts.
22
+
23
+
24
+ ## 2. Other design concerns
25
+
26
+ * Allow a set of `vcpkg` commands to optionally accept additional paths to be used when searching for ports.
27
+ * Additional paths must take precedence when resolving names of ports to install.
28
+ * Allow users to specify multiple additional paths.
29
+ * Provide a simple disambiguation mechanism to resolve ambiguous port names.
30
+ * After resolving a port name, the installation process has to work the same as for ports shipped by `vcpkg`.
31
+ * This **DOES NOT ENABLE MULTIPLE VERSIONS** of a same library to be **INSTALLED SIDE-BY-SIDE**.
32
+
33
+
34
+ ## 3. Proposed solution
35
+
36
+ This document proposes allowing additional locations to search for ports during package installation that will override and complement the set of ports provided by `vcpkg` (ports under the `<vcpkg_root>/ports` directory).`
37
+
38
+ A new option `--overlay-ports` will be added to the `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, `vcpkg export`, and `vcpkg depend-info` commands to specify additional paths containing ports.
39
+
40
+ From a user experience perspective, a user expresses interest in adding additional lookup locations by passing the `--overlay-ports` option followed by a path to:
41
+
42
+ * an individual port (directory containing a `CONTROL` file),
43
+ * `vcpkg install sqlite3 --overlay-ports="C:\custom-ports\sqlite3"`
44
+
45
+ * a directory containing ports,
46
+ * `vcpkg install sqlite3 --overlay-ports=\\share\org\custom-ports`
47
+
48
+ * a file listing paths to the former two.
49
+ > NOTE: Reading paths from a text file is not available in the current implementation, some revisions to this part of the specification are being made and will be implemented in a future date.
50
+
51
+ * `vcpkg install sqlite3 --overlay-ports=..\port-repos.txt`
52
+
53
+ _port-repos.txt_
54
+
55
+ ```
56
+ .\experimental-ports\sqlite3
57
+ C:\custom-ports
58
+ \\share\team\custom-ports
59
+ \\share\org\custom-ports
60
+ ```
61
+ *Relative paths inside this file are resolved relatively to the file's location. In this case a `experimental-ports` directory should exist at the same level as the `port-repos.txt` file.*
62
+
63
+ _NOTE: It is not the goal of this document to discuss library versioning or project dependency management solutions, which require the ability to install multiple versions of a same library side-by-side._
64
+
65
+ ### Multiple additional paths
66
+
67
+ Users can provide multiple additional paths by repeating the `--overlay-ports` option.
68
+
69
+ ```
70
+ vcpkg install sqlite3
71
+ --overlay-ports="..\experimental-ports\sqlite3"
72
+ --overlay-ports="C:\custom-ports"
73
+ --overlay-ports="\\share\team\custom-ports
74
+ ```
75
+
76
+ ### Overlaying ports
77
+
78
+ Port name resolution follows the order in which additional paths are specified, with the first match being selected for installation, and falling back to `<vcpkg-root>/ports` if the port is not found in any of the additional paths.
79
+
80
+ No effort is made to compare version numbers inside the `CONTROL` files, or to determine which port contains newer or older files.
81
+
82
+ ### Examples
83
+
84
+ Given the following directory structure:
85
+
86
+ ```
87
+ team-ports/
88
+ |-- sqlite3/
89
+ |---- CONTROL
90
+ |-- rapidjson/
91
+ |---- CONTROL
92
+ |-- curl/
93
+ |---- CONTROL
94
+
95
+ my-ports/
96
+ |-- sqlite3/
97
+ |---- CONTROL
98
+ |-- rapidjson/
99
+ |---- CONTROL
100
+
101
+ vcpkg
102
+ |-- ports/
103
+ |---- <upstream ports>
104
+ |-- vcpkg.exe
105
+ |-- preferred-ports.txt
106
+ ```
107
+ * #### Example #1:
108
+
109
+ Running:
110
+
111
+ ```
112
+ vcpkg/vcpkg.exe install sqlite3 --overlay-ports=my-ports --overlay-ports=team-ports
113
+ ```
114
+
115
+ Results in `my-ports/sqlite3` getting installed as that location appears first in the command line arguments.
116
+
117
+ * #### Example #2:
118
+
119
+ A specific version of a port can be given priority by adding its path first in the list of arguments:
120
+
121
+ ```
122
+ vcpkg/vcpkg.exe install sqlite3 rapidjson curl
123
+ --overlay-ports=my-ports/rapidjson
124
+ --overlay-ports=vcpkg/ports/curl
125
+ --overlay-ports=team-ports
126
+ ```
127
+
128
+ Installs:
129
+ * `sqlite3` from `team-ports/sqlite3`
130
+ * `rapidjson` from `my-ports/rapidjson`
131
+ * `curl` from `vcpkg/ports/curl`
132
+
133
+ * #### Example #3:
134
+
135
+ > NOTE: Reading paths from a text file is not available in the current implementation, some revisions to this part of the specification are being made and will be implemented in a future date.
136
+
137
+ Given the content of `preferred-ports.txt` as:
138
+
139
+ ```
140
+ ./ports/curl
141
+ /my-ports/rapidjson
142
+ /team-ports
143
+ ```
144
+
145
+ A location can be appended or prepended to those included in `preferred-ports.txt` via the command line, like this:
146
+
147
+ ```
148
+ vcpkg/vcpkg.exe install sqlite3 curl --overlay-ports=my-ports --overlay-ports=vcpkg/preferred-ports.txt
149
+ ```
150
+
151
+ Which results in `my-ports/sqlite3` and `vcpkg/ports/curl` getting installed.
152
+
153
+
154
+ ## 4. Proposed User experience
155
+
156
+ ### i. User wants to preserve an older version of a port
157
+
158
+ Developer Alice and her team use `vcpkg` to acquire **OpenCV** and some other packages. She has even contributed many patches to add features to the **OpenCV 3** port in `vcpkg`. But, one day, she notices that a PR to update **OpenCV** to the next major version has been merged.
159
+
160
+ Alice wants to update some packages available in `vcpkg`. Unfortunately, updating her project to use the latest **OpenCV** is not immediately possible.
161
+
162
+ Alice creates a private GitHub repository and checks in the set of ports that she wants to preserve. Then provides her teammates with the link to clone her private ports repository.
163
+
164
+ ```
165
+ mkdir vcpkg-custom-ports
166
+ cd vcpkg-custom-ports
167
+ git init
168
+ cp -r %VCPKG_ROOT%/ports/opencv .
169
+ git add .
170
+ git commit -m "[opencv] Add OpenCV 3 port"
171
+ git remote add origin https://github.com/<Alice's GitHub username>/vcpkg-custom-ports.git
172
+ git push -u origin master
173
+ ```
174
+
175
+ Now her team is able to use:
176
+
177
+ ```
178
+ git clone https://github.com/<Alice's GitHub username>/vcpkg-custom-ports.git
179
+ vcpkg update --overlay-ports=./vcpkg-custom-ports
180
+ vcpkg upgrade --no-dry-run --overlay-ports=./vcpkg-custom-ports
181
+ ```
182
+
183
+ to upgrade their packages and preserve the old version of **OpenCV** they require.
third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/prefab.md ADDED
@@ -0,0 +1,160 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Vcpkg: export Android prefab Archives (AAR files)
2
+
3
+ **Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
4
+
5
+ Vcpkg can export android archives ([AAR files](https://developer.android.com/studio/projects/android-library)). Once an archive is created, it can imported in Android Studio as a native dependent. The archive is automatically consumed using [android studio's prefab tool](https://github.com/google/prefab).
6
+
7
+ For more information on Prefab, refer to:
8
+ * The [official prefab documentation](https://google.github.io/prefab).
9
+ * a blog post from Android developers blog: [Native Dependencies in Android Studio 4.0](https://android-developers.googleblog.com/2020/02/native-dependencies-in-android-studio-40.html)
10
+
11
+ _Note for Android Studio users: prefab packages are supported on Android Studio 4+_
12
+
13
+ ## Requirements
14
+
15
+ 1. `ndk <required>`
16
+
17
+ Set environment variable `ANDROID_NDK_HOME` to your android ndk installation. For example:
18
+
19
+ ````
20
+ export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle
21
+ ````
22
+
23
+ 2. `7zip <required on windows>` or `zip <required on linux>`
24
+
25
+ 3. `maven <optional>`
26
+
27
+ 4. Android triplets
28
+
29
+ See [android.md](../users/android.md) for instructions on how to install the triplets.
30
+
31
+ *Please note that in order to use "prefab" (see below), the four architectures are required. If any is missing the export will fail*
32
+
33
+
34
+ ## Example exporting [jsoncpp]
35
+
36
+ First "vcpkg install" the 4 android architectures (it is mandatory to export all 4 of them)
37
+
38
+ ````
39
+ ./vcpkg install jsoncpp:arm-android jsoncpp:arm64-android jsoncpp:x64-android jsoncpp:x86-android
40
+ ````
41
+
42
+
43
+ Then, export the prefab:
44
+
45
+ Note:
46
+ * The `--prefab-maven` flag is optional. Call it if you maven is installed.
47
+ * The `--prefab-debug` flag will output instructions on how to use the prefab archive via gradle.
48
+
49
+ ```
50
+ ./vcpkg export --triplet x64-android jsoncpp --prefab --prefab-maven --prefab-debug
51
+ ```
52
+
53
+ You will see an output like this:
54
+ ```
55
+ The following packages are already built and will be exported:
56
+ jsoncpp:arm64-android
57
+
58
+ Exporting package jsoncpp...
59
+ [DEBUG] Found 4 triplets
60
+ arm64-android
61
+ x64-android
62
+ x86-android
63
+ arm-android
64
+
65
+ ...
66
+ ... Lots of output...
67
+ ...
68
+
69
+ [INFO] Scanning for projects...
70
+ Downloading from central: https://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-clean-plugin/2.5/maven-clean-plugin-2.5.pom
71
+
72
+ ...
73
+ ... Lots of output...
74
+ ...
75
+
76
+ [INFO] BUILD SUCCESS
77
+ [INFO] Total time: 2.207 s
78
+ [INFO] Finished at: 2020-05-10T14:42:28+02:00
79
+
80
+
81
+ ...
82
+ ... Lots of output...
83
+ ...
84
+
85
+ [DEBUG] Configuration properties in Android Studio
86
+ In app/build.gradle
87
+
88
+ com.vcpkg.ndk.support:jsoncpp:1.9.2
89
+
90
+ And cmake flags
91
+
92
+ externalNativeBuild {
93
+ cmake {
94
+ arguments '-DANDROID_STL=c++_shared'
95
+ cppFlags "-std=c++17"
96
+ }
97
+ }
98
+
99
+ In gradle.properties
100
+
101
+ android.enablePrefab=true
102
+ android.enableParallelJsonGen=false
103
+ android.prefabVersion=${prefab.version}
104
+
105
+ Successfully exported jsoncpp. Checkout .../vcpkg/prefab
106
+
107
+ ```
108
+
109
+ #### The output directory after export
110
+
111
+ ````
112
+ prefab
113
+ └── jsoncpp/
114
+ ├── aar/
115
+ │   ├── AndroidManifest.xml
116
+ │   ├── META-INF/
117
+ │   │   └── LICENSE
118
+ │   └── prefab/
119
+ │   ├── modules/
120
+ │   │   └── jsoncpp/
121
+ │   │   ├── libs/
122
+ │   │   │   ├── android.arm64-v8a/
123
+ │   │   │   │   ├── abi.json
124
+ │   │   │   │   ├── include/
125
+ │   │   │   │   │   └── json/
126
+ │   │   │   │   │   ├── json.h
127
+ │   │   │   │   │   └── ....
128
+ │   │   │   │   └── libjsoncpp.so
129
+ │   │   │   ├── android.armeabi-v7a/
130
+ │   │   │   │   ├── abi.json
131
+ │   │   │   │   ├── include/
132
+ │   │   │   │   │   └── json/
133
+ │   │   │   │   │   ├── json.h
134
+ │   │   │   │   │   └── ....
135
+ │   │   │   │   └── libjsoncpp.so
136
+ │   │   │   ├── android.x86/
137
+ │   │   │   │   ├── abi.json
138
+ │   │   │   │   ├── include/
139
+ │   │   │   │   │   └── json/
140
+ │   │   │   │   │   ├── json.h
141
+ │   │   │   │   │   └── ....
142
+ │   │   │   │   └── libjsoncpp.so
143
+ │   │   │   └── android.x86_64/
144
+ │   │   │   ├── abi.json
145
+ │   │   │   ├── include/
146
+ │   │   │   │   └── json/
147
+ │   │   │   │   │   ├── json.h
148
+ │   │   │   │   │   └── ....
149
+ │   │   │   └── libjsoncpp.so
150
+ │   │   └── module.json
151
+ │   └── prefab.json
152
+ ├── jsoncpp-1.9.2.aar
153
+ └── pom.xml
154
+ ````
155
+
156
+ ## Example consuming [jsoncpp] via vcpkg and prefab
157
+
158
+ See the example repo here:
159
+
160
+ https://github.com/atkawa7/prefab-vpkg-integration-sample
third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/registries-2.md ADDED
@@ -0,0 +1,559 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Registries: Take 2 (including Git Registries)
2
+
3
+ **Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
4
+
5
+ Originally, the design of registries was decided upon and written up in the [Registries RFC](registries.md).
6
+ However, as we've gotten further into the design process of git registries and versioning,
7
+ and discussed the interaction of versioning with registries,
8
+ it's become clear that the existing design was lacking.
9
+ We need to have an on-disk port database that is not tied to the ports tree.
10
+
11
+ This RFC is a new design for registries, that includes this registry database.
12
+ It also includes the design for git registries,
13
+ which are likely to be the predominant form of registries in the wild.
14
+ They are also what we will start to treat the default registry as,
15
+ to allow for updating ports without updating the vcpkg executable
16
+ (likely necessary for binary releases).
17
+
18
+ ## Design Considerations
19
+
20
+ After internal discussions of the relationship between versioning and registries,
21
+ it was clear that the existing design of registries does not play well with versioning.
22
+ It was also clear that it was necessary to have metadata about ports in a separate place from the ports tree;
23
+ in fact, after discussion, it was clear that the ports tree should be considered an implementation detail;
24
+ a backing store for build process information (e.g., `portfile.cmake` and the patches) and the manifest.
25
+
26
+ From this, it's clear that vcpkg needs to add a new set of metadata.
27
+ The versioning implementation has decided on `port_versions`, and thus that's what this RFC uses.
28
+
29
+ Since we're replacing the existing ports directory with a new method of describing ports,
30
+ this means that the ports directory is no longer anything but a data store.
31
+ This also means that the existing rules around locations of ports is no longer required;
32
+ however, it will still keep getting followed for the main repository,
33
+ and it's recommended that other registries follow the same pattern to make contributing easier.
34
+
35
+ ## What does the registry database look like?
36
+
37
+ We don't wish to have the same problem as we do right now,
38
+ where there are nearly 1500 entries in a single directory.
39
+ We solve this by placing each database entry into `port_versions/<first character of port name>-/<port name>.json`.
40
+ For example, the database entry for 7zip is in `port_versions/7-/7zip.json`.
41
+
42
+ Each of these database entries contains all of the versions of the port throughout history,
43
+ along with versioning and feature metadata, so that we do not have to check out old manifests or CONTROL files
44
+ to get at that information.
45
+
46
+ Each database entry file must be a top-level array of port version objects, which contain the following entries:
47
+ * A version field: `"version-string"`, `"version"`, etc. Same as in the manifest.
48
+ * Optionally, `"port-version"`: Same as in the manifest.
49
+
50
+ And also contain a description of where to find the build files for this port; the possibilities include:
51
+
52
+ * `"git-tree"`: The [git object ID] of a tree object; this is only allowed for git registries.
53
+ Note that this ID must be an ID from the repository where the registry is located.
54
+ * `"path"`: A path describing where to find the build files.
55
+ The first entry in this path should be `$`, which means "this path starts at the root of the registry".
56
+ No other kinds of paths are allowed.
57
+ * For example: `$/foo/bar` gives you `foo/bar` underneath the folder containing the `port_versions` directory.
58
+ * `/foo/bar` and `foo/bar` are both disallowed.
59
+
60
+ Using a `"git-tree"` as a backend in a non-git registry, and using a `"path"` in a git registry,
61
+ is not permitted. Future extensions may include things like remote archives or git repositories,
62
+ or may allow `"path"` in git registries.
63
+
64
+ Note that a registry entry should _always_ be additive;
65
+ deleting existing entries is unsupported and may result in bad behavior.
66
+ The only modification to existing entries that is allowable is moving the backing store
67
+ for the build files, assuming that the new build files are equivalent to the old build files.
68
+ (For example, a filesystem registry might have a new way of laying out where ports are).
69
+
70
+ Additionally, we'd like a new way of describing the set of ports that make up a "baseline".
71
+ This is currently done with the reference of the vcpkg git repository -
72
+ each reference has a set of versions that are tested against each other,
73
+ and this is a major feature of vcpkg.
74
+ We wish to have the same feature in the new versioning world,
75
+ and so we'll have a set of baseline versions in the registry database.
76
+
77
+ Baselines act differently between git registries or the builtin registry,
78
+ and in filesystem registries.
79
+ In git registries and the builtin registry,
80
+ since there's a history that one can access,
81
+ a baseline is the `"default"` entry in the baseline at the reference specified.
82
+ In filesystem registries, since there is no accessible history,
83
+ the baseline identifiers are mapped directly to entries in the baseline file,
84
+ without translation; by default, the `"default"` entry is used.
85
+
86
+ These baselines are placed in `port_versions/baseline.json`.
87
+ This is an object mapping baseline names to baseline objects,
88
+ where baseline objects map port names to version objects.
89
+ A version object contains `"baseline"`, which is un-schemed version,
90
+ and optionally `"port-version"`.
91
+
92
+ [git object ID]: https://git-scm.com/book/en/v2/Git-Internals-Git-Objects
93
+
94
+ ### Example of a baseline file
95
+
96
+ The following is a reasonable baseline.json for a filesystem registry that only has two ports:
97
+
98
+ ```json
99
+ {
100
+ "default": {
101
+ "abseil": { "baseline": "2020-03-03" },
102
+ "zlib": { "baseline": "1.2.11", "port-version": 9 }
103
+ },
104
+ "old": {
105
+ "abseil": { "baseline": "2019-02-11" },
106
+ "zlib": { "baseline": "1.2.11", "port-version": 3 }
107
+ },
108
+ "really-old": {
109
+ "zlib": { "baseline": "1.2.9" }
110
+ }
111
+ }
112
+ ```
113
+
114
+ ### Example of a registry database entry file
115
+
116
+ Note: This file assumes that the versions RFC has been implemented,
117
+ and thus that minimum versions are required;
118
+ the syntax may change in the time between now and finishing the implementation.
119
+
120
+ This example is of `ogre`, since this port has both features and dependencies;
121
+ remember that this file would be `port_versions/o-/ogre.json`.
122
+
123
+ ```json
124
+ [
125
+ {
126
+ "version-string": "1.12.7",
127
+ "git-tree": "466e96fd2e17dd2453aa31dc0bc61bdcf53e7f61",
128
+ },
129
+ {
130
+ "version-string": "1.12.1",
131
+ "port-version": 1,
132
+ "git-tree": "0de81b4f7e0ec24966e929c2ea64e16c15e71d5e",
133
+ },
134
+ ...
135
+ ]
136
+ ```
137
+
138
+ #### Filesystem Registry Databases
139
+
140
+ Filesystem registries are the simplest possible registry;
141
+ they have a `port_versions` directory at the top-level, which contains the registry database.
142
+ It's expected that the filesystem registry would have a filesystem backing store:
143
+ something like the existing `ports` directory, except with separate versions.
144
+ There won't be a specific way to lay the ports tree out as mandated by the tool,
145
+ as we are treating the ports tree as an implementation detail of the registry;
146
+ it's simply a way to get the files for a port.
147
+ As an example, let's assume that the registry is laid out something like this:
148
+
149
+ ```
150
+ <registry>/
151
+ port_versions/
152
+ baseline.json
153
+ a-/
154
+ abseil.json
155
+ asmjit.json
156
+ o-/
157
+ ogre.json
158
+ ports/
159
+ a-/
160
+ abseil/
161
+ 2020-03-03_7/
162
+ vcpkg.json
163
+ portfile.cmake
164
+ ...
165
+ 2020-03-03_8/
166
+ vcpkg.json
167
+ portfile.cmake
168
+ ...
169
+ ...
170
+ asmjit/
171
+ 2020-05-08/
172
+ CONTROL
173
+ portfile.cmake
174
+ ...
175
+ 2020-07-22/
176
+ vcpkg.json
177
+ portfile.cmake
178
+ ...
179
+ o-/
180
+ ogre/
181
+ 1.12.7/
182
+ ...
183
+ 1.12.1/
184
+ ...
185
+ ...
186
+ ...
187
+ ```
188
+
189
+ Then, let's look at updating `asmjit` to latest.
190
+
191
+ The current manifest file, in `asmjit/2020-07-22/vcpkg.json` looks like:
192
+
193
+ ```json
194
+ {
195
+ "name": "asmjit",
196
+ "version-string": "2020-07-22",
197
+ "description": "Complete x86/x64 JIT and Remote Assembler for C++",
198
+ "homepage": "https://github.com/asmjit/asmjit",
199
+ "supports": "!arm"
200
+ }
201
+ ```
202
+
203
+ while the current `port_versions/a-/asmjit.json` looks like:
204
+
205
+ ```json
206
+ [
207
+ {
208
+ "version-string": "2020-07-22",
209
+ "path": "$/ports/a-/asmjit/2020-07-22"
210
+ },
211
+ {
212
+ "version-string": "2020-05-08",
213
+ "path": "$/ports/a-/asmjit/2020-05-08"
214
+ }
215
+ ]
216
+ ```
217
+
218
+ with `port_versions/baseline.json` looking like:
219
+
220
+ ```json
221
+ {
222
+ "default": {
223
+ ...,
224
+ "asmjit": { "baseline": "2020-07-22" },
225
+ ...
226
+ }
227
+ }
228
+ ```
229
+
230
+ and we'd like to update to `2020-10-08`.
231
+ We should first copy the existing implementation to a new folder:
232
+
233
+ ```sh
234
+ $ cp -r ports/a-/asmjit/2020-07-22 ports/a-/asmjit/2020-10-08
235
+ ```
236
+
237
+ then, we'll make the edits required to `ports/a-/asmjit/2020-10-08` to update to latest.
238
+ We should then update `port_versions/a-/asmjit.json`:
239
+
240
+ ```json
241
+ [
242
+ {
243
+ "version-string": "2020-10-08",
244
+ "path": "$/ports/a-/asmjit/2020-10-08"
245
+ },
246
+ {
247
+ "version-string": "2020-07-22",
248
+ "path": "$/ports/a-/asmjit/2020-07-22"
249
+ },
250
+ {
251
+ "version-string": "2020-05-08",
252
+ "path": "$/ports/a-/asmjit/2020-05-08"
253
+ }
254
+ ]
255
+ ```
256
+
257
+ and update `port_versions/baseline.json`:
258
+
259
+ ```json
260
+ {
261
+ "default": {
262
+ ...,
263
+ "asmjit": { "baseline": "2020-10-08" },
264
+ ...
265
+ }
266
+ }
267
+ ```
268
+
269
+ and we're done 😊.
270
+
271
+ #### Git Registry Databases
272
+
273
+ Git registries are not quite as simple as filesystem registries,
274
+ but they're still pretty simple, and are likely to be the most common:
275
+ the default registry is a git registry, for example.
276
+ There is not a specific way the tool requires one to lay out the backing store,
277
+ as long as it's possible to get an object hash that corresponds to a checked-in git tree
278
+ of the build information.
279
+ This allows, for example, the current vcpkg default registry way of laying out ports,
280
+ where the latest version of a port `<P>` is at `ports/<P>`,
281
+ and it also allows for any number of other designs.
282
+ One interesting design, for example,
283
+ is having an `old-ports` branch which is updated whenever someone want to backfill versions;
284
+ then, one could push the old version to the `old-ports` branch,
285
+ and then update the HEAD branch with the git tree of the old version in `port_versions/p-/<P>`.
286
+
287
+ As above, we want to update `asmjit` to latest; let's assume we're working in the default vcpkg registry
288
+ (the <https://github.com/microsoft/vcpkg> repository):
289
+
290
+ The current manifest file for `asmjit` looks like:
291
+
292
+ ```json
293
+ {
294
+ "name": "asmjit",
295
+ "version-string": "2020-07-22",
296
+ "description": "Complete x86/x64 JIT and Remote Assembler for C++",
297
+ "homepage": "https://github.com/asmjit/asmjit",
298
+ "supports": "!arm"
299
+ }
300
+ ```
301
+
302
+ and the current `port_versions/a-/asmjit.json` looks like:
303
+
304
+ ```json
305
+ [
306
+ {
307
+ "version-string": "2020-07-22",
308
+ "git-tree": "fa0c36ba15b48959ab5a2df3463299e1d2473b6f"
309
+ }
310
+ ]
311
+ ```
312
+
313
+ Now, let's update it to the latest version:
314
+
315
+ ```json
316
+ {
317
+ "name": "asmjit",
318
+ "version-string": "2020-10-08",
319
+ "description": "Complete x86/x64 JIT and Remote Assembler for C++",
320
+ "homepage": "https://github.com/asmjit/asmjit",
321
+ "supports": "!arm"
322
+ }
323
+ ```
324
+
325
+ and make the proper edits to the portfile.cmake. Then, let's commit the changes:
326
+
327
+ ```cmd
328
+ > git add ./ports/asmjit
329
+ > git commit -m "[asmjit] update asmjit to 2020-10-08"
330
+ ```
331
+
332
+ In `git-tree` mode, one needs to commit the new version of the port to get the git tree hash;
333
+ we use `git rev-parse` to do so:
334
+
335
+ ```cmd
336
+ > git rev-parse HEAD:ports/asmjit
337
+ 2bb51d8ec8b43bb9b21032185ca8123da10ecc6c
338
+ ```
339
+
340
+ and then modify `port_versions/a-/asmjit.json` as follows:
341
+
342
+ ```json
343
+ [
344
+ {
345
+ "version-string": "2020-10-08",
346
+ "git-tree": "2bb51d8ec8b43bb9b21032185ca8123da10ecc6c"
347
+ },
348
+ {
349
+ "version-string": "2020-07-22",
350
+ "git-tree": "fa0c36ba15b48959ab5a2df3463299e1d2473b6f"
351
+ }
352
+ ]
353
+ ```
354
+
355
+ Then we can commit and push this new database with:
356
+
357
+ ```sh
358
+ $ git add port_versions
359
+ $ git commit --amend --no-edit
360
+ $ git push
361
+ ```
362
+
363
+ ## Consuming Registries
364
+
365
+ The `vcpkg-configuration.json` file from the [first registries RFC](registries.md)
366
+ is still the same, except that the registries have a slightly different layout.
367
+ A `<configuration>` is still an object with the following fields:
368
+ * Optionally, `"default-registry"`: A `<registry-implementation>` or `null`
369
+ * Optionally, `"registries"`: An array of `<registry>`s
370
+
371
+ Additionally, `<registry>` is still the same;
372
+ a `<registry-implementation>` object, plus the following properties:
373
+ * Optionally, `"baseline"`: A named baseline. Defaults to `"default"`.
374
+ * Optionally, `"packages"`: An array of `<package-name>`s
375
+
376
+ however, `<registry-implementation>`s are now slightly different:
377
+ * `<registry-implementation.builtin>`:
378
+ * `"kind"`: The string `"builtin"`
379
+ * `<registry-implementation.filesystem>`:
380
+ * `"kind"`: The string `"filesystem"`
381
+ * `"path"`: A path
382
+ * `<registry-implementation.git>`:
383
+ * `"kind"`: The string `"git"`
384
+ * `"repository"`: A URI
385
+
386
+ The `"packages"` field of distinct registries must be disjoint,
387
+ and each `<registry>` must have at the `"packages"` property,
388
+ since otherwise there's no point.
389
+
390
+ As an example, a package which uses a different default registry, and a different registry for boost,
391
+ might look like the following:
392
+
393
+ ```json
394
+ {
395
+ "default-registry": {
396
+ "kind": "filesystem",
397
+ "path": "vcpkg-ports"
398
+ },
399
+ "registries": [
400
+ {
401
+ "kind": "builtin",
402
+ "packages": [ "cppitertools" ]
403
+ }
404
+ ]
405
+ }
406
+ ```
407
+
408
+ This will install `fmt` from `<directory-of-vcpkg-configuration.json>/vcpkg-ports`,
409
+ and `cppitertools` and the `boost` ports from the registry that ships with vcpkg.
410
+ Notably, this does not replace behavior up the tree -- only the `vcpkg-configuration.json`s
411
+ for the current invocation do anything.
412
+
413
+ ### Filesystem Registries
414
+
415
+ A filesystem registry takes on the form:
416
+
417
+ * `"kind"`: The string `"filesystem"`
418
+ * `"path"`: The path to the filesystem registry's root, i.e. the directory containing the `port_versions` directory.
419
+
420
+ ```json
421
+ {
422
+ "kind": "filesystem",
423
+ "path": "vcpkg-registry"
424
+ }
425
+ ```
426
+
427
+ Unlike git registries, where there's quite a bit of interesting stuff going on,
428
+ there isn't much stuff to do with filesystem registries.
429
+ We simply use the registry database at `<registry root>/port_versions` to get information about ports.
430
+
431
+ ### Git Registries
432
+
433
+ A git registry takes on the form:
434
+
435
+ * `"kind"`: The string `"git"`
436
+ * `"repository"`: The URL at which the git repository lives. May be any kind of URL that git understands
437
+
438
+ ```json
439
+ {
440
+ "kind": "git",
441
+ "repository": "https://github.com/microsoft/vcpkg"
442
+ }
443
+ ```
444
+
445
+ Whenever the first vcpkg command is run with a git registry,
446
+ vcpkg notes down the exact commit that HEAD points to at the time of the run in the `vcpkg-lock.json` file.
447
+ This will be used as the commit which vcpkg takes the `"default"` baseline from,
448
+ and vcpkg will only update that commit when `vcpkg update` is run.
449
+
450
+ Since the `"versions"` field is strictly additive, we don't consider older refs than `HEAD`.
451
+ We update the repository on some reasonable clip.
452
+ Likely, whenever a command is run that will change the set of installed ports.
453
+
454
+ #### `vcpkg-lock.json`
455
+
456
+ This file will contain metadata that we need to save across runs,
457
+ to allow us to keep a "state-of-the-world" that doesn't change unless one explicitly asks for it to change.
458
+ This means that, even across different machines, the same registries will be used.
459
+ We will also be able to write down version resolution in this file as soon as that feature is added.
460
+
461
+ It is recommended that one adds this `vcpkg-lock.json` to one's version control.
462
+ This file is machine generated, and it is not specified how it's laid out;
463
+ however, for purposes of this RFC, we will define how it relates to git registries.
464
+
465
+ In `vcpkg-lock.json`, in the top level object,
466
+ there will be a `"registries"` property that is an object.
467
+ This object will contain a `"git"` field, which is an array of git-registry objects,
468
+ that contain:
469
+
470
+ * `"repository"`: The `"repository"` field from the git registry object
471
+ * `"baseline"`: The name of the baseline that we've used
472
+ * `"baseline-ref"`: The ref which we've gotten the specific baseline from.
473
+
474
+ For example, a `vcpkg-lock.json` might look like:
475
+
476
+ ```json
477
+ {
478
+ "registries": {
479
+ "git": [
480
+ {
481
+ "repository": "https://github.com/microsoft/vcpkg",
482
+ "baseline": "default",
483
+ "baseline-ref": "6185aa76504a5025f36754324abf307cc776f3da"
484
+ }
485
+ ]
486
+ }
487
+ }
488
+ ```
489
+
490
+ #### `vcpkg update`
491
+
492
+ You'll notice that once the repository is added the first time,
493
+ there is only one way to update the repository to the tag at a later date - deleting the lock file.
494
+ We additionally want to add support for the user updating the registry by themselves -
495
+ they will be able to do this via the `vcpkg update` command.
496
+ The `vcpkg update` command will, for each git registry,
497
+ update the registry and repoint the `"commit"` field in `vcpkg-lock.json` to the latest `HEAD`.
498
+
499
+ There is no way to update only one git registry to a later date, since versions are strictly additive.
500
+
501
+ ## Git Registries: Implementation on Disk
502
+
503
+ There are two implementations on disk to consider here: the implementation of the registry database,
504
+ and once we have the database entries for the ports, accessing the port data from the git tree object.
505
+
506
+ Both of these implementations are placed in the vcpkg cache home (shared by binary caching archives).
507
+ On unix, this is located at `$XDG_CACHE_HOME/vcpkg` if the environment variable exists,
508
+ otherwise `$HOME/.cache/vcpkg`; on Windows, it's located at `%LOCALAPPDATA%\vcpkg`.
509
+ In this document, we use the variable `$CACHE_ROOT` to refer to this folder.
510
+ We will add a new folder, `$CACHE_ROOT/registries`, which will contain all the data we need.
511
+
512
+ First, we'll discuss the registry database.
513
+
514
+ ### Registry Database
515
+
516
+ At `$CACHE_ROOT/registries/git`,
517
+ we'll create a new git repository root which contains all information from all git registries,
518
+ since the hashes should be unique, and this allows for deduplication
519
+ across repositories which have the same commits (e.g., for mirrors).
520
+ In order to get the data from git registries, we simply `fetch` the URL of the git registry.
521
+
522
+ In order to grab a specific database entry from a git registry, `git show` is used to grab the
523
+ file from the right commit: `git show <commit id> -- port_versions/<first character>-/<portname>.json`.
524
+
525
+ One unfortunate thing about having one directory being used for all vcpkg instances on a machine is
526
+ that it's possible to have an issue with concurrency - for example, after `fetch`ing the latest HEAD
527
+ of `https://github.com/microsoft/vcpkg`, another vcpkg process might fetch the latest HEAD of
528
+ `https://github.com/meow/vcpkg` before the first vcpkg process has the chance to `git rev-parse FETCH_HEAD`.
529
+ Since the first vcpkg process will run `git rev-parse` after the second fetch is done,
530
+ instead of getting the `HEAD` of `microsoft/vcpkg`, they instead get the `HEAD` of `meow/vcpkg`.
531
+ We will solve this by having a mutex file in `$CACHE_ROOT/registries/git`
532
+ that vcpkg locks before any fetches (and unlocks after `rev-parse`ing).
533
+
534
+ ### Accessing Port Data from `git-tree`s
535
+
536
+ Once we've done version resolution and everything with the database,
537
+ we then need to access the port data from the git history.
538
+ We will add a new folder, `$CACHE_ROOT/registries/git-trees`, into which we'll check out the port data.
539
+
540
+ In this `git-trees` directory, we will have all of the trees we check out, at their hashes.
541
+ For example, the asmjit port data from above will be located at
542
+ `git-trees/2bb51d8ec8b43bb9b21032185ca8123da10ecc6c`.
543
+ We will add a mutex file in this `git-trees` directory as well which is taken whenever
544
+ we are checking out a new git tree.
545
+ We wish to allow multiple vcpkg instances to read port data at a time,
546
+ and thus we do the check outs semi-atomically - if `git-trees/<hash>` exists,
547
+ then the `<hash>` must be completely checked out.
548
+ vcpkg does this by first checking out to a temporary directory,
549
+ and then renaming to the actual hash.
550
+
551
+ ## Future Extensions
552
+
553
+ The way forward for this is to allow the `"builtin"` registry to be a git registry,
554
+ in order to support packaging and shipping vcpkg as a binary.
555
+ This is currently our plan, although it definitely is still a ways out.
556
+ Git registries _are_ an important step on that road,
557
+ but are also a good way to support both enterprise,
558
+ and experimentation by our users.
559
+ They allow us a lot more flexibility than we've had in the past.
third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/registries.md ADDED
@@ -0,0 +1,287 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Package Federation: Custom Registries
2
+
3
+ **Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
4
+
5
+ As it is now, vcpkg has over 1400 ports in the default registry (the `/ports` directory).
6
+ For the majority of users, this repository of packages is enough. However, many enterprises
7
+ need to more closely control their dependencies for one reason or another, and this document
8
+ lays out a method which we will build into vcpkg for exactly that reason.
9
+
10
+ ## Background
11
+
12
+ A registry is simply a set of packages. In fact, there is already a registry in vcpkg: the default one.
13
+ Package federation, implemented via custom registries, allows one to add new packages,
14
+ edit existing packages, and have as much or as little control as one likes over the dependencies that one uses.
15
+ It gives the control over dependencies that an enterprise requires.
16
+
17
+ ### How Does the Current Default Registry Work?
18
+
19
+ Of course, the existing vcpkg tool does have packages in the official,
20
+ default registry. The way we describe these packages is in the ports tree –
21
+ at the base of the vcpkg install directory, there is a directory named ports,
22
+ which contains on the order of 1300 directories, one for each package. Then,
23
+ in each package directory, there are at least two files: a CONTROL or
24
+ vcpkg.json file, which contains the name, version, description, and features
25
+ of the package; and a portfile.cmake file which contains the information on
26
+ how to download and build the package. There may be other files in this
27
+ registry, like patches or usage instructions, but only those two files are
28
+ needed.
29
+
30
+ ### Existing vcpkg Registry-like Features
31
+
32
+ There are some existing features in vcpkg that act somewhat like a custom
33
+ registry. The most obvious feature that we have is overlay ports – this
34
+ feature allows you to specify any number of directories as "overlays", which
35
+ either contain a package definition directly, or which contain some number of
36
+ package directories; these overlays will be used instead of the ports tree
37
+ for packages that exist in both places, and are specified exclusively on the
38
+ command line. Additionally, unfortunately, if one installs a package from
39
+ overlay ports that does not exist in the ports tree, one must pass these
40
+ overlays to every vcpkg installation command.
41
+
42
+ There is also the less obvious "feature" which works by virtue of the ports
43
+ tree being user-editable: one can always edit the ports tree on their own
44
+ machine, and can even fork vcpkg and publish their own ports tree.
45
+ Unfortunately, this then means that any updates to the source tree require
46
+ merges, as opposed to being able to fast-forward to the newest sources.
47
+
48
+ ### Why Registries?
49
+
50
+ There are many reasons to want custom registries; however, the most important reasons are:
51
+
52
+ * Legal requirements – a company like Microsoft or Google
53
+ needs the ability to strictly control the code that goes into their products,
54
+ making certain that they are following the licenses strictly.
55
+ * There have been examples in the past where a library which is licensed under certain terms contains code
56
+ which is not legally allowed to be licensed under those terms (see [this example][legal-example],
57
+ where a person tried to merge Microsoft-owned, Apache-licensed code into the GPL-licensed libstdc++).
58
+ * Technical requirements – a company may wish to run their own tests on the packages they ship,
59
+ such as [fuzzing].
60
+ * Other requirements – an organization may wish to strictly control its dependencies for a myriad of other reasons.
61
+ * Newer versions – vcpkg may not necessarily always be up to date for all libraries in our registry,
62
+ and an organization may require a newer version than we ship;
63
+ they can very easily update this package and have the version that they want.
64
+ * Port modifications – vcpkg has somewhat strict policies on port modifications,
65
+ and an organization may wish to make different modifications than we do.
66
+ It may allow that organization to make certain that the package works on triplets
67
+ that our team does not test as extensively.
68
+ * Testing – just like port modifications, if a team wants to do specific testing on triplets they care about,
69
+ they can do so via their custom registry.
70
+
71
+ Then, there is the question of why vcpkg needs a new solution for custom registries,
72
+ beyond the existing overlay ports feature. There are two big reasons –
73
+ the first is to allow a project to define the registries that they use for their dependencies,
74
+ and the second is the clear advantage in the user experience of the vcpkg tool.
75
+ If a project requires specific packages to come from specific registries,
76
+ they can do so without worrying that a user accidentally misses the overlay ports part of a command.
77
+ Additionally, beyond a feature which makes overlay ports easier to use,
78
+ custom registries allow for more complex and useful infrastructure around registries.
79
+ In the initial custom registry implementation, we will allow overlay ports style paths,
80
+ as well as git repositories, which means that people can run and use custom registries
81
+ without writing their own infrastructure around getting people that registry.
82
+
83
+ It is the intention of vcpkg to be the most user-friendly package manager for C++,
84
+ and this allows us to fulfill on that intention even further.
85
+ As opposed to having to write `--overlay-ports=path/to/overlay` for every command one runs,
86
+ or adding an environment variable `VCPKG_OVERLAY_PORTS`,
87
+ one can simply write vcpkg install and the registries will be taken care of for you.
88
+ As opposed to having to use git submodules, or custom registry code for every project,
89
+ one can write and run the infrastructure in one place,
90
+ and every project that uses that registry requires only a few lines of JSON.
91
+
92
+ [legal-example]: https://gcc.gnu.org/legacy-ml/libstdc++/2019-09/msg00054.html
93
+ [fuzzing]: https://en.wikipedia.org/wiki/Fuzzing
94
+
95
+ ## Specification
96
+
97
+ We will be adding a new file that vcpkg understands - `vcpkg-configuration.json`.
98
+ The way that vcpkg will find this file is different depending on what mode vcpkg is in:
99
+ in classic mode, vcpkg finds this file alongside the vcpkg binary, in the root directory.
100
+ In manifest mode, vcpkg finds this file alongside the manifest. For the initial implementation,
101
+ this is all vcpkg will look for; however, in the future, vcpkg will walk the tree and include
102
+ configuration all along the way: this allows for overriding defaults.
103
+ The specific algorithm for applying this is not yet defined, since currently only one
104
+ `vcpkg-configuration.json` is allowed.
105
+
106
+ The only thing allowed in a `vcpkg-configuration.json` is a `<configuration>` object.
107
+
108
+ A `<configuration>` is an object:
109
+ * Optionally, `"default-registry"`: A `<registry-implementation>` or `null`
110
+ * Optionally, `"registries"`: An array of `<registry>`s
111
+
112
+ Since this is the first RFC that adds anything to this field,
113
+ as of now the only properties that can live in that object will be
114
+ these.
115
+
116
+ A `<registry-implementation>` is an object matching one of the following:
117
+ * `<registry-implementation.builtin>`:
118
+ * `"kind"`: The string `"builtin"`
119
+ * `<registry-implementation.directory>`:
120
+ * `"kind"`: The string `"directory"`
121
+ * `"path"`: A path
122
+ * `<registry-implementation.git>`:
123
+ * `"kind"`: The string `"git"`
124
+ * `"repository"`: A URI
125
+ * Optionally, `"path"`: An absolute path into the git repository
126
+ * Optionally, `"ref"`: A git reference
127
+
128
+ A `<registry>` is a `<registry-implementation>` object, plus the following properties:
129
+ * Optionally, `"scopes"`: An array of `<package-name>`s
130
+ * Optionally, `"packages"`: An array of `<package-name>`s
131
+
132
+ The `"packages"` and `"scopes"` fields of distinct registries must be disjoint,
133
+ and each `<registry>` must have at least one of the `"scopes"` and `"packages"` property,
134
+ since otherwise there's no point.
135
+
136
+ As an example, a package which uses a different default registry, and a different registry for boost,
137
+ might look like the following:
138
+
139
+ ```json
140
+ {
141
+ "default-registry": {
142
+ "kind": "directory",
143
+ "path": "vcpkg-ports"
144
+ },
145
+ "registries": [
146
+ {
147
+ "kind": "git",
148
+ "repository": "https://github.com/boostorg/vcpkg-ports",
149
+ "ref": "v1.73.0",
150
+ "scopes": [ "boost" ]
151
+ },
152
+ {
153
+ "kind": "builtin",
154
+ "packages": [ "cppitertools" ]
155
+ }
156
+ ]
157
+ }
158
+ ```
159
+
160
+ This will install `fmt` from `<directory-of-vcpkg.json>/vcpkg-ports`,
161
+ `cppitertools` from the registry that ships with vcpkg,
162
+ and any `boost` dependencies from `https://github.com/boostorg/vcpkg-ports`.
163
+ Notably, this does not replace behavior up the tree -- only the `vcpkg-configuration.json`s
164
+ for the current invocation do anything.
165
+
166
+ ### Behavior
167
+
168
+ When a vcpkg command requires the installation of dependencies,
169
+ it will generate the initial list of dependencies from the package,
170
+ and then run the following algorithm on each dependency:
171
+
172
+ 1. Figure out which registry the package should come from by doing the following:
173
+ 1. If there is a registry in the registry set which contains the dependency name in the `"packages"` array,
174
+ then use that registry.
175
+ 2. For every scope, in order from most specific to least,
176
+ if there is a registry in the registry set which contains that scope in the `"scopes"` array,
177
+ then use that registry.
178
+ (For example, for `"cat.meow.cute"`, check first for `"cat.meow.cute"`, then `"cat.meow"`, then `"cat"`).
179
+ 3. If the default registry is not `null`, use that registry.
180
+ 4. Else, error.
181
+ 2. Then, add that package's dependencies to the list of packages to find, and repeat for the next dependency.
182
+
183
+ vcpkg will also rerun this algorithm whenever an install is run with different configuration.
184
+
185
+ ### How Registries are Laid Out
186
+
187
+ There are three kinds of registries, but they only differ in how the registry gets onto one's filesystem.
188
+ Once the registry is there, package lookup runs the same, with each kind having it's own way of defining its
189
+ own root.
190
+
191
+ In order to find a port `meow` in a registry with root `R`, vcpkg first sees if `R/meow` exists;
192
+ if it does, then the port root is `R/meow`. Otherwise, see if `R/m-` exists; if it does,
193
+ then the port root is `R/m-/meow`. (note: this algorithm may be extended further in the future).
194
+
195
+ For example, given the following port root:
196
+
197
+ ```
198
+ R/
199
+ abseil/...
200
+ b-/
201
+ boost/...
202
+ boost-build/...
203
+ banana/...
204
+ banana/...
205
+ ```
206
+
207
+ The port root for `abseil` is `R/abseil`; the port root for `boost` is `R/b-/boost`;
208
+ the port root for `banana` is `R/banana` (although this duplication is not recommended).
209
+
210
+ The reason we are making this change to allow more levels in the ports tree is that ~1300
211
+ ports are hard to look through in a tree view, and this allows us to see only the ports we're
212
+ interested in. Additionally, no port name may end in a `-`, so this means that these port subdirectories
213
+ will never intersect with actual ports. Additionally, since we use only ASCII for port names,
214
+ we don't have to worry about graphemes vs. code units vs. code points -- in ASCII, they are equivalent.
215
+
216
+ Let's now look at how different registry kinds work:
217
+
218
+ #### `<registry.builtin>`
219
+
220
+ For a `<registry.builtin>`, there is no configuration required.
221
+ The registry root is simply `<vcpkg-root>/ports`.
222
+
223
+ #### `<registry.directory>`
224
+
225
+ For a `<registry.directory>`, it is again fairly simple.
226
+ Given `$path` the value of the `"path"` property, the registry root is either:
227
+
228
+ * If `$path` is absolute, then the registry root is `$path`.
229
+ * If `$path` is drive-relative (only important on Windows), the registry root is
230
+ `(drive of vcpkg.json)/$path`
231
+ * If `$path` is relative, the registry root is `(directory of vcpkg.json)/$path`
232
+
233
+ Note that the path to vcpkg.json is _not_ canonicalized; it is used exactly as it is seen by vcpkg.
234
+
235
+ #### `<registry.git>`
236
+
237
+ This registry is the most complex. We would like to cache existing registries,
238
+ but we don't want to ignore new updates to the registry.
239
+ It is the opinion of the author that we want to find more updates than not,
240
+ so we will update the registry whenever the `vcpkg.json` or `vcpkg-configuration.json`
241
+ is modified. We will do so by keeping a sha512 of the `vcpkg.json` and `vcpkg-configuration.json`
242
+ inside the `vcpkg-installed` directory.
243
+
244
+ We will download the specific ref of the repository to a central location (and update as needed),
245
+ and the root will be either: `<path to repository>`, if the `"path"` property is not defined,
246
+ or else `<path to repository>/<path property>` if it is defined.
247
+ The `"path"` property must be absolute, without a drive, and will be treated as relative to
248
+ the path to the repository. For example:
249
+
250
+ ```json
251
+ {
252
+ "kind": "git",
253
+ "repository": "https://github.com/microsoft/vcpkg",
254
+ "path": "/ports"
255
+ }
256
+ ```
257
+
258
+ is the correct way to refer to the registry built in to vcpkg, at the latest version.
259
+
260
+ The following are all incorrect:
261
+
262
+ ```json
263
+ {
264
+ "$reason": "path can't be drive-absolute",
265
+ "kind": "git",
266
+ "repository": "https://github.com/microsoft/vcpkg",
267
+ "path": "F:/ports"
268
+ }
269
+ ```
270
+
271
+ ```json
272
+ {
273
+ "$reason": "path can't be relative",
274
+ "kind": "git",
275
+ "repository": "https://github.com/microsoft/vcpkg",
276
+ "path": "ports"
277
+ }
278
+ ```
279
+
280
+ ```json
281
+ {
282
+ "$reason": "path _really_ can't be relative like that",
283
+ "kind": "git",
284
+ "repository": "https://github.com/microsoft/vcpkg",
285
+ "path": "../../meow/ports"
286
+ }
287
+ ```
third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/scripts-extraction.md ADDED
@@ -0,0 +1,66 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Scripts Tree Extraction
2
+
3
+ **Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
4
+
5
+ ## Background
6
+
7
+ We extracted vcpkg-tool as part of a future wherein Registries are the primary mechanism for interacting with the ports tree, which would allow the vcpkg tool and associated artifacts to be deployed and figure the rest out on their own. Unfortunately, we have concurrently edited things in the so called "scripts" tree which lives in support of ports but really probably belongs in the vcpkg-tool repo.
8
+
9
+ Moreover, as part of stabilizing registries, the interface exposed by the scripts tree becomes contractual rather than something we can change in concert with ports, since we can no longer see the universe of ports to validate that changes are correct.
10
+
11
+ To that end we are auditing the contents of the scripts tree to make sure it is a solid foundation for future work.
12
+
13
+ The work list is contained in [Issue #16188].
14
+
15
+ [Issue #16188]: https://github.com/microsoft/vcpkg/issues/16188
16
+
17
+ ## Audit Points
18
+
19
+ The following are assertions we want to be able to make about the contents of the scripts tree. Note that this does *not* refer to `vcpkg.cmake` since that needs to work with older versions of cmake.
20
+
21
+ These are design ideals that we may break in some limited cases where that makes sense.
22
+
23
+ - We always use `cmake_parse_arguments` rather than function parameters, or referring to `${ARG<N>}`.
24
+ - Exception: there are exclusively positional parameters. This should be _very rare_.
25
+ - In this case, positional parameters should be put in the function declaration
26
+ (rather than using `${ARG<N>}`), and should be named according to local rules
27
+ (i.e. `snake_case`).
28
+ - Exception: positional parameters that are optional should be given a name via
29
+ `set(argument_name "${ARG<N>}") after checking `${ARGC}`.
30
+ - Note: in cases where there are positional parameters along with non-positional parameters, positional parameters should be referred to by `arg_UNPARSED_ARGUMENTS`.
31
+ - All `cmake_parse_arguments` use `PARSE_ARGV` for resistance to embedded semicolons.
32
+ - All `foreach` loops use `IN LISTS` for resistance to embedded semicolons.
33
+ - The variable `${ARGV}` is unreferenced.
34
+ - We use functions, not macros or top level code.
35
+ - Scripts in the scripts tree should not be expected to need changes as part of normal operation. (For example, `vcpkg_acquire_msys` has hard coded specific packages and versions thereof used which we believe is unacceptable)
36
+ - All non-splat variable expansions are in quotes "".
37
+ - There are no "pointer" parameters (where a user passes a variable name rather than the contents) except for out parameters.
38
+ - Undefined names are not referenced.
39
+ - Out parameters only set `PARENT_SCOPE`.
40
+ - `CACHE` variables are not used.
41
+ - `include()`s are removed and fixes to `port.cmake` et al. are made as necessary to avoid this.
42
+ - `foreach(RANGE)`'s arguments _must always be_ natural numbers, and `<start>` _must always be_ less than or equal to `<stop>`.
43
+ - This should be checked.
44
+
45
+ ### Naming Variables
46
+
47
+ - `cmake_parse_arguments`: set prefix to `"arg"`
48
+ - local variables are named `snake_case`
49
+ - Internal global variable names are named `Z_VCPKG_`.
50
+ - External experimental global variable names are named `X_VCPKG_`.
51
+ - Internal functions are named `z_vcpkg_*`
52
+ - Functions which are internal to a single function (i.e., helper functions)
53
+ are named `[z_]<func>_<name>`, where `<func>` is the name of the function they are
54
+ a helper to, and `<name>` is what the helper function does.
55
+ - `z_` should be added to the front if `<func>` doesn't have a `z_`,
56
+ but don't name a helper function `z_z_foo_bar`.
57
+ - Public global variables are named `VCPKG_`.
58
+
59
+ ## Prognosis
60
+
61
+ Not everything should remain in the scripts tree. As part of this audit, each helper will be dealt with in one of several ways:
62
+
63
+ - Stay in scripts tree
64
+ - Deleted outright
65
+ - Moved to a tool port
66
+ - Deprecated
third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/versioning.md ADDED
@@ -0,0 +1,357 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Versioning Specification
2
+
3
+ **Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
4
+
5
+ **Up-to-date documentation is available at [Versioning](../users/versioning.md).**
6
+
7
+ ## Glossary
8
+ Some of the terms used in this document have similar meaning when discussed by the community, and because of that, they can cause confusion and ambiguity. To solve this issue, we will assign specific meaning to these terms and try to keep a consistent usage through the document.
9
+
10
+ **Library**: A piece of software (source code, binary files, documentation, license, etc.) that is intended to be reused by other software.
11
+
12
+ **Package**: A package can contain a library, collection of libraries, build scripts, software tools, or other components necessary for their use. The goal of vcpkg is to facilitate the installation of these packages in the user's environment.
13
+
14
+ **Port**: A vcpkg specific term, a port contains:
15
+
16
+ * Metadata about a package: package version, supported features, dependencies, etc.
17
+ * Instructions to acquire, build if necessary, and install the package.
18
+
19
+ ## 1 Enabling package versioning
20
+ On launch, the versioning feature will be disabled by default. Users can enable this feature by setting the `versions` feature flag.
21
+
22
+ Example:
23
+ ```
24
+ vcpkg --feature-flags=versions install
25
+ ```
26
+
27
+ ### 1.1 Proposed experience
28
+ This feature requires the use of manifests to declare project dependencies. To allow versioning, the following features are added to manifests:
29
+
30
+ * Ability to declare a package's versioning scheme.
31
+ * Ability to declare version constraints on dependencies.
32
+ * Ability for a top-level manifest to override all other version constraints.
33
+ * Ability to declare a baseline for all versions.
34
+
35
+ Example: A manifest (`vcpkg.json`) using versioning features.
36
+ ```json
37
+ {
38
+ "name": "versions-test",
39
+ "version": "1.0.0",
40
+ "dependencies": ["fmt", {"name": "zlib", "version>=": "1.2.11"}],
41
+ "$x-default-baseline": "9fd3bd594f41afb8747e20f6ac9619f26f333cbe"
42
+ }
43
+ ```
44
+
45
+ The example above shows some new manifest properties:
46
+ * `"version"`: Declares a version using a dot-separated versioning scheme (`1.0.0`).
47
+ * `"version>="`: Declares a minimum version constraint on package `zlib`.
48
+ * `"$x-default-baseline"`: Declares a baseline version for all packages.
49
+
50
+ All these new features are described in more detail in this document.
51
+
52
+ ## 2 Specifying package versions
53
+ Through the years, C++ software authors have adopted multiple versioning schemes and practices that sometimes conflict between each other. On vcpkg, the most recurrent versioning schemes found are:
54
+ * Semantic versions
55
+ * Dates
56
+ * Repository commits
57
+ * Arbitrary strings
58
+
59
+ For vcpkg to achieve wide adoption and compatibility with existing projects, it is important that we respect the versioning schemes used by each of the packages contained in our ports catalog.
60
+
61
+ ### 2.1 Port versions
62
+ Package versioning information is divided in two parts: a version string and a port version.
63
+ Port versions are a concept exclusive to vcpkg, they do not form part of a package’s upstream. But allow for versioning of the vcpkg ports themselves.
64
+
65
+ Packages can also include the port version as part of a version constraint by using the “port-version” property on their dependencies.
66
+
67
+ #### `port-version`
68
+
69
+ An integer value that increases each time a vcpkg-specific change is made to the port.
70
+
71
+ The rules for port versions are:
72
+ * Start at 0 for the original version of the port,
73
+ * increase by 1 each time a vcpkg-specific change is made to the port that does not increase the version of the package,
74
+ * and reset to 0 each time the version of the package is updated.
75
+
76
+ Defaults to 0 if omitted.
77
+
78
+ ### 2.2 Package versions
79
+ Versions are an important part of a package’s upstream metadata. Ports in vcpkg should attempt to follow the versioning conventions used by the package’s authors. For that reason, when declaring a package’s version the appropriate scheme should be used.
80
+
81
+ Each versioning scheme defines their own rules on what is a valid version string and more importantly the rules for how to sort versions using the same scheme.
82
+
83
+ The versioning schemes understood by vcpkg are:
84
+
85
+ Manifest property | Versioning scheme
86
+ ------------------|------------------------------------
87
+ `version` | For dot-separated numeric versions
88
+ `version-semver` | For SemVer compliant versions
89
+ `version-date` | For dates in the format YYYY-MM-DD
90
+ `version-string` | For arbitrary strings
91
+
92
+ A manifest must contain only one version declaration.
93
+
94
+ #### `version`
95
+ Accepts version strings that follow a relaxed, dot-separated-, semver-like scheme.
96
+
97
+ The version is logically composed of dot-separated (`.`) numeric sections. Each section must contain an integer positive number with no leading zeroes.
98
+
99
+ The regex pattern for this versioning scheme is: `(0|[1-9]\d*)(\.(0|[1-9]\d*))*`
100
+
101
+ _Sorting behavior_: When comparing two versions, each section is compared from left to right by their numeric value, until the first difference is found. A version with the smallest set of sections takes precedence over another with a larger set of sections, given that all their preceding sections compare equally.
102
+
103
+ Example:
104
+ `0` < `0.1` < `0.1.0` < `1` < `1.0.0` < `1.0.1` < `1.1`< `2.0.0`
105
+
106
+ #### `version-semver`
107
+ Accepts version strings that follow semantic versioning conventions as described in the [semantic versioning specification](https://semver.org/#semantic-versioning-specification-semver).
108
+
109
+ _Sorting behavior_: Strings are sorted following the rules described in the semantic versioning specification.
110
+
111
+ Example:
112
+ `1.0.0-1` < `1.0.0-alpha` < `1.0.0-beta` < `1.0.0` < `1.0.1` < `1.1.0`
113
+
114
+ #### `version-date`
115
+
116
+ Accepts version strings that can be parsed to a date following the ISO-8601 format `YYYY-MM-DD`. Disambiguation identifiers are allowed in the form of dot-separated-, positive-, integer-numbers with no leading zeroes.
117
+
118
+ The regex pattern for this versioning scheme is: `\d{4}-\d{2}-\d{2}(\.(0|[1-9]\d*))*`.
119
+
120
+ _Sorting behavior_: Strings are sorted first by their date part, then by numeric comparison of their disambiguation identifiers. Disambiguation identifiers follow the rules of the relaxed (version) scheme.
121
+
122
+ Examples:
123
+ `2020-01-01` < `2020-01-01.1` < `2020-02-01.1.2` < `2020-02-01.1.3` < `2020-02-01`
124
+
125
+ #### `version-string`
126
+ For packages using version strings that do not fit any of the other schemes, it accepts most arbitrary strings, but some special characters like `#` are disallowed.
127
+
128
+ _Sorting behavior_: No sorting is attempted on the version string itself. However, if the strings match exactly, the port versions can be compared and sorted.
129
+
130
+ Examples:
131
+ `apple` <> `orange` <> `orange.2` <> `orange2`
132
+ `watermelon` (`port-version`: 0) < `watermelon` (`port-version`: 1)
133
+
134
+ ##### Example: Manifests using different versioning schemes
135
+ ```json
136
+ {
137
+ "name": "openssl",
138
+ "version": "1.1.1",
139
+ "port-version": 0
140
+ }
141
+ ```
142
+ ```json
143
+ {
144
+ "name": "bzip2",
145
+ "version-semver": "1.0.8",
146
+ }
147
+ ```
148
+ ```json
149
+ {
150
+ "name": "abseil",
151
+ "version-date": "2020-03-03",
152
+ "port-version": 8
153
+ }
154
+ ```
155
+ ```json
156
+ {
157
+ "name": "d3dx12",
158
+ "version-string": "may2020",
159
+ "port-version": 0
160
+ }
161
+ ```
162
+
163
+ ## 3 Specifying dependency versions
164
+
165
+ ### 3.1 On manifest files
166
+ Manifest files help users specify complex versioned dependency graphs in a declarative manner. In this document we define a top-level manifest as the manifest file written by a user to declare their project’s dependencies. This is opposed to a port’s manifest file, which is used by port’s to declare the dependencies of the package it contains.
167
+
168
+ There are three mechanisms you can use in your manifest files to control which versions of your packages are installed: **version constraints, registry baselines and overrides**.
169
+
170
+ #### Version constraints
171
+ Specifying a version constraint is the most direct way to control which version of a package is installed, in vcpkg you can declare minimum version constraints using the syntax `"version>=": "1.0.0"`.
172
+
173
+ #### Registry baseline
174
+ Baselines are used to set lower boundaries on package versions. A baseline effectively adds a minimum version constraint on all the packages declared in it.
175
+
176
+ But what is a baseline?
177
+
178
+ In the main registry, the baseline is a file located in `${VCPKG_ROOT}/versions/baseline.json`. This file contains a version declaration for each package in vcpkg. The format of this file is the following:
179
+
180
+ ```json
181
+ {
182
+ "default": [
183
+ {
184
+ ...
185
+ "fmt": { "version-semver": "7.1.2", "port-version": 0},
186
+ ...
187
+ }
188
+ ]
189
+ }
190
+ ```
191
+
192
+ The baseline file is tracked under source control. For any given revision of the registry, the versions declared in the baseline file must match the current versions of the ports in the registry at that revision.
193
+
194
+ Old revisions of vcpkg that do not contain a baseline file can still work with versioning. As a fallback, if no baseline is available at a given revision, vcpkg will use its local baseline file. If a local baseline file does not exist, the local version of the port will be used as the baseline version.
195
+
196
+ Baselines define a minimum version constraint an all packages contained in it.
197
+
198
+ For example, if the baseline contains the entry:
199
+ ```
200
+ “fmt”: { “version-semver”: “7.1.2”, “port-version”: 0 }
201
+ ```
202
+
203
+ A minimum version constraint will be added to `fmt` so that vcpkg won’t install a version lower than `7.1.2` with port version `0`.
204
+
205
+ #### Overrides
206
+ Declaring an override forces vcpkg to ignore all other constraints, both top-level and transitive constraints, and use the version specified in the override. This is useful for pinning exact versions and for resolving version conflicts.
207
+
208
+ ## 4 Version constraints
209
+
210
+ ### 4.1 Declaring a baseline
211
+ For the initial implementation, the method to declare a baseline is to set the `“$x-default-baseline”` property.
212
+
213
+ The use of `“$x-default-baseline”` is temporary and will very likely change in the future, as we work on implementing custom registries.
214
+
215
+ #### `$x-default-baseline`
216
+ Accepts a Git commit ID. Vcpkg will try to find a baseline file in the given commit ID and use that to set the baseline versions (lower bound versions) of all declared dependencies.
217
+
218
+ When resolving version constraints for a package, vcpkg will look for a baseline version:
219
+ * First by looking at the baseline file in the given commit ID.
220
+ * If the given commit ID does not contain a baseline file, vcpkg will fallback to use the local baseline file instead.
221
+ * If there’s no local baseline file, vcpkg will use the version currently available in the ports directory.
222
+
223
+ _NOTE: If a baseline file is found, but it does not contain an entry for the package, the vcpkg invocation will fail._
224
+
225
+ Example:
226
+ ```json
227
+ {
228
+ "name": "project",
229
+ "version": "1.0.0",
230
+ "dependencies": ["zlib", "fmt"],
231
+ "$x-default-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe"
232
+ }
233
+ ```
234
+
235
+ Baselines can be used without any other version constraints to obtain behavior close to using “classic” mode.
236
+
237
+ ### 4.2 Declaring minimum version constraints
238
+ A minimum version requirement puts a lower boundary on the versions that can be used to satisfy a dependency. This means that any version that is newer than the requirement is valid (including major version changes).
239
+
240
+ Vcpkg will use the oldest identified version that can satisfy all the version requirements in a build graph. Using a minimum version approach has the following advantages:
241
+ * Is predictable and easy to understand.
242
+ * User controls when upgrades happen, as in, no upgrades are performed automatically when a new version is released.
243
+ * Avoids using a SAT solver.
244
+
245
+ Minimum version requirements are expressed by using the `"version>="` property in the dependencies list.
246
+
247
+ Example:
248
+ ```json
249
+ {
250
+ "name": "project",
251
+ "version-semver": "1.0.0",
252
+ "dependencies": [
253
+ { "name": "zlib", "version>=": "1.2" },
254
+ { "name": "rapidjson", "version>=": "2020-02-01" }
255
+ ]
256
+ }
257
+ ```
258
+
259
+ ### 4.3 Declaring port version constraints
260
+ To be consistent with the minimum version approach, vcpkg uses the lowest available port version that matches the package version. There are many scenarios where a higher port version is desirable, e.g.: support for new platforms, fixing installation issues, among others.
261
+
262
+ As part of the dependency object a port version can be specified. An error will be emitted if a non-existent port-version for the given package version is requested.
263
+
264
+ Example:
265
+ ```json
266
+ {
267
+ "name": "project",
268
+ "version-semver": "1.0.0",
269
+ "dependencies": [
270
+ { "name": "zlib", "version>=": "1.2" },
271
+ { "name": "rapidjson", "version=": "2020-02-01", "port-version": 2 }
272
+ ]
273
+ }
274
+ ```
275
+
276
+ ### 4.4 Declaring overrides
277
+ Overrides are declared as an array of package version declarations.
278
+
279
+ For an override to take effect, the overridden package must form part of the dependency graph. That means that a dependency must be declared either by the top-level manifest or be part of a transitive dependency.
280
+
281
+ Example:
282
+ ```json
283
+ {
284
+ "name": "project",
285
+ "version": "1.0.0",
286
+ "dependencies": ["cpprestsdk"],
287
+ "overrides": [{"name":"zlib", "version-semver":"1.2.10"}],
288
+ "$x-default-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe"
289
+ }
290
+ ```
291
+
292
+ In the previous example, `zlib` is not a direct dependency of the project but it is a dependency for `cpprestsdk`, so the override takes effect forcing `zlib` to version `1.2.10`.
293
+
294
+ ## 5 Design considerations
295
+
296
+ ### 5.1 Constraint resolution
297
+ Given a manifest with a set of versioned dependencies, vcpkg will attempt to calculate a package installation plan that satisfies all the constraints. Constraints can be declared in the top-level manifest but can also be added transitively by indirect dependencies.
298
+
299
+ Vcpkg roughly follows the steps below to compute an installation plan, the installation plan will either contain a valid set of package versions, or a list of version conflicts.
300
+
301
+ * Add all top-level constraints to the plan.
302
+ * Recursively add transitive constraints to the plan.
303
+ * Each time a constraint is added for a package, also add it’s baseline version as a minimum constraint.
304
+ * Each time a constraint is added:
305
+ * If an override exists for the package, select the version in the override.
306
+ * Otherwise:
307
+ * If there is no previous version selected.
308
+ * Select the minimal version that satisfies the constraint.
309
+ * If there is a previous version selected:
310
+ * If the versioning scheme of the new constraint does not match that of the previously selected version:
311
+ * Add a version conflict.
312
+ * If the constraint’s version is not comparable to the previously selected version. For example, comparing “version-string: apple” to “version-string: orange”:
313
+ * Add a version conflict.
314
+ * If the constraints version is higher than the previously selected version:
315
+ * Select the highest version.
316
+ * Otherwise, keep the previous selection.
317
+ * Review the plan:
318
+ * If there are no conflicts, install the selected packages.
319
+ * Otherwise, report the conflicts to the user.
320
+
321
+ ### 5.2 Acquiring port versions
322
+ Although the concept of package versions has always been present in vcpkg, the concept of version constraints has been not.
323
+
324
+ With the introduction of versioning constraints, it is now possible that a package depends on a port version that does not match the one available locally. This raises a problem as vcpkg needs to know how to acquire the port files for the requested version.
325
+
326
+ To solve this problem, a new set of metadata needs to be introduced. This specification proposes a that a new "versions" folder is added as part of a registry. In the main vcpkg registry, this means a new root level versions directory.
327
+
328
+ The versions directory, from here on referred as the versions database, will contain JSON files for each one of the ports available in the registry. Each file will list all the versions available for a package and contain a Git tree-ish object that vcpkg can check out to obtain that version’s portfiles.
329
+
330
+ As part of the versioning implementation, a generator for these database files will be implemented. The generator will extract from our repository’s Git history, all the versions of each port that had been available at any moment in time and compile them into these database files.
331
+
332
+ Example: generated `zlib.json`
333
+ ```json
334
+ {
335
+ "versions": [
336
+ {
337
+ "git-tree": "2dfc991c739ab9f2605c2ad91a58a7982eb15687",
338
+ "version-string": "1.2.11",
339
+ "port-version": 9
340
+ },
341
+ { “$truncated for brevity” },
342
+ {
343
+ "git-tree": "a516e5ee220c8250f21821077d0e3dd517f02631",
344
+ "version-string": "1.2.10",
345
+ "port-version": 0
346
+ },
347
+ {
348
+ "git-tree": "3309ec82cd96d752ff890c441cb20ef49b52bf94",
349
+ "version-string": "1.2.8",
350
+ "port-version": 0
351
+ }
352
+ ]
353
+ }
354
+ ```
355
+
356
+ For each port, its corresponding versions file should be located in `versions/{first letter of port name}-/{port name}.json`. For example, zlib’s version file will be located in `versions/z-/zlib.json`.
357
+ Aside from port version files, the current baseline file is located in `versions/baseline.json`.
third-party/DPVO/Pangolin/scripts/vcpkg/docs/users/android.md ADDED
@@ -0,0 +1,224 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Vcpkg and Android
2
+
3
+ **The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/android.md).**
4
+
5
+ Android is not officially supported, and there are no official android triplets at the moment.
6
+
7
+ However, some packages can compile to Android, and the situation is improving: see the list of [PR related to Android](https://github.com/Microsoft/vcpkg/pulls?q=+android+).
8
+
9
+
10
+ ## Android build requirements
11
+
12
+ 1. Download the [android ndk](https://developer.android.com/ndk/downloads/)
13
+
14
+ 2. Set environment variable `ANDROID_NDK_HOME` to your android ndk installation.
15
+ For example:
16
+
17
+ ````bash
18
+ export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle
19
+ ````
20
+
21
+ Or:
22
+ ````bash
23
+ export ANDROID_NDK_HOME=/home/your-account/Android/android-ndk-r21b
24
+ ````
25
+
26
+ 3. Install [vcpkg](https://github.com/microsoft/vcpkg)
27
+
28
+ 4. Set environment variable `VCPKG_ROOT` to your vcpkg installation.
29
+ ````bash
30
+ export VCPKG_ROOT=/path/to/vcpkg
31
+ ````
32
+
33
+ ## vcpkg triplets and their corresponding android ABI
34
+
35
+ There are four different Android ABI, each of which maps to
36
+ a vcpkg triplet. The following table outlines the mapping from vcpkg architectures to android architectures
37
+
38
+ |VCPKG_TARGET_TRIPLET | ANDROID_ABI |
39
+ |---------------------------|----------------------|
40
+ |arm64-android | arm64-v8a |
41
+ |arm-android | armeabi-v7a |
42
+ |x64-android | x86_64 |
43
+ |x86-android | x86 |
44
+
45
+ ## Install libraries for Android using vcpkg
46
+
47
+ Example for jsoncpp:
48
+
49
+ ````bash
50
+ cd $VCPKG_ROOT
51
+
52
+ # specify the triplet like this
53
+ ./vcpkg install jsoncpp --triplet arm-android
54
+ # or like this
55
+ ./vcpkg install jsoncpp:arm64-android
56
+ ./vcpkg install jsoncpp:x86-android
57
+ ./vcpkg install jsoncpp:x64-android
58
+ ````
59
+
60
+ ### Using Vulkan SDK
61
+
62
+ Vcpkg has a [`vulkan` package](https://github.com/microsoft/vcpkg/blob/master/ports/vulkan/portfile.cmake) which allows you to `find_package(Vulkan)`. To use it you have to provide `VULKAN_SDK` environment variable.
63
+
64
+ ```bash
65
+ export VULKAN_SDK=/usr/local
66
+ ./vcpkg install vulkan
67
+ ```
68
+
69
+ NDK already contains [Vulkan](https://developer.android.com/ndk/guides/graphics/getting-started) headers and `libvulkan.so` binaries for each of its architecture.
70
+ To expose them to VcPkg, you can consider `export VULKAN_SDK=...` for each installation.
71
+ But by placing `set(ENV{VULKAN_SDK} ...)` in the triplet files, you can skip the tedious work.
72
+
73
+ If you are using NDK 21.3.6528147 or earlier version, it will be like the following.
74
+
75
+ ```cmake
76
+ # In android triplets... (e.g. arm64-android.cmake)
77
+ set(VCPKG_CMAKE_SYSTEM_NAME Android)
78
+ # ...
79
+ # If your API level is 30, libvulkan.so is at $ENV{ANDROID_NDK_HOME}/platforms/android-30/arch-arm64/usr/lib
80
+ set(ENV{VULKAN_SDK} $ENV{ANDROID_NDK_HOME}/sysroot/usr)
81
+ ```
82
+
83
+ Notice that **the location of the sysroot has changed since NDK 22**. (see https://github.com/android/ndk/issues/1407)
84
+ If you prefer using [the latest version](https://developer.android.com/studio/projects/install-ndk#default-ndk-per-agp), check the [BuildSystemMaintainers.md of the NDK document](https://android.googlesource.com/platform/ndk/+/master/docs/BuildSystemMaintainers.md#sysroot) and then put appropriate path for your system.
85
+
86
+ For example, Mac OS users will use the path like this.
87
+
88
+ ```cmake
89
+ # In android triplets... (e.g. arm64-android.cmake)
90
+ set(VCPKG_CMAKE_SYSTEM_NAME Android)
91
+ # ...
92
+ # If your API level is 30, libvulkan.so is at $ENV{ANDROID_NDK_HOME}/toolchains/llvm/prebuilt/darwin-x86_64/sysroot/usr/lib/aarch64-linux-android/30
93
+ set(ENV{VULKAN_SDK} $ENV{ANDROID_NDK_HOME}/toolchains/llvm/prebuilt/darwin-x86_64/sysroot/usr)
94
+ ```
95
+
96
+ By doing this for all android triplets, you can install `vulkan` and the packages that require it. (e.g. `vulkan-hpp`)
97
+
98
+ <details>
99
+ <summary markdown="span">`vcpkg install vulkan-hpp:arm64-android`</summary>
100
+
101
+ ```console
102
+ user@host$ ./vcpkg install vulkan-hpp:arm64-android
103
+ Computing installation plan...
104
+ The following packages will be built and installed:
105
+ * vulkan[core]:arm64-android -> 1.1.82.1-1
106
+ vulkan-hpp[core]:arm64-android -> 2019-05-11-1
107
+ Additional packages (*) will be modified to complete this operation.
108
+ Detecting compiler hash for triplet arm64-android...
109
+ ...
110
+ Starting package 1/2: vulkan:arm64-android
111
+ Building package vulkan[core]:arm64-android...
112
+ -- Using community triplet arm64-android. This triplet configuration is not guaranteed to succeed.
113
+ -- [COMMUNITY] Loading triplet configuration from: /.../vcpkg/triplets/community/arm64-android.cmake
114
+ -- Querying VULKAN_SDK Environment variable
115
+ -- Searching /.../Library/Android/sdk/ndk/22.1.7171670/toolchains/llvm/prebuilt/darwin-x86_64/sysroot/usr/include/vulkan/ for vulkan.h
116
+ -- Found vulkan.h
117
+ -- Performing post-build validation
118
+ -- Performing post-build validation done
119
+ ...
120
+ Building package vulkan[core]:arm64-android... done
121
+ Installing package vulkan[core]:arm64-android...
122
+ Installing package vulkan[core]:arm64-android... done
123
+ Elapsed time for package vulkan:arm64-android: 35.9 ms
124
+ Starting package 2/2: vulkan-hpp:arm64-android
125
+ Building package vulkan-hpp[core]:arm64-android...
126
+ -- Using community triplet arm64-android. This triplet configuration is not guaranteed to succeed.
127
+ -- [COMMUNITY] Loading triplet configuration from: /.../vcpkg/triplets/community/arm64-android.cmake
128
+ -- Using cached /.../vcpkg/downloads/KhronosGroup-Vulkan-Hpp-5ce8ae7fd0d9c0543d02f33cfa8a66e6a43e2150.tar.gz
129
+ -- Cleaning sources at /.../vcpkg/buildtrees/vulkan-hpp/src/e6a43e2150-4f344cd911.clean. Use --editable to skip cleaning for the packages you specify.
130
+ -- Extracting source /.../vcpkg/downloads/KhronosGroup-Vulkan-Hpp-5ce8ae7fd0d9c0543d02f33cfa8a66e6a43e2150.tar.gz
131
+ -- Using source at /.../vcpkg/buildtrees/vulkan-hpp/src/e6a43e2150-4f344cd911.clean
132
+ -- Performing post-build validation
133
+ -- Performing post-build validation done
134
+ ...
135
+ Building package vulkan-hpp[core]:arm64-android... done
136
+ Installing package vulkan-hpp[core]:arm64-android...
137
+ Installing package vulkan-hpp[core]:arm64-android... done
138
+ Elapsed time for package vulkan-hpp:arm64-android: 144.5 ms
139
+
140
+ Total elapsed time: 1.013 s
141
+
142
+ The package vulkan-hpp:arm64-android is header only and can be used from CMake via:
143
+
144
+ find_path(VULKAN_HPP_INCLUDE_DIRS "vulkan/vulkan.hpp")
145
+ target_include_directories(main PRIVATE ${VULKAN_HPP_INCLUDE_DIRS})
146
+
147
+ ```
148
+
149
+ </details>
150
+
151
+
152
+ ## Consume libraries using vpckg, cmake and the android toolchain
153
+
154
+ 1. Combine vcpkg and Android toolchains
155
+
156
+ vcpkg and android both provide dedicated toolchains:
157
+ ````bash
158
+ vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
159
+ android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
160
+ ````
161
+
162
+ When using vcpkg, the vcpkg toolchain shall be specified first.
163
+
164
+ However, vcpkg provides a way to preload and additional toolchain, with the VCPKG_CHAINLOAD_TOOLCHAIN_FILE option.
165
+
166
+ ````bash
167
+ cmake \
168
+ -DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \
169
+ -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \
170
+ ...
171
+ ````
172
+
173
+ 2. Specify the android abi and vcpkg triplet
174
+
175
+ When compiling for android, you need to select a matching "android abi" / "vcpkg triplet" pair.
176
+
177
+ For example:
178
+
179
+ ````bash
180
+ android_abi=armeabi-v7a
181
+ vcpkg_target_triplet=arm-android
182
+
183
+ cmake
184
+ ...
185
+ -DVCPKG_TARGET_TRIPLET=$vcpkg_target_triplet \
186
+ -DANDROID_ABI=$android_abi
187
+ ````
188
+
189
+ ### Test on an example
190
+
191
+ The folder [docs/examples/vcpkg_android_example_cmake](../examples/vcpkg_android_example_cmake) provides a working example, with an android library that consumes the jsoncpp library:
192
+
193
+ *Details*
194
+
195
+ * The [CMakeLists](../examples/vcpkg_android_example_cmake/CMakeLists.txt) simply uses `find_package` and `target_link_library`
196
+
197
+ * The [compile.sh](../examples/vcpkg_android_example_cmake/compile.sh) script enables you to select any matching pair of "android abi" / "vcpkg triplet" and to test the compilation
198
+
199
+ * The dummy [my_lib.cpp](../examples/vcpkg_android_example_cmake/my_lib.cpp) file uses the jsoncpp library
200
+
201
+ *Note*: this example only compiles an Android library, as the compilation of a full fledged Android App is beyond the scope of this document.
202
+
203
+ ### Test on an example, using [vcpkg_android.cmake](../examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake)
204
+
205
+ The folder [docs/examples/vcpkg_android_example_cmake_script](../examples/vcpkg_android_example_cmake_script) provides the same example, and uses a cmake script in order to simplify the usage.
206
+
207
+ *Details*
208
+
209
+ * The main [CMakeLists](../examples/vcpkg_android_example_cmake_script/CMakeLists.txt) loads [vcpkg_android.cmake](../examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake) if the flag `VCPKG_TARGET_ANDROID` is set:
210
+ ````cmake
211
+ if (VCPKG_TARGET_ANDROID)
212
+ include("cmake/vcpkg_android.cmake")
213
+ endif()
214
+ ````
215
+ *Important: place these lines before calling project() !*
216
+
217
+ * The [compile.sh](../examples/vcpkg_android_example_cmake_script/compile.sh) script shows that it is then possible to compile for android using a simple cmake invocation, for example:
218
+ ````bash
219
+ cmake .. -DVCPKG_TARGET_ANDROID=ON -DANDROID_ABI=armeabi-v7a
220
+ ````
221
+
222
+ ## Consume libraries using vpckg, and Android prefab Archives (AAR files)
223
+
224
+ See [prefab.md](../specifications/prefab.md)
third-party/DPVO/Pangolin/scripts/vcpkg/docs/users/assetcaching.md ADDED
@@ -0,0 +1,58 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Asset Caching
2
+
3
+ **The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/assetcaching.md).**
4
+
5
+ **Experimental feature: this may change or be removed at any time**
6
+
7
+ Vcpkg can utilize mirrors to cache downloaded assets, ensuring continued operation even if the original source changes
8
+ or disappears.
9
+
10
+ In-tool help is available via `vcpkg help assetcaching`.
11
+
12
+ ## Configuration
13
+
14
+ Asset caching can be configured by setting the environment variable `X_VCPKG_ASSET_SOURCES` to a semicolon-delimited
15
+ list of source strings. Characters can be escaped using backtick (\`).
16
+
17
+ ### Valid source strings
18
+
19
+ The `<rw>` optional parameter for certain strings controls how they will be accessed. It can be specified as `read`,
20
+ `write`, or `readwrite` and defaults to `read`.
21
+
22
+ #### `clear`
23
+
24
+ Syntax: `clear`
25
+
26
+ Removes all previous sources
27
+
28
+ #### `x-azurl`
29
+
30
+ Syntax: `x-azurl,<url>[,<sas>[,<rw>]]`
31
+
32
+ Adds an Azure Blob Storage source, optionally using Shared Access Signature validation. URL should include the container
33
+ path and be terminated with a trailing `/`. SAS, if defined, should be prefixed with a `?`. Non-Azure servers will also
34
+ work if they respond to GET and PUT requests of the form: `<url><sha512><sas>`. As an example, if you set
35
+ `X_VCPKG_ASSET_SOURCES` to `x-azurl,https://mydomain.com/vcpkg/,token=abc123,readwrite` your server should respond to
36
+ `GET` and `PUT` requests of the form `https://mydomain.com/vcpkg/<sha512>?token=abc123`.
37
+
38
+ You can also use the filesystem (e.g. a network drive) via `file://` as asset cache. For example you then set
39
+ `X_VCPKG_ASSET_SOURCES` to `x-azurl,file:///Z:/vcpkg/assetcache/,,readwrite` when you have a network folder mounted at
40
+ `Z:/`.
41
+
42
+ The workflow of this asset source is:
43
+
44
+ 1. Attemp to read from the mirror
45
+ 2. (If step 1 failed) Read from the original url
46
+ 3. (If step 2 succeeded) Write back to the mirror
47
+
48
+ You can enable/disable steps 1 and 3 via the [`<rw>`](#valid-source-strings) specifier and you can disable step 2 via
49
+ `x-block-origin` below.
50
+
51
+ See also the [binary caching documentation for Azure Blob Storage](binarycaching.md#azure-blob-storage-experimental) for
52
+ more information on how to set up an `x-azurl` source.
53
+
54
+ #### `x-block-origin`
55
+
56
+ Syntax: `x-block-origin`
57
+
58
+ Disables use of the original URLs in case the mirror does not have the file available.