Spaces:
Sleeping
Sleeping
34bad85e8f4867cc4aae63614ab916b258f738b7d991cec1f2cecea7c449afc7
Browse files- third-party/DPVO/Pangolin/scripts/vcpkg/docs/README.md +76 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_configure_make.md +93 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_configure_meson.md +44 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_configure_qmake.md +29 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_copy_pdbs.md +29 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_copy_tool_dependencies.md +23 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_copy_tools.md +36 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_download_distfile.md +62 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_execute_build_process.md +38 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_execute_in_download_mode.md +21 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_execute_required_process.md +51 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_execute_required_process_repeat.md +19 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_extract_source_archive.md +86 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_extract_source_archive_ex.md +26 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_fail_port_install.md +45 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_find_acquire_program.md +51 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_find_fortran.md +25 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_fixup_cmake_targets.md +62 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_fixup_pkgconfig.md +49 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_bitbucket.md +60 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_git.md +53 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_github.md +78 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_gitlab.md +71 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_from_sourceforge.md +73 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_get_program_files_platform_bitness.md +15 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_get_windows_sdk.md +13 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_host_path_list.md +29 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_cmake.md +29 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_gn.md +31 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_make.md +26 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_meson.md +22 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_msbuild.md +95 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_nmake.md +68 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_install_qmake.md +26 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_list.md +94 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_minimum_required.md +17 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/maintainers/vcpkg_replace_string.md +12 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/regenerate.ps1 +353 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/binarycaching.md +159 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/export-command.md +174 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/feature-packages.md +291 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/manifests.md +302 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/ports-overlay.md +183 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/prefab.md +160 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/registries-2.md +559 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/registries.md +287 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/scripts-extraction.md +66 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/specifications/versioning.md +357 -0
- third-party/DPVO/Pangolin/scripts/vcpkg/docs/users/android.md +224 -0
- 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.
|