From 547c030e68163025534ca3cfa372a95a88fefe24 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Thu, 16 Feb 2023 11:36:51 -0800 Subject: [PATCH] [vcpkg docs] Remove docs migrated to https://learn.microsoft.com/vcpkg and Microsoft/vcpkg-docs (#28350) * [docs] Remove embedded documentation in favor of learn.microsoft.com * [docs] Remove validation workflow --- .github/workflows/validateDocs.yml | 54 -- README.md | 28 +- docs/README.md | 86 --- docs/_config.yml | 1 - docs/about/faq.md | 134 ----- docs/about/privacy.md | 50 -- docs/commands/common-options.md | 121 ---- docs/commands/install.md | 193 ------ docs/commands/integrate.md | 84 --- docs/commands/list.md | 31 - docs/commands/remove.md | 43 -- docs/commands/search.md | 37 -- docs/commands/update-baseline.md | 42 -- docs/commands/version.md | 25 - docs/examples/adding-an-explicit-usage.md | 36 -- .../examples/installing-and-using-packages.md | 182 ------ docs/examples/manifest-mode-cmake.md | 200 ------- .../modify-baseline-to-pin-old-boost.md | 191 ------ .../overlay-triplets-linux-dynamic.md | 126 ---- docs/examples/packaging-github-repos.md | 54 -- docs/examples/packaging-zipfiles.md | 76 --- docs/examples/patching.md | 220 ------- .../vcpkg_android_example_cmake/.gitignore | 1 - .../CMakeLists.txt | 5 - .../vcpkg_android_example_cmake/compile.sh | 54 -- .../vcpkg_android_example_cmake/my_lib.cpp | 8 - .../.gitignore | 1 - .../CMakeLists.txt | 13 - .../cmake/vcpkg_android.cmake | 99 ---- .../compile.sh | 37 -- .../my_lib.cpp | 8 - docs/examples/versioning.getting-started.md | 249 -------- docs/maintainers/authoring-script-ports.md | 45 -- docs/maintainers/cmake-guidelines.md | 166 ------ docs/maintainers/control-files.md | 205 ------- docs/maintainers/execute_process.md | 11 - .../internal/vcpkg_catalog_release_process.md | 14 - .../internal/vcpkg_tool_release_process.md | 48 -- .../internal/z_vcpkg_apply_patches.md | 32 - .../z_vcpkg_forward_output_variable.md | 38 -- .../internal/z_vcpkg_function_arguments.md | 29 - .../internal/z_vcpkg_get_cmake_vars.md | 36 -- .../internal/z_vcpkg_prettify_command_line.md | 21 - .../internal/z_vcpkg_setup_pkgconfig_path.md | 16 - docs/maintainers/maintainer-guide.md | 435 -------------- docs/maintainers/manifest-files.md | 551 ----------------- docs/maintainers/portfile-functions.md | 99 ---- docs/maintainers/ports/vcpkg-cmake-config.md | 10 - .../vcpkg_cmake_config_fixup.md | 54 -- .../maintainers/ports/vcpkg-cmake-get-vars.md | 3 - .../vcpkg_cmake_get_vars.md | 41 -- docs/maintainers/ports/vcpkg-cmake.md | 7 - .../ports/vcpkg-get-python-packages.md | 6 - .../x_vcpkg_get_python_packages.md | 38 -- docs/maintainers/ports/vcpkg-gn.md | 12 - .../ports/vcpkg-gn/vcpkg_gn_configure.md | 32 - .../ports/vcpkg-gn/vcpkg_gn_install.md | 29 - .../ports/vcpkg-pkgconfig-get-modules.md | 6 - .../x_vcpkg_pkgconfig_get_modules.md | 45 -- docs/maintainers/ports/vcpkg-qmake.md | 7 - .../ports/vcpkg-qmake/vcpkg_qmake_build.md | 27 - .../vcpkg-qmake/vcpkg_qmake_configure.md | 37 -- .../ports/vcpkg-qmake/vcpkg_qmake_install.md | 20 - docs/maintainers/pr-review-checklist.md | 115 ---- docs/maintainers/registries.md | 360 ----------- docs/maintainers/vcpkg_acquire_msys.md | 60 -- docs/maintainers/vcpkg_add_to_path.md | 27 - docs/maintainers/vcpkg_apply_patches.md | 18 - .../vcpkg_backup_restore_env_vars.md | 26 - docs/maintainers/vcpkg_build_cmake.md | 38 -- docs/maintainers/vcpkg_build_make.md | 57 -- docs/maintainers/vcpkg_build_msbuild.md | 66 --- docs/maintainers/vcpkg_build_ninja.md | 19 - docs/maintainers/vcpkg_build_nmake.md | 89 --- docs/maintainers/vcpkg_build_qmake.md | 12 - .../vcpkg_buildpath_length_warning.md | 16 - docs/maintainers/vcpkg_check_features.md | 136 ----- docs/maintainers/vcpkg_check_linkage.md | 38 -- .../vcpkg_clean_executables_in_bin.md | 25 - docs/maintainers/vcpkg_clean_msbuild.md | 17 - docs/maintainers/vcpkg_cmake_build.md | 68 --- docs/maintainers/vcpkg_cmake_configure.md | 137 ----- docs/maintainers/vcpkg_cmake_install.md | 53 -- docs/maintainers/vcpkg_common_definitions.md | 38 -- docs/maintainers/vcpkg_configure_cmake.md | 87 --- docs/maintainers/vcpkg_configure_gn.md | 34 -- docs/maintainers/vcpkg_configure_make.md | 97 --- docs/maintainers/vcpkg_configure_meson.md | 44 -- docs/maintainers/vcpkg_configure_qmake.md | 29 - docs/maintainers/vcpkg_copy_pdbs.md | 29 - .../vcpkg_copy_tool_dependencies.md | 23 - docs/maintainers/vcpkg_copy_tools.md | 36 -- docs/maintainers/vcpkg_download_distfile.md | 62 -- .../vcpkg_execute_build_process.md | 38 -- .../vcpkg_execute_in_download_mode.md | 21 - .../vcpkg_execute_required_process.md | 62 -- .../vcpkg_execute_required_process_repeat.md | 19 - .../vcpkg_extract_source_archive.md | 154 ----- .../vcpkg_extract_source_archive_ex.md | 22 - docs/maintainers/vcpkg_fail_port_install.md | 45 -- .../maintainers/vcpkg_find_acquire_program.md | 51 -- docs/maintainers/vcpkg_find_fortran.md | 25 - docs/maintainers/vcpkg_fixup_cmake_targets.md | 62 -- docs/maintainers/vcpkg_fixup_pkgconfig.md | 49 -- docs/maintainers/vcpkg_from_bitbucket.md | 60 -- docs/maintainers/vcpkg_from_git.md | 63 -- docs/maintainers/vcpkg_from_github.md | 78 --- docs/maintainers/vcpkg_from_gitlab.md | 71 --- docs/maintainers/vcpkg_from_sourceforge.md | 73 --- ...cpkg_get_program_files_platform_bitness.md | 15 - docs/maintainers/vcpkg_get_windows_sdk.md | 13 - docs/maintainers/vcpkg_host_path_list.md | 29 - docs/maintainers/vcpkg_install_cmake.md | 29 - docs/maintainers/vcpkg_install_copyright.md | 69 --- docs/maintainers/vcpkg_install_gn.md | 31 - docs/maintainers/vcpkg_install_make.md | 26 - docs/maintainers/vcpkg_install_meson.md | 22 - docs/maintainers/vcpkg_install_msbuild.md | 95 --- docs/maintainers/vcpkg_install_nmake.md | 79 --- docs/maintainers/vcpkg_install_qmake.md | 26 - docs/maintainers/vcpkg_list.md | 94 --- docs/maintainers/vcpkg_minimum_required.md | 17 - docs/maintainers/vcpkg_replace_string.md | 12 - docs/specifications/binarycaching.md | 159 ----- docs/specifications/export-command.md | 174 ------ docs/specifications/feature-packages.md | 291 --------- docs/specifications/manifests.md | 302 ---------- docs/specifications/ports-overlay.md | 183 ------ docs/specifications/prefab.md | 160 ----- docs/specifications/registries-2.md | 561 ------------------ docs/specifications/registries.md | 289 --------- docs/specifications/scripts-extraction.md | 66 --- docs/specifications/versioning.md | 357 ----------- docs/users/android.md | 221 ------- docs/users/assetcaching.md | 58 -- docs/users/authentication.md | 91 --- docs/users/binarycaching.md | 288 --------- docs/users/buildsystems/cmake-integration.md | 231 -------- docs/users/buildsystems/export-command.md | 20 - docs/users/buildsystems/integration.md | 10 - docs/users/buildsystems/manual-integration.md | 31 - .../users/buildsystems/msbuild-integration.md | 138 ----- docs/users/config-environment.md | 105 ---- docs/users/host-dependencies.md | 65 -- docs/users/manifests.md | 356 ----------- docs/users/mingw.md | 155 ----- docs/users/registries.md | 381 ------------ docs/users/selecting-library-features.md | 92 --- docs/users/triplets.md | 247 -------- .../versioning.implementation-details.md | 134 ----- docs/users/versioning.md | 174 ------ 151 files changed, 8 insertions(+), 13246 deletions(-) delete mode 100644 .github/workflows/validateDocs.yml delete mode 100644 docs/README.md delete mode 100644 docs/_config.yml delete mode 100644 docs/about/faq.md delete mode 100644 docs/about/privacy.md delete mode 100644 docs/commands/common-options.md delete mode 100644 docs/commands/install.md delete mode 100644 docs/commands/integrate.md delete mode 100644 docs/commands/list.md delete mode 100644 docs/commands/remove.md delete mode 100644 docs/commands/search.md delete mode 100644 docs/commands/update-baseline.md delete mode 100644 docs/commands/version.md delete mode 100644 docs/examples/adding-an-explicit-usage.md delete mode 100644 docs/examples/installing-and-using-packages.md delete mode 100644 docs/examples/manifest-mode-cmake.md delete mode 100644 docs/examples/modify-baseline-to-pin-old-boost.md delete mode 100644 docs/examples/overlay-triplets-linux-dynamic.md delete mode 100644 docs/examples/packaging-github-repos.md delete mode 100644 docs/examples/packaging-zipfiles.md delete mode 100644 docs/examples/patching.md delete mode 100644 docs/examples/vcpkg_android_example_cmake/.gitignore delete mode 100644 docs/examples/vcpkg_android_example_cmake/CMakeLists.txt delete mode 100755 docs/examples/vcpkg_android_example_cmake/compile.sh delete mode 100644 docs/examples/vcpkg_android_example_cmake/my_lib.cpp delete mode 100644 docs/examples/vcpkg_android_example_cmake_script/.gitignore delete mode 100644 docs/examples/vcpkg_android_example_cmake_script/CMakeLists.txt delete mode 100644 docs/examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake delete mode 100755 docs/examples/vcpkg_android_example_cmake_script/compile.sh delete mode 100644 docs/examples/vcpkg_android_example_cmake_script/my_lib.cpp delete mode 100644 docs/examples/versioning.getting-started.md delete mode 100644 docs/maintainers/authoring-script-ports.md delete mode 100644 docs/maintainers/cmake-guidelines.md delete mode 100644 docs/maintainers/control-files.md delete mode 100644 docs/maintainers/execute_process.md delete mode 100644 docs/maintainers/internal/vcpkg_catalog_release_process.md delete mode 100644 docs/maintainers/internal/vcpkg_tool_release_process.md delete mode 100644 docs/maintainers/internal/z_vcpkg_apply_patches.md delete mode 100644 docs/maintainers/internal/z_vcpkg_forward_output_variable.md delete mode 100644 docs/maintainers/internal/z_vcpkg_function_arguments.md delete mode 100644 docs/maintainers/internal/z_vcpkg_get_cmake_vars.md delete mode 100644 docs/maintainers/internal/z_vcpkg_prettify_command_line.md delete mode 100644 docs/maintainers/internal/z_vcpkg_setup_pkgconfig_path.md delete mode 100644 docs/maintainers/maintainer-guide.md delete mode 100644 docs/maintainers/manifest-files.md delete mode 100644 docs/maintainers/portfile-functions.md delete mode 100644 docs/maintainers/ports/vcpkg-cmake-config.md delete mode 100644 docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md delete mode 100644 docs/maintainers/ports/vcpkg-cmake-get-vars.md delete mode 100644 docs/maintainers/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md delete mode 100644 docs/maintainers/ports/vcpkg-cmake.md delete mode 100644 docs/maintainers/ports/vcpkg-get-python-packages.md delete mode 100644 docs/maintainers/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md delete mode 100644 docs/maintainers/ports/vcpkg-gn.md delete mode 100644 docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md delete mode 100644 docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md delete mode 100644 docs/maintainers/ports/vcpkg-pkgconfig-get-modules.md delete mode 100644 docs/maintainers/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md delete mode 100644 docs/maintainers/ports/vcpkg-qmake.md delete mode 100644 docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_build.md delete mode 100644 docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_configure.md delete mode 100644 docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_install.md delete mode 100644 docs/maintainers/pr-review-checklist.md delete mode 100644 docs/maintainers/registries.md delete mode 100644 docs/maintainers/vcpkg_acquire_msys.md delete mode 100644 docs/maintainers/vcpkg_add_to_path.md delete mode 100644 docs/maintainers/vcpkg_apply_patches.md delete mode 100644 docs/maintainers/vcpkg_backup_restore_env_vars.md delete mode 100644 docs/maintainers/vcpkg_build_cmake.md delete mode 100644 docs/maintainers/vcpkg_build_make.md delete mode 100644 docs/maintainers/vcpkg_build_msbuild.md delete mode 100644 docs/maintainers/vcpkg_build_ninja.md delete mode 100644 docs/maintainers/vcpkg_build_nmake.md delete mode 100644 docs/maintainers/vcpkg_build_qmake.md delete mode 100644 docs/maintainers/vcpkg_buildpath_length_warning.md delete mode 100644 docs/maintainers/vcpkg_check_features.md delete mode 100644 docs/maintainers/vcpkg_check_linkage.md delete mode 100644 docs/maintainers/vcpkg_clean_executables_in_bin.md delete mode 100644 docs/maintainers/vcpkg_clean_msbuild.md delete mode 100644 docs/maintainers/vcpkg_cmake_build.md delete mode 100644 docs/maintainers/vcpkg_cmake_configure.md delete mode 100644 docs/maintainers/vcpkg_cmake_install.md delete mode 100644 docs/maintainers/vcpkg_common_definitions.md delete mode 100644 docs/maintainers/vcpkg_configure_cmake.md delete mode 100644 docs/maintainers/vcpkg_configure_gn.md delete mode 100644 docs/maintainers/vcpkg_configure_make.md delete mode 100644 docs/maintainers/vcpkg_configure_meson.md delete mode 100644 docs/maintainers/vcpkg_configure_qmake.md delete mode 100644 docs/maintainers/vcpkg_copy_pdbs.md delete mode 100644 docs/maintainers/vcpkg_copy_tool_dependencies.md delete mode 100644 docs/maintainers/vcpkg_copy_tools.md delete mode 100644 docs/maintainers/vcpkg_download_distfile.md delete mode 100644 docs/maintainers/vcpkg_execute_build_process.md delete mode 100644 docs/maintainers/vcpkg_execute_in_download_mode.md delete mode 100644 docs/maintainers/vcpkg_execute_required_process.md delete mode 100644 docs/maintainers/vcpkg_execute_required_process_repeat.md delete mode 100644 docs/maintainers/vcpkg_extract_source_archive.md delete mode 100644 docs/maintainers/vcpkg_extract_source_archive_ex.md delete mode 100644 docs/maintainers/vcpkg_fail_port_install.md delete mode 100644 docs/maintainers/vcpkg_find_acquire_program.md delete mode 100644 docs/maintainers/vcpkg_find_fortran.md delete mode 100644 docs/maintainers/vcpkg_fixup_cmake_targets.md delete mode 100644 docs/maintainers/vcpkg_fixup_pkgconfig.md delete mode 100644 docs/maintainers/vcpkg_from_bitbucket.md delete mode 100644 docs/maintainers/vcpkg_from_git.md delete mode 100644 docs/maintainers/vcpkg_from_github.md delete mode 100644 docs/maintainers/vcpkg_from_gitlab.md delete mode 100644 docs/maintainers/vcpkg_from_sourceforge.md delete mode 100644 docs/maintainers/vcpkg_get_program_files_platform_bitness.md delete mode 100644 docs/maintainers/vcpkg_get_windows_sdk.md delete mode 100644 docs/maintainers/vcpkg_host_path_list.md delete mode 100644 docs/maintainers/vcpkg_install_cmake.md delete mode 100644 docs/maintainers/vcpkg_install_copyright.md delete mode 100644 docs/maintainers/vcpkg_install_gn.md delete mode 100644 docs/maintainers/vcpkg_install_make.md delete mode 100644 docs/maintainers/vcpkg_install_meson.md delete mode 100644 docs/maintainers/vcpkg_install_msbuild.md delete mode 100644 docs/maintainers/vcpkg_install_nmake.md delete mode 100644 docs/maintainers/vcpkg_install_qmake.md delete mode 100644 docs/maintainers/vcpkg_list.md delete mode 100644 docs/maintainers/vcpkg_minimum_required.md delete mode 100644 docs/maintainers/vcpkg_replace_string.md delete mode 100644 docs/specifications/binarycaching.md delete mode 100644 docs/specifications/export-command.md delete mode 100644 docs/specifications/feature-packages.md delete mode 100644 docs/specifications/manifests.md delete mode 100644 docs/specifications/ports-overlay.md delete mode 100644 docs/specifications/prefab.md delete mode 100644 docs/specifications/registries-2.md delete mode 100644 docs/specifications/registries.md delete mode 100644 docs/specifications/scripts-extraction.md delete mode 100644 docs/specifications/versioning.md delete mode 100644 docs/users/android.md delete mode 100644 docs/users/assetcaching.md delete mode 100644 docs/users/authentication.md delete mode 100644 docs/users/binarycaching.md delete mode 100644 docs/users/buildsystems/cmake-integration.md delete mode 100644 docs/users/buildsystems/export-command.md delete mode 100644 docs/users/buildsystems/integration.md delete mode 100644 docs/users/buildsystems/manual-integration.md delete mode 100644 docs/users/buildsystems/msbuild-integration.md delete mode 100644 docs/users/config-environment.md delete mode 100644 docs/users/host-dependencies.md delete mode 100644 docs/users/manifests.md delete mode 100644 docs/users/mingw.md delete mode 100644 docs/users/registries.md delete mode 100644 docs/users/selecting-library-features.md delete mode 100644 docs/users/triplets.md delete mode 100644 docs/users/versioning.implementation-details.md delete mode 100644 docs/users/versioning.md diff --git a/.github/workflows/validateDocs.yml b/.github/workflows/validateDocs.yml deleted file mode 100644 index 3a85654808..0000000000 --- a/.github/workflows/validateDocs.yml +++ /dev/null @@ -1,54 +0,0 @@ -name: Doc Validation - -on: - pull_request: - paths: - - 'docs/**' - -jobs: - validate: - runs-on: ubuntu-22.04 - - steps: - - name: Checkout - uses: actions/checkout@v3 - with: - path: vcpkg - - - name: Checkout Website - uses: actions/checkout@v3 - with: - repository: vcpkg/vcpkg.github.io - ref: '8ee5cacc91b6e017b5e4236940d9f385c1563598' - path: vcpkg.github.io - - - uses: actions/cache@v3 - with: - path: ~/.npm - key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} - restore-keys: | - ${{ runner.os }}-node- - - - run: npm ci - working-directory: vcpkg.github.io - - - name: Purge existing html files - run: rm -rf en - working-directory: vcpkg.github.io - - # The current navbar embeds a link to integration.md which no longer exists - - name: Ignore navbar - run: echo "" > templates/navbar.html - working-directory: vcpkg.github.io - - - name: Generate Core Pages - run: node scripts/generatePages.js - working-directory: vcpkg.github.io - - - name: Generate Docs Pages - run: node scripts/generateDocs.js ../vcpkg/docs - working-directory: vcpkg.github.io - - - name: Check Links - run: VCPKG_VALIDATE_LINKS_ONLY_DOCS=1 node scripts/validateLinks.js - working-directory: vcpkg.github.io diff --git a/README.md b/README.md index b29fe52d2f..5d609d5eff 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ you can run `vcpkg help`, or `vcpkg help [command]` for command-specific help. * GitHub: ports at [https://github.com/microsoft/vcpkg](https://github.com/microsoft/vcpkg), program at [https://github.com/microsoft/vcpkg-tool](https://github.com/microsoft/vcpkg-tool) * Slack: [https://cppalliance.org/slack/](https://cppalliance.org/slack/), the #vcpkg channel * Discord: [\#include \](https://www.includecpp.org), the #🌏vcpkg channel -* Docs: [Documentation](docs/README.md) +* Docs: [Documentation](https://learn.microsoft.com/vcpkg) # Table of Contents @@ -55,11 +55,6 @@ and potentially add the port to vcpkg. After you've gotten vcpkg installed and working, you may wish to add [tab completion](#tab-completionauto-completion) to your shell. -Finally, if you're interested in the future of vcpkg, -check out the [manifest][getting-started:manifest-spec] guide! -This is an experimental feature and will likely have bugs, -so try it out and [open all the issues][contributing:submit-issue]! - ## Quick Start: Windows Prerequisites: @@ -128,9 +123,6 @@ With CMake, you will still need to `find_package` and the like to use the librar Check out the [CMake section](#using-vcpkg-with-cmake) for more information, including on using CMake with an IDE. -For any other tools, including Visual Studio Code, -check out the [integration guide][getting-started:integration]. - ## Quick Start: Unix Prerequisites for Linux: @@ -172,8 +164,6 @@ Check out the [CMake section](#using-vcpkg-with-cmake) for more information on how best to use vcpkg with CMake, and CMake Tools for VSCode. -For any other tools, check out the [integration guide][getting-started:integration]. - ## Installing Linux Developer Tools Across the different distros of Linux, there are different packages you'll @@ -262,8 +252,7 @@ This will still allow people to not use vcpkg, by passing the `CMAKE_TOOLCHAIN_FILE` directly, but it will make the configure-build step slightly easier. -[getting-started:using-a-package]: docs/examples/installing-and-using-packages.md -[getting-started:integration]: docs/users/buildsystems/integration.md +[getting-started:using-a-package]: https://learn.microsoft.com/vcpkg/examples/installing-and-using-packages.md [getting-started:git]: https://git-scm.com/downloads [getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools [getting-started:linux-gcc]: #installing-linux-developer-tools @@ -271,7 +260,6 @@ but it will make the configure-build step slightly easier. [getting-started:macos-brew]: #installing-gcc-on-macos [getting-started:macos-gcc]: #installing-gcc-on-macos [getting-started:visual-studio]: https://visualstudio.microsoft.com/ -[getting-started:manifest-spec]: docs/specifications/manifests.md # Tab-Completion/Auto-Completion @@ -293,10 +281,10 @@ depending on the shell you use, then restart your console. # Examples -See the [documentation](docs/README.md) for specific walkthroughs, -including [installing and using a package](docs/examples/installing-and-using-packages.md), -[adding a new package from a zipfile](docs/examples/packaging-zipfiles.md), -and [adding a new package from a GitHub repo](docs/examples/packaging-github-repos.md). +See the [documentation](https://learn.microsoft.com/vcpkg) for specific walkthroughs, +including [installing and using a package](https://learn.microsoft.com/vcpkg/examples/installing-and-using-packages.md), +[adding a new package from a zipfile](https://learn.microsoft.com/vcpkg/examples/packaging-zipfiles.md), +and [adding a new package from a GitHub repo](https://learn.microsoft.com/vcpkg/examples/packaging-github-repos.md). Our docs are now also available online at our website https://vcpkg.io/. We really appreciate any and all feedback! You can submit an issue in https://github.com/vcpkg/vcpkg.github.io/issues. @@ -335,7 +323,7 @@ by the original developers of those libraries, and download source code and buil official distribution locations. For use behind a firewall, the specific access needed will depend on which ports are being installed. If you must install in in an "air gapped" environment, consider installing once in a non-"air gapped" environment, populating an -[asset cache](docs/users/assetcaching.md) shared with the otherwise "air gapped" environment. +[asset cache](https://learn.microsoft.com/vcpkg/users/assetcaching.md) shared with the otherwise "air gapped" environment. # Telemetry @@ -346,4 +334,4 @@ You can opt-out of telemetry by - passing --disable-metrics to vcpkg on the command line - setting the VCPKG_DISABLE_METRICS environment variable -Read more about vcpkg telemetry at docs/about/privacy.md +[Read more about vcpkg telemetry](https://learn.microsoft.com/vcpkg/about/privacy.html) diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 71b3fc74df..0000000000 --- a/docs/README.md +++ /dev/null @@ -1,86 +0,0 @@ -### Quick Start - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/README.md).** - -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! - -### Examples - -- [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md) -- [Packaging Zipfiles Example: zlib](examples/packaging-zipfiles.md) -- [Packaging GitHub Repositories Example: libogg](examples/packaging-github-repos.md) -- [Patching Example: Patching libpng to work for x64-uwp](examples/patching.md) -- [Getting Started with Versioning](examples/versioning.getting-started.md) -- [Manifest Mode: CMake Example](examples/manifest-mode-cmake.md) -- [Pin old Boost Versions](examples/modify-baseline-to-pin-old-boost.md) -- [Using Overlay Triplets](examples/overlay-triplets-linux-dynamic.md) - -### Command Line Reference - -- [Common Options](commands/common-options.md) -- Commands - - [vcpkg install](commands/install.md) - - [vcpkg integrate](commands/integrate.md) - - [vcpkg list](commands/list.md) - - [vcpkg remove](commands/remove.md) - - [vcpkg search](commands/search.md) - - [vcpkg update-baseline](commands/update-baseline.md) - - [vcpkg version](commands/version.md) - -### User Help - -- [Buildsystem Integration](users/buildsystems/integration.md) -- [Triplet files](users/triplets.md) -- [Configuration and Environment](users/config-environment.md) -- [Authentication](users/authentication.md) -- [Manifest Mode](users/manifests.md) -- [Binary Caching](users/binarycaching.md) -- [Asset Caching](users/assetcaching.md) -- [Versioning](users/versioning.md) -- [Usage with Android](users/android.md) -- [Usage with Mingw-w64](users/mingw.md) -- [Host Dependencies](users/host-dependencies.md) -- [Using Registries](users/registries.md) - -### Maintainer Help - -- [Manifest Files - vcpkg.json](maintainers/manifest-files.md) -- [Control Files](maintainers/control-files.md) -- [Portfile Functions](maintainers/portfile-functions.md) -- [Authoring Script Ports](maintainers/authoring-script-ports.md) -- [Common CMake Definitions](maintainers/vcpkg_common_definitions.md) -- [Maintainer Guidelines](maintainers/maintainer-guide.md) -- [Creating Registries](maintainers/registries.md) -- [CMake Guidelines](maintainers/cmake-guidelines.md) - -### [Vcpkg-Tool](https://github.com/microsoft/vcpkg-tool) Maintainer Help - -- [Testing](https://github.com/microsoft/vcpkg-tool/tree/main/docs/testing.md) -- [Benchmarking](https://github.com/microsoft/vcpkg-tool/tree/main/docs/benchmarking.md) -- [Layout of the vcpkg source tree](https://github.com/microsoft/vcpkg-tool/tree/main/docs/layout.md) - -### Community Resources (not directly affiliated with vcpkg) - -- [vcpkgx.com](https://vcpkgx.com/) - Package index + search -- [vcpkg.dev](https://vcpkg.dev/) - Package index + search -- [vcpkg.link](https://vcpkg.link/) - Package index + search - -### Blog posts - -- [Vcpkg Host Dependencies for Cross-Compilation](https://devblogs.microsoft.com/cppblog/vcpkg-host-dependencies/) -- [Registries: Bring your own libraries to vcpkg](https://devblogs.microsoft.com/cppblog/registries-bring-your-own-libraries-to-vcpkg/) -- [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/) -- [Vcpkg: 2019.06 Update (overlay ports, overlay triplets, `vcpkg_check_features`)](https://devblogs.microsoft.com/cppblog/vcpkg-2019-06-update/) -- [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/) -- [Vcpkg: Using multiple enlistments to handle multiple versions of a library](https://blogs.msdn.microsoft.com/vcblog/2017/10/23/vcpkg-using-multiple-enlistments/) -- [Vcpkg: introducing the export command](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) -- [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/) -- [Vcpkg recent enhancements](https://blogs.msdn.microsoft.com/vcblog/2017/02/14/vcpkg-recent-enhancements/) -- [Vcpkg 3 Months Anniversary, Survey](https://blogs.msdn.microsoft.com/vcblog/2017/01/11/vcpkg-3-months-anniversary-survey/) -- [Vcpkg updates: Static linking is now available](https://blogs.msdn.microsoft.com/vcblog/2016/11/01/vcpkg-updates-static-linking-is-now-available/) -- [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/) - -### Other - -- [FAQ](about/faq.md) -- [Privacy](about/privacy.md) diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index c4192631f2..0000000000 --- a/docs/_config.yml +++ /dev/null @@ -1 +0,0 @@ -theme: jekyll-theme-cayman \ No newline at end of file diff --git a/docs/about/faq.md b/docs/about/faq.md deleted file mode 100644 index 0e9b8ddef0..0000000000 --- a/docs/about/faq.md +++ /dev/null @@ -1,134 +0,0 @@ -# Frequently Asked Questions - -## Can I contribute a new library? -Yes! Start out by reading our [contribution guidelines](https://github.com/Microsoft/vcpkg/blob/master/CONTRIBUTING.md). -If you want to contribute but don't have a particular library in mind then take a look at the list -of [new port requests](https://github.com/Microsoft/vcpkg/issues?q=is%3Aissue+is%3Aopen+label%3Acategory%3Anew-port). - -## Can vcpkg create pre-built binary packages? What is the binary format used by vcpkg? -Yes! See the [`export` command](../users/buildsystems/export-command.md) if you wish to produce binaries for exporting into other environments. - -Alternatively, if your goal is to preserve binaries produced by `vcpkg install` operations for later re-use, see the [Binary Caching feature](../users/binarycaching.md) - -## How do I update libraries? -The `vcpkg update` command lists all packages which are out-of-sync with your current portfiles. To update a package, follow the instructions in the command. - -## How do I get more libraries? -The list of libraries is enumerated from the [`ports\`](https://github.com/Microsoft/vcpkg/blob/master/ports) directory. By design, you can add and remove libraries from this directory as you see fit for yourself or your company -- see our examples on packaging [zipfiles](../examples/packaging-zipfiles.md) and [GitHub repos](../examples/packaging-github-repos.md). - -We recommend cloning directly from [GitHub](https://github.com/microsoft/vcpkg) and using `git pull` to update the list of portfiles. Once you've updated your portfiles, `vcpkg update` will indicate any installed libraries that are now out of date. - -## Can I build a private library with this tool? -Yes. Follow [our packaging zlib Example](../examples/packaging-zipfiles.md) for creating a portfile using a fake URL. Then, either pre-seed the `downloads\` folder with a zip containing your private sources or replace the normal calls to `vcpkg_download_distfile` and `vcpkg_extract_source_archive` with functions that unpack your source code. - -You can take this further by publishing your private libraries into a registry. See the article on [Creating Registries](../maintainers/registries.md). A registry is a catalog of ports, similar to the one provided with vcpkg that contains open source libraries. - -## Can I use a prebuilt private library with this tool? -Yes. The `portfile.cmake` for a library is fundamentally a script that places the headers and binaries into the correct arrangement in the `${CURRENT_PACKAGES_DIR}`, so to pull in prebuilt binaries you can write a portfile which directly downloads and arranges the files. - -To see an example of this, look at [`ports\opengl\portfile.cmake`](https://github.com/microsoft/vcpkg/blob/master/ports/opengl/portfile.cmake) which simply copies files out of the Windows SDK. - -## Which platforms can I target with vcpkg? -Our built-in, CI-tested triplets are: -* Windows Desktop (x86, x64, x64-static, arm64) -* Universal Windows Platform (x64, and ARM) -* Mac OS X (x64-static) -* Linux (x64-static) - -However, there is an even larger number of community triplets available with more platforms and architectures, including for iOS, Android, MinGW, WebAssembly, freeBSD, and openBSD. - -You can also define your own triplets depending on your needs. - -See `vcpkg help triplet` for the current list. - -## Does vcpkg run on Linux/OS X? -Yes! We continuously test on OS X and Ubuntu 16.04, however we know users have been successful with Arch, Fedora, and FreeBSD. If you have trouble with your favorite Linux distribution, let us know in an issue and we'd be happy to help! - -## How do I update vcpkg? -Execute `git pull` to get the latest sources, then run `bootstrap-vcpkg.bat` (Windows) or `./bootstrap-vcpkg.sh` (Unix) to update vcpkg. - -## How do I use different versions of a library on one machine? -Within a single instance of vcpkg (e.g. one set of `installed\`, `packages\`, `ports\` and so forth), you can only have one version of a library installed (otherwise, the headers would conflict with each other!). For those with experience with system-wide package managers, packages in vcpkg correspond to the `X-dev` or `X-devel` packages. - -To use different versions of a library for different projects, we recommend making separate instances of vcpkg and using the [per-project integration mechanisms](../users/buildsystems/integration.md). The versions of each library are specified by the files in `ports\`, so they are easily manipulated using standard `git` commands. This makes it very easy to roll back the entire set of libraries to a consistent set of older versions which all work with each other. If you need to then pin a specific library forward, that is as easy as checking out the appropriate version of `ports\\`. - -If your application is very sensitive to the versions of libraries, we recommend checking in the specific set of portfiles you need into your source control along with your project sources and using the `--vcpkg-root` option to redirect the working directory of `vcpkg.exe`. - -## How does vcpkg protect my privacy? -See the [Privacy document](privacy.md) for all information regarding privacy. - -## Can I use my own CMake toolchain file with vcpkg's toolchain file? -Yes. If you already have a CMake toolchain file, you will need to include our toolchain file at the end of yours. This should be as simple as an `include(\scripts\buildsystems\vcpkg.cmake)` directive. Alternatively, you could copy the contents of our `scripts\buildsystems\vcpkg.cmake` into the end of your existing toolchain file. - -## Can I use my own/specific flags for rebuilding libs? -Yes. In the current version, there is not yet a standardized global way to change them, however you can edit individual portfiles and tweak the exact build process however you'd like. - -By saving the changes to the portfile (and checking them in), you'll get the same results even if you're rebuilding from scratch in the future and forgot what exact settings you used. - -## Can I get vcpkg integration for custom configurations? - -Yes. While vcpkg will only produce the standard "Release" and "Debug" configurations when building a library, you can get integration support for your projects' custom configurations, in addition to your project's standard configurations. - -First of all, vcpkg will automatically assume any custom configuration starting with "Release" (resp. "Debug") as a configuration that is compatible with the standard "Release" (resp. "Debug") configuration and will act accordingly. - -For other configurations, you only need to override the MSBuild `$(VcpkgConfiguration)` macro in your project file (.vcxproj) to declare the compatibility between your configuration, and the target standard configuration. Unfortunately, due to the sequential nature of MSBuild, you'll need to add those settings much higher in your vcxproj so that it is declared before the Vcpk integration is loaded. It is recommend that the `$(VcpkgConfiguration)` macro is added to the "Globals" PropertyGroup. - -For example, you can add support for your "MyRelease" configuration by adding in your project file: -``` - - ... - Release - -``` -Of course, this will only produce viable binaries if your custom configuration is compatible with the target configuration (e.g. they should both link with the same runtime library). - -## I can't use user-wide integration. Can I use a per-project integration? - -Yes. A NuGet package suitable for per-project use can be generated via either the `vcpkg integrate project` command (lightweight linking) or the `vcpkg export --nuget` command (shrinkwrapped). - -A lower level mechanism to achieve the same as the `vcpkg integrate project` NuGet package is via the `\scripts\buildsystems\msbuild\vcpkg.targets` file. All you need is to import it in your .vcxproj file, replacing `` with the path where you installed vcpkg: - -``` - -``` - -## How can I remove temporary files? - -You can save some disk space by completely removing the `packages\`, `buildtrees\`, and `downloads\` folders. - -## How is CMake used internally by vcpkg? -Vcpkg uses CMake internally as a build scripting language. This is because CMake is already an extremely common build system for cross-platform open source libraries and is becoming very popular for C++ projects in general. It is easy to acquire on Windows, does not require system-wide installation, and legible for unfamiliar users. - -## Will vcpkg support downloading compiled binaries from a public or private server? -We would like to eventually support downloading precompiled binaries, similar to other system package managers. - -In a corporate scenario, we currently recommend building the libraries once and using the [Binary Caching](../users/binarycaching.md) feature to re-use binaries across different machines and for local development vs. CI scenarios. - -## What Visual C++ toolsets are supported? -We support Visual Studio 2015 Update 3 and above. - -## Why does Visual Studio not use my libraries with user-wide integration enabled? -Enabling user-wide integration (`vcpkg integrate install`) changes the default for some project properties. In particular, "C/C++/General/Additional Include Directories" and "Linker/General/Additional Library Directories" are normally blank *without* user-wide integration. *With* integration, a blank value means that the augmented default supplied by vcpkg is overridden, and headers/libraries will not be found. To reinstate the default, set the properties to inherit from parent. - -## Why not NuGet? -NuGet is a package manager for .NET libraries with a strong dependency on MSBuild. It does not meet the specific needs of Native C++ customers in at least three ways. - -- **Compilation Flavors**. With so many possible combinations of compilation options, the task of providing a truly complete set of options is intrinsically impossible. Furthermore, the download size for reasonably complete binary packages becomes enormous. This makes it a requirement to split the results into multiple packages, but then searching becomes very difficult. - -- **Binary vs Source**. Very closely tied to the first point, NuGet is designed from the ground up to provide relatively small, prebuilt binaries. Due to the nature of native code, developers need to have access to the source code to ensure ABI compatibility, performance, integrity, and debuggability. - -- **Per-dll vs Per-application**. NuGet is highly project centric. This works well in managed languages with naturally stable ABIs, because base libraries can continue to evolve without breaking those higher up. However, in native languages where the ABI is much more fragile, the only robust strategy is to explicitly build each library against the exact dependencies that will be included in the final application. This is difficult to ensure in NuGet and leads to a highly disconnected and independently versioned ecosystem. - -## Why not Conan? -Conan.io is a publicly-federated, project-centric, cross-platform, C++ package manager written in python. Our primary differences are: - -- **Public federation vs private federation**. Conan relies on individuals publishing independent copies of each package. We believe this approach encourages a large number of packages that are all broken in different ways. We believe it is a waste of user's time to pick through the list of 20+ public packages for Boost 1.56 to determine the handful that will work for their particular situation. In contrast, we believe there should be a single, collaboratively maintained version which works for the vast majority of cases and allow users to hack freely on their private versions. We believe this will result in a set of high quality packages that are heavily tested with each other and form a fantastic base for any private modifications you need. - -- **Per-dll vs Per-application**. When dependencies are independently versioned on a library level, it encourages every build environment to be a completely unique, unable to take advantage of or contribute to a solid, well tested ecosystem. In contrast, by versioning all libraries together as a platform (similar to a system package manager), we hope to congregate testing and effort on very common sets of library versions to maximize the quality and stability of the ecosystem. This also completely designs out the ability for a library to ask for versions that conflict with the application's choices (I want openssl Z and boost X but X only claims to work with openssl Y). - -- **Cross-platform vs single-platform**. While being hosted on many platforms is an excellent north star, we believe the level of system integration and stability provided by apt-get, yum, and homebrew is well worth needing to exchange `apt-get install libboost-all-dev` with `brew install boost` in automated scripts. We chose to make our system as easy as possible to integrate into a world with these very successful system managers -- one more line for `vcpkg install boost` -- instead of attempting to replace them where they are already so successful and well-loved. - -- **C++/CMake vs python**. While Python is an excellent language loved by many, we believe that transparency and familiarity are the most important factors when choosing a tool as important to your workflow as a package manager. Consequently, we chose to make the implementation languages be as universally accepted as possible: C++ should be used in a C++ package manager for C++ programmers. You should not be required to learn another programming language just to understand your package manager. - -## Why not Chocolatey? -Chocolatey is an excellent system for managing applications. However, it is not currently designed to acquire redistributable developer assets and help you with debugging. Vcpkg, in comparison, is designed to get you the libraries you need to build your application and help you deliver through any platform you'd like (including Chocolatey!). diff --git a/docs/about/privacy.md b/docs/about/privacy.md deleted file mode 100644 index d2ba7552e1..0000000000 --- a/docs/about/privacy.md +++ /dev/null @@ -1,50 +0,0 @@ -# Vcpkg Telemetry and Privacy - -vcpkg collects telemetry data to understand usage issues, such as failing packages, and to guide tool improvements. The collected data is anonymous. -For more information about how Microsoft protects your privacy, see https://privacy.microsoft.com/en-US/privacystatement#mainenterprisedeveloperproductsmodule - -## Scope - -We explicitly ONLY collect information from invocations of the tool itself; we do NOT add any tracking information into the produced libraries. Telemetry is collected when using any of the `vcpkg` commands. - -## How to opt out - -The vcpkg telemetry feature is enabled by default. In order to opt-out of data collection, you can re-run the bootstrap script with the following flag, for Windows and Linux/OSX, respectively: - -```PS> .\bootstrap-vcpkg.bat -disableMetrics``` - -```~/$ ./bootstrap-vcpkg.sh -disableMetrics``` - -## Disclosure - -vcpkg displays text similar to the following when you build vcpkg. This is how Microsoft notifies you about data collection. - -``` -Telemetry ---------- -vcpkg collects usage data in order to help us improve your experience. -The data collected by Microsoft is anonymous. -You can opt-out of telemetry by re-running the bootstrap-vcpkg script with -disableMetrics, -passing --disable-metrics to vcpkg on the command line, -or by setting the VCPKG_DISABLE_METRICS environment variable. - -Read more about vcpkg telemetry at docs/about/privacy.md -``` - -## Data Collected - -The telemetry feature doesn't collect personal data, such as usernames or email addresses. It doesn't scan your code and doesn't extract project-level data, such as name, repository, or author. The data is sent securely to Microsoft servers and held under restricted access. - -Protecting your privacy is important to us. If you suspect the telemetry is collecting sensitive data or the data is being insecurely or inappropriately handled, file an issue in the Microsoft/vcpkg repository or send an email to vcpkg@microsoft.com for investigation. - -We collect various telemetry events such as the command line used, the time of invocation, and how long execution took. Some commands also add additional calculated information (such as the full set of libraries to install). We generate a completely random UUID on first use and attach it to each event. - -You can see the telemetry events any command by appending `--printmetrics` after the vcpkg command line. - -In the source code (included at https://github.com/microsoft/vcpkg-tool/ ), you can search for calls to the functions `track_property()`, `track_feature()`, `track_metric()`, and `track_buildtime()` -to see every specific data point we collect. - -## Avoid inadvertent disclosure information - -vcpkg contributors and anyone else running a version of vcpkg that they built themselves should consider the path to their source code. If a crash occurs when using vcpkg, the file path from the build machine is collected as part of the stack trace and isn't hashed. -Because of this, builds of vcpkg shouldn't be located in directories whose path names expose personal or sensitive information. diff --git a/docs/commands/common-options.md b/docs/commands/common-options.md deleted file mode 100644 index 43460af526..0000000000 --- a/docs/commands/common-options.md +++ /dev/null @@ -1,121 +0,0 @@ -# Common Command Options - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/common-options.md).** - -Most vcpkg commands accept a group of common options that control cross-cutting aspects of the tool. Not all options affect every command. For example, a command that does not download any files will be unaffected by changing the downloads directory. - - - -## `--x-asset-sources=` - -**Experimental: will change or be removed at any time** - -Specify the cache configuration for [Asset Caching](../users/assetcaching.md). - - - -## `--binarysource=` - -Add a source for [Binary Caching](../users/binarycaching.md). - -This option can be specified multiple times; see the Binary Caching documentation for how multiple binary sources interact. - - - -## `--x-buildtrees-root=` - -**Experimental: will change or be removed at any time** - -Specifies the temporary path to store intermediate build files, such as objects or unpacked source code. - -Defaults to `buildtrees/` under the vcpkg root folder. - - - -## `--downloads-root=` - -Specify where downloaded tools and source code archives should be kept. - -Defaults to the `VCPKG_DOWNLOADS` environment variable. If that is unset, defaults to `downloads/` under the vcpkg root folder. - - - -## `--host-triplet=` - -Specify the host [architecture triplet][triplets]. - -Defaults to the `VCPKG_DEFAULT_HOST_TRIPLET` environment variable. If that is unset, deduced based on the host architecture and operating system. - - - -## `--x-install-root=` - -**Experimental: will change or be removed at any time** - -Specifies the path to lay out installed packages. - -In Classic Mode, defaults to `installed/` under the vcpkg root folder. - -In [Manifest Mode](../users/manifests.md), defaults to `vcpkg_installed/` under the manifest folder. - - - -## `--x-manifest-root=` - -**Experimental: will change or be removed at any time** - -Specifies the directory containing [`vcpkg.json`](../users/manifests.md). - -Defaults to searching upwards from the current working directory for the nearest `vcpkg.json`. - - - -## `--overlay-ports=` - -Specifies a directory containing [overlay ports](../specifications/ports-overlay.md). - -This option can be specified multiple times; ports will resolve to the first match. - - - -## `--overlay-triplets=` - -Specifies a directory containing [overlay triplets](../examples/overlay-triplets-linux-dynamic.md). - -This option can be specified multiple times; [triplets][] will resolve to the first match. - - - -## `--x-packages-root=` - -**Experimental: will change or be removed at any time** - -Specifies the temporary path to stage intermediate package files before final install. - -Defaults to `packages/` under the vcpkg root folder. - - - -## `--triplet=` - -Specify the target [architecture triplet][triplets]. - -Defaults to the `VCPKG_DEFAULT_TRIPLET` environment variable. If that is unset, deduced based on the host architecture and operating system. - -Note that on Windows operating systems, the architecture is always deduced as x86 for legacy reasons. - - - -## `--vcpkg-root=` - -Specifies the vcpkg root folder. - -Defaults to the directory containing the vcpkg program. The directory must be a valid vcpkg instance, such as a `git clone` of `https://github.com/microsoft/vcpkg`. This option can be used to run a custom-built copy of the tool directly from the build folder. - -## Response Files (`@`) - -The vcpkg command line accepts text files containing newline-separated command line parameters. - -The tool will act as though the items in the file were spliced into the command line in place of the `@` reference. Response files cannot contain additional response files. - -[triplets]: ../users/triplets.md diff --git a/docs/commands/install.md b/docs/commands/install.md deleted file mode 100644 index f79929edb8..0000000000 --- a/docs/commands/install.md +++ /dev/null @@ -1,193 +0,0 @@ -# vcpkg install - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/install.md).** - -## Synopsis - -**Classic Mode** -```no-highlight -vcpkg install [options] ... -``` - -**Manifest Mode** -```no-highlight -vcpkg install [options] -``` - -## Description - -Build and install port packages. - -### Classic Mode - -In Classic Mode, this verb adds port packages to the existing set in the [installed directory][] (defaults to `installed/` under the vcpkg root). This can require removing and rebuilding existing packages, which can fail. - - - -**Package Syntax** -``` -portname[feature1,feature2]:triplet -``` - -Package references without a triplet are automatically qualified by the [default target triplet](common-options.md#triplet). Package references that do not explicitly list `core` are considered to imply all default features. - -### Manifest Mode - -In [Manifest Mode][], this verb sets the [installed directory][] to the state specified by the `vcpkg.json` manifest file, adding, removing, or rebuilding packages as needed. - -[installed directory]: common-options.md#install-root - -## Options - -All vcpkg commands support a set of [common options](common-options.md). - -### `--allow-unsupported` - -Instead of stopping on an unsupported port, continue with a warning. - -By default, vcpkg refuses to execute an install plan containing a port installation for a triplet outside its [`"supports"`][supports] clause. The [`"supports"`][supports] clause of a package describes the full set of platforms a package is expected to be buildable on. This flag instructs vcpkg to warn that the build is expected to fail instead of stopping. - -### `--clean-after-build` - -Clean buildtrees, packages, and downloads after building each package. - -This option has the same effect as passing [`--clean-buildtrees-after-build`](#clean-buildtrees-after-build), [`--clean-downloads-after-build`](#clean-downloads-after-build), and [`--clean-packages-after-build`](#clean-packages-after-build). - - - -### `--clean-buildtrees-after-build` - -Clean all subdirectories from the buildtrees temporary subfolder after building each package. - -All top-level files in the buildtrees subfolder (e.g. `buildtrees/zlib/config-x64-windows-out.log`) will be kept. All subdirectories will be deleted. - - - -### `--clean-downloads-after-build` - -Clean all unextracted assets from the `downloads/` folder after building each package. - -All top level files in the `downloads/` folder will be deleted. Extracted tools will be kept. - - - -### `--clean-packages-after-build` - -Clean the packages temporary subfolder after building each package. - -The packages subfolder for the built package (for example, `packages/zlib_x64-windows`) will be deleted after installation. - -### `--dry-run` - -Print the install plan, but do not remove or install any packages. - -The install plan lists all packages and features that will be installed, as well as any other packages that need to be removed and rebuilt. - - - -### `--editable` - -**Classic Mode Only** - -Perform editable builds for all directly referenced packages on the command line. - -When vcpkg builds ports, it purges and re-extracts the source code each time to ensure inputs are accurately. This is necessary for [Manifest Mode][] to accurately update what is installed and [Binary Caching][] to ensure cached content is correct. - -Passing the `--editable` flag disables this behavior, preserving edits to the extracted sources in the `buildtrees/` folder. This helps develop patches quickly by avoiding the need to write a file on each change. - -Sources extracted during an editable build do not have a `.clean/` suffix on the directory name and will not be cleared by subsequent non-editable builds. - -### `--enforce-port-checks` - -Fail install if a port has detected problems or attempts to use a deprecated feature. - -By default, vcpkg will run several checks on built packages and emit warnings if any issues are detected. This flag upgrades those warnings to an error. - - - -### `--x-feature=` - -**Experimental and may change or be removed at any time** - -**[Manifest Mode][] Only** - -Specify an additional [feature](../users/manifests.md#features) from the `vcpkg.json` to install dependencies for. - -By default, only [`"dependencies"`][dependencies] and the dependencies of the [`"default-features"`][default-features] will be installed. - -### `--head` - -**Classic Mode Only** - -Request all packages explicitly referenced on the command line to fetch the latest sources available when building. - -This flag is only intended for temporary testing and is not intended for production or long-term use. This disables [Binary Caching][] for all explicitly referenced packages and their dependents because vcpkg cannot accurately track all inputs. - -### `--keep-going` - -Continue the install plan after the first failure. - -By default, vcpkg will stop at the first package build failure. This flag instructs vcpkg to continue building and installing other parts of the install plan that don't depend upon the failed package. - -### `--x-no-default-features` - -**Experimental and may change or be removed at any time** - -**[Manifest Mode][] Only** - -Don't install the default features from the top-level manifest. - -When using `install` in Manifest Mode, by default all dependencies of the features listed in [`"default-features"`][default-features] will be installed. This flag disables that behavior so only features explicitly enabled by [`--x-feature`](#feature) will be installed. - -### `--no-downloads` - -When building a package, prevent ports from downloading new assets during the build. - -By default, ports will acquire source code and tools on demand from the internet (subject to [Asset Caching][]). This parameter blocks downloads and restricts ports to only the assets that were previously downloaded and cached on the machine. - -### `--only-downloads` - -Attempt to download all assets required for an install plan without performing any builds. - -When passed this option, vcpkg will run each build in the plan until it makes its first non-downloading external process call. Most ports perform all downloads before the first external process call (usually to their buildsystem), so this procedure will download all required assets. Ports that do not follow this procedure will not have their assets predownloaded. - -### `--only-binarycaching` - -Refuse to perform any builds. Only restore packages from [Binary Caches][Binary Caching]. - -This flag blocks vcpkg from performing builds on demand and will fail if a package cannot be found in any binary caches. - -### `--recurse` - -**Classic Mode Only** - -Approve an install plan that requires rebuilding packages. - -In order to modify the set of features of an installed package, vcpkg must remove and rebuild that package. Because this has the potential of failing and leaving the install tree with fewer packages than the user started with, the user must approve plans that rebuild packages by passing this flag. - -### `--x-use-aria2` - -**Experimental and may change or be removed at any time** - -Use aria2 to perform download tasks. - - - -### `--x-write-nuget-packages-config` - -**Experimental and may change or be removed at any time** - -Writes out a NuGet `packages.config`-formatted file for use with [Binary Caching][]. - -This option can be used in conjunction with `--dry-run` to obtain the list of NuGet packages required from [Binary Caching][] without building or installing any packages. This enables the NuGet command line to be invoked separately for advanced scenarios, such as using alternate protocols to acquire the `.nupkg` files. - -### `--no-print-usage` - -Suppress generation of usage text printed at the end of installation. - -[Asset Caching]: ../users/assetcaching.md -[Binary Caching]: ../users/binarycaching.md -[Manifest Mode]: ../users/manifests.md -[supports]: ../users/manifests.md#supports -[default-features]: ../users/manifests.md#default-features -[dependencies]: ../users/manifests.md#dependencies diff --git a/docs/commands/integrate.md b/docs/commands/integrate.md deleted file mode 100644 index 8ea29899b8..0000000000 --- a/docs/commands/integrate.md +++ /dev/null @@ -1,84 +0,0 @@ -# vcpkg integrate - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/integrate.md).** - -## Synopsis - -**Buildsystem Integration** -```no-highlight -vcpkg integrate [options] install -vcpkg integrate [options] remove -vcpkg integrate [options] project -``` -**Shell Integration** -```no-highlight -vcpkg integrate [options] powershell -vcpkg integrate [options] bash -vcpkg integrate [options] zsh -vcpkg integrate [options] x-fish -``` - -## Description - -Integrate vcpkg with shells and buildsystems. - -### `vcpkg integrate install` - -Integrates with [Visual Studio](../users/buildsystems/msbuild-integration.md#user-wide-integration) (Windows-only), sets the user-wide vcpkg instance, and displays CMake integration help. - -On Windows with Visual Studio 2015, this subcommand will add redirecting logic into the MSBuild installation which will automatically pick up each user's user-wide vcpkg instance. Visual Studio 2017 and newer have this logic in the box. - -To set the user-wide vcpkg instance, vcpkg creates a few short files containing the absolute path to the vcpkg instance inside the user's user-wide configuration location: - -- `%LOCALAPPDATA%\vcpkg` or `%APPDATA%\Local\vcpkg` on Windows -- `$HOME/.vcpkg` or `/var/.vcpkg` on non-Windows - -Displays the full path to the [CMake toolchain file](../users/buildsystems/cmake-integration.md). Running this command is not required to use the toolchain file. - -### `vcpkg integrate remove` - -Removes the user-wide vcpkg instance setting. - -This command deletes the linking files from the user-wide configuration location created by `vcpkg integrate install`. - -### `vcpkg integrate project` - -Creates a linked NuGet package for MSBuild integration. - -See [MSBuild Per-Project Integration](../users/buildsystems/msbuild-integration.md#linked-nuget-package) for more information. - -### `vcpkg integrate powershell` - -**Windows Only** - -Adds vcpkg tab-completion support to the current user's Powershell profile. - -### `vcpkg integrate bash` - -**Non-Windows Only** - -Adds vcpkg tab-completion support to the current user's `.bashrc` (`.bash_profile` on MacOS). - -### `vcpkg integrate zsh` - -**Non-Windows Only** - -Adds vcpkg tab-completion support to the current user's `.zshrc`. - -### `vcpkg integrate x-fish` - -**Non-Windows Only** - -Adds vcpkg tab-completion support to the current user's fish shell completions directory. - -## Example -```no-highlight -$ vcpkg integrate install -Applied user-wide integration for this vcpkg root. - -CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=/workspaces/vcpkg/scripts/buildsystems/vcpkg.cmake" -``` - -## Options - -All vcpkg commands support a set of [common options](common-options.md). diff --git a/docs/commands/list.md b/docs/commands/list.md deleted file mode 100644 index c2281e96c1..0000000000 --- a/docs/commands/list.md +++ /dev/null @@ -1,31 +0,0 @@ -# vcpkg list - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/list.md).** - -## Synopsis - -```no-highlight -vcpkg list [options] -``` - -## Description - -Shows a list of the packages in the installed tree, along with the version and description of each. - -## Example -```no-highlight -$ vcpkg list - -cxxopts:x64-windows 3.0.0 This is a lightweight C++ option parser library... -fmt:x64-windows 9.0.0 Formatting library for C++. It can be used as a... -range-v3:x64-windows 0.12.0 Range library for C++11/14/17/20. -vcpkg-cmake-config:x64-windows 2022-02-06#1 -vcpkg-cmake:x64-windows 2022-08-18 -``` - -## Options - -All vcpkg commands support a set of [common options](https://github.com/microsoft/vcpkg/blob/5fac018507e67a8b98141b9d4cebeb07c9bd5cba/docs/commands/common-options.md). - -### `--x-full-desc` -Print the full, untruncated description of each package. diff --git a/docs/commands/remove.md b/docs/commands/remove.md deleted file mode 100644 index 4e1cb0c1c2..0000000000 --- a/docs/commands/remove.md +++ /dev/null @@ -1,43 +0,0 @@ -# vcpkg remove - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/remove.md).** - -## Synopsis - -```no-highlight -vcpkg remove [options] ... -``` - -```no-highlight -vcpkg remove --outdated [options] -``` - -## Description - -Remove port packages from Classic Mode. - -`remove` removes listed packages and any packages that require them from the Classic Mode [installed directory](common-options.md#install-root). See the [install command documentation](install.md#package-syntax) for detailed syntax of the `` parameter. - -This command is not currently supported in [Manifest Mode][]. - -## Options - -All vcpkg commands support a set of [common options](common-options.md). - -### `--recurse` - -Allow removing packages not specified on the command line. - -By default, vcpkg refuses to execute a removal plan that would remove packages not listed on the command line. - -### `--dry-run` - -Print the packages to be removed, but do not remove them. - -### `--outdated` - -Remove all packages that do not match the available port versions. - -For each installed package, vcpkg will compare the installed version string to the version string of the current recipe. If those versions differ, the package will be selected for removal. If `--outdated` is passed, no packages should be listed on the command line. - -[Manifest Mode]: ../users/manifests.md diff --git a/docs/commands/search.md b/docs/commands/search.md deleted file mode 100644 index 093685fa33..0000000000 --- a/docs/commands/search.md +++ /dev/null @@ -1,37 +0,0 @@ -# vcpkg search - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/search.md).** - -## Synopsis - -```no-highlight -vcpkg search [options] [query] -``` - -## Description - -Searches for available packages by name and description. - -Search performs a case-insensitive search through all available package names and descriptions. The results are displayed in a tabular format. - -## Example -```no-highlight -$ vcpkg search zlib -miniz 2.2.0#1 Single C source file zlib-replacement library -zlib 1.2.12#1 A compression library -zlib-ng 2.0.6 zlib replacement with optimizations for 'next generation' systems -``` - -## Options - -All vcpkg commands support a set of [common options](common-options.md). - -### `--x-full-desc` - -**Experimental and may change or be removed at any time** - -Do not truncate long descriptions. - -By default, long descriptions will be truncated to keep the tabular output browsable. - -[Registries]: ../users/registries.md diff --git a/docs/commands/update-baseline.md b/docs/commands/update-baseline.md deleted file mode 100644 index 8a5b36711f..0000000000 --- a/docs/commands/update-baseline.md +++ /dev/null @@ -1,42 +0,0 @@ -# vcpkg x-update-baseline - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/update-baseline.md).** - -**This command is experimental and may change or be removed at any time** - -## Synopsis - -```no-highlight -vcpkg x-update-baseline [options] [--add-initial-baseline] [--dry-run] -``` - -## Description - -Update baselines for all configured [registries][]. - -In [Manifest Mode][], this command operates on all [registries][] in the `vcpkg.json` and the [`vcpkg-configuration.json`][vcj]. In Classic Mode, this command operates on the [`vcpkg-configuration.json`][vcj] in the vcpkg instance (`$VCPKG_ROOT`). - -See the [versioning documentation](../users/versioning.md#baselines) for more information about baselines. - -## Options - -All vcpkg commands support a set of [common options](common-options.md). - -### `--dry-run` - -Print the planned baseline upgrades, but do not modify the files on disk. - - - -### `--add-initial-baseline` - -**[Manifest Mode][] Only** - -Add a [`"builtin-baseline"`][builtin-baseline] field to the `vcpkg.json` if it does not already have one. - -Without this flag, it is an error to run this command on a manifest that does not have any [registries][] configured. - -[Manifest Mode]: ../users/manifests.md -[builtin-baseline]: ../users/manifests.md#builtin-baseline -[vcj]: ../users/registries.md#vcpkg-configurationjson -[registries]: ../users/registries.md diff --git a/docs/commands/version.md b/docs/commands/version.md deleted file mode 100644 index 4c4df15418..0000000000 --- a/docs/commands/version.md +++ /dev/null @@ -1,25 +0,0 @@ -# vcpkg version - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/version.md).** - -## Synopsis - -```no-highlight -vcpkg version -``` - -## Description - -Displays the version of the vcpkg executable. - -## Example -```no-highlight -$ vcpkg version -vcpkg package management program version 2022-09-01-dfb82802c8cc562ce3b665a904a65b22314de724 - -See LICENSE.txt for license information. -``` - -## Options - -All vcpkg commands support a set of [common options](common-options.md). diff --git a/docs/examples/adding-an-explicit-usage.md b/docs/examples/adding-an-explicit-usage.md deleted file mode 100644 index 57fb89cb43..0000000000 --- a/docs/examples/adding-an-explicit-usage.md +++ /dev/null @@ -1,36 +0,0 @@ -## How to: Add an explicit usage file to a port. - -`vcpkg` generates usage text for customers who install particular ports, if the customer names that -specific port. For example: - -``` -$> vcpkg install zlib:x64-windows -Computing installation plan... -The following packages will be built and installed: - * vcpkg-cmake[core]:x64-windows -> 2022-09-26 - zlib[core]:x64-windows -> 1.2.12#2 -Additional packages (*) will be modified to complete this operation. -Detecting compiler hash for triplet x64-windows... -Restored 2 package(s) from C:\Users\bion\AppData\Local\vcpkg\archives in 77.46 ms. Use --debug to see more details. -Installing 1/2 vcpkg-cmake:x64-windows... -Elapsed time to handle vcpkg-cmake:x64-windows: 10.32 ms -Installing 2/2 zlib:x64-windows... -Elapsed time to handle zlib:x64-windows: 20.89 ms -Total elapsed time: 2.747 s - -The package zlib is compatible with built-in CMake targets: - - find_package(ZLIB REQUIRED) - target_link_libraries(main PRIVATE ZLIB::ZLIB) -``` - -If there is no explicit usage installed by the port, vcpkg will generate default usage text by -inspecting with the port installs. If the default usage text is suboptimal, it can be overridden by -a port installing a file named "usage" in its "share" directory. - -1. Create a file named `usage` in the port directory, with the content you want displayed. -2. To `portfile.cmake`, add -``` -file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}") -``` -3. Update the port-version and rerun `vcpkg x-add-version` if necessary. diff --git a/docs/examples/installing-and-using-packages.md b/docs/examples/installing-and-using-packages.md deleted file mode 100644 index 612d5bdbe0..0000000000 --- a/docs/examples/installing-and-using-packages.md +++ /dev/null @@ -1,182 +0,0 @@ -## Installing and Using Packages Example: SQLite - -_Note: this old example uses Classic Mode, but most developers will be happier with Manifest Mode. See [Manifest Mode: CMake Example](manifest-mode-cmake.md) for an example of converting to Manifest Mode._ - - - [Step 1: Install](#install) - - [Step 2: Use](#use) - - [VS/MSBuild Project (User-wide integration)](#msbuild) - - [CMake (Toolchain file)](#cmake) - - [Other integration options](../users/buildsystems/integration.md) - ---- - -## Step 1: Install - -First, we need to know what name [SQLite](https://sqlite.org) goes by in the ports tree. To do that, we'll run the `search` command and inspect the output: -```no-highlight -PS D:\src\vcpkg> .\vcpkg search sqlite -libodb-sqlite 2.4.0 Sqlite support for the ODB ORM library -sqlite3 3.32.1 SQLite is a software library that implements a se... - -If your library is not listed, please open an issue at: - https://github.com/Microsoft/vcpkg/issues -``` -Looking at the list, we can see that the port is named "sqlite3". You can also run the `search` command without arguments to see the full list of packages. - -Installing is then as simple as using the `install` command. -```no-highlight -PS D:\src\vcpkg> .\vcpkg install sqlite3 -Computing installation plan... -The following packages will be built and installed: - sqlite3[core]:x86-windows -Starting package 1/1: sqlite3:x86-windows -Building package sqlite3[core]:x86-windows... --- Downloading https://sqlite.org/2020/sqlite-amalgamation-3320100.zip... --- Extracting source C:/src/vcpkg/downloads/sqlite-amalgamation-3320100.zip --- Applying patch fix-arm-uwp.patch --- Using source at C:/src/vcpkg/buildtrees/sqlite3/src/3320100-15aeda126a.clean --- Configuring x86-windows --- Building x86-windows-dbg --- Building x86-windows-rel --- Performing post-build validation --- Performing post-build validation done -Building package sqlite3[core]:x86-windows... done -Installing package sqlite3[core]:x86-windows... -Installing package sqlite3[core]:x86-windows... done -Elapsed time for package sqlite3:x86-windows: 12 s - -Total elapsed time: 12.04 s - -The package sqlite3:x86-windows provides CMake targets: - - find_package(unofficial-sqlite3 CONFIG REQUIRED) - target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3)) - -``` - -We can check that sqlite3 was successfully installed for x86 Windows desktop by running the `list` command. -```no-highlight -PS D:\src\vcpkg> .\vcpkg list -sqlite3:x86-windows 3.32.1 SQLite is a software library that implements a se... -``` - -To install for other architectures and platforms such as Universal Windows Platform or x64 Desktop, you can suffix the package name with `:`. -```no-highlight -PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows -``` - -See `.\vcpkg help triplet` for all supported targets. - ---- - -## Step 2: Use - -#### VS/MSBuild Project (User-wide integration) - -The recommended and most productive way to use vcpkg is via user-wide integration, making the system available for all projects you build. The user-wide integration will prompt for administrator access the first time it is used on a given machine, but afterwards is no longer required and the integration is configured on a per-user basis. -```no-highlight -PS D:\src\vcpkg> .\vcpkg integrate install -Applied user-wide integration for this vcpkg root. - -All C++ projects can now #include any installed libraries. -Linking will be handled automatically. -Installing new libraries will make them instantly available. -``` -*Note: You will need to restart Visual Studio or perform a Build to update intellisense with the changes.* - -You can now simply use File -> New Project in Visual Studio and the library will be automatically available. For SQLite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html). - -To remove the integration for your user, you can use `.\vcpkg integrate remove`. - - -#### CMake (Toolchain File) - -The best way to use installed libraries with cmake is via the toolchain file `scripts\buildsystems\vcpkg.cmake`. To use this file, you simply need to add it onto your CMake command line as: -`-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake`. - -If you are using CMake through Open Folder with Visual Studio you can define `CMAKE_TOOLCHAIN_FILE` by adding a "variables" section to each of your `CMakeSettings.json` configurations: - -```json -{ - "configurations": [{ - "name": "x86-Debug", - "generator": "Visual Studio 15 2017", - "configurationType" : "Debug", - "buildRoot": "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}", - "cmakeCommandArgs": "", - "buildCommandArgs": "-m -v:minimal", - "variables": [{ - "name": "CMAKE_TOOLCHAIN_FILE", - "value": "D:\\src\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake" - }] - }] -} -``` -*Note: It might be necessary to delete the CMake cache folder of each modified configuration, to force a full regeneration. In the `CMake` menu, under `Cache ()` you'll find `Delete Cache Folders`.* - -Now let's make a simple CMake project with a main file. -```cmake -# CMakeLists.txt -cmake_minimum_required(VERSION 3.0) -project(test) - -find_package(unofficial-sqlite3 CONFIG REQUIRED) - -add_executable(main main.cpp) - -target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3) -``` -```cpp -// main.cpp -#include -#include - -int main() -{ - printf("%s\n", sqlite3_libversion()); - return 0; -} -``` - -Then, we build our project in the normal CMake way: -```no-highlight -PS D:\src\cmake-test> mkdir build -PS D:\src\cmake-test> cd build -PS D:\src\cmake-test\build> cmake .. "-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake" - // omitted CMake output here // --- Build files have been written to: D:/src/cmake-test/build -PS D:\src\cmake-test\build> cmake --build . - // omitted MSBuild output here // -Build succeeded. - 0 Warning(s) - 0 Error(s) - -Time Elapsed 00:00:02.38 -PS D:\src\cmake-test\build> .\Debug\main.exe -3.15.0 -``` - -*Note: The correct sqlite3.dll is automatically copied to the output folder when building for x86-windows. You will need to distribute this along with your application.* - -##### Handling libraries without native cmake support - -Unlike other platforms, we do not automatically add the `include\` directory to your compilation line by default. If you're using a library that does not provide CMake integration, you will need to explicitly search for the files and add them yourself using [`find_path()`][1] and [`find_library()`][2]. - -```cmake -# To find and use catch -find_path(CATCH_INCLUDE_DIR catch.hpp) -include_directories(${CATCH_INCLUDE_DIR}) - -# To find and use azure-storage-cpp -find_path(WASTORAGE_INCLUDE_DIR was/blob.h) -find_library(WASTORAGE_LIBRARY wastorage) -include_directories(${WASTORAGE_INCLUDE_DIR}) -link_libraries(${WASTORAGE_LIBRARY}) - -# Note that we recommend using the target-specific directives for a cleaner cmake: -# target_include_directories(main ${LIBRARY}) -# target_link_libraries(main PRIVATE ${LIBRARY}) -``` - -[1]: https://cmake.org/cmake/help/latest/command/find_path.html -[2]: https://cmake.org/cmake/help/latest/command/find_library.html diff --git a/docs/examples/manifest-mode-cmake.md b/docs/examples/manifest-mode-cmake.md deleted file mode 100644 index 77891b60e7..0000000000 --- a/docs/examples/manifest-mode-cmake.md +++ /dev/null @@ -1,200 +0,0 @@ -# Manifest Mode: CMake Example - -We would like to add [vcpkg manifest support](../users/manifests.md) to an existing cmake project! -Let's create a simple project that prints the fibonacci sequence up to a certain number, -using some common dependencies. - -## Initial Layout - -Let's create the following file layout: - -```no-highlight -fibo/ - src/ - main.cxx - CMakeLists.txt -``` - -And we wish to use [fmt](https://github.com/fmtlib/fmt), [range-v3](https://github.com/ericniebler/range-v3), -and [cxxopts](https://github.com/jarro2783/cxxopts). - -Let's write our `CMakeLists.txt` first: - -```cmake -cmake_minimum_required(VERSION 3.15) - -project(fibo CXX) - -find_package(fmt REQUIRED) -find_package(range-v3 REQUIRED) -find_package(cxxopts REQUIRED) - -add_executable(fibo src/main.cxx) -target_compile_features(fibo PRIVATE cxx_std_17) - -target_link_libraries(fibo - PRIVATE - fmt::fmt - range-v3::range-v3 - cxxopts::cxxopts) -``` - -And then we should add `main.cxx`: - -```cxx -#include -#include -#include - -namespace view = ranges::views; - -int fib(int x) { - int a = 0, b = 1; - - for (int it : view::repeat(0) | view::take(x)) { - (void)it; - int tmp = a; - a += b; - b = tmp; - } - - return a; -} - -int main(int argc, char** argv) { - cxxopts::Options options("fibo", "Print the fibonacci sequence up to a value 'n'"); - options.add_options() - ("n,value", "The value to print to", cxxopts::value()->default_value("10")); - - auto result = options.parse(argc, argv); - auto n = result["value"].as(); - - for (int x : view::iota(1) | view::take(n)) { - fmt::print("fib({}) = {}\n", x, fib(x)); - } -} -``` - -This is a simple project of course, but it should give us a clean project to start with. -Let's try it out! - -Let's assume you have `fmt`, `range-v3`, and `cxxopts` installed with vcpkg classic mode; -then, you can just do a simple: - -```cmd -D:\src\fibo> cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake --- Building for: Visual Studio 16 2019 --- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.19041. --- The CXX compiler identification is MSVC 19.27.29111.0 --- Detecting CXX compiler ABI info --- Detecting CXX compiler ABI info - done --- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx64/x64/cl.exe - skipped --- Detecting CXX compile features --- Detecting CXX compile features - done --- Configuring done --- Generating done --- Build files have been written to: D:/src/fibo/build -D:\src\fibo> cmake --build build -Microsoft (R) Build Engine version 16.7.0+b89cb5fde for .NET Framework -Copyright (C) Microsoft Corporation. All rights reserved. - - Checking Build System - Building Custom Rule D:/src/fibo/CMakeLists.txt - main.cxx - The contents of are available only with C++20 or later. - fibo.vcxproj -> D:\src\fibo\build\Debug\fibo.exe - Building Custom Rule D:/src/fibo/CMakeLists.txt -``` - -And now we can try out the `fibo` binary! - -```cmd -D:\src\fibo> .\build\Debug\fibo.exe -n 7 -fib(1) = 1 -fib(2) = 1 -fib(3) = 2 -fib(4) = 3 -fib(5) = 5 -fib(6) = 8 -fib(7) = 13 -``` - -it works! - -## Converting to Manifest Mode - -We now wish to use manifest mode, so all of our dependencies are managed for us! Let's write a `vcpkg.json`: - -```json -{ - "name": "fibo", - "version-string": "0.1.0", - "dependencies": [ - "cxxopts", - "fmt", - "range-v3" - ] -} -``` - -Let's delete the build directory and rerun the build: - -```cmd -D:\src\fibo> rmdir /S /Q build -D:\src\fibo> cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake --- Running vcpkg install -Detecting compiler hash for triplet x64-windows... -The following packages will be built and installed: - cxxopts[core]:x64-windows - fmt[core]:x64-windows - range-v3[core]:x64-windows -Starting package 1/3: cxxopts:x64-windows -Building package cxxopts[core]:x64-windows... -Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\d2\d2d1e5302cdfefef2fd090d8eda84cc0c1fbe6f1.zip -Building package cxxopts[core]:x64-windows... done -Installing package cxxopts[core]:x64-windows... -Installing package cxxopts[core]:x64-windows... done -Elapsed time for package cxxopts:x64-windows: 50.64 ms -Starting package 2/3: fmt:x64-windows -Building package fmt[core]:x64-windows... -Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\bf\bf00d5214e912d71414b545b241f54ef87fdf6e5.zip -Building package fmt[core]:x64-windows... done -Installing package fmt[core]:x64-windows... -Installing package fmt[core]:x64-windows... done -Elapsed time for package fmt:x64-windows: 225 ms -Starting package 3/3: range-v3:x64-windows -Building package range-v3[core]:x64-windows... -Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\fe\fe2cdedef6953bf954e8ddca471bf3cc8d9b06d7.zip -Building package range-v3[core]:x64-windows... done -Installing package range-v3[core]:x64-windows... -Installing package range-v3[core]:x64-windows... done -Elapsed time for package range-v3:x64-windows: 1.466 s - -Total elapsed time: 1.742 s - --- Running vcpkg install - done --- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.19041. --- The CXX compiler identification is MSVC 19.27.29111.0 --- Detecting CXX compiler ABI info --- Detecting CXX compiler ABI info - done --- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx64/x64/cl.exe - skipped --- Detecting CXX compile features --- Detecting CXX compile features - done --- Configuring done --- Generating done --- Build files have been written to: D:/src/fibo/build -D:\src\fibo> cmake --build build -Microsoft (R) Build Engine version 16.7.0+b89cb5fde for .NET Framework -Copyright (C) Microsoft Corporation. All rights reserved. - - Checking Build System - Building Custom Rule D:/src/fibo/CMakeLists.txt - main.cxx - The contents of are available only with C++20 or later. - fibo.vcxproj -> D:\src\fibo\build\Debug\fibo.exe - Building Custom Rule D:/src/fibo/CMakeLists.txt -``` - -You can see that with just a _single file_, we've changed over to manifests without _any_ trouble. -The build system doesn't change _at all_! We just add a `vcpkg.json` file, delete the build directory, -and reconfigure. And we're done! diff --git a/docs/examples/modify-baseline-to-pin-old-boost.md b/docs/examples/modify-baseline-to-pin-old-boost.md deleted file mode 100644 index 21d6f1a3ee..0000000000 --- a/docs/examples/modify-baseline-to-pin-old-boost.md +++ /dev/null @@ -1,191 +0,0 @@ -# Pin old Boost versions -This document will teach you how to set versions of meta-packages like `boost` or `qt5`. - -**What is a meta-package?** -In vcpkg we call meta-packages to ports that by themselves don't install anything but that instead forward installation to another port or ports. The reasons for these meta-packages to exist are plenty: to install different versions of a library depending on platform or to conveniently install/uninstall a catalog of related packages (Boost and Qt). - -In the case of Boost, it is unlikely that a user requires all of the 140+ Boost libraries in their project. For the sake of convenience, vcpkg splits Boost into multiple sub-packages broken down to individual libraries. By doing so, users can limit the subset of Boost libraries that they depend on. - -If a user wants to install all of the Boost libraries available in vcpkg, they can do so by installing the `boost` meta-package. - -Due to the nature of meta-packages, some unexpected issues arise when trying to use them with versioning. If a user writes the following manifest file: - -`vcpkg.json` -```json -{ - "name": "demo", - "version": "1.0.0", - "builtin-baseline": "787fe1418ea968913cc6daf11855ffd8b0b5e9d4", - "dependencies": [ "boost-tuple" ], - "overrides": [ - { "name": "boost", "version": "1.72.0" } - ] -} -``` - -The resulting installation plan is: -``` -The following packages will be built and installed: - boost-assert[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-assert\3393715b4ebe30fe1c3b68acf7f84363e611f156 - boost-compatibility[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-compatibility\cda5675366367789659c59aca65fc57d03c51deb - boost-config[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-config\ca82ca1b9c1739c91f3cf42c68cee56c896ae6bd - boost-container-hash[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-container-hash\bf472c23d29c3d80b562c43471eb92cea998f372 - boost-core[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-core\20a19f6ece37686a02eed33e1f58add8b7a2582a - boost-detail[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-detail\96744251f025f9b3c856a275dfc338031876777b - boost-integer[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-integer\de70ce0d1500df1eda3496c4f98f42f5db256b4a - boost-io[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-io\7bf3407372f8fc2a99321d24a0e952d44fe25bf3 - boost-preprocessor[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-preprocessor\8d78b8ba2e9f54cb00137115ddd2ffec1c63c149 - boost-static-assert[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-static-assert\2a41c4703c7122de25b1c60510c43edc9371f63d - boost-throw-exception[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-throw-exception\b13bdf32a20786a0165cc20205ef63765cac0627 - boost-tuple[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-tuple\22e3d000a178a88992c430d8ae8a0244c7dea674 - boost-type-traits[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-type-traits\8829793f6c6c913257314caa317599f8d253a5ca - boost-uninstall[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-uninstall\08933bad27b6d41caef0940c31e2069ecb6a079c - boost-utility[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-utility\47572946bf6a63c731b9c4142eecb8bef3d3b270 - boost-vcpkg-helpers[core]:x64-windows -> 7#2 -- D:\vcpkg\buildtrees\versioning\versions\boost-vcpkg-helpers\2a21e5ab45d1ce41c185faf85dff0670ea6def1d -``` - -It is reasonable to expect that overriding `boost` to version 1.72.0 results in all Boost packages being pinned to version 1.72.0. **However, vcpkg does not treat the `boost` meta-package any differently that any other port.** In other words, vcpkg has no notion that `boost` is related to all the other `boost-*` libraries, other than it depends on all of them. For this reason, all the other boost packages are installed at version 1.75.0, which is the baseline version. - -Below, we describe two methods to pin down Boost versions effectively. - -## Method 1: Pin specific packages -Use `"overrides"` to force specific versions in a package-by-package basis. - -`vcpkg.json` -```json -{ - "name": "demo", - "version": "1.0.0", - "builtin-baseline": "787fe1418ea968913cc6daf11855ffd8b0b5e9d4", - "dependencies": [ "boost-tuple" ], - "overrides": [ - { "name": "boost-core", "version": "1.72" }, - { "name": "boost-integer", "version": "1.72" }, - { "name": "boost-io", "version": "1.72" }, - { "name": "boost-tuple", "version": "1.72" } - ] -} -``` - -This method allows you to quickly set the specific versions you want, but you will need to write an override for each package. Boost libraries are also heavily interdependent, which means that you may end up writing a lot of override lines. - -The second method makes it easy to pin the entire Boost collection and end up with a very simple manifest file. - -## Method 2: Modify baseline -An easy way to set the version for the entirety of boost is to use the `"builtin-baseline"` property. - -As of right now, it is only possible to go back to Boost version `1.75.0` using a baseline, since that was the contemporary Boost version when the versioning feature was merged. **But, it is possible to modify the baseline to whatever you like and use that instead.** - -### Step 1: Create a new branch -As described in the versioning documentation. The value that goes in `"builtin-baseline"` is a git commit in the microsoft/vcpkg repository's history. If you want to customize the baseline and have control over the vcpkg instance, you can create a new commit with said custom baseline. - -Let's start by creating a new branch to hold our modified baseline. - -In the directory containing your clone of the vcpkg Git repository run: - -``` -git checkout -b custom-boost-baseline -``` - -This will create a new branch named `custom-boost-baseline` and check it out immediately. - -### Step 2: Modify the baseline -The next step is to modify the baseline file, open the file in your editor of choice and modify the entries for the Boost libraries. - -Change the `"baseline"` version to your desired version. -_NOTE: Remember to also set the port versions to 0 (or your desired version)._ - -`${vcpkg-root}/versions/baseline.json` -```diff -... - "boost": { -- "baseline": "1.75.0", -+ "baseline": "1.72.0", - "port-version": 0 - }, - "boost-accumulators": { -- "baseline": "1.75.0", -- "port-version": 1 -+ "baseline": "1.72.0", -+ "port-version": 0 - }, - "boost-algorithm": { -- "baseline": "1.75.0", -+ "baseline": "1.72.0", - "port-version": 0 - }, - "boost-align": { -- "baseline": "1.75.0", -+ "baseline": "1.72.0", - "port-version": 0 - }, -... - "boost-uninstall: { - "baseline": "1.75.0", - "port-version": 0 - }, -... -``` - -Some `boost-` packages are helpers used by vcpkg and are not part of Boost. For example, `"boost-uninstall"` is a vcpkg helper to conveniently uninstall all Boost libraries, but it didn't exist for Boost version `1.72.0`, in this case it is fine to leave it at `1.75.0` to avoid baseline errors (since all versions in `baseline.json` must have existed). - -### Step 3: Commit your changes -After saving your modified file, run these commands to commit your changes: - -``` -git add versions/baseline.json -git commit -m "Baseline Boost 1.72.0" -``` - -You can set the commit message to whatever you want, just make it useful for you. - -### Step 4: Get your baseline commit SHA -Once all your changes are ready, you can get the commit SHA by running: -``` -git rev-parse HEAD -``` - -The output of that command will be the commit SHA you need to put as the `"builtin-baseline"` in your project's manifest file. Copy the 40-hex digits and save them to use later in your manifest file. - -### Step 5: (Optional) Go back to the main repository branch -Once your changes have been committed locally, you can refer to the commit SHA regardless of the repository branch you're working on. So, let's go back to the main vcpkg repository branch. - -``` -git checkout master -``` - -### Step 6: Create your manifest file with your custom baseline - -```json -{ - "name": "demo", - "version": "1.0.0", - "builtin-baseline": "9b5cf7c3d9376ddf43429671282972ec4f99aa85", - "dependencies": [ "boost-tuple" ] -} -``` - -In this example, commit SHA `9b5cf7c3d9376ddf43429671282972ec4f99aa85` is the commit ID with the modified baseline. Even when a different branch (`master` in this case) is checked out, Git is able to find the commit as long as the branch with the modified baseline exists (the `custom-boost-baseline` branch we created in step 1). - -We run `vcpkg install` in the directory containing our manifest file and the output looks like this: - -``` -The following packages will be built and installed: - boost-assert[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-assert\6754398591f48435b28014ca0d60e5375a4c04d1 - boost-compatibility[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-compatibility\9893ff3c554575bc712df4108a949e07b269f401 - boost-config[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-config\de2784767046b06ec31eb718f10df512e51f2aad - boost-container-hash[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-container-hash\cc19fb0154bbef188f309f49b2664ec7623b96b6 - boost-core[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-core\0eb5e20df9e267e9eca325be946f52ceb8a60229 - boost-detail[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-detail\759d7c6a3f9dbaed0b0c69fa0bb764f7606bb02d - boost-integer[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-integer\173956c61a26e83b0f8b58b0baf60f06aeee637c - boost-preprocessor[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-preprocessor\86eb3938b7875f124feb845331dbe84cbab5d1c6 - boost-static-assert[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-static-assert\e82d8f7f3ee07e927dc374f5a08ed6d6f4ef81f4 - boost-throw-exception[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-throw-exception\64df295f7df41de4fcb219834889b126b5020def - boost-tuple[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-tuple\b3e1b01ffce6e367e4fed0a5538a8546abacb6b2 - boost-type-traits[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-type-traits\5e44ec657660eccf4d3b2710b092dd238e1e7a2d - boost-uninstall[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-uninstall\08933bad27b6d41caef0940c31e2069ecb6a079c - boost-utility[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-utility\7d721b2458d5d595ac341eb54883274f38a4b8c2 - boost-vcpkg-helpers[core]:x64-windows -> 7#2 -- D:\vcpkg\buildtrees\versioning\versions\boost-vcpkg-helpers\2a21e5ab45d1ce41c185faf85dff0670ea6def1d -``` - -Notice how simple our manifest file has become, instead of having a multitude of `"overrides"` you can pin down all Boost packages just by setting the `"builtin-baseline"` to be your modified baseline commit SHA. diff --git a/docs/examples/overlay-triplets-linux-dynamic.md b/docs/examples/overlay-triplets-linux-dynamic.md deleted file mode 100644 index 25872b724b..0000000000 --- a/docs/examples/overlay-triplets-linux-dynamic.md +++ /dev/null @@ -1,126 +0,0 @@ -# Using Overlay Triplets - -## Building dynamic libraries on Linux - -Using **vcpkg** you can build libraries for many configurations out of the box. However, this doesn't currently include shared libraries on Linux and Mac OS. - -This doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms! This document will guide you through creating your own custom triplets with `--overlay-triplets` to easily build dynamic libraries on Linux. - -### Step 1: Create the custom triplet files - -To save time, copy the existing `x64-linux.cmake` triplet file. - -```sh -~/git$ mkdir custom-triplets -~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-dynamic.cmake -``` - -And modify `custom-triplets/x64-linux-dynamic.cmake` to match the contents below: -```cmake -# ~/git/custom-triplets/x64-linux-dynamic.cmake -set(VCPKG_TARGET_ARCHITECTURE x64) -set(VCPKG_CRT_LINKAGE dynamic) -set(VCPKG_LIBRARY_LINKAGE dynamic) # This changed from static to dynamic - -set(VCPKG_CMAKE_SYSTEM_NAME Linux) -``` - -### Step 2: Use `--overlay-triplets` to build dynamic libraries - -Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory. - -``` -~/git$ vcpkg/vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=custom-triplets -The following packages will be built and installed: - sqlite3[core]:x64-linux-dynamic -Starting package 1/1: sqlite3:x64-linux-dynamic -Building package sqlite3[core]:x64-linux-dynamic... --- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux-dynamic.cmake --- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip... --- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip --- Applying patch fix-arm-uwp.patch --- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92 --- Configuring x64-linux-dynamic-dbg --- Configuring x64-linux-dynamic-rel --- Building x64-linux-dynamic-dbg --- Building x64-linux-dynamic-rel --- Performing post-build validation --- Performing post-build validation done -Building package sqlite3[core]:x64-linux-dynamic... done -Installing package sqlite3[core]:x64-linux-dynamic... -Installing package sqlite3[core]:x64-linux-dynamic... done -Elapsed time for package sqlite3:x64-linux-dynamic: 44.82 s - -Total elapsed time: 44.82 s - -The package sqlite3:x64-linux-dynamic provides CMake targets: - - find_package(unofficial-sqlite3 CONFIG REQUIRED) - target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3) -``` - -Overlay triplets enables your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`. - -When using the `--overlay-triplets` option, a message like the following lets you know that a custom triplet is being used: - -``` --- Loading triplet configuration from: /home/custom-triplets/x64-linux-dynamic.cmake -``` - -## Overriding default triplets - -As you may have noticed, the default triplets for Windows (`x86-windows` and `x64-windows`) install dynamic libraries, while a suffix (`-static`) is needed for static libraries. This is different with Linux and Mac OS where static libraries are built by `x64-linux` and `x64-osx`. - -Using `--overlay-triplets` it is possible to override the default triplets to accomplish the same behavior on Linux: - -* `x64-linux`: Builds dynamic libraries, -* `x64-linux-static`: Builds static libraries. - -### Step 1: Create the overlay triplets - -Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`. Then, copy the default `x64-linux` triplet (which builds static libraries) in your `custom-triplets` folder and rename it to `x64-linux-static.cmake`. - -```sh -~/git$ mv custom-triplets/x64-linux-dynamic.cmake custom-triplets/x64-linux.cmake -~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-static.cmake -``` - -### Step 2: Use `--overlay-triplets` to override default triplets - -Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory. - -``` -~/git$ vcpkg/vcpkg install sqlite3:x64-linux --overlay-triplets=custom-triplets -The following packages will be built and installed: - sqlite3[core]:x64-linux -Starting package 1/1: sqlite3:x64-linux -Building package sqlite3[core]:x64-linux... --- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake --- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip... --- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip --- Applying patch fix-arm-uwp.patch --- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92 --- Configuring x64-linux-dbg --- Configuring x64-linux-rel --- Building x64-linux-dbg --- Building x64-linux-rel --- Performing post-build validation --- Performing post-build validation done -Building package sqlite3[core]:x64-linux... done -Installing package sqlite3[core]:x64-linux... -Installing package sqlite3[core]:x64-linux... done -Elapsed time for package sqlite3:x64-linux: 44.82 s - -Total elapsed time: 44.82 s - -The package sqlite3:x64-linux provides CMake targets: - - find_package(unofficial-sqlite3 CONFIG REQUIRED) - target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3) -``` - -Note that the default triplet is masked by your custom triplet: - -``` --- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake -``` diff --git a/docs/examples/packaging-github-repos.md b/docs/examples/packaging-github-repos.md deleted file mode 100644 index 889a4aaa18..0000000000 --- a/docs/examples/packaging-github-repos.md +++ /dev/null @@ -1,54 +0,0 @@ -## Packaging Github Repos Example: libogg -### Create the manifest file -The manifest file (called `vcpkg.json`) is a json file describing the package's metadata. - -For libogg, we'll create the file `ports/libogg/vcpkg.json` with the following content: - -```json -{ - "name": "libogg", - "version-string": "1.3.3", - "description": "Ogg is a multimedia container format, and the native file and stream format for the Xiph.org multimedia codecs." -} -``` - -You can format the manifest file to our specifications with `vcpkg format-manifest ports/libogg/vcpkg.json`. - -### Create the portfile -`portfile.cmake` describes how to build and install the package. First we download the project from Github with [`vcpkg_from_github`](../maintainers/vcpkg_from_github.md): - -```cmake -vcpkg_from_github( - OUT_SOURCE_PATH SOURCE_PATH - REPO xiph/ogg - REF v1.3.3 - SHA512 0bd6095d647530d4cb1f509eb5e99965a25cc3dd9b8125b93abd6b248255c890cf20710154bdec40568478eb5c4cde724abfb2eff1f3a04e63acef0fbbc9799b - HEAD_REF master -) -``` - -The important parts to update are `REPO` for the GitHub repository path, `REF` for a stable tag/commit to use, and `SHA512` with the checksum of the downloaded file (you can get this easily by setting it to `0`, trying to install the package, and copying the checksum). - -Finally, we configure the project with CMake, install the package, and copy over the license file: - -```cmake -vcpkg_cmake_configure(SOURCE_PATH ${SOURCE_PATH}) -vcpkg_cmake_install() -file(INSTALL "${SOURCE_PATH}/COPYING" DESTINATION "${CURRENT_PACKAGES_DIR}/share/libogg" RENAME copyright) -``` - -Check the documentation for [`vcpkg_cmake_configure`](../maintainers/vcpkg_cmake_configure.md) and [`vcpkg_cmake_install`](../maintainers/vcpkg_cmake_install.md) if your package needs additional options. - -Now you can run `vcpkg install libogg` to build and install the package. - -### Suggested example portfiles -In the `ports/` directory are many libraries that can be used as examples, including many that are not based on CMake. - -- Header only libraries - - rapidjson - - range-v3 -- MSBuild-based - - mpg123 -- Non-CMake, custom buildsystem - - openssl - - ffmpeg diff --git a/docs/examples/packaging-zipfiles.md b/docs/examples/packaging-zipfiles.md deleted file mode 100644 index 7f2a7405bc..0000000000 --- a/docs/examples/packaging-zipfiles.md +++ /dev/null @@ -1,76 +0,0 @@ -## Packaging `.zip` Files Example: zlib - -### Bootstrap with `create` -First, locate a globally accessible archive of the library's sources. Zip, gzip, and bzip are all supported. Strongly prefer official sources or mirrors over unofficial mirrors. - -*Looking at zlib's website, the URL http://zlib.net/zlib-1.2.12.tar.gz looks appropriate.* - -Second, determine a suitable package name. This should be ASCII, lowercase, and recognizable to someone who knows the library's "human name". If the library is already packaged in another package manager, prefer that name. - -*Since zlib is already packaged as zlib, we will use the name zlib2 for this example.* - -Finally, if the server's name for the archive is not very descriptive (such as downloading a zipped commit or branch from GitHub), choose a nice archive name of the form `-.zip`. - -*`zlib1212.zip` is a fine name, so no change needed.* - -All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports/`. - -```no-highlight -PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib-1.2.12.tar.gz zlib1212.tar.gz --- Generated portfile: D:/src/vcpkg/ports/zlib2/portfile.cmake -``` - -### Create the manifest file -In addition to the generated `ports//portfile.cmake`, we also need a `ports//vcpkg.json` file. This file is a simple set of fields describing the package's metadata. - -*For zlib2, we'll create the file `ports/zlib2/vcpkg.json` with the following contents:* -```json -{ - "name": "zlib2", - "version-string": "1.2.12", - "description": "A Massively Spiffy Yet Delicately Unobtrusive Compression Library" -} -``` - -### Tweak the generated portfile -The generated `portfile.cmake` will need some editing to correctly package most libraries in the wild, however we can start by trying out the build. - -```no-highlight -PS D:\src\vcpkg> .\vcpkg install zlib2 -Computing installation plan... -The following packages will be built and installed: - zlib2[core]:x64-uwp -Starting package 1/1: zlib2:x64-uwp -Building package zlib2[core]:x64-uwp... --- Using cached C:/src/vcpkg/downloads/zlib1212.tar.gz --- Cleaning sources at C:/src/vcpkg/buildtrees/zlib2/src/1.2.12-deec42f53b.clean. Pass --editable to vcpkg to reuse sources. --- Extracting source C:/src/vcpkg/downloads/zlib1212.tar.gz --- Applying patch cmake_dont_build_more_than_needed.patch --- Using source at C:/src/vcpkg/buildtrees/zlib2/src/1.2.12-deec42f53b.clean --- Configuring x64-uwp --- Building x64-uwp-dbg --- Building x64-uwp-rel --- Installing: C:/src/vcpkg/packages/zlib2_x64-uwp/share/zlib2/copyright --- Performing post-build validation -Include files should not be duplicated into the /debug/include directory. If this cannot be disabled in the project cmake, use - file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include) -/debug/share should not exist. Please reorganize any important files, then use - file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/share) -The software license must be available at ${CURRENT_PACKAGES_DIR}/share/zlib2/copyright -Found 3 error(s). Please correct the portfile: - D:\src\vcpkg\ports\zlib2\portfile.cmake -``` - -At this point, it is a matter of reading the error messages and log files while steadily improving the quality of the portfile. Zlib required providing a discrete copy of the LICENSE to copy into the package, suppressing the build and installation of executables and headers, and removing the static libraries after they were installed. - -### Suggested example portfiles -In the `ports/` directory are many libraries that can be used as examples, including many that are not based on CMake. - -- Header only libraries - - rapidjson - - range-v3 -- MSBuild-based - - mpg123 -- Non-CMake, custom buildsystem - - openssl - - ffmpeg diff --git a/docs/examples/patching.md b/docs/examples/patching.md deleted file mode 100644 index dc9de16827..0000000000 --- a/docs/examples/patching.md +++ /dev/null @@ -1,220 +0,0 @@ -## Patching Example: Patching libpng to work for x64-uwp - -### Initial error logs -First, try building: - -```no-highlight -PS D:\src\vcpkg> vcpkg install libpng:x64-uwp --editable -Computing installation plan... -The following packages will be built and installed: - libpng[core]:x64-uwp -Starting package 1/1: libpng:x64-uwp -Building package libpng[core]:x64-uwp... --- Using cached D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz --- Extracting source D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz --- Using source at D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-c993153cdf --- Configuring x64-uwp --- Building x64-uwp-rel -CMake Error at scripts/cmake/execute_required_process.cmake:14 (message): - Command failed: C:/Program Files/CMake/bin/cmake.exe;--build;.;--config;Release - - Working Directory: D:/src/vcpkg/buildtrees/libpng/x64-uwp-rel - - See logs for more information: - - D:\src\vcpkg\buildtrees\libpng\build-x64-uwp-rel-out.log - D:\src\vcpkg\buildtrees\libpng\build-x64-uwp-rel-err.log - -Call Stack (most recent call first): - scripts/cmake/vcpkg_build_cmake.cmake:3 (execute_required_process) - ports/libpng/portfile.cmake:22 (vcpkg_build_cmake) - scripts/ports.cmake:84 (include) - - -Error: build command failed -``` - -Next, looking at the above logs (build-xxx-out.log and build-xxx-err.log). - -```no-highlight -// build-x64-uwp-rel-out.log -... -"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) -> -"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj" (default target) (3) -> -(ClCompile target) -> - D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf\pngerror.c(775): warning C4013: 'ExitProcess' undefined; assuming extern returning int [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj] - - -"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) -> -"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj" (default target) (3) -> -(Link target) -> - pngerror.obj : error LNK2019: unresolved external symbol _ExitProcess referenced in function _png_longjmp [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj] - D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\Release\libpng16.dll : fatal error LNK1120: 1 unresolved externals [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj] - - 1 Warning(s) - 2 Error(s) - -Time Elapsed 00:00:04.19 -``` - -### Identify the problematic code - -Taking a look at [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682658(v=vs.85).aspx) shows that `ExitProcess` is only available for desktop apps. Additionally, it's useful to see the surrounding context: - -```c -/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngerror.c:769 */ - /* If control reaches this point, png_longjmp() must not return. The only - * choice is to terminate the whole process (or maybe the thread); to do - * this the ANSI-C abort() function is used unless a different method is - * implemented by overriding the default configuration setting for - * PNG_ABORT(). - */ - PNG_ABORT(); -``` - -A recursive search for `PNG_ABORT` reveals the definition: -```no-highlight -PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> findstr /snipl "PNG_ABORT" * -CHANGES:701: Added PNG_SETJMP_SUPPORTED, PNG_SETJMP_NOT_SUPPORTED, and PNG_ABORT() macros -libpng-manual.txt:432:errors will result in a call to PNG_ABORT() which defaults to abort(). -libpng-manual.txt:434:You can #define PNG_ABORT() to a function that does something -libpng-manual.txt:2753:errors will result in a call to PNG_ABORT() which defaults to abort(). -libpng-manual.txt:2755:You can #define PNG_ABORT() to a function that does something -libpng-manual.txt:4226:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()), -libpng.3:942:errors will result in a call to PNG_ABORT() which defaults to abort(). -libpng.3:944:You can #define PNG_ABORT() to a function that does something -libpng.3:3263:errors will result in a call to PNG_ABORT() which defaults to abort(). -libpng.3:3265:You can #define PNG_ABORT() to a function that does something -libpng.3:4736:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()), -png.h:994: * will use it; otherwise it will call PNG_ABORT(). This function was -pngerror.c:773: * PNG_ABORT(). -pngerror.c:775: PNG_ABORT(); -pngpriv.h:459:#ifndef PNG_ABORT -pngpriv.h:461:# define PNG_ABORT() ExitProcess(0) -pngpriv.h:463:# define PNG_ABORT() abort() -``` - -This already gives us some great clues, but the full definition tells the complete story. - -```c -/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngpriv.h:459 */ -#ifndef PNG_ABORT -# ifdef _WINDOWS_ -# define PNG_ABORT() ExitProcess(0) -# else -# define PNG_ABORT() abort() -# endif -#endif -``` - -`abort()` is a standard CRT call and certainly available in UWP, so we just need to convince libpng to be more platform agnostic. The easiest and most reliable way to achieve this is to patch the code; while in this particular case we could pass in a compiler flag to override `PNG_ABORT` because this is a private header, in general it is more reliable to avoid adding more required compiler switches when possible (especially when it isn't already exposed as a CMake option). - -### Patching the code to improve compatibility - -We recommend using git to create the patch file, since you'll already have it installed. -```no-highlight -PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git init . -Initialized empty Git repository in D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-c993153cdf/.git/ - -PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git add . -warning: LF will be replaced by CRLF in ANNOUNCE. -The file will have its original line endings in your working directory. -... - -PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git commit -m "temp" -[master (root-commit) 68f253f] temp - 422 files changed, 167717 insertions(+) -... -``` - -Now we can modify `pngpriv.h` to use `abort()` everywhere. -```c -/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngpriv.h:459 */ -#ifndef PNG_ABORT -# define PNG_ABORT() abort() -#endif -``` - -The output of `git diff` is already in patch format, so we just need to save the patch into the `ports/libpng` directory. -```no-highlight -PS buildtrees\libpng\src\v1.6.37-c993153cdf> git diff --ignore-space-at-eol | out-file -enc ascii ..\..\..\..\ports\libpng\use-abort-on-all-platforms.patch -``` - -Finally, we need to apply the patch after extracting the source. -```cmake -# ports\libpng\portfile.cmake -... -vcpkg_extract_source_archive_ex( - OUT_SOURCE_PATH SOURCE_PATH - ARCHIVE ${ARCHIVE} - PATCHES - "use-abort-on-all-platforms.patch" -) - -vcpkg_cmake_configure( -... -``` - -### Verification - -To be completely sure this works from scratch, we need to remove the package and rebuild it: - -```no-highlight -PS D:\src\vcpkg> vcpkg remove libpng:x64-uwp -Package libpng:x64-uwp was successfully removed -``` - -Now we try a fresh, from scratch install. - -```no-highlight -PS D:\src\vcpkg> vcpkg install libpng:x64-uwp -Computing installation plan... -The following packages will be built and installed: - libpng[core]:x64-uwp -Starting package 1/1: libpng:x64-uwp -Building package libpng[core]:x64-uwp... -Could not locate cached archive: C:\Users\me\AppData\Local\vcpkg/archives\f4\f44b54f818f78b9a4ccd34b3666f566f94286850.zip --- Using cached D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz --- Extracting source D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz --- Applying patch use_abort.patch --- Applying patch cmake.patch --- Applying patch pkgconfig.patch --- Applying patch pkgconfig.2.patch --- Using source at D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-10db9f58e4.clean --- Configuring x64-uwp --- Building x64-uwp-dbg --- Building x64-uwp-rel --- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/lib/pkgconfig/libpng.pc --- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/lib/pkgconfig/libpng16.pc --- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/debug/lib/pkgconfig/libpng.pc --- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/debug/lib/pkgconfig/libpng16.pc --- Installing: D:/src/vcpkg/packages/libpng_x64-uwp/share/libpng/copyright --- Performing post-build validation --- Performing post-build validation done -Stored binary cache: C:\Users\me\AppData\Local\vcpkg/archives\f4\f44b54f818f78b9a4ccd34b3666f566f94286850.zip -Building package libpng[core]:x64-uwp... done -Installing package libpng[core]:x64-uwp... -Installing package libpng[core]:x64-uwp... done -Elapsed time for package libpng:x64-uwp: 11.94 s - -Total elapsed time: 11.95 s - -The package libpng:x64-uwp provides CMake targets: - - find_package(libpng CONFIG REQUIRED) - target_link_libraries(main PRIVATE png) -``` - -Finally, to fully commit and publish the changes, we need to bump the port version in `vcpkg.json`, -and add the patch file to source control, then make a Pull Request! - -```json -{ - "name": "libpng", - "version": "1.6.37", - "port-version": 1, - "dependencies": [ - "zlib" - ] -} -``` diff --git a/docs/examples/vcpkg_android_example_cmake/.gitignore b/docs/examples/vcpkg_android_example_cmake/.gitignore deleted file mode 100644 index 378eac25d3..0000000000 --- a/docs/examples/vcpkg_android_example_cmake/.gitignore +++ /dev/null @@ -1 +0,0 @@ -build diff --git a/docs/examples/vcpkg_android_example_cmake/CMakeLists.txt b/docs/examples/vcpkg_android_example_cmake/CMakeLists.txt deleted file mode 100644 index 7572bbbc83..0000000000 --- a/docs/examples/vcpkg_android_example_cmake/CMakeLists.txt +++ /dev/null @@ -1,5 +0,0 @@ -cmake_minimum_required(VERSION 3.0) -project(test) -find_package(jsoncpp CONFIG REQUIRED) -add_library(my_lib my_lib.cpp) -target_link_libraries(my_lib jsoncpp_lib) diff --git a/docs/examples/vcpkg_android_example_cmake/compile.sh b/docs/examples/vcpkg_android_example_cmake/compile.sh deleted file mode 100755 index 1d1aa60a92..0000000000 --- a/docs/examples/vcpkg_android_example_cmake/compile.sh +++ /dev/null @@ -1,54 +0,0 @@ -# -# 1. Check the presence of required environment variables -# -if [ -z ${ANDROID_NDK_HOME+x} ]; then - echo "Please set ANDROID_NDK_HOME" - exit 1 -fi -if [ -z ${VCPKG_ROOT+x} ]; then - echo "Please set VCPKG_ROOT" - exit 1 -fi - -# -# 2. Set the path to the toolchains -# -vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake - - -# -# 3. Select a pair "Android abi" / "vcpkg triplet" -# Uncomment one of the four possibilities below -# - -android_abi=armeabi-v7a -vcpkg_target_triplet=arm-android - -# android_abi=x86 -# vcpkg_target_triplet=x86-android - -# android_abi=arm64-v8a -# vcpkg_target_triplet=arm64-android - -# android_abi=x86_64 -# vcpkg_target_triplet=x64-android - - -# -# 4. Install the library via vcpkg -# -$VCPKG_ROOT/vcpkg install jsoncpp:$vcpkg_target_triplet - -# -# 5. Test the build -# -rm -rf build -mkdir build -cd build -cmake .. \ - -DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \ - -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \ - -DVCPKG_TARGET_TRIPLET=$vcpkg_target_triplet \ - -DANDROID_ABI=$android_abi -make diff --git a/docs/examples/vcpkg_android_example_cmake/my_lib.cpp b/docs/examples/vcpkg_android_example_cmake/my_lib.cpp deleted file mode 100644 index f0165d72df..0000000000 --- a/docs/examples/vcpkg_android_example_cmake/my_lib.cpp +++ /dev/null @@ -1,8 +0,0 @@ -#include - -int answer() -{ - Json::Value meaning_of; - meaning_of["everything"] = 42; - return meaning_of["everything"].asInt(); -} diff --git a/docs/examples/vcpkg_android_example_cmake_script/.gitignore b/docs/examples/vcpkg_android_example_cmake_script/.gitignore deleted file mode 100644 index 378eac25d3..0000000000 --- a/docs/examples/vcpkg_android_example_cmake_script/.gitignore +++ /dev/null @@ -1 +0,0 @@ -build diff --git a/docs/examples/vcpkg_android_example_cmake_script/CMakeLists.txt b/docs/examples/vcpkg_android_example_cmake_script/CMakeLists.txt deleted file mode 100644 index eded6e5473..0000000000 --- a/docs/examples/vcpkg_android_example_cmake_script/CMakeLists.txt +++ /dev/null @@ -1,13 +0,0 @@ -cmake_minimum_required(VERSION 3.0) - -# if -DVCPKG_TARGET_ANDROID=ON is specified when invoking cmake, load cmake/vcpkg_android.cmake -# !!! Important: place this line before calling project() !!! -if (VCPKG_TARGET_ANDROID) - include("cmake/vcpkg_android.cmake") -endif() - -project(test) - -find_package(jsoncpp CONFIG REQUIRED) -add_library(my_lib my_lib.cpp) -target_link_libraries(my_lib JsonCpp::JsonCpp) diff --git a/docs/examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake b/docs/examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake deleted file mode 100644 index 3f09b1114e..0000000000 --- a/docs/examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake +++ /dev/null @@ -1,99 +0,0 @@ -# -# vcpkg_android.cmake -# -# Helper script when using vcpkg with cmake. It should be triggered via the variable VCPKG_TARGET_ANDROID -# -# For example: -# if (VCPKG_TARGET_ANDROID) -# include("cmake/vcpkg_android.cmake") -# endif() -# -# This script will: -# 1 & 2. check the presence of needed env variables: ANDROID_NDK_HOME and VCPKG_ROOT -# 3. set VCPKG_TARGET_TRIPLET according to ANDROID_ABI -# 4. Combine vcpkg and Android toolchains by setting CMAKE_TOOLCHAIN_FILE -# and VCPKG_CHAINLOAD_TOOLCHAIN_FILE - -# Note: VCPKG_TARGET_ANDROID is not an official Vcpkg variable. -# it is introduced for the need of this script - -if (VCPKG_TARGET_ANDROID) - - # - # 1. Check the presence of environment variable ANDROID_NDK_HOME - # - if (NOT DEFINED ENV{ANDROID_NDK_HOME}) - message(FATAL_ERROR " - Please set an environment variable ANDROID_NDK_HOME - For example: - export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle - Or: - export ANDROID_NDK_HOME=/home/your-account/Android/android-ndk-r21b - ") - endif() - - # - # 2. Check the presence of environment variable VCPKG_ROOT - # - if (NOT DEFINED ENV{VCPKG_ROOT}) - message(FATAL_ERROR " - Please set an environment variable VCPKG_ROOT - For example: - export VCPKG_ROOT=/path/to/vcpkg - ") - endif() - - - # - # 3. Set VCPKG_TARGET_TRIPLET according to ANDROID_ABI - # - # There are four different Android ABI, each of which maps to - # a vcpkg triplet. The following table outlines the mapping from vcpkg architectures to android architectures - # - # |VCPKG_TARGET_TRIPLET | ANDROID_ABI | - # |---------------------------|----------------------| - # |arm64-android | arm64-v8a | - # |arm-android | armeabi-v7a | - # |x64-android | x86_64 | - # |x86-android | x86 | - # - # The variable must be stored in the cache in order to successfully the two toolchains. - # - if (ANDROID_ABI MATCHES "arm64-v8a") - set(VCPKG_TARGET_TRIPLET "arm64-android" CACHE STRING "" FORCE) - elseif(ANDROID_ABI MATCHES "armeabi-v7a") - set(VCPKG_TARGET_TRIPLET "arm-android" CACHE STRING "" FORCE) - elseif(ANDROID_ABI MATCHES "x86_64") - set(VCPKG_TARGET_TRIPLET "x64-android" CACHE STRING "" FORCE) - elseif(ANDROID_ABI MATCHES "x86") - set(VCPKG_TARGET_TRIPLET "x86-android" CACHE STRING "" FORCE) - else() - message(FATAL_ERROR " - Please specify ANDROID_ABI - For example - cmake ... -DANDROID_ABI=armeabi-v7a - - Possible ABIs are: arm64-v8a, armeabi-v7a, x64-android, x86-android - ") - endif() - message("vcpkg_android.cmake: VCPKG_TARGET_TRIPLET was set to ${VCPKG_TARGET_TRIPLET}") - - - # - # 4. Combine vcpkg and Android toolchains - # - - # vcpkg and android both provide dedicated toolchains: - # - # vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake - # android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake - # - # When using vcpkg, the vcpkg toolchain shall be specified first. - # However, vcpkg provides a way to preload and additional toolchain, - # with the VCPKG_CHAINLOAD_TOOLCHAIN_FILE option. - set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE $ENV{ANDROID_NDK_HOME}/build/cmake/android.toolchain.cmake) - set(CMAKE_TOOLCHAIN_FILE $ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake) - message("vcpkg_android.cmake: CMAKE_TOOLCHAIN_FILE was set to ${CMAKE_TOOLCHAIN_FILE}") - message("vcpkg_android.cmake: VCPKG_CHAINLOAD_TOOLCHAIN_FILE was set to ${VCPKG_CHAINLOAD_TOOLCHAIN_FILE}") - -endif(VCPKG_TARGET_ANDROID) diff --git a/docs/examples/vcpkg_android_example_cmake_script/compile.sh b/docs/examples/vcpkg_android_example_cmake_script/compile.sh deleted file mode 100755 index abd981a6a2..0000000000 --- a/docs/examples/vcpkg_android_example_cmake_script/compile.sh +++ /dev/null @@ -1,37 +0,0 @@ -# 1. Install the library via vcpkg -# This install jsoncpp for the 4 android target ABIs and for the host computer. -# see the correspondence between ABIs and vcpkg triplets in the table below: -# -# |VCPKG_TARGET_TRIPLET | ANDROID_ABI | -# |---------------------------|----------------------| -# |arm64-android | arm64-v8a | -# |arm-android | armeabi-v7a | -# |x64-android | x86_64 | -# |x86-android | x86 | -$VCPKG_ROOT/vcpkg install \ - jsoncpp \ - jsoncpp:arm-android \ - jsoncpp:arm64-android \ - jsoncpp:x86-android \ - jsoncpp:x64-android - - -# 2. Test the build -# -# First, select an android ABI -# Uncomment one of the four possibilities below -# -android_abi=armeabi-v7a -# android_abi=x86 -# android_abi=arm64-v8a -# android_abi=x86_64 - -rm -rf build -mkdir build && cd build - -# DVCPKG_TARGET_ANDROID will load vcpkg_android.cmake, -# which will then load the android + vcpkg toolchains. -cmake .. \ - -DVCPKG_TARGET_ANDROID=ON \ - -DANDROID_ABI=$android_abi -make diff --git a/docs/examples/vcpkg_android_example_cmake_script/my_lib.cpp b/docs/examples/vcpkg_android_example_cmake_script/my_lib.cpp deleted file mode 100644 index f0165d72df..0000000000 --- a/docs/examples/vcpkg_android_example_cmake_script/my_lib.cpp +++ /dev/null @@ -1,8 +0,0 @@ -#include - -int answer() -{ - Json::Value meaning_of; - meaning_of["everything"] = 42; - return meaning_of["everything"].asInt(); -} diff --git a/docs/examples/versioning.getting-started.md b/docs/examples/versioning.getting-started.md deleted file mode 100644 index 4dd1e66fe9..0000000000 --- a/docs/examples/versioning.getting-started.md +++ /dev/null @@ -1,249 +0,0 @@ -# Getting started with versioning - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/examples/versioning.getting-started.md).** - -Vcpkg lets you take control of which version of packages to install in your projects using manifests. - -## Using versions with manifests - -Let's start with creating a simple CMake project that depends on `fmt` and `zlib`. - -Create a folder with the following files: - -**vcpkg.json** -```json -{ - "name": "versions-test", - "version": "1.0.0", - "dependencies": [ - { - "name": "fmt", - "version>=": "7.1.3#1" - }, - "zlib" - ], - "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc" -} -``` - -**main.cpp** -```c++ -#include -#include - -int main() -{ - fmt::print("fmt version is {}\n" - "zlib version is {}\n", - FMT_VERSION, ZLIB_VERSION); - return 0; -} -``` - -**CMakeLists.txt** -```CMake -cmake_minimum_required(VERSION 3.18) - -project(versionstest CXX) - -add_executable(main main.cpp) - -find_package(ZLIB REQUIRED) -find_package(fmt CONFIG REQUIRED) -target_link_libraries(main PRIVATE ZLIB::ZLIB fmt::fmt) -``` - -And now we build and run our project with CMake: - -1. Create the build directory for the project. -``` -PS D:\versions-test> mkdir build -PS D:\versions-test> cd build -``` - -2. Configure CMake. -``` -PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake .. --- Running vcpkg install -Detecting compiler hash for triplet x86-windows... -The following packages will be built and installed: - fmt[core]:x64-windows -> 7.1.3#1 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72 - vcpkg-cmake[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake\51896aa8073adb5c8450daa423d03eedf0dfc61f - vcpkg-cmake-config[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake-config\d255b3d566a8861dcc99a958240463e678528066 - zlib[core]:x64-windows -> 1.2.11#9 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4 -... -``` - -3. Build the project. -``` -PS D:\versions-test\build> cmake --build . -[2/2] Linking CXX executable main.exe -``` - -4. Run it! -``` -PS D:\versions-test\build> ./main.exe -fmt version is 70103 -zlib version is 1.2.11 -``` - -Take a look at the output: - -``` -fmt[core]:x86-windows -> 7.1.3#1 -- D:\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72 -... -zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4 -``` - -Instead of using the portfiles in `ports/`, vcpkg is checking out the files for each version in `buildtrees/versioning/versions/`. The files in `ports/` are still used when running vcpkg in classic mode. - -_NOTE: Output from vcpkg while configuring CMake is only available when using CMake version `3.18` or newer. If you're using an older CMake you can check the `vcpkg-manifest-install.log` file in your build directory instead._ - -Read our [manifests announcement blog post](https://devblogs.microsoft.com/cppblog/vcpkg-accelerate-your-team-development-environment-with-binary-caching-and-manifests/#using-manifests-with-msbuild-projects) to learn how to use manifests with MSBuild. - -### Manifest changes -If you have used manifests before you will notice that there are some new JSON properties. Let's review these changes: - -#### **`version`** -```json -{ - "name": "versions-test", - "version": "1.0.0" -} -``` - -This is your project's version declaration. Previously, you could only declare versions for your projects using the `version-string` property. Now that versioning has come around, vcpkg is aware of some new versioning schemes. - -Version scheme | Description ----------------- | --------------- -`version` | Dot-separated numerics: `1.0.0.5`. -`version-semver` | Compliant [semantic versions](https://semver.org): `1.2.0` and `1.2.0-rc`. -`version-date` | Dates in `YYYY-MM-DD` format: `2021-01-01` -`version-string` | Arbitrary strings: `vista`, `candy`. - -#### **`version>=`** -```json -{ - "dependencies": [ - { "name": "fmt", "version>=": "7.1.3" }, - "zlib" - ] -} -``` - -This property is used to express minimum version constraints, it is allowed only as part of the `"dependencies"` declarations. In our example we set an explicit constraint on version `7.1.3#1` of `fmt`. - -Vcpkg is allowed to upgrade this constraint if a transitive dependency requires a newer version. For example, if `zlib` were to declare a dependency on `fmt` version `7.1.4` then vcpkg would install `7.1.4` instead. - -Vcpkg uses a minimum version approach, in our example, even if `fmt` version `8.0.0` were to be released, vcpkg would still install version `7.1.3#1` as that is the minimum version that satisfies the constraint. The advantages of this approach are that you don't get unexpected dependency upgrades when you update vcpkg and you get reproducible builds (in terms of version used) as long as you use the same manifest. - -If you want to upgrade your dependencies, you can bump the minimum version constraint or use a newer baseline. - -#### **`builtin-baseline`** - -```json -{ "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc" } -``` - -This field declares the versioning baseline for all ports. Setting a baseline is required to enable versioning, otherwise you will get the current versions on the ports directory. You can run 'git rev-parse HEAD' to get the current commit of vcpkg and set it as the builtin-baseline. See the [`builtin-baseline` documentation](../users/manifests.md#builtin-baseline) for more information. - -In our example, you can notice that we do not declare a version constraint for `zlib`; instead, the version is taken from the baseline. Internally, vcpkg will look in commit `3426db05b996481ca31e95fff3734cf23e0f51bc` to find out what version of `zlib` was the latest at that point in time (in our case it was `1.2.11#9`). - -During version resolution, baseline versions are treated as minimum version constraints. If you declare an explicit constraint that is lower than a baseline version, the explicit constraint will be upgraded to the baseline version. - -For example, if we modified our dependencies like this: -```json -{ "dependencies": [ - { - "name": "fmt", - "version>=": "7.1.3#1" - }, - { - "name": "zlib", - "version>=": "1.2.11#7" - } -] } -``` - -_NOTE: The value `1.2.11#7` represents version `1.2.11`, port version `7`._ - -Since the baseline introduces a minimum version constraint for `zlib` at `1.2.11#9` and a higher version does satisfy the minimum version constraint for `1.2.11#7`, vcpkg is allowed to upgrade it. - -Baselines are also a convenient mechanism to upgrade multiple versions at a time, for example, if you wanted to depend on multiple `boost` libraries, it is more convenient to set the `baseline` once than declaring a version constraint on each package. - -But what if you want to pin a version older than the baseline? - -#### **`overrides`** - -Since baselines establish a version floor for all packages and explicit constraints get upgraded when they are lower than the baseline, we need another mechanism to downgrade versions past the baseline. - -The mechanism vcpkg provides for that scenario is `overrides`. When an override is declared on a package, vcpkg will ignore all other version constraints either directly declared in the manifest or from transitive dependencies. In short, `overrides` will force vcpkg to use the exact version declared, period. - -Let's modify our example once more, this time to force vcpkg to use version `6.0.0` of `fmt`. - -```json -{ - "name": "versions-test", - "version": "1.0.0", - "dependencies": [ - { - "name": "fmt", - "version>=": "7.1.3#1" - }, - { - "name": "zlib", - "version>=": "1.2.11#7" - } - ], - "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc", - "overrides": [ - { - "name": "fmt", - "version": "6.0.0" - } - ] -} -``` - -Rebuild our project: - -``` -PS D:\versions-test\build> rm ./CMakeCache.txt -PS D:\versions-test\build> rm -r ./vcpkg_installed -PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake .. --- Running vcpkg install -Detecting compiler hash for triplet x86-windows... -The following packages will be built and installed: - fmt[core]:x86-windows -> 6.0.0 -- D:\vcpkg\buildtrees\versioning\versions\fmt\d99b6a35e1406ba6b6e09d719bebd086f83ed5f3 - zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4 -... -PS D:\versions-test\build> cmake --build . -[2/2] Linking CXX executable main.exe -``` - -And run it! -``` -PS D:\versions-test\build> .\main.exe -fmt version is 60000 -zlib version is 1.2.11 -``` - -Notice how the `fmt` is now at version `6.0.0` just like we wanted. - -## Versions and custom ports - -The last thing to discuss is how overlay ports interact with versioning resolution. The answer is: they don't. - -Going into more detail, when you provide an overlay for a port, vcpkg will always use the overlay port without caring what version is contained in it. The reasons are two-fold: (1) it is consistent with the existing behavior of overlay ports of completely masking the existing port, and (2) overlay ports do not (and are not expected to) provide enough information to power vcpkg's versioning feature. - -If you want to have flexible port customization along with versioning, you should consider making your own custom registry. See our [registries specification for more details](../specifications/registries.md). - -## Further reading - -If you're interested in delving deeper into the details of how versioning works we recommended that you read the [original versioning specification](../specifications/versioning.md) and the [implementation details](../users/versioning.implementation-details.md). - -See also: - -* [Versioning docs](../users/versioning.md) -* [Original specification](../specifications/versioning.md) -* [Versioning implementation details](../users/versioning.implementation-details.md) diff --git a/docs/maintainers/authoring-script-ports.md b/docs/maintainers/authoring-script-ports.md deleted file mode 100644 index f14eaa4407..0000000000 --- a/docs/maintainers/authoring-script-ports.md +++ /dev/null @@ -1,45 +0,0 @@ -# Authoring Script Ports - -Ports can expose functions for other ports to consume during their build. For -example, the `vcpkg-cmake` helper port exposes the `vcpkg_cmake_configure()` -helper function. Packaging common scripts into a shared helper port makes -maintenance easier because all consumers can be updated from a single place. -Because the scripts come from a port, they can be versioned and depended upon -via all the same mechanisms as any other port. - -Script ports are implemented via the `vcpkg-port-config.cmake` extension -mechanism. Before invoking the `portfile.cmake` of a port, vcpkg will first -import `share//vcpkg-port-config.cmake` from each direct dependency. If -the direct dependency is a host dependency, the import will be performed in the -host installed tree (e.g. -`${HOST_INSTALLED_DIR}/share//vcpkg-port-config.cmake`). - -Only direct dependencies are considered for `vcpkg-port-config.cmake` inclusion. -This means that if a script port relies on another script port, it must -explicitly import the `vcpkg-port-config.cmake` of its dependency. - -Script-to-script dependencies should not be marked as host. The dependency from -a target port to a script should be marked host, which means that scripts should -always already be natively compiling. By making script-to-script dependencies -`"host": false`, it ensures that one script can depend upon the other being in -its same install directory. - -Ports should never provide a `vcpkg-port-config.cmake` file under a different -`share/` subdirectory than the current port (`${PORT}`). - -## Example - -```cmake -# ${CURRENT_PACKAGES_DIR}/share/my-helper/vcpkg-port-config.cmake - -# This include guard ensures the file will be loaded only once -include_guard(GLOBAL) - -# This is how you could pull in a transitive dependency -include("${CMAKE_CURRENT_LIST_DIR}/../my-other-helper/vcpkg-port-config.cmake") - -# Finally, it is convention to put each public function into a separate file with a matching name -include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_01.cmake") -include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_02.cmake") -include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_03.cmake") -``` diff --git a/docs/maintainers/cmake-guidelines.md b/docs/maintainers/cmake-guidelines.md deleted file mode 100644 index fb682f2760..0000000000 --- a/docs/maintainers/cmake-guidelines.md +++ /dev/null @@ -1,166 +0,0 @@ -# CMake Guidelines - -We expect that all CMake scripts that are either: - -- In the `scripts/` directory, or -- In a `vcpkg-*` port - -should follow the guidelines laid out in this document. -Existing scripts may not follow these guidelines yet; -it is expected that we will continue to update old scripts -to fall in line with these guidelines. - -These guidelines are intended to create stability in our scripts. -We hope that they will make both forwards and backwards compatibility easier. - -## The Guidelines - -- Except for out-parameters, we always use `cmake_parse_arguments()` - rather than function parameters or referring to `${ARG}`. - - This doesn't necessarily need to be followed for "script-local helper functions" - - In this case, positional parameters should be put in the function - declaration (rather than using `${ARG}`), - and should be named according to local rules (i.e. `snake_case`). - - Exception: positional parameters that are optional should be - given a name via `set(argument_name "${ARG}")`, after checking `ARGC`. - - Out-parameters should be the first parameter to a function. Example: - ```cmake - function(format out_var) - cmake_parse_arguments(PARSE_ARGV 1 "arg" ...) - # ... set(buffer "output") - set("${out_var}" "${buffer}" PARENT_SCOPE) - endfunction() - ``` -- There are no unparsed or unused arguments. - Always check for `ARGN` or `arg_UNPARSED_ARGUMENTS`. - `FATAL_ERROR` when possible, `WARNING` if necessary for backwards compatibility. -- All `cmake_parse_arguments` must use `PARSE_ARGV`. -- All `foreach` loops must use `IN LISTS`, `IN ITEMS`, or `RANGE`. -- The variables `${ARGV}` and `${ARGN}` are unreferenced, - except in helpful messages to the user. - - (i.e., `message(FATAL_ERROR "blah was passed extra arguments: ${ARGN}")`) -- We always use functions, not macros or top level code. - - Exception: "script-local helper macros". It is sometimes helpful to define a small macro. - This should be done sparingly, and functions should be preferred. - - Exception: `vcpkg.cmake`'s `find_package`. -- Scripts in the scripts tree should not be expected to need observable changes - as part of normal operation. - - Example violation: `vcpkg_acquire_msys()` has hard-coded packages and versions - that need updating over time due to the MSYS project dropping old packages. - - Example exception: `vcpkg_from_sourceforge()` has a list of mirrors which - needs maintenance, but does not have an observable behavior impact on the callers. -- Rules for quoting: there are three kinds of arguments in CMake - - unquoted (`foo(BAR)`), quoted (`foo("BAR")`), and bracketed (`foo([[BAR]])`). - Follow these rules to quote correctly: - - If an argument contains a variable expansion `${...}`, - it must be quoted. - - Exception: a "splat" variable expansion, when one variable will be - passed to a function as multiple arguments. In this case, the argument - should simply be `${foo}`: - ```cmake - vcpkg_list(SET working_directory) - if(DEFINED "arg_WORKING_DIRECTORY") - vcpkg_list(SET working_directory WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}") - endif() - # calls do_the_thing() if NOT DEFINED arg_WORKING_DIRECTORY, - # else calls do_the_thing(WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}") - do_the_thing(${working_directory}) - ``` - - Otherwise, if the argument contains any escape sequences that are not - `\\`, `\"`, or `\$`, that argument must be a quoted argument. - - For example: `"foo\nbar"` must be quoted. - - Otherwise, if the argument contains a `\`, a `"`, or a `$`, - that argument should be bracketed. - - Example: - ```cmake - set(x [[foo\bar]]) - set(y [=[foo([[bar\baz]])]=]) - ``` - - Otherwise, if the argument contains characters that are - not alphanumeric or `_`, that argument should be quoted. - - Otherwise, the argument should be unquoted. - - Exception: arguments to `if()` of type `` should always be quoted: - - Both arguments to the comparison operators - - `EQUAL`, `STREQUAL`, `VERSION_LESS`, etc. - - The first argument to `MATCHES` and `IN_LIST` - - Example: - ```cmake - if("${FOO}" STREQUAL "BAR") # ... - if("${BAZ}" EQUAL "0") # ... - if("FOO" IN_LIST list_variable) # ... - if("${bar}" MATCHES [[a[bcd]+\.[bcd]+]]) # ... - ``` - - For single expressions and for other types of predicates that do not - take ``, use the normal rules. -- There are no "pointer" or "in-out" parameters - (where a user passes a variable name rather than the contents), - except for simple out-parameters. -- Variables are not assumed to be empty. - If the variable is intended to be used locally, - it must be explicitly initialized to empty with `set(foo "")` if it is a string variable, - and `vcpkg_list(SET foo)` if it is a list variable. -- `set(var)` should not be used. Use `unset(var)` to unset a variable, - `set(var "")` to set it to the empty string, - and `vcpkg_list(SET var)` to set it to the empty list. - _Note: the empty string and the empty list are the same value;_ - _this is a notational difference rather than a difference in result_ -- All variables expected to be inherited from the parent scope across an API boundary - (i.e. not a file-local function) should be documented. - Note that all variables mentioned in triplets.md are considered documented. -- Out parameters are only set in `PARENT_SCOPE` and are never read. - See also the helper `z_vcpkg_forward_output_variable()` to forward out parameters through a function scope. -- `CACHE` variables are used only for global variables which are shared internally among strongly coupled - functions and for internal state within a single function to avoid duplicating work. - These should be used extremely sparingly and should use the `Z_VCPKG_` prefix to avoid - colliding with any local variables that would be defined by any other code. - - Examples: - - `vcpkg_cmake_configure`'s `Z_VCPKG_CMAKE_GENERATOR` - - `z_vcpkg_get_cmake_vars`'s `Z_VCPKG_GET_CMAKE_VARS_FILE` -- `include()`s are only allowed in `ports.cmake` or `vcpkg-port-config.cmake`. -- `foreach(RANGE)`'s arguments _must always be_ natural numbers, - and `` _must always be_ less than or equal to ``. - - This must be checked by something like: - ```cmake - if("${start}" LESS_EQUAL "${end}") - foreach(RANGE "${start}" "${end}") - ... - endforeach() - endif() - ``` -- All port-based scripts must use `include_guard(GLOBAL)` - to avoid being included multiple times. - -### CMake Versions to Require - -- All CMake scripts, except for `vcpkg.cmake`, - may assume the version of CMake that is present in the - `cmake_minimum_required` of `ports.cmake`. - - This `cmake_minimum_required` should be bumped every time a new version - of CMake is added to `vcpkgTools.xml`, as should the - `cmake_minimum_required` in all of the helper `CMakeLists.txt` files. -- `vcpkg.cmake` must assume a version of CMake back to 3.7.2 in general - - Specific functions and options may assume a greater CMake version; - if they do, make sure to comment that function or option - with the required CMake version. - - -### Changing Existing Functions - -- Never remove arguments in non-internal functions; - if they should no longer do anything, just take them as normal and warn on use. -- Never add a new mandatory argument. - -### Naming Variables - -- `cmake_parse_arguments`: set prefix to `"arg"` -- Local variables are named with `snake_case` -- Internal global variable names are prefixed with `Z_VCPKG_`. -- External experimental global variable names are prefixed with `X_VCPKG_`. - -- Internal functions are prefixed with `z_vcpkg_` - - Functions which are internal to a single function (i.e., helper functions) - are named `[z_]_`, where `` is the name of the function they are - a helper to, and `` is what the helper function does. - - `z_` should be added to the front if `` doesn't have a `z_`, - but don't name a helper function `z_z_foo_bar`. -- Public global variables are named `VCPKG_`. diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md deleted file mode 100644 index 7064ad40e7..0000000000 --- a/docs/maintainers/control-files.md +++ /dev/null @@ -1,205 +0,0 @@ -# CONTROL files - -**CONTROL files are retained for backwards compatibility with earlier versions of vcpkg; -all new features are added only to [vcpkg.json manifest files](manifest-files.md), and we recommend using vcpkg.json for any newly authored port. -Use `./vcpkg format-manifest ports//CONTROL` to convert an existing CONTROL file to a vcpkg.json file.** - -The `CONTROL` file contains metadata about the port. The syntax is based on [the Debian `control` format][debian] although we only support the subset of fields documented here. - -Field names are case-sensitive and start the line without leading whitespace. Paragraphs are separated by one or more empty lines. - -[debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html - -## Source Paragraph - -The first paragraph in a `CONTROL` file is the Source paragraph. It must have a `Source`, `Version`, and `Description` field. The full set of fields is documented below. - -### Examples: -```no-highlight -Source: ace -Version: 6.5.5 -Description: The ADAPTIVE Communication Environment -``` - -```no-highlight -Source: vtk -Version: 8.2.0 -Port-Version: 2 -Description: Software system for 3D computer graphics, image processing, and visualization -Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype, expat, hdf5, libjpeg-turbo, proj4, lz4, libtheora, atlmfc (windows), eigen3, double-conversion, pugixml, libharu, sqlite3, netcdf-c -``` - - -### Recognized fields - -#### Source -The name of the port. - -When adding new ports be aware that the name may conflict with other projects that are not a part of vcpkg. For example `json` conflicts with too many other projects so you should add a scope to the name such as `taocpp-json` to make it unique. Verify there are no conflicts on a search engine as well as on other package collections. - -Package collections to check for conflicts: - -+ [Repology](https://repology.org/projects/) -+ [Debian packages](https://www.debian.org/distrib/packages) -+ [Packages search](https://pkgs.org/) - -#### Version -The library version. - -This field is an alphanumeric string that may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bit strings and are only evaluated for equality. - -For tagged-release ports, we follow the following convention: - -1. If the port follows a scheme like `va.b.c`, we remove the leading `v`. In this case, it becomes `a.b.c`. -2. If the port includes its own name in the version like `curl-7_65_1`, we remove the leading name: `7_65_1` - -For rolling-release ports, we use the date that the _commit was accessed by you_, formatted as `YYYY-MM-DD`. Stated another way: if someone had a time machine and went to that date, they would see this commit as the latest master. - -For example, given: -1. The latest commit was made on 2019-04-19 -2. The current version string is `2019-02-14-1` -3. Today's date is 2019-06-01. - -Then if you update the source version today, you should give it version `2019-06-01`. - -#### Port-Version -The version of the port. - -This field is a non-negative integer. It allows one to version the port file separately from the version of the underlying library; if you make a change to a port, without changing the underlying version of the library, you should increment this field by one (starting at `0`, which is equivalent to no `Port-Version` field). When the version of the underlying library is upgraded, this field should be set back to `0` (i.e., delete the `Port-Version` field). - -##### Examples: -```no-highlight -Version: 1.0.5 -Port-Version: 2 -``` -```no-highlight -Version: 2019-03-21 -``` - -#### Description -A description of the library. - -By convention the first line of the description is a summary of the library. An optional detailed description follows. The detailed description can be multiple lines, all starting with whitespace. - -##### Examples: -```no-highlight -Description: C++ header-only JSON library -``` -```no-highlight -Description: Mosquitto is an open source message broker that implements the MQ Telemetry Transport protocol versions 3.1 and 3.1.1. - MQTT provides a lightweight method of carrying out messaging using a publish/subscribe model. This makes it suitable for "machine - to machine" messaging such as with low power sensors or mobile devices such as phones, embedded computers or microcontrollers like the Arduino. -``` - -#### Homepage -The URL of the homepage for the library where a user is able to find additional documentation or the original source code. - -Example: -```no-highlight -Homepage: https://github.com/Microsoft/vcpkg -``` - -#### Build-Depends -Comma separated list of vcpkg ports the library has a dependency on. - -Vcpkg does not distinguish between build-only dependencies and runtime dependencies. The complete list of dependencies needed to successfully use the library should be specified. - -*For example: websocketpp is a header only library, and thus does not require any dependencies at install time. However, downstream users need boost and openssl to make use of the library. Therefore, websocketpp lists boost and openssl as dependencies* - -If the port is dependent on optional features of another library those can be specified using the `portname[featurelist]` syntax. If the port does not require any features from the dependency, this should be specified as `portname[core]`. - -Dependencies can be filtered based on the target triplet to support differing requirements. These filters use the same syntax as the Supports field below and are surrounded in parentheses following the portname and feature list. - -##### Example: -```no-highlight -Build-Depends: rapidjson, curl[core,openssl] (!windows), curl[core,winssl] (windows) -``` - -#### Default-Features -Comma separated list of optional port features to install by default. - -This field is optional. - -##### Example: -```no-highlight -Default-Features: dynamodb, s3, kinesis -``` - - -#### Supports -Expression that evaluates to true when the port is expected to build successfully for a triplet. - -Currently, this field is only used in the CI testing to skip ports. In the future, this mechanism is intended to warn users in advance that a given install tree is not expected to succeed. Therefore, this field should be used optimistically; in cases where a port is expected to succeed 10% of the time, it should still be marked "supported". - -The grammar for the supports expression uses standard operators: -- `!expr` - negation -- `expr|expr` - or (`||` is also supported) -- `expr&expr` - and (`&&` is also supported) -- `(expr)` - grouping/precedence - -The predefined expressions are computed from standard triplet settings: -- `native` - `TARGET_TRIPLET` == `HOST_TRIPLET` -- `x64` - `VCPKG_TARGET_ARCHITECTURE` == `"x64"` -- `x86` - `VCPKG_TARGET_ARCHITECTURE` == `"x86"` -- `arm` - `VCPKG_TARGET_ARCHITECTURE` == `"arm"` or `VCPKG_TARGET_ARCHITECTURE` == `"arm64"` -- `arm64` - `VCPKG_TARGET_ARCHITECTURE` == `"arm64"` -- `windows` - `VCPKG_CMAKE_SYSTEM_NAME` == `""` or `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"` -- `uwp` - `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"` -- `linux` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Linux"` -- `osx` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Darwin"` -- `android` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Android"` -- `static` - `VCPKG_LIBRARY_LINKAGE` == `"static"` -- `wasm32` - `VCPKG_TARGET_ARCHITECTURE` == `"wasm32"` -- `emscripten` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Emscripten"` - -These predefined expressions can be overridden in the triplet file via the [`VCPKG_DEP_INFO_OVERRIDE_VARS`](../users/triplets.md) option. - -This field is optional and defaults to true. - -> Implementers' Note: these terms are computed from the triplet via the `vcpkg_get_dep_info` mechanism. - -##### Example: -```no-highlight -Supports: !(uwp|arm) -``` - -## Feature Paragraphs - -Multiple optional features can be specified in the `CONTROL` files. It must have a `Feature` and `Description` field. It can optionally have a `Build-Depends` field. It must be separated from other paragraphs by one or more empty lines. - -### Example: -```no-highlight -Source: vtk -Version: 8.2.0-2 -Description: Software system for 3D computer graphics, image processing, and visualization -Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype, expat, hdf5, libjpeg-turbo, proj4, lz4, libtheora, atlmfc (windows), eigen3, double-conversion, pugixml, libharu, sqlite3, netcdf-c - -Feature: openvr -Description: OpenVR functionality for VTK -Build-Depends: sdl2, openvr - -Feature: qt -Description: Qt functionality for VTK -Build-Depends: qt5 - -Feature: mpi -Description: MPI functionality for VTK -Build-Depends: mpi, hdf5[parallel] - -Feature: python -Description: Python functionality for VTK -Build-Depends: python3 -``` - -### Recognized fields - -#### Feature -The name of the feature. - -#### Description -A description of the feature using the same syntax as the port `Description` field. - -#### Build-Depends -The list of dependencies required to build and use this feature. - -On installation the dependencies from all selected features are combined to produce the full dependency list for the build. This field follows the same syntax as `Build-Depends` in the Source Paragraph. diff --git a/docs/maintainers/execute_process.md b/docs/maintainers/execute_process.md deleted file mode 100644 index 688ec84646..0000000000 --- a/docs/maintainers/execute_process.md +++ /dev/null @@ -1,11 +0,0 @@ -# execute_process - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/execute_process.md). - -Intercepts all calls to execute_process() inside portfiles and fails when Download Mode -is enabled. - -In order to execute a process in Download Mode call `vcpkg_execute_in_download_mode()` instead. - -## Source -[scripts/cmake/execute\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake) diff --git a/docs/maintainers/internal/vcpkg_catalog_release_process.md b/docs/maintainers/internal/vcpkg_catalog_release_process.md deleted file mode 100644 index 5acd12b375..0000000000 --- a/docs/maintainers/internal/vcpkg_catalog_release_process.md +++ /dev/null @@ -1,14 +0,0 @@ -# vcpkg_catalog_release_process - -This document describes the acceptance criteria / process we use when doing a vcpkg release. - -1. Generate a new GitHub Personal Access Token with repo permissions. -2. Using the PAT, invoke $/scripts/Get-Changelog.ps1 `-StartDate (previous release date) -EndDate (Get-Date) -OutFile path/to/results.md` -3. Create a new GitHub release in this repo. -4. Submit a vcpkg.ci (full tree rebuild) run with the same SHA as that release. -5. Use the "auto-generate release notes". Copy the "new contributors" and "full changelog" parts to the end of `path/to/results.md`. -6. Change `## New Contributors` to `#### New Contributors` -7. In `path/to/results.md`, update `LINK TO BUILD` with the most recent link to vcpkg.ci run. -8. In `path/to/results.md`, fill out the tables for number of existing ports and successful ports. -9. Replace the contents of the release notes with the contents of `path/to/results.md` -10. After the full rebuild submission completes, update the link to the one for the exact SHA, the counts, and remove "(tentative)". diff --git a/docs/maintainers/internal/vcpkg_tool_release_process.md b/docs/maintainers/internal/vcpkg_tool_release_process.md deleted file mode 100644 index d7456a3dcb..0000000000 --- a/docs/maintainers/internal/vcpkg_tool_release_process.md +++ /dev/null @@ -1,48 +0,0 @@ -# vcpkg_tool_release_process - -This document describes the acceptance criteria / process we use when doing a vcpkg-tool update, -such as https://github.com/microsoft/vcpkg/pull/23757 - -1. Verify that all tests etc. are passing in the vcpkg-tool repo's `main` branch, and that the - contents therein are acceptable for release. (Steps after this will sign code there, so this - review is responsible gating what has access to code signing.) -2. Check that the changes there are in fact the changes that we want in that release. (Be aware, - you are responsible for what is about to be signed with a Microsoft code signing certificate by - proceeding) -3. Submit a new full tree rebuild by microsoft.vcpkg.ci ( - https://dev.azure.com/vcpkg/public/_build?definitionId=29 as of this writing) and queue a new - build with the vcpkg-tool SHA overridden to the one you wish to use. Example: - https://dev.azure.com/vcpkg/public/_build/results?buildId=73664&view=results -4. (Probably the next day) Check over the failures and ensure any differences with the most recent - full rebuild using the previous tool version are understood. -5. Submit a signed build from "vcpkg Signed Binaries (from GitHub)" ( - https://devdiv.visualstudio.com/DevDiv/_build?definitionId=17772&_a=summary as of this writing) -6. The signed build will automatically create a draft GitHub release at - https://github.com/microsoft/vcpkg-tool/releases . Erase the contents filled in there and press - the "auto generate release notes" button. Manually remove any entries created by the automated - localization tools which will start with `* LEGO: Pull request from juno/`. -7. Publish that draft release as "pre-release". -8. Clean up a machine for the following tests: - * Delete `VCPKG_DOWNLOADS/artifacts` (which forces artifacts to be reacquired) - * Delete `LOCALAPPDATA/vcpkg` (which forces registries to be reacquired) -9. Smoke test the 'one liner' installer: (Where 2022-06-15 is replaced with the right release name) - * Powershell: - `iex (iwr https://github.com/microsoft/vcpkg-tool/releases/download/2022-06-15/vcpkg-init.ps1)` - * Batch: - `curl -L -o vcpkg-init.cmd https://github.com/microsoft/vcpkg-tool/releases/download/2022-06-15/vcpkg-init.ps1 && .\vcpkg-init.cmd` - * Bash: - `. <(curl https://github.com/microsoft/vcpkg-tool/releases/download/2022-06-15/vcpkg-init -L)` -10. Test that embedded scenarios work for vcpkg-artifacts: - Ensure that none of the following report errors: - 1. git clone https://github.com/some-example/blink/ - 2. cd blink - 3. vcpkg activate - 4. idf.py set-target ESP32 - 5. cd build - 6. ninja -11. In the vcpkg repo, draft a PR which updates `bootstrap-vcpkg.sh` and `boostrap-vcpkg.ps1` - with the new release date, and update SHAs as appropriate in the .sh script. (For example, see - https://github.com/microsoft/vcpkg/pull/23757) -12. Merge the tool update PR. -13. Change the github release in vcpkg-tool from "prerelease" to "release". (This automatically - updates the aka.ms links) diff --git a/docs/maintainers/internal/z_vcpkg_apply_patches.md b/docs/maintainers/internal/z_vcpkg_apply_patches.md deleted file mode 100644 index 64351ed526..0000000000 --- a/docs/maintainers/internal/z_vcpkg_apply_patches.md +++ /dev/null @@ -1,32 +0,0 @@ -# z_vcpkg_apply_patches - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/). - -**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.** - -Apply a set of patches to a source tree. - -```cmake -z_vcpkg_apply_patches( - SOURCE_PATH - [QUIET] - PATCHES ... -) -``` - -The `` should be set to `${SOURCE_PATH}` by convention, -and is the path to apply the patches in. - -`z_vcpkg_apply_patches` will take the list of ``es, -which are by default relative to the port directory, -and apply them in order using `git apply`. -Generally, these ``es take the form of `some.patch` -to select patches in the port directory. -One may also download patches and use `${VCPKG_DOWNLOADS}/path/to/some.patch`. - -If `QUIET` is not passed, it is a fatal error for a patch to fail to apply; -otherwise, if `QUIET` is passed, no message is printed. -This should only be used for edge cases, such as patches that are known to fail even on a clean source tree. - -## Source -[scripts/cmake/z\_vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_apply_patches.cmake) diff --git a/docs/maintainers/internal/z_vcpkg_forward_output_variable.md b/docs/maintainers/internal/z_vcpkg_forward_output_variable.md deleted file mode 100644 index 10c5855df6..0000000000 --- a/docs/maintainers/internal/z_vcpkg_forward_output_variable.md +++ /dev/null @@ -1,38 +0,0 @@ -# z_vcpkg_forward_output_variable - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/). - -This macro helps with forwarding values from inner function calls, -through a local function scope, into pointer out parameters. - -```cmake -z_vcpkg_forward_output_variable(ptr_to_parent_var var_to_forward) -``` - -is equivalent to - -```cmake -if(DEFINED ptr_to_parent_var) - if(DEFINED value_var) - set("${ptr_to_parent_var}" "${value_var}" PARENT_SCOPE) - else() - unset("${ptr_to_parent_var}" PARENT_SCOPE) - endif() -endif() -``` - -Take note that the first argument should be a local variable that has a value of the parent variable name. -Most commonly, this local is the result of a pointer-out parameter to a function. -If the variable in the first parameter is not defined, this function does nothing, -simplifying functions with optional out parameters. -Most commonly, this should be used in cases like: - -```cmake -function(my_function out_var) - file(SHA512 "somefile.txt" local_var) - z_vcpkg_forward_output_variable(out_var local_var) -endfunction() -``` - -## Source -[scripts/cmake/z\_vcpkg\_forward\_output\_variable.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_forward_output_variable.cmake) diff --git a/docs/maintainers/internal/z_vcpkg_function_arguments.md b/docs/maintainers/internal/z_vcpkg_function_arguments.md deleted file mode 100644 index ac6fb1b609..0000000000 --- a/docs/maintainers/internal/z_vcpkg_function_arguments.md +++ /dev/null @@ -1,29 +0,0 @@ -# z_vcpkg_function_arguments - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/). - -**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.** -Get a list of the arguments which were passed in. -Unlike `ARGV`, which is simply the arguments joined with `;`, -so that `(A B)` is not distinguishable from `("A;B")`, -this macro gives `"A;B"` for the first argument list, -and `"A\;B"` for the second. - -```cmake -z_vcpkg_function_arguments( []) -``` - -`z_vcpkg_function_arguments` gets the arguments between `ARGV` and the last argument. -`` defaults to `0`, so that all arguments are taken. - -## Example: -```cmake -function(foo_replacement) - z_vcpkg_function_arguments(ARGS) - foo(${ARGS}) - ... -endfunction() -``` - -## Source -[scripts/cmake/z\_vcpkg\_function\_arguments.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_function_arguments.cmake) diff --git a/docs/maintainers/internal/z_vcpkg_get_cmake_vars.md b/docs/maintainers/internal/z_vcpkg_get_cmake_vars.md deleted file mode 100644 index 2dcf2a8e7e..0000000000 --- a/docs/maintainers/internal/z_vcpkg_get_cmake_vars.md +++ /dev/null @@ -1,36 +0,0 @@ -# z_vcpkg_get_cmake_vars - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/). - -**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.** -Runs a cmake configure with a dummy project to extract certain cmake variables - -## Usage -```cmake -z_vcpkg_get_cmake_vars() -``` - -`z_vcpkg_get_cmake_vars(cmake_vars_file)` sets `` to -a path to a generated CMake file, with the detected `CMAKE_*` variables -re-exported as `VCPKG_DETECTED_*`. - -## Notes -Avoid usage in portfiles. - -All calls to `z_vcpkg_get_cmake_vars` will result in the same output file; -the output file is not generated multiple times. - -## Examples - -* [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake) - -### Basic Usage - -```cmake -z_vcpkg_get_cmake_vars(cmake_vars_file) -include("${cmake_vars_file}") -message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CXX_FLAGS}") -``` - -## Source -[scripts/cmake/z\_vcpkg\_get\_cmake\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_get_cmake_vars.cmake) diff --git a/docs/maintainers/internal/z_vcpkg_prettify_command_line.md b/docs/maintainers/internal/z_vcpkg_prettify_command_line.md deleted file mode 100644 index f17114bce8..0000000000 --- a/docs/maintainers/internal/z_vcpkg_prettify_command_line.md +++ /dev/null @@ -1,21 +0,0 @@ -# z_vcpkg_prettify_command_line - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/). - -**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.** -Turn a command line into a formatted string. - -```cmake -z_vcpkg_prettify_command_line( ...) -``` - -This command is for internal use, when printing out to a message. - -## Examples - -* `scripts/cmake/vcpkg_execute_build_process.cmake` -* `scripts/cmake/vcpkg_execute_required_process.cmake` -* `scripts/cmake/vcpkg_execute_required_process_repeat.cmake` - -## Source -[scripts/cmake/z\_vcpkg\_prettify\_command\_line.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_prettify_command_line.cmake) diff --git a/docs/maintainers/internal/z_vcpkg_setup_pkgconfig_path.md b/docs/maintainers/internal/z_vcpkg_setup_pkgconfig_path.md deleted file mode 100644 index 80c6654b76..0000000000 --- a/docs/maintainers/internal/z_vcpkg_setup_pkgconfig_path.md +++ /dev/null @@ -1,16 +0,0 @@ -# z_vcpkg_setup_pkgconfig_path - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/). - -`z_vcpkg_setup_pkgconfig_path` sets up environment variables to use `pkgconfig`, such as `PKG_CONFIG` and `PKG_CONFIG_PATH`. -The original values are restored with `z_vcpkg_restore_pkgconfig_path`. `BASE_DIRS` indicates the base directories to find `.pc` files; typically `${CURRENT_INSTALLED_DIR}`, or `${CURRENT_INSTALLED_DIR}/debug`. - -```cmake -z_vcpkg_setup_pkgconfig_path(BASE_DIRS <"${CURRENT_INSTALLED_DIR}" ...>) -# Build process that may transitively invoke pkgconfig -z_vcpkg_restore_pkgconfig_path() -``` - - -## Source -[scripts/cmake/z\_vcpkg\_setup\_pkgconfig\_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_setup_pkgconfig_path.cmake) diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md deleted file mode 100644 index 47703b246a..0000000000 --- a/docs/maintainers/maintainer-guide.md +++ /dev/null @@ -1,435 +0,0 @@ -# Maintainer Guidelines and Policies - -This document lists a set of policies that you should apply when adding or updating a port recipe. -It is intended to serve the role of -[Debian's Policy Manual](https://www.debian.org/doc/debian-policy/), -[Homebrew's Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines), and -[Homebrew's Formula Cookbook](https://docs.brew.sh/Formula-Cookbook). - -## PR Structure - -### Make separate Pull Requests per port - -Whenever possible, separate changes into multiple PRs. -This makes them significantly easier to review and prevents issues with one set of changes from holding up every other change. - -### Avoid trivial changes in untouched files - -For example, avoid reformatting or renaming variables in portfiles that otherwise have no reason to be modified for the issue at hand. -However, if you need to modify the file for the primary purpose of the PR (updating the library), -then obviously beneficial changes like fixing typos are appreciated! - -### Check names against other repositories - -A good service to check many at once is [Repology](https://repology.org/). -If the library you are adding could be confused with another one, -consider renaming to make it clear. We prefer when names are longer and/or -unlikely to conflict with any future use of the same name. If the port refers -to a library on GitHub, a good practice is to prefix the name with the organization -if there is any chance of confusion. - -### Use GitHub Draft PRs - -GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge. -Most new PRs should be opened as drafts and converted to normal PRs once the CI passes. - -More information about GitHub Draft PRs: -https://github.blog/2019-02-14-introducing-draft-pull-requests/ - -## Portfiles - -### Avoid deprecated helper functions - -At this time, the following helpers are deprecated: - -- [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md) should be replaced by the supported overload of [`vcpkg_extract_source_archive()`] (with `ARCHIVE`) -- The deprecated overload of [`vcpkg_extract_source_archive()`] without `ARCHIVE` should be replaced by the supported overload with `ARCHIVE`. -- `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md)) -- `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md) -- `vcpkg_copy_tool_dependencies()` should be replaced by [`vcpkg_copy_tools()`](vcpkg_copy_tools.md) -- `vcpkg_configure_cmake` should be replaced by [`vcpkg_cmake_configure()`](vcpkg_cmake_configure.md) after removing `PREFER_NINJA` (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md)) -- `vcpkg_build_cmake` should be replaced by [`vcpkg_cmake_build()`](vcpkg_cmake_build.md) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md)) -- `vcpkg_install_cmake` should be replaced by [`vcpkg_cmake_install()`](vcpkg_cmake_install.md) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md)) -- `vcpkg_fixup_cmake_targets` should be replaced by [`vcpkg_cmake_config_fixup`](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md#vcpkg_cmake_config_fixup) (from port [`vcpkg-cmake-config`](ports/vcpkg-cmake-config.md#vcpkg-cmake-config)) - -Some of the replacement helper functions are in "tools ports" to allow consumers to pin their -behavior at specific versions, to allow locking the behavior of the helpers at a particular -version. Tools ports need to be added to your port's `"dependencies"`, like so: - -```json -{ - "name": "vcpkg-cmake", - "host": true -}, -{ - "name": "vcpkg-cmake-config", - "host": true -} -``` - -[`vcpkg_extract_source_archive()`]: vcpkg_extract_source_archive.md - -### Avoid excessive comments in portfiles - -Ideally, portfiles should be short, simple, and as declarative as possible. -Remove any boiler plate comments introduced by the `create` command before submitting a PR. - -### Ports must not be path dependent - -Ports must not change their behavior based on which ports are already installed in a form that would change which contents that port installs. For example, given: - -``` -> vcpkg install a -> vcpkg install b -> vcpkg remove a -``` - -and - -``` -> vcpkg install b -``` - -the files installed by `b` must be the same, regardless of influence by the previous installation of `a`. This means that ports must not try to detect whether something is provided in the installed tree by another port before taking some action. A specific and common cause of such "path dependent" behavior is described below in "When defining features, explicitly control dependencies." - -### Unique port attribution rule - -In the entire vcpkg system, no two ports a user is expected to use concurrently may provide the same file. If a port tries to install a file already provided by another file, installation will fail. If a port wants to use an extremely common name for a header, for example, it should place those headers in a subdirectory rather than in `include`. - -### Add CMake exports in an unofficial- namespace - -A core design ideal of vcpkg is to not create "lock-in" for customers. In the build system, there should be no difference between depending on a library from the system, and depending on a library from vcpkg. To that end, we avoid adding CMake exports or targets to existing libraries with "the obvious name", to allow upstreams to add their own official CMake exports without conflicting with vcpkg. - -To that end, any CMake configs that the port exports, which are not in the upstream library, should have `unofficial-` as a prefix. Any additional targets should be in the `unofficial::::` namespace. - -This means that the user should see: - * `find_package(unofficial- CONFIG)` as the way to get at the unique-to-vcpkg package - * `unofficial::::` as an exported target from that port. - -Examples: - * [`brotli`](https://github.com/microsoft/vcpkg/blob/4f0a640e4c5b74166b759a862d7527c930eff32e/ports/brotli/install.patch) creates the `unofficial-brotli` package, producing target `unofficial::brotli::brotli`. - -### Install copyright file - -Each port has to provide a file named `copyright` in the folder `${CURRENT_PACKAGES_DIR}/share/${PORT}`. - -Many ports are using this code to install a copyright file: - -```cmake -file(INSTALL "${SOURCE_PATH}LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright) -``` - -This is discouraged in favour of [`vcpkg_install_copyright()`](vcpkg_install_copyright.md). New ports should use `vcpkg_install_copyright()` instead. However, it is still valid for existing ports to use something like the code above. You may replace this with `vcpkg_install_copyright` but you don't have to. - -`vcpkg_install_copyright` also includes the functionallity to handle multiple copyright files. See its [documentation](vcpkg_install_copyright.md) for more info. - -## Features - -### Do not use features to implement alternatives - -Features must be treated as additive functionality. If port[featureA] installs and port[featureB] installs, then port[featureA,featureB] must install. Moreover, if a second port depends on [featureA] and a third port depends on [featureB], installing both the second and third ports should have their dependencies satisfied. - -Libraries in this situation must choose one of the available options as expressed in vcpkg, and users who want a different setting must use overlay ports at this time. - -Existing examples we would not accept today retained for backwards compatibility: - * `libgit2`, `libzip`, `open62541` all have features for selecting a TLS or crypto backend. Note that `curl` has different crypto backend options but allows selecting between them at runtime, meaning the above tenet is maintained. - * `darknet` has `opencv2`, `opencv3`, features to control which version of opencv to use for its dependencies. - -### A feature may engage preview or beta functionality - -Notwithstanding the above, if there is a preview branch or similar where the preview functionality has a high probability of not disrupting the non-preview functionality (for example, no API removals), a feature is acceptable to model this setting. - -Examples: - * The Azure SDKs (of the form `azure-Xxx`) have a `public-preview` feature. - * `imgui` has an `experimental-docking` feature which engages their preview docking branch which uses a merge commit attached to each of their public numbered releases. - -### Default features should enable behaviors, not APIs - -If a consumer is depending directly upon a library, they can list out any desired features easily (`library[feature1,feature2]`). However, if a consumer _does not know_ they are using a library, they cannot list out those features. If that hidden library is like `libarchive` where features are adding additional compression algorithms (and thus behaviors) to an existing generic interface, default features offer a way to ensure a reasonably functional transitive library is built even if the final consumer doesn't name it directly. - -If the feature adds additional APIs (or executables, or library binaries) and doesn't modify the behavior of existing APIs, it should be left off by default. This is because any consumer which might want to use those APIs can easily require it via their direct reference. - -If in doubt, do not mark a feature as default. - -### Do not use features to control alternatives in published interfaces - -If a consumer of a port depends on only the core functionality of that port, with high probability they must not be broken by turning on the feature. This is even more important when the alternative is not directly controlled by the consumer, but by compiler settings like `/std:c++17` / `-std=c++17`. - -Existing examples we would not accept today retained for backwards compatibility: - * `redis-plus-plus[cxx17]` controls a polyfill but does not bake the setting into the installed tree. - * `ace[wchar]` changes all APIs to accept `const wchar_t*` rather than `const char*`. - -### A feature may replace polyfills with aliases provided that replacement is baked into the installed tree - -Notwithstanding the above, ports may remove polyfills with a feature, as long as: - 1. Turning on the feature changes the polyfills to aliases of the polyfilled entity - 2. The state of the polyfill is baked into the installed headers, such that ABI mismatch "impossible" runtime errors are unlikely - 3. It is possible for a consumer of the port to write code which works in both modes, for example by using a typedef which is either polyfilled or not - -Example: - * `abseil[cxx17]` changes `absl::string_view` to a replacement or `std::string_view`; the patch -https://github.com/microsoft/vcpkg/blob/981e65ce0ac1f6c86e5a5ded7824db8780173c76/ports/abseil/fix-cxx-standard.patch implements the baking requirement - -### Recommended solutions - -If it's critical to expose the underlying alternatives, we recommend providing messages at build time to instruct the user on how to copy the port into a private overlay: -```cmake -set(USING_DOG 0) -message(STATUS "This version of LibContosoFrobnicate uses the Kittens backend. To use the Dog backend instead, create an overlay port of this with USING_DOG set to 1 and the `kittens` dependency replaced with `dog`.") -message(STATUS "This recipe is at ${CMAKE_CURRENT_LIST_DIR}") -message(STATUS "See the overlay ports documentation at https://github.com/microsoft/vcpkg/blob/master/docs/specifications/ports-overlay.md") -``` - -## Build Techniques - -### Do not use vendored dependencies - -Do not use embedded copies of libraries. -All dependencies should be split out and packaged separately so they can be updated and maintained. - -### Prefer using CMake - -When multiple buildsystems are available, prefer using CMake. -Additionally, when appropriate, it can be easier and more maintainable to rewrite alternative buildsystems into CMake using `file(GLOB)` directives. - -Examples: [abseil](../../ports/abseil/portfile.cmake) - -### Choose either static or shared binaries - -By default, `vcpkg_cmake_configure()` will pass in the appropriate setting for `BUILD_SHARED_LIBS`, -however for libraries that don't respect that variable, you can switch on `VCPKG_LIBRARY_LINKAGE`: - -```cmake -string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC) -string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED) - -vcpkg_cmake_configure( - SOURCE_PATH ${SOURCE_PATH} - OPTIONS - -DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC} - -DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED} -) -``` - -### When defining features, explicitly control dependencies - -When defining a feature that captures an optional dependency, -ensure that the dependency will not be used accidentally when the feature is not explicitly enabled. - -```cmake -set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON) -set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB OFF) -if ("zlib" IN_LIST FEATURES) - set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF) - set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB ON) -endif() - -vcpkg_cmake_configure( - SOURCE_PATH ${SOURCE_PATH} - OPTIONS - -DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB} - -DCMAKE_REQUIRE_FIND_PACKAGE_ZLIB=${CMAKE_REQUIRE_FIND_PACKAGE_ZLIB} -) -``` - -The snippet below using `vcpkg_check_features()` is equivalent, [see the documentation](vcpkg_check_features.md). - -```cmake -vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS - FEATURES - "zlib" CMAKE_REQUIRE_FIND_PACKAGE_ZLIB - INVERTED_FEATURES - "zlib" CMAKE_DISABLE_FIND_PACKAGE_ZLIB -) - -vcpkg_cmake_configure( - SOURCE_PATH ${SOURCE_PATH} - OPTIONS - ${FEATURE_OPTIONS} -) -``` - -Note that `ZLIB` in the above is case-sensitive. See the [CMAKE_DISABLE_FIND_PACKAGE_PackageName](https://cmake.org/cmake/help/v3.22/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html) and [CMAKE_REQUIRE_FIND_PACKAGE_PackageName](https://cmake.org/cmake/help/v3.22/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.html) documnetation for more details. - -### Place conflicting libs in a `manual-link` directory - -A lib is considered conflicting if it does any of the following: -+ Define `main` -+ Define malloc -+ Define symbols that are also declared in other libraries - -Conflicting libs are typically by design and not considered a defect. Because some build systems link against everything in the lib directory, these should be moved into a subdirectory named `manual-link`. - -## Manifests and CONTROL files - -When adding a new port, use the new manifest syntax for defining a port; -you may also change over to manifests when modifying an existing port. -You may do so easily by running the `vcpkg format-manifest` command, which will convert existing CONTROL -files into manifest files. Do not convert CONTROL files that have not been modified. - -## Versioning - -### Follow common conventions for the `"version"` field - -See our [versioning documentation](../users/versioning.md#version-schemes) for a full explanation of our conventions. - -### Update the `"port-version"` field in the manifest file of any modified ports - -Vcpkg uses this field to determine whether a given port is out-of-date and should be changed whenever the port's behavior changes. - -Our convention is to use the `"port-version"` field for changes to the port that don't change the upstream version, and to reset the `"port-version"` back to zero when an update to the upstream version is made. - -For Example: - -- Zlib's package version is currently `1.2.1`, with no explicit `"port-version"` (equivalent to a `"port-version"` of `0`). -- You've discovered that the wrong copyright file has been deployed, and fixed that in the portfile. -- You should update the `"port-version"` field in the manifest file to `1`. - -See our [manifest files document](manifest-files.md#port-version) for a full explanation of our conventions. - -### Update the version files in `versions/` of any modified ports - -Vcpkg uses a set of metadata files to power its versioning feature. -These files are located in the following locations: -* `${VCPKG_ROOT}/versions/baseline.json`, (this file is common to all ports) and -* `${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json` (one per port). - -For example, for `zlib` the relevant files are: -* `${VCPKG_ROOT}/versions/baseline.json` -* `${VCPKG_ROOT}/versions/z-/zlib.json` - -We expect that each time you update a port, you also update its version files. - -**The recommended method to update these files is to run the `x-add-version` command, e.g.:** - -``` -vcpkg x-add-version zlib -``` - -If you're updating multiple ports at the same time, instead you can run: - -``` -vcpkg x-add-version --all -``` - -To update the files for all modified ports at once. - -_NOTE: These commands require you to have committed your changes to the ports before running them. The reason is that the Git SHA of the port directory is required in these version files. But don't worry, the `x-add-version` command will warn you if you have local changes that haven't been committed._ - -See our [versioning specification](../specifications/versioning.md) and [registries specification](../specifications/registries-2.md) to learn how vcpkg interacts with these files. - -## Patching - -### Prefer options over patching - -It is preferable to set options in a call to `vcpkg_configure_xyz()` over patching the settings directly. - -Common options that allow avoiding patching: -1. [MSBUILD] `` settings inside the project file can be overridden via `/p:` parameters -2. [CMAKE] Calls to `find_package(XYz)` in CMake scripts can be disabled via [`-DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON`](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html) -3. [CMAKE] Cache variables (declared as `set(VAR "value" CACHE STRING "Documentation")` or `option(VAR "Documentation" "Default Value")`) can be overridden by just passing them in on the command line as `-DVAR:STRING=Foo`. One notable exception is if the `FORCE` parameter is passed to `set()`. See also the [CMake `set` documentation](https://cmake.org/cmake/help/v3.15/command/set.html) - -### Prefer patching over overriding `VCPKG_` values - -Some variables prefixed with `VCPKG_` have an equivalent `CMAKE_`. -However, not all of them are passed to the internal package build [(see implementation: Windows toolchain)](../../scripts/toolchains/windows.cmake). - -Consider the following example: - -```cmake -set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}") -set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}") -``` - -Using `vcpkg`'s built-in toolchains this works, because the value of `VCPKG__FLAGS` is forwarded to the appropriate `CMAKE_LANG_FLAGS` variable. But, a custom toolchain that is not aware of `vcpkg`'s variables will not forward them. - -Because of this, it is preferable to patch the buildsystem directly when setting `CMAKE__FLAGS`. - -### Minimize patches - -When making changes to a library, strive to minimize the final diff. This means you should _not_ reformat the upstream source code when making changes that affect a region. Also, when disabling a conditional, it is better to add a `AND FALSE` or `&& 0` to the condition than to delete every line of the conditional. - -Don't add patches if the port is outdated and updating the port to a newer released version would solve the same issue. vcpkg prefers updating ports over patching outdated versions unless the version bump breaks a considerable amount of dependent ports. - -This helps to keep the size of the vcpkg repository down as well as improves the likelihood that the patch will apply to future code versions. - -### Do not implement features in patches - -The purpose of patching in vcpkg is to enable compatibility with compilers, libraries, and platforms. It is not to implement new features in lieu of following proper Open Source procedure (submitting an Issue/PR/etc). - -## Do not build tests/docs/examples by default - -When submitting a new port, check for any options like `BUILD_TESTS` or `WITH_TESTS` or `POCO_ENABLE_SAMPLES` and ensure the additional binaries are disabled. This minimizes build times and dependencies for the average user. - -Optionally, you can add a `test` feature which enables building the tests, however this should not be in the `Default-Features` list. - -## Enable existing users of the library to switch to vcpkg - -### Do not add `CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS` - -Unless the author of the library is already using it, we should not use this CMake functionality because it interacts poorly with C++ templates and breaks certain compiler features. Libraries that don't provide a .def file and do not use __declspec() declarations simply do not support shared builds for Windows and should be marked as such with `vcpkg_check_linkage(ONLY_STATIC_LIBRARY)`. - -### Do not rename binaries outside the names given by upstream - -This means that if the upstream library has different names in release and debug (libx versus libxd), then the debug library should not be renamed to `libx`. Vice versa, if the upstream library has the same name in release and debug, we should not introduce a new name. - -Important caveat: -- Static and shared variants often should be renamed to a common scheme. This enables consumers to use a common name and be ignorant of the downstream linkage. This is safe because we only make one at a time available. - -Note that if a library generates CMake integration files (`foo-config.cmake`), renaming must be done through patching the CMake build itself instead of simply calling `file(RENAME)` on the output archives/LIBs. - -Finally, DLL files on Windows should never be renamed post-build because it breaks the generated LIBs. - -## Code format - -### Vcpkg internal code - -We require the C++ code inside vcpkg to follow the clang-format, if you change them. Please perform the following steps after modification: - -- Use Visual Studio: -1. Configure your [clang-format tools](https://devblogs.microsoft.com/cppblog/clangformat-support-in-visual-studio-2017-15-7-preview-1/). -2. Open the modified file. -3. Use shortcut keys Ctrl+K, Ctrl+D to format the current file. - -- Use tools: -1. Install [llvm clang-format](https://releases.llvm.org/download.html#10.0.0) -2. Run command: -```cmd -> LLVM_PATH/bin/clang-format.exe -style=file -i changed_file.cpp -``` - -### Manifests - -We require that the manifest file be formatted. Use the following command to format all manifest files: - -```cmd -> vcpkg format-manifest --all -``` - -## Useful implementation notes - -### Portfiles are run in Script Mode - -While `portfile.cmake`'s and `CMakeLists.txt`'s share a common syntax and core CMake language constructs (aka "Scripting Commands"), portfiles run in "Script Mode", whereas `CMakeLists.txt` files run in "Project Mode". The most important difference between these two modes is that "Script Mode" does not have the concepts of "Toolchain", "Language" and "Target". Any behaviors, including scripting commands, which depend on these constructs (e.g. `CMAKE_CXX_COMPILER`, `CMAKE_EXECUTABLE_SUFFIX`, `CMAKE_SYSTEM_NAME`) will not be correct. - -Portfiles have direct access to variables set in the triplet file, but `CMakeLists.txt`s do not (though there is often a translation that happens -- `VCPKG_LIBRARY_LINKAGE` versus `BUILD_SHARED_LIBS`). - -Portfiles and Project builds invoked by portfiles are run in different processes. Conceptually: - -```no-highlight -+----------------------------+ +------------------------------------+ -| CMake.exe | | CMake.exe | -+----------------------------+ +------------------------------------+ -| Triplet file | ====> | Toolchain file | -| (x64-windows.cmake) | | (scripts/buildsystems/vcpkg.cmake) | -+----------------------------+ +------------------------------------+ -| Portfile | ====> | CMakeLists.txt | -| (ports/foo/portfile.cmake) | | (buildtrees/../CMakeLists.txt) | -+----------------------------+ +------------------------------------+ -``` - -To determine the host in a portfile, the standard CMake variables are fine (`CMAKE_HOST_WIN32`). - -To determine the target in a portfile, the vcpkg triplet variables should be used (`VCPKG_CMAKE_SYSTEM_NAME`). - -See also our [triplet documentation](../users/triplets.md) for a full enumeration of possible settings. diff --git a/docs/maintainers/manifest-files.md b/docs/maintainers/manifest-files.md deleted file mode 100644 index d2ad992a5b..0000000000 --- a/docs/maintainers/manifest-files.md +++ /dev/null @@ -1,551 +0,0 @@ -# Manifest files - `vcpkg.json` - -The `vcpkg.json` file contains metadata about the port. -It's a JSON file, and replaces the existing CONTROL file metadata structure. -It must have a top level object, and all fields are case sensitive. - -## Examples: - -The most important fields in a manifest, the ones which are required for all ports, -are the `"name"` field, and a version field (for now, just `"version-string"`). -There's more information about these fields below. - -```json -{ - "name": "ace", - "version-string": "6.5.5" -} -``` - -```json -{ - "name": "vtk", - "version-string": "8.2.0", - "port-version": 2, - "description": "Software system for 3D computer graphics, image processing, and visualization", - "dependencies": [ - { - "name": "atlmfc", - "platform": "windows" - }, - "double-conversion", - "eigen3", - "expat", - "freetype", - "glew", - "hdf5", - "jsoncpp", - "libharu", - "libjpeg-turbo", - "libpng", - "libtheora", - "libxml2", - "lz4", - "netcdf-c", - "proj4", - "pugixml", - "sqlite3", - "tiff", - "zlib" - ] -} -``` - -## Fields - -### `"name"` -The name of the port. - -When adding new ports be aware that the name may conflict with other projects that are not a part of vcpkg. For example `json` conflicts with too many other projects so you should add a scope to the name such as `taocpp-json` to make it unique. Verify there are no conflicts on a search engine as well as on other package collections. - -Package collections to check for conflicts: - -+ [Repology](https://repology.org/projects/) -+ [Debian packages](https://www.debian.org/distrib/packages) -+ [Packages search](https://pkgs.org/) - -A name must be an identifier: i.e., it must only consist of lowercase ascii alphabetic characters, -numbers, and hyphens, and it must not begin nor end with a hyphen. - -### Version fields - -Currently there are different fields for special versioning. Namely: - -Manifest property | Versioning scheme -------------------|------------------------------------ -`version` | For dot-separated numeric versions -`version-semver` | For SemVer compliant versions -`version-date` | For dates in the format YYYY-MM-DD -`version-string` | For arbitrary strings - -See https://github.com/microsoft/vcpkg/blob/master/docs/specifications/versioning.md#22-package-versions for more details. - -Additionally, `"port-version"` is used to differentiate between port changes that don't change the underlying library version. - -#### `"version-string"` - -This field is an ascii string, and may contain alphanumeric characters, `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as byte strings and are only evaluated for equality. - -For tagged-release ports, we follow the following convention: - -1. If the library follows a scheme like `va.b.c`, we remove the leading `v`. In this case, it becomes `a.b.c`. -2. If the library includes its own name in the version like `curl-7_65_1`, we remove the leading name: `7_65_1` -3. If the library is versioned by dates, format the resulting version string just like the upstream library; - for example, Abseil formats their dates `lts_2020_02_25`, so the `"version-string"` should be `"lts_2020_02_25"`. - -For rolling-release ports, we use the date that the _commit was accessed by you_, formatted as `YYYY-MM-DD`. Stated another way: if someone had a time machine and went to that date, they would see this commit as the latest master. - -For example, given: -1. The latest commit was made on 2019-04-19 -2. The current version string is `2019-02-14` -3. Today's date is 2019-06-01. - -Then if you update the source version today, you should give it version `2019-06-01`. - -#### `"port-version"` - -The version of the port, aside from the library version. - -This field is a non-negative integer. -It allows one to version the port file separately from the version of the underlying library; -if you make a change to a port, without changing the underlying version of the library, -you should increment this field by one (starting at `0`, which is equivalent to no `"port-version"` field). -When the version of the underlying library is upgraded, -this field should be set back to `0` (i.e., delete the `"port-version"` field). - -#### Examples: -```json -{ - "version": "1.0.5", - "port-version": 2 -} -``` - -```json -{ - "version": "2019-03-21" -} -``` - -### `"description"` - -A description of the library. - -This field can either be a single string, which should be a summary of the library, -or can be an array, with the first line being a summary and the remaining lines being the detailed description - -one string per line. - -#### Examples: -```json -{ - "description": "C++ header-only JSON library" -} -``` -```json -{ - "description": [ - "Mosquitto is an open source message broker that implements the MQ Telemetry Transport protocol versions 3.1 and 3.1.1.", - "MQTT provides a lightweight method of carrying out messaging using a publish/subscribe model." - "This makes it suitable for 'machine to machine' messaging such as with low power sensors or mobile devices such as phones, embedded computers or microcontrollers like the Arduino." - ] -} -``` - -### `"homepage"` - -The URL of the homepage for the library where a user is able to find additional documentation or the original source code. - -#### Example: -```json -{ - "homepage": "https://github.com/microsoft/vcpkg" -} -``` - -### `"documentation"` - -The URL where a user would be able to find official documentation for the library. Optional. - -### `"maintainers"` - -A list of strings that define the set of maintainers of a package. -It's recommended that these take the form of `Givenname Surname `, -but this field is not checked for consistency. - -Optional. - -### `"dependencies"` - -An array of ports the library has a dependency on. - -vcpkg does not distinguish between build-only dependencies and runtime dependencies. -The complete list of dependencies needed to successfully use the library should be specified. - -For example: websocketpp is a header only library, and thus does not require any dependencies at install time. -However, downstream users need boost and openssl to make use of the library. -Therefore, websocketpp lists boost and openssl as dependencies. - -Each dependency may be either an identifier, or an object. -For many dependencies, just listing the name of the library should be fine; -however, if one needs to add extra information to that dependency, one may use the dependency object. -For a dependency object, the `"name"` field is used to designate the library; -for example the dependency object `{ "name": "zlib" }` is equivalent to just writing `"zlib"`. - -If the port is dependent on optional features of another library, -those can be specified using the `"features"` field of the dependency object. -If the port does not require any features from the dependency, -this should be specified with the `"default-features"` fields set to `false`. - -Dependencies can also be filtered based on the target triplet to support differing requirements. -These filters use the same syntax as the `"supports"` field below, -and are specified in the `"platform"` field. - -#### Example: -```json -{ - "dependencies": [ - { - "name": "curl", - "default-features": false, - "features": [ - "winssl" - ], - "platform": "windows" - }, - { - "name": "curl", - "default-features": false, - "features": [ - "openssl" - ], - "platform": "!windows" - }, - "rapidjson" - ] -} -``` - -### `"features"` - -Multiple optional features can be specified in manifest files, in the `"features"` object field. -This field is a map from the feature name, to the feature's information. -Each one must have a `"description"` field, and may also optionally have a `"dependencies"` field. - -A feature's name must be an identifier - -in other words, lowercase alphabetic characters, digits, and hyphens, -neither starting nor ending with a hyphen. - -A feature's `"description"` is a description of the feature, -and is the same kind of thing as the port `"description"` field. - -A feature's `"dependencies"` field contains the list of extra dependencies required to build and use this feature; -this field isn't required if the feature doesn't require any extra dependencies. -On installation the dependencies from all selected features are combined to produce the full dependency list for the build. - -#### Example: - -```json -{ - "name": "vtk", - "version-string": "8.2.0", - "port-version": 2, - "description": "Software system for 3D computer graphics, image processing, and visualization", - "dependencies": [ - { - "name": "atlmfc", - "platform": "windows" - }, - "double-conversion", - "eigen3", - "expat", - "freetype", - "glew", - "hdf5", - "jsoncpp", - "libharu", - "libjpeg-turbo", - "libpng", - "libtheora", - "libxml2", - "lz4", - "netcdf-c", - "proj4", - "pugixml", - "sqlite3", - "tiff", - "zlib" - ], - "features": { - "mpi": { - "description": "MPI functionality for VTK", - "dependencies": [ - { - "name": "hdf5", - "features": [ - "parallel" - ] - }, - "mpi" - ] - }, - "openvr": { - "description": "OpenVR functionality for VTK", - "dependencies": [ - "openvr", - "sdl2" - ] - }, - "python": { - "description": "Python functionality for VTK", - "dependencies": [ - "python3" - ] - }, - "qt": { - "description": "Qt functionality for VTK", - "dependencies": [ - "qt5" - ] - } - } -} -``` - -### `"default-features"` - -An array of feature names that the library uses by default, if nothing else is specified. - -#### Example: -```json -{ - "default-features": [ - "kinesis" - ], - "features": { - "dynamodb": { - "description": "Build dynamodb support", - "dependencies": [ - "dynamodb" - ] - }, - "kinesis": { - "description": "build kinesis support" - } - } -} -``` - -### `"supports"` - -A string, formatted as a platform expression, -that evaluates to true when the port should build successfully for a triplet. - -This field is used in the CI testing to skip ports, -and warns users in advance that a given install tree is not expected to succeed. -Therefore, this field should be used optimistically; -in cases where a port is expected to succeed 10% of the time, it should still be marked "supported". - -The grammar for this top-level platform expression, in [EBNF], is as follows: - -```ebnf -whitespace-character = -| ? U+0009 "CHARACTER TABULATION" ? -| ? U+000A "LINE FEED" ? -| ? U+000D "CARRIAGE RETURN" ? -| ? U+0020 "SPACE" ? ; -optional-whitespace = { whitespace-character } ; -required-whitespace = whitespace-character, { optional-whitespace } ; - -lowercase-alpha = -| "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" -| "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" ; -digit = -| "0" | "1" | "2" | "3" | "4" -| "5" | "6" | "7" | "8" | "9" ; -identifier-character = -| lowercase-alpha -| digit ; - -platform-expression-list = -| platform-expression { ",", optional-whitespace, platform-expression } ; - -platform-expression = -| platform-expression-not -| platform-expression-and -| platform-expression-or ; - -platform-expression-identifier = -| identifier-character, { identifier-character }, optional-whitespace ; - -platform-expression-grouped = -| "(", optional-whitespace, platform-expression, ")", optional-whitespace ; - -platform-expression-simple = -| platform-expression-identifier -| platform-expression-grouped ; - -platform-expression-unary-keyword-operand = -| required-whitespace, platform-expression-simple -| optional-whitespace, platform-expression-grouped ; - -platform-expression-not = -| platform-expression-simple -| "!", optional-whitespace, platform-expression-simple -| "not", platform-expression-unary-keyword-operand ; - -platform-expression-binary-keyword-first-operand = -| platform-expression-not, required-whitespace -| platform-expression-grouped ; - -platform-expression-binary-keyword-second-operand = -| required-whitespace, platform-expression-not -| platform-expression-grouped ; - -platform-expression-and = -| platform-expression-not, { "&", optional-whitespace, platform-expression-not } -| platform-expression-binary-keyword-first-operand, { "and", platform-expression-binary-keyword-second-operand } ; - -platform-expression-or = -| platform-expression-not, { "|", optional-whitespace, platform-expression-not } -| platform-expression-binary-keyword-first-operand, { "or", platform-expression-binary-keyword-second-operand } (* to allow for future extension *) ; - -top-level-platform-expression = optional-whitespace, platform-expression-list ; -``` - -Basically, there are four kinds of expressions -- identifiers, negations, ands, and ors. -Negations may only negate an identifier or a grouped expression. -Ands and ors are a list of `&` or `|` separated identifiers, negated expressions, and grouped expressions. -One may not mix `&` and `|` without parentheses for grouping. - -These predefined identifier expressions are computed from standard triplet settings: -- `native` - `TARGET_TRIPLET` == `HOST_TRIPLET`; - useful for ports which depend on their own built binaries in their build. -- `x64` - `VCPKG_TARGET_ARCHITECTURE` == `"x64"` -- `x86` - `VCPKG_TARGET_ARCHITECTURE` == `"x86"` -- `arm` - `VCPKG_TARGET_ARCHITECTURE` == `"arm"` or `VCPKG_TARGET_ARCHITECTURE` == `"arm64"` -- `arm64` - `VCPKG_TARGET_ARCHITECTURE` == `"arm64"` -- `windows` - `VCPKG_CMAKE_SYSTEM_NAME` == `""` or `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"` -- `mingw` - `VCPKG_CMAKE_SYSTEM_NAME` == `"MinGW"` -- `uwp` - `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"` -- `linux` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Linux"` -- `osx` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Darwin"` -- `android` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Android"` -- `static` - `VCPKG_LIBRARY_LINKAGE` == `"static"` -- `wasm32` - `VCPKG_TARGET_ARCHITECTURE` == `"wasm32"` -- `emscripten` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Emscripten"` -- `staticcrt` - `VCPKG_CRT_LINKAGE` == `"static"` - -These predefined identifier expressions can be overridden in the triplet file, -via the [`VCPKG_DEP_INFO_OVERRIDE_VARS`](../users/triplets.md) option, -and new identifier expressions can be added via the same mechanism. - -This field is optional and defaults to true. - -> Implementers' Note: these terms are computed from the triplet via the `vcpkg_get_dep_info` mechanism. - -[EBNF]: https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form - -#### Example: -```json -{ - "supports": "!uwp & !(arm & !arm64)" -} -``` - -This means "doesn't support uwp, nor arm32 (but does support arm64)". - -### `"license"` - -The license of the port. This is an [SPDX license expression], -or `null` for proprietary licenses and other licenses for which -one should "just read the `copyright` file" (e.g., Qt). - -[SPDX license expression]: https://spdx.dev/ids/#how - -Additionally, you can find the list of [recognized license IDs] -and [recognized license exception IDs] in Annex A of the SPDX specification. - -[recognized license IDs]: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-list/#a1-licenses-with-short-identifiers -[recognized license exception IDs]: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-list/#a2-exceptions-list - -The following is an EBNF conversion of the ABNF located at -, -and this is what we actually parse in vcpkg. -Note that vcpkg does not support DocumentRefs. - -```ebnf -idchar = ? regex /[-.a-zA-Z0-9]/ ? -idstring = ( idchar ), { idchar } ; - -(* note that unrecognized license and license exception IDs will be warned against *) -license-id = idstring ; -license-exception-id = idstring ; -(* note that DocumentRefs are unsupported by this implementation *) -license-ref = "LicenseRef-", idstring ; - -with = [ whitespace ], "WITH", [ whitespace ] ; -and = [ whitespace ], "AND", [ whitespace ] ; -or = [ whitespace ], "OR", [ whitespace ] ; - -simple-expression = [ whitespace ], ( - | license-id - | license-id, "+" - | license-ref - ), [ whitespace ] ; - -(* the following are split up from compound-expression to make precedence obvious *) -parenthesized-expression = - | simple-expression - | [ whitespace ], "(", or-expression, ")", [ whitespace ] ; - -with-expression = - | parenthesized-expression - | simple-expression, with, license-exception-id, [ whitespace ] ; - -(* note: "a AND b OR c" gets parsed as "(a AND b) OR c" *) -and-expression = with-expression, { and, with-expression } ; -or-expression = and-expression, { or, and-exression } ; - -license-expression = or-expression ; -``` - -#### Examples - -For libraries with simple licensing, -only one license identifier may be needed; - -vcpkg, for example, would use this since it uses the MIT license: - -```json -{ - "license": "MIT" -} -``` - -Many GPL'd projects allow either the GPL 2 or any later versions: - -```json -{ - "license": "GPL-2.0-or-later" -} -``` - -Many Rust projects, in order to make certain they're useable with GPL, -but also desiring the MIT license, will allow licensing under either -the MIT license or Apache 2.0: - -```json -{ - "license": "Apache-2.0 OR MIT" -} -``` - -Some major projects include exceptions; -the Microsoft C++ standard library, and the LLVM project, -are licensed under Apache 2.0 with the LLVM exception: - -```json -{ - "license": "Apache-2.0 WITH LLVM-exception" -} -``` diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md deleted file mode 100644 index 60beddb790..0000000000 --- a/docs/maintainers/portfile-functions.md +++ /dev/null @@ -1,99 +0,0 @@ -# Portfile helper functions -- [execute\_process](execute_process.md) -- [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md) -- [vcpkg\_add\_to\_path](vcpkg_add_to_path.md) -- [vcpkg\_apply\_patches](vcpkg_apply_patches.md) (deprecated) -- [vcpkg\_backup\_restore\_env\_vars](vcpkg_backup_restore_env_vars.md) -- [vcpkg\_build\_cmake](vcpkg_build_cmake.md) (deprecated, use [vcpkg\_cmake\_build](vcpkg_cmake_build.md)) -- [vcpkg\_build\_make](vcpkg_build_make.md) -- [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md) -- [vcpkg\_build\_ninja](vcpkg_build_ninja.md) -- [vcpkg\_build\_nmake](vcpkg_build_nmake.md) -- [vcpkg\_build\_qmake](vcpkg_build_qmake.md) -- [vcpkg\_buildpath\_length\_warning](vcpkg_buildpath_length_warning.md) -- [vcpkg\_check\_features](vcpkg_check_features.md) -- [vcpkg\_check\_linkage](vcpkg_check_linkage.md) -- [vcpkg\_clean\_executables\_in\_bin](vcpkg_clean_executables_in_bin.md) -- [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md) -- [vcpkg\_common\_definitions](vcpkg_common_definitions.md) -- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md) (deprecated, use [vcpkg\_cmake\_configure](vcpkg_cmake_configure.md)) -- [vcpkg\_configure\_gn](vcpkg_configure_gn.md) (deprecated, use [vcpkg\_gn\_configure](ports/vcpkg-gn/vcpkg_gn_configure.md)) -- [vcpkg\_configure\_make](vcpkg_configure_make.md) -- [vcpkg\_configure\_meson](vcpkg_configure_meson.md) -- [vcpkg\_configure\_qmake](vcpkg_configure_qmake.md) -- [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md) -- [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md) -- [vcpkg\_copy\_tools](vcpkg_copy_tools.md) -- [vcpkg\_download\_distfile](vcpkg_download_distfile.md) -- [vcpkg\_execute\_build\_process](vcpkg_execute_build_process.md) -- [vcpkg\_execute\_in\_download\_mode](vcpkg_execute_in_download_mode.md) -- [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md) -- [vcpkg\_execute\_required\_process\_repeat](vcpkg_execute_required_process_repeat.md) -- [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md) -- [vcpkg\_extract\_source\_archive\_ex](vcpkg_extract_source_archive_ex.md) -- [vcpkg\_fail\_port\_install](vcpkg_fail_port_install.md) (deprecated) -- [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md) -- [vcpkg\_find\_fortran](vcpkg_find_fortran.md) -- [vcpkg\_fixup\_cmake\_targets](vcpkg_fixup_cmake_targets.md) (deprecated, use [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md)) -- [vcpkg\_fixup\_pkgconfig](vcpkg_fixup_pkgconfig.md) -- [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md) -- [vcpkg\_from\_git](vcpkg_from_git.md) -- [vcpkg\_from\_github](vcpkg_from_github.md) -- [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md) -- [vcpkg\_from\_sourceforge](vcpkg_from_sourceforge.md) -- [vcpkg\_get\_program\_files\_platform\_bitness](vcpkg_get_program_files_platform_bitness.md) -- [vcpkg\_get\_windows\_sdk](vcpkg_get_windows_sdk.md) -- [vcpkg\_host\_path\_list](vcpkg_host_path_list.md) -- [vcpkg\_install\_cmake](vcpkg_install_cmake.md) (deprecated, use [vcpkg\_cmake\_install](vcpkg_cmake_install.md)) -- [vcpkg\_install\_gn](vcpkg_install_gn.md) (deprecated, use [vcpkg\_gn\_install](ports/vcpkg-gn/vcpkg_gn_install.md)) -- [vcpkg\_install\_copyright](vcpkg_install_copyright.md) -- [vcpkg\_install\_make](vcpkg_install_make.md) -- [vcpkg\_install\_meson](vcpkg_install_meson.md) -- [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md) -- [vcpkg\_install\_nmake](vcpkg_install_nmake.md) -- [vcpkg\_install\_qmake](vcpkg_install_qmake.md) -- [vcpkg\_list](vcpkg_list.md) -- [vcpkg\_minimum\_required](vcpkg_minimum_required.md) -- [vcpkg\_replace\_string](vcpkg_replace_string.md) - -## Internal Functions - -- [z\_vcpkg\_apply\_patches](internal/z_vcpkg_apply_patches.md) -- [z\_vcpkg\_forward\_output\_variable](internal/z_vcpkg_forward_output_variable.md) -- [z\_vcpkg\_function\_arguments](internal/z_vcpkg_function_arguments.md) -- [z\_vcpkg\_get\_cmake\_vars](internal/z_vcpkg_get_cmake_vars.md) -- [z\_vcpkg\_prettify\_command\_line](internal/z_vcpkg_prettify_command_line.md) -- [z\_vcpkg\_setup\_pkgconfig\_path](internal/z_vcpkg_setup_pkgconfig_path.md) - -## Scripts from Ports - -### [vcpkg-cmake](ports/vcpkg-cmake.md) - -- [vcpkg\_cmake\_build](vcpkg_cmake_build.md) -- [vcpkg\_cmake\_configure](vcpkg_cmake_configure.md) -- [vcpkg\_cmake\_install](vcpkg_cmake_install.md) - -### [vcpkg-gn](ports/vcpkg-gn.md) - -- [vcpkg\_gn\_configure](ports/vcpkg-gn/vcpkg_gn_configure.md) -- [vcpkg\_gn\_install](ports/vcpkg-gn/vcpkg_gn_install.md) - -### [vcpkg-cmake-config](ports/vcpkg-cmake-config.md) - -- [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md) - -### [vcpkg-cmake-get-vars](ports/vcpkg-cmake-get-vars.md) - -- [vcpkg\_cmake\_get\_vars](ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md) - -### [vcpkg-pkgconfig-get-modules](ports/vcpkg-pkgconfig-get-modules.md) - -- [x\_vcpkg\_pkgconfig\_get\_modules](ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md) - -### [vcpkg-get-python-packages](ports/vcpkg-get-python-packages.md) - -- [x\_vcpkg\_get\_python\_packages](ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md) - -### [vcpkg-qmake](ports/vcpkg-qmake.md) - -- [vcpkg\_qmake\_configure](ports/vcpkg-qmake/vcpkg_qmake_configure.md) diff --git a/docs/maintainers/ports/vcpkg-cmake-config.md b/docs/maintainers/ports/vcpkg-cmake-config.md deleted file mode 100644 index 18e7bb9ac8..0000000000 --- a/docs/maintainers/ports/vcpkg-cmake-config.md +++ /dev/null @@ -1,10 +0,0 @@ -# vcpkg-cmake-config - -`vcpkg-cmake-config` provides `vcpkg_cmake_config_fixup()`, -a function which both: - -- Fixes common mistakes in port build systems, like using absolute paths -- Merges the debug and release config files. - -This function should almost always be used when a port has `*config.cmake` files, -even when the buildsystem of the project is not CMake. diff --git a/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md b/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md deleted file mode 100644 index 469e0b197a..0000000000 --- a/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md +++ /dev/null @@ -1,54 +0,0 @@ -# vcpkg_cmake_config_fixup - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md). - -Merge release and debug CMake targets and configs to support multiconfig generators. - -Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries. - -```cmake -vcpkg_cmake_config_fixup( - [PACKAGE_NAME ] - [CONFIG_PATH ] - [TOOLS_PATH ] - [DO_NOT_DELETE_PARENT_CONFIG_PATH] - [NO_PREFIX_CORRECTION] -) -``` - -For many ports, `vcpkg_cmake_config_fixup()` on its own should work, -as `PACKAGE_NAME` defaults to `${PORT}` and `CONFIG_PATH` defaults to `share/${PACKAGE_NAME}`. -For ports where the package name passed to `find_package` is distinct from the port name, -`PACKAGE_NAME` should be changed to be that name instead. -For ports where the directory of the `*config.cmake` files cannot be set, -use the `CONFIG_PATH` to change the directory where the files come from. - -By default the parent directory of CONFIG_PATH is removed if it is named "cmake". -Passing the `DO_NOT_DELETE_PARENT_CONFIG_PATH` option disable such behavior, -as it is convenient for ports that install -more than one CMake package configuration file. - -The `NO_PREFIX_CORRECTION` option disables the correction of `_IMPORT_PREFIX` -done by vcpkg due to moving the config files. -Currently the correction does not take into account how the files are moved, -and applies a rather simply correction which in some cases will yield the wrong results. - -## How it Works - -1. Moves `/debug//*targets-debug.cmake` to `/share/${PACKAGE_NAME}`. -2. Transforms all references matching `/bin/*.exe` to `/${TOOLS_PATH}/*.exe` on Windows. -3. Transforms all references matching `/bin/*` to `/${TOOLS_PATH}/*` on other platforms. -4. Fixes `${_IMPORT_PREFIX}` in auto generated targets. -5. Replaces `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs. -6. Merges INTERFACE_LINK_LIBRARIES of release and debug configurations. -7. Replaces `${CURRENT_INSTALLED_DIR}` with `${VCPKG_IMPORT_PREFIX}` in targets. -8. Removes `/debug//*config.cmake`. - -## Examples - -* [concurrentqueue](https://github.com/Microsoft/vcpkg/blob/master/ports/concurrentqueue/portfile.cmake) -* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake) -* [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake) - -## Source -[ports/vcpkg-cmake-config/vcpkg\_cmake\_config\_fixup.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.cmake) diff --git a/docs/maintainers/ports/vcpkg-cmake-get-vars.md b/docs/maintainers/ports/vcpkg-cmake-get-vars.md deleted file mode 100644 index 4881c82185..0000000000 --- a/docs/maintainers/ports/vcpkg-cmake-get-vars.md +++ /dev/null @@ -1,3 +0,0 @@ -# vcpkg-cmake-get-vars - -This port contains a helper function to extract CMake variables into the scope of the portfile or other scripts diff --git a/docs/maintainers/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md b/docs/maintainers/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md deleted file mode 100644 index a9d4a82b5d..0000000000 --- a/docs/maintainers/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md +++ /dev/null @@ -1,41 +0,0 @@ -# vcpkg_cmake_get_vars - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md). - -Runs a cmake configure with a dummy project to extract certain cmake variables - -## Usage -```cmake -vcpkg_cmake_get_vars() -``` - -`vcpkg_cmake_get_vars()` sets `` to -a path to a generated CMake file, with the detected `CMAKE_*` variables -re-exported as `VCPKG_DETECTED_CMAKE_*`. - -Additionally sets, for `RELEASE` and `DEBUG`: -- VCPKG_COMBINED_CXX_FLAGS_ -- VCPKG_COMBINED_C_FLAGS_ -- VCPKG_COMBINED_SHARED_LINKER_FLAGS_ -- VCPKG_COMBINED_STATIC_LINKER_FLAGS_ -- VCPKG_COMBINED_EXE_LINKER_FLAGS_ - -Most users should use these pre-combined flags instead of attempting -to read the `VCPKG_DETECTED_*` flags directly. - -## Notes -Avoid usage in portfiles. - -All calls to `vcpkg_cmake_get_vars` will result in the same output file; -the output file is not generated multiple times. - -### Basic Usage - -```cmake -vcpkg_cmake_get_vars(cmake_vars_file) -include("${cmake_vars_file}") -message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CMAKE_CXX_FLAGS}") -``` - -## Source -[ports/vcpkg-cmake-get-vars/vcpkg\_cmake\_get\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.cmake) diff --git a/docs/maintainers/ports/vcpkg-cmake.md b/docs/maintainers/ports/vcpkg-cmake.md deleted file mode 100644 index 52f6c1fcd4..0000000000 --- a/docs/maintainers/ports/vcpkg-cmake.md +++ /dev/null @@ -1,7 +0,0 @@ -# vcpkg-cmake - -This port contains portfile helper functions for dealing with a CMake buildsystem. - -- [`vcpkg_cmake_configure()`](../vcpkg_cmake_configure.md) -- [`vcpkg_cmake_install()`](../vcpkg_cmake_install.md) -- [`vcpkg_cmake_build()`](../vcpkg_cmake_build.md) diff --git a/docs/maintainers/ports/vcpkg-get-python-packages.md b/docs/maintainers/ports/vcpkg-get-python-packages.md deleted file mode 100644 index 8061d05d92..0000000000 --- a/docs/maintainers/ports/vcpkg-get-python-packages.md +++ /dev/null @@ -1,6 +0,0 @@ -# vcpkg-get-python-packages - -**Experimental: will change or be removed at any time** - -`vcpkg-get-python-packages` provides `x_vcpkg_get_python_packages()`, a function which simplifies getting -python packages. diff --git a/docs/maintainers/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md b/docs/maintainers/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md deleted file mode 100644 index 26d57e4fa6..0000000000 --- a/docs/maintainers/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md +++ /dev/null @@ -1,38 +0,0 @@ -# x_vcpkg_get_python_packages - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md). - -Experimental -Retrieve needed python packages - -## Usage -```cmake -x_vcpkg_get_python_packages( - [PYTHON_VERSION (2|3)] - PYTHON_EXECUTABLE - REQUIREMENTS_FILE - PACKAGES ... - [OUT_PYTHON_VAR somevar] -) -``` -## Parameters - -### PYTHON_VERSION -Python version to be used. Either 2 or 3 - -### PYTHON_EXECUTABLE -Full path to the python executable - -### REQUIREMENTS_FILE -Requirement file with the list of python packages - -### PACKAGES -List of python packages to acquire - -### OUT_PYTHON_VAR -Variable to store the path to the python binary inside the virtual environment - - - -## Source -[ports/vcpkg-get-python-packages/x\_vcpkg\_get\_python\_packages.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.cmake) diff --git a/docs/maintainers/ports/vcpkg-gn.md b/docs/maintainers/ports/vcpkg-gn.md deleted file mode 100644 index 21c440dd89..0000000000 --- a/docs/maintainers/ports/vcpkg-gn.md +++ /dev/null @@ -1,12 +0,0 @@ -# vcpkg-gn - -This port contains cmake functions for dealing with a GN buildsystem. - -## Example - -```cmake -vcpkg_gn_configure( - SOURCE_PATH "${SOURCE_PATH}" -) -vcpkg_gn_install() -``` diff --git a/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md b/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md deleted file mode 100644 index da9326a810..0000000000 --- a/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md +++ /dev/null @@ -1,32 +0,0 @@ -# vcpkg_gn_configure - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md). - -Generate Ninja (GN) targets - -## Usage: -```cmake -vcpkg_gn_configure( - SOURCE_PATH - [OPTIONS ] - [OPTIONS_DEBUG ] - [OPTIONS_RELEASE ] -) -``` - -## Parameters: -### SOURCE_PATH (required) -The path to the GN project. - -### OPTIONS -Options to be passed to both the debug and release targets. -Note: Must be provided as a space-separated string. - -### OPTIONS_DEBUG (space-separated string) -Options to be passed to the debug target. - -### OPTIONS_RELEASE (space-separated string) -Options to be passed to the release target. - -## Source -[ports/vcpkg-gn/vcpkg\_gn\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_configure.cmake) diff --git a/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md b/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md deleted file mode 100644 index e520fcc96a..0000000000 --- a/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md +++ /dev/null @@ -1,29 +0,0 @@ -# vcpkg_gn_install - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md). - -Installs a GN project. - -In order to build a GN project without installing, use [`vcpkg_build_ninja()`]. - -## Usage: -```cmake -vcpkg_gn_install( - SOURCE_PATH - [TARGETS ...] -) -``` - -## Parameters: -### SOURCE_PATH -The path to the source directory - -### TARGETS -Only install the specified targets. - -Note: includes must be handled separately - -[`vcpkg_build_ninja()`]: vcpkg_build_ninja.md - -## Source -[ports/vcpkg-gn/vcpkg\_gn\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_install.cmake) diff --git a/docs/maintainers/ports/vcpkg-pkgconfig-get-modules.md b/docs/maintainers/ports/vcpkg-pkgconfig-get-modules.md deleted file mode 100644 index ac99412c24..0000000000 --- a/docs/maintainers/ports/vcpkg-pkgconfig-get-modules.md +++ /dev/null @@ -1,6 +0,0 @@ -# vcpkg-pkgconfig-get-modules - -**Experimental: will change or be removed at any time** - -`vcpkg-pkgconfig-get-modules` provides `x_vcpkg_pkgconfig_get_modules()`, a function which simplifies calling -`pkg-config` in portfiles in order to gather dependencies for exotic buildsystems. diff --git a/docs/maintainers/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md b/docs/maintainers/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md deleted file mode 100644 index 1dbcf37e03..0000000000 --- a/docs/maintainers/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md +++ /dev/null @@ -1,45 +0,0 @@ -# x_vcpkg_pkgconfig_get_modules - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md). - -Experimental -Retrieve required module information from pkgconfig modules - -## Usage -```cmake -x_vcpkg_pkgconfig_get_modules( - PREFIX - MODULES ... - [CFLAGS] - [LIBS] - [LIBRARIES] - [LIBRARIES_DIRS] - [INCLUDE_DIRS] -) -``` -## Parameters - -### PREFIX -Used variable prefix to use - -### MODULES -List of pkgconfig modules to retrieve information for. - -### LIBS -Returns `"${PKGCONFIG}" --libs` in _LIBS_(DEBUG|RELEASE) - -### LIBRARIES -Returns `"${PKGCONFIG}" --libs-only-l` in _LIBRARIES_(DEBUG|RELEASE) - -### LIBRARIES_DIRS -Returns `"${PKGCONFIG}" --libs-only-L` in _LIBRARIES_DIRS_(DEBUG|RELEASE) - -### INCLUDE_DIRS -Returns `"${PKGCONFIG}" --cflags-only-I` in _INCLUDE_DIRS_(DEBUG|RELEASE) - -## Examples - -* [qt5-base](https://github.com/microsoft/vcpkg/blob/master/ports/qt5-base/portfile.cmake) - -## Source -[ports/vcpkg-pkgconfig-get-modules/x\_vcpkg\_pkgconfig\_get\_modules.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.cmake) diff --git a/docs/maintainers/ports/vcpkg-qmake.md b/docs/maintainers/ports/vcpkg-qmake.md deleted file mode 100644 index fe5050ec3a..0000000000 --- a/docs/maintainers/ports/vcpkg-qmake.md +++ /dev/null @@ -1,7 +0,0 @@ -# vcpkg-qmake - -This port contains qmake functions for dealing with a QMake buildsystem. - -In the common case, `vcpkg_qmake_configure()` (with appropriate arguments) -followed by `vcpkg_install_qmake()` will be enough to build and install a port. - diff --git a/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_build.md b/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_build.md deleted file mode 100644 index 92171c977c..0000000000 --- a/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_build.md +++ /dev/null @@ -1,27 +0,0 @@ -# vcpkg_qmake_build - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_build.md). - -Build a qmake-based project, previously configured using vcpkg_qmake_configure. - -```cmake -vcpkg_qmake_configure( - [SKIP_MAKEFILES] - [BUILD_LOGNAME arg1] - [TARGETS arg1 [arg2 ...]] - [RELEASE_TARGETS arg1 [arg2 ...]] - [DEBUG_TARGETS arg1 [arg2 ...]] -) -``` - -### SKIP_MAKEFILES -Skip the generation of makefiles - -### BUILD_LOGNAME -Configuration independent prefix for the build log files (default:'build') - -### TARGETS, RELEASE\_TARGETS, DEBUG\_TARGETS -Targets to build for a certain configuration. - -## Source -[ports/vcpkg-qmake/vcpkg\_qmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-qmake/vcpkg_qmake_build.cmake) diff --git a/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_configure.md b/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_configure.md deleted file mode 100644 index 6ad2384c33..0000000000 --- a/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_configure.md +++ /dev/null @@ -1,37 +0,0 @@ -# vcpkg_qmake_configure - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_configure.md). - -Configure a qmake-based project. - -###User setable triplet variables: -VCPKG_OSX_DEPLOYMENT_TARGET: Determines QMAKE_MACOSX_DEPLOYMENT_TARGET -VCPKG_QMAKE_COMMAND: Path to qmake. (default: "${CURRENT_HOST_INSTALLED_DIR}/tools/Qt6/bin/qmake${VCPKG_HOST_EXECUTABLE_SUFFIX}") -VCPKG_QT_CONF_(RELEASE|DEBUG): Path to qt.config being used for RELEASE/DEBUG. (default: "${CURRENT_INSTALLED_DIR}/tools/Qt6/qt_(release|debug).conf") -VCPKG_QT_TARGET_MKSPEC: Qt mkspec to use -VCPKG_QMAKE_OPTIONS(_RELEASE|_DEBUG)?: Extra options to pass to QMake - -```cmake -vcpkg_qmake_configure( - SOURCE_PATH - [QMAKE_OPTIONS arg1 [arg2 ...]] - [QMAKE_OPTIONS_RELEASE arg1 [arg2 ...]] - [QMAKE_OPTIONS_DEBUG arg1 [arg2 ...]] - [OPTIONS arg1 [arg2 ...]] - [OPTIONS_RELEASE arg1 [arg2 ...]] - [OPTIONS_DEBUG arg1 [arg2 ...]] -) -``` - -### SOURCE_PATH -The path to the *.pro qmake project file. - -### QMAKE_OPTIONS, QMAKE_OPTIONS\_RELEASE, QMAKE_OPTIONS\_DEBUG -options directly passed to qmake with the form QMAKE_X=something or CONFIG=something - -### OPTIONS, OPTIONS\_RELEASE, OPTIONS\_DEBUG -The options passed after -- to qmake. - - -## Source -[ports/vcpkg-qmake/vcpkg\_qmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-qmake/vcpkg_qmake_configure.cmake) diff --git a/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_install.md b/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_install.md deleted file mode 100644 index 55ef586046..0000000000 --- a/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_install.md +++ /dev/null @@ -1,20 +0,0 @@ -# vcpkg_qmake_install - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_install.md). - -Build and install a qmake project. - - -```cmake -vcpkg_qmake_install(...) -``` - -### Parameters: -See [`vcpkg_qmake_build()`](vcpkg_qmake_build.md). - -### Notes: -This command transparently forwards to [`vcpkg_qmake_build()`](vcpkg_qmake_build.md) -and appends the 'install' target - -## Source -[ports/vcpkg-qmake/vcpkg\_qmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-qmake/vcpkg_qmake_install.cmake) diff --git a/docs/maintainers/pr-review-checklist.md b/docs/maintainers/pr-review-checklist.md deleted file mode 100644 index 05baaa58ed..0000000000 --- a/docs/maintainers/pr-review-checklist.md +++ /dev/null @@ -1,115 +0,0 @@ -Vcpkg PR Checklist -===================== -Revision: 1 - -## Overview -This document provides an annotated checklist which vcpkg team members use to apply the "reviewed" label on incoming pull requests. If a pull request violates any of these points, we may ask contributors to make necessary changes before we can merge the changeset. - -Feel free to create an issue or pull request if you feel that this checklist can be improved. Please increment the revision number when modifying the checklist content. - -## Checklist -You can link any of these checklist items in a GitHub comment by copying the link address attached to each item code. - -
-c000001: No deprecated helper functions are used - -See our [Maintainer Guidelines and Policies](maintainer-guide.md#avoid-deprecated-helper-functions) for more information. - -
- -
-c000002: `"port-version"` field is updated - -See our [Maintainer Guidelines and Policies](maintainer-guide.md#versioning) for more information. - -
- -
-c000003: New ports contain a `"description"` field written in English - -A description only one or a few sentences long is helpful. Consider using the library's official description from their `README.md` or similar if possible. Automatic translations are acceptable and we are happy to clean up translations to English for our contributors. - -See our [manifest file documentation](manifest-files.md#description) for more information. - -
- -
-c000004: No unnecessary comments are present in the changeset - -See our [Maintainer Guidelines and Policies](maintainer-guide.md#avoid-excessive-comments-in-portfiles) for more information. - -
- -
-c000005: Downloaded archives are versioned if available - -
-c000006: New ports pass CI checks for triplets that the library officially supports - -To ensure vcpkg ports are of a high quality, we ask that incoming ports support the official platforms for the library in question. - -
- -
-c000007: Patches fix issues that are vcpkg-specific only - -If possible, patches to the library source code should be upstreamed to the library's official repository. Opening up a pull request on the library's repository will help to improve the library for everyone, not just vcpkg users. - -
- -
-c000008: New ports download source code from the official source if available - -To respect library authors and keep code secure, please have ports download source code from the official source. We may make exceptions if the original source code is not available and there is substantial community interest in maintaining the library in question. - -
- -
-c000009: Ports and port features are named correctly - -For user accessibility, we prefer names of ports and port features to be intuitive and close to their counterparts in official sources and other package managers. If you are unsure about the naming of a port or port feature, we recommend checking repology.org, packages.ubuntu.com, or searching for additional information using a search engine. We can also help our contributors with this, so feel free to ask for naming suggestions if you are unsure. - -
- -
-c000010: Library targets are exported when appropriate - -To provide users with a seamless build system integration, please be sure to export and provide a means of finding the library targets intended to be used downstream. Targets not meant to be exported should be be marked private and not exported. - -
- -
-c000011: Ports do not use applications which modify the user's system - -Ports should uphold vcpkg's contract of not modifying the user's system by avoiding applications which do so. Examples of these applications are `sudo`, `apt`, `brew`, or `pip`. Please use an alternative to these types of programs wherever possible. - -
- -
-c000012: Ports with system dependencies include an information message during installation - -Some ports have library and tool dependencies that do not exist within vcpkg. For these missing dependencies, we ask that contributors add a message to the top of the port's `portfile.cmake` stating the missing dependencies and how to acquire them. We ask that the message is displayed before any major work is done to ensure that users can "early out" of the installation process as soon as possible in case they are missing the dependency. - -Example: -```cmake -message( -"${PORT} currently requires the following libraries from the system package manager: - autoconf libtool -These can be installed on Ubuntu systems via sudo apt install autoconf libtool" -) -``` - -
- -
-c000013: Manifest files are used instead of CONTROL files for new ports - -Many existing ports use the CONTROL file syntax; while this syntax will be supported for some time to come, -new ports should not use these. Any newly added port _must_ use the manifest files. - -We also recommend, when significant modifications are made to ports, that one switches to manifest files; -however, this is not required. You may find `vcpkg format-manifest` useful. diff --git a/docs/maintainers/registries.md b/docs/maintainers/registries.md deleted file mode 100644 index 12a98c208d..0000000000 --- a/docs/maintainers/registries.md +++ /dev/null @@ -1,360 +0,0 @@ -# Creating Registries - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/maintainers/registries.md).** - -There are two parts to using registries; this documents the creation side of -the relationship. In order to learn more about using registries that others -have created, please read [this documentation](../users/registries.md). -## Table of Contents - -- [Creating Registries](#creating-registries) - - [Table of Contents](#table-of-contents) - - [Overview](#overview) - - [Git Registries](#git-registries) - - [Adding a New Version](#adding-a-new-version) - - [Filesystem Registries](#filesystem-registries) - - [Adding a New Version](#adding-a-new-version-1) - - [Builtin Registries](#builtin-registries) - -## Overview - -Registries are collections of ports and their versions. There are two major -choices of implementation for registries, if you want to create your own - -git registries, and filesystem registries. - -Git registries are simple git repositories, and can be shared publicly or -privately via normal mechanisms for git repositories. The vcpkg repository at -, for example, is a git registry. - -Filesystem registries are designed as more of a testing ground. Given that they -literally live on your filesystem, the only way to share them is via shared -directories. However, filesystem registries can be useful as a way to represent -registries held in non-git version control systems, assuming one has some way -to get the registry onto the disk. - -Note that we expect the set of registry types to grow over time; if you would -like support for registries built in your favorite public version control -system, don't hesitate to open a PR. - -The basic structure of a registry is: - -- The set of versions that are considered "latest" at certain times in history, - known as the "baseline". -- The set of all the versions of all the ports, and where to find each of - these in the registry. - -### Git Registries - -As you're following along with this documentation, it may be helpful to have -a working example to refer to. We've written one and put it here: -. - -All git registries must have a `versions/baseline.json` file. This file -contains the set of "latest versions" at a certain commit. It is laid out as -a top-level object containing only the `"default"` field. This field should -contain an object mapping port names to the version which is currently the -latest. - -Here's an example of a valid baseline.json: - -```json -{ - "default": { - "kitten": { - "baseline": "2.6.2", - "port-version": 0 - }, - "port-b": { - "baseline": "19.00", - "port-version": 2 - } - } -} -``` - -The `versions` directory contains all the information about which versions of -which packages are contained in the registry, along with where those versions -are stored. The rest of the registry just acts as a backing store, as far as -vcpkg is concerned: only things inside the `versions` directory will be used -to direct how your registry is seen by vcpkg. - -Each port in a registry should exist in the versions directory as -`-/.json`; in other words, the -information about the `kitten` port would be located in -`versions/k-/kitten.json`. This should be a top-level object with only a -single field: `"versions"`. This field should contain an array of version -objects: - -- The version of the port in question; should be exactly the same as the - `vcpkg.json` file, including the version fields and `"port-version"`. -- The `"git-tree"` field, which is a git tree; in other words, what you get - when you write `git rev-parse COMMIT-ID:path/to/port`. - -Note that the version fields for ports with `CONTROL` files, is -`"version-string"`; we do not recommend using `CONTROL` files in new -registries, however. - -_WARNING_: One very important part of registries is that versions should -_never_ be changed. Updating to a later ref should never remove or change an -existing version. It must always be safe to update a registry. - -Here's an example of a valid version database for a `kitten` port with one -version: - -```json -{ - "versions": [ - { - "version": "2.6.2", - "port-version": 0, - "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e" - } - ] -} -``` - -In general, it's not important where you place port directories. However, the -idiom in vcpkg is to follow what the built in vcpkg registry does: your -`kitten` port should be placed in `ports/kitten`. - -_WARNING_: One other thing to keep in mind is that when you update a registry, -all previous versions should also be accessible. Since your user will set their -baseline to a commit ID, that commit ID must always exist, and be accessible -from your HEAD commit, which is what is actually fetched. This means that your -HEAD commit should be a child of all previous HEAD commits. - -### Builtin Registries - -Builtin registries are treated as special [Git registries](#git-registries). Instead of fetching from a remote url, builtin registries consult the `$VCPKG_ROOT/.git` directory of the vcpkg clone. They use the currently checked out `$VCPKG_ROOT/versions` directory as the source for versioning information. - -#### Adding a New Version - -There is some git trickery involved in creating a new version of a port. The -first thing to do is make some changes, update the `"port-version"` and regular -version field as you need to, and then test with `overlay-ports`: -`vcpkg install kitten --overlay-ports=ports/kitten`. - -Once you've finished your testing, you'll need to make sure that the directory -as it is is under git's purview. You'll do this by creating a temporary commit: - -```pwsh -> git add ports/kitten -> git commit -m 'temporary commit' -``` - -Then, get the git tree ID of the directory: - -```pwsh -> git rev-parse HEAD:ports/kitten -73ad3c823ef701c37421b450a34271d6beaf7b07 -``` - -Then, you can add this version to the versions database. At the top of your -`versions/k-/kitten.json`, you can add (assuming you're adding version -`2.6.3#0`): - -```json -{ - "versions": [ - { - "version": "2.6.3", - "port-version": 0, - "git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07" - }, - { - "version": "2.6.2", - "port-version": 0, - "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e" - } - ] -} -``` - -then, you'll want to modify your `versions/baseline.json` with your new version -as well: - -```json -{ - "default": { - "kitten": { - "baseline": "2.6.3", - "port-version": 0 - }, - "port-b": { - "baseline": "19.00", - "port-version": 2 - } - } -} -``` - -and amend your current commit: - -```pwsh -> git commit --amend -``` - -then share away! - -### Filesystem Registries - -As you're following along with this documentation, it may be helpful to have -a working example to refer to. We've written one and put it here: -. - -All filesystem registries must have a `versions/baseline.json` file. This file -contains the set of "latest versions" for a certain version of the registry. -It is laid out as a top-level object containing a map from version name to -"baseline objects", which map port names to the version which is considered -"latest" for that version of the registry. - -Filesystem registries need to decide on a versioning scheme. Unlike git -registries, which have the implicit versioning scheme of refs, filesystem -registries can't rely on the version control system here. One possible option -is to do a daily release, and have your "versions" be dates. - -_WARNING_: A baseline must not be modified once published. If you want to change or update versions, you need to create a new baseline in the `baseline.json` file. - -Here's an example of a valid `baseline.json`, for a registry that has decided -upon dates for their versions: - -```json -{ - "2021-04-16": { - "kitten": { - "baseline": "2.6.2", - "port-version": 0 - }, - "port-b": { - "baseline": "19.00", - "port-version": 2 - } - }, - "2021-04-15": { - "kitten": { - "baseline": "2.6.2", - "port-version": 0 - }, - "port-b": { - "baseline": "19.00", - "port-version": 1 - } - } -} -``` - -The `versions` directory contains all the information about which versions of -which packages are contained in the registry, along with where those versions -are stored. The rest of the registry just acts as a backing store, as far as -vcpkg is concerned: only things inside the `versions` directory will be used -to direct how your registry is seen by vcpkg. - -Each port in a registry should exist in the versions directory as -`-/.json`; in other words, the -information about the `kitten` port would be located in -`versions/k-/kitten.json`. This should be a top-level object with only a -single field: `"versions"`. This field should contain an array of version -objects: - -- The version of the port in question; should be exactly the same as the - `vcpkg.json` file, including the version fields and `"port-version"`. -- The `"path"` field: a relative directory, rooted at the base of the registry - (in other words, the directory where `versions` is located), to the port - directory. It should look something like `"$/path/to/port/dir`" - -Note that the version fields for ports with `CONTROL` files, is -`"version-string"`; we do not recommend using `CONTROL` files in new -registries, however. - -In general, it's not important where you place port directories. However, the -idiom in vcpkg is to follow somewhat closely to what the built in vcpkg -registry does: your `kitten` port at version `x.y.z` should be placed in -`ports/kitten/x.y.z`, with port versions appended as you see fit (although -since `#` is not a good character to use for file names, perhaps use `_`). - -_WARNING_: One very important part of registries is that versions should -_never_ be changed. One should never remove or change an existing version. -Your changes to your registry shouldn't change behavior to downstream users. - -Here's an example of a valid version database for a `kitten` port with one -version: - -```json -{ - "versions": [ - { - "version": "2.6.2", - "port-version": 0, - "path": "$/ports/kitten/2.6.2_0" - } - ] -} -``` - -#### Adding a New Version - -Unlike git registries, adding a new version to a filesystem registry mostly -involves a lot of copying. The first thing to do is to copy the latest -version of your port into a new version directory, update the version and -`"port-version"` fields as you need to, and then test with `overlay-ports`: -`vcpkg install kitten --overlay-ports=ports/kitten/new-version`. - -Once you've finished your testing, you can add this new version to the top of -your `versions/k-/kitten.json`: - -```json -{ - "versions": [ - { - "version": "2.6.3", - "port-version": 0, - "path": "$/ports/kitten/2.6.3_0" - }, - { - "version": "2.6.2", - "port-version": 0, - "path": "$/ports/kitten/2.6.2_0" - } - ] -} -``` - -then, you'll want to modify your `versions/baseline.json` with your new version -as well (remember not to modify existing baselines): - -```json -{ - "2021-04-17": { - "kitten": { - "baseline": "2.6.3", - "port-version": 0 - }, - "port-b": { - "baseline": "19.00", - "port-version": 2 - } - }, - "2021-04-16": { - "kitten": { - "baseline": "2.6.2", - "port-version": 0 - }, - "port-b": { - "baseline": "19.00", - "port-version": 2 - } - }, - "2021-04-15": { - "kitten": { - "baseline": "2.6.2", - "port-version": 0 - }, - "port-b": { - "baseline": "19.00", - "port-version": 1 - } - } -} -``` - -and you're done! diff --git a/docs/maintainers/vcpkg_acquire_msys.md b/docs/maintainers/vcpkg_acquire_msys.md deleted file mode 100644 index 5093f90fa0..0000000000 --- a/docs/maintainers/vcpkg_acquire_msys.md +++ /dev/null @@ -1,60 +0,0 @@ -# vcpkg_acquire_msys - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_acquire_msys.md). - -Download and prepare an MSYS2 instance. - -## Usage -```cmake -vcpkg_acquire_msys( - PACKAGES ... - [NO_DEFAULT_PACKAGES] - [DIRECT_PACKAGES ...] -) -``` - -## Parameters -### MSYS_ROOT_VAR -An out-variable that will be set to the path to MSYS2. - -### PACKAGES -A list of packages to acquire in msys. - -To ensure a package is available: `vcpkg_acquire_msys(MSYS_ROOT PACKAGES make automake1.16)` - -### NO_DEFAULT_PACKAGES -Exclude the normal base packages. - -The list of base packages includes: bash, coreutils, sed, grep, gawk, gzip, diffutils, make, and pkg-config - -### DIRECT_PACKAGES -A list of URL/SHA512 pairs to acquire in msys. - -This parameter can be used by a port to privately extend the list of msys packages to be acquired. -The URLs can be found on the msys2 website[1] and should be a direct archive link: - - https://repo.msys2.org/mingw/i686/mingw-w64-i686-gettext-0.19.8.1-9-any.pkg.tar.zst - -[1] https://packages.msys2.org/search - -## Notes -A call to `vcpkg_acquire_msys` will usually be followed by a call to `bash.exe`: -```cmake -vcpkg_acquire_msys(MSYS_ROOT) -set(BASH ${MSYS_ROOT}/usr/bin/bash.exe) - -vcpkg_execute_required_process( - COMMAND ${BASH} --noprofile --norc "${CMAKE_CURRENT_LIST_DIR}\\build.sh" - WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel - LOGNAME build-${TARGET_TRIPLET}-rel -) -``` - -## Examples - -* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake) -* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake) -* [libvpx](https://github.com/Microsoft/vcpkg/blob/master/ports/libvpx/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_acquire\_msys.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_acquire_msys.cmake) diff --git a/docs/maintainers/vcpkg_add_to_path.md b/docs/maintainers/vcpkg_add_to_path.md deleted file mode 100644 index 76fb251b93..0000000000 --- a/docs/maintainers/vcpkg_add_to_path.md +++ /dev/null @@ -1,27 +0,0 @@ -# vcpkg_add_to_path - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_add_to_path.md). - -Add a directory or directories to the PATH environment variable - -```cmake -vcpkg_add_to_path([PREPEND] [...]) -``` - -`vcpkg_add_to_path` adds all of the paths passed to it to the PATH environment variable. -If PREPEND is passed, then those paths are prepended to the PATH environment variable, -so that they are searched first; otherwise, those paths are appended, so they are -searched after the paths which are already in the environment variable. - -The paths are added in the order received, so that the first path is always searched -before a later path. - -If no paths are passed, then nothing will be done. - -## Examples: -* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75) -* [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15) -* [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13) - -## Source -[scripts/cmake/vcpkg\_add\_to\_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake) diff --git a/docs/maintainers/vcpkg_apply_patches.md b/docs/maintainers/vcpkg_apply_patches.md deleted file mode 100644 index a3aad07145..0000000000 --- a/docs/maintainers/vcpkg_apply_patches.md +++ /dev/null @@ -1,18 +0,0 @@ -# vcpkg_apply_patches - -**This function has been deprecated in favor of the `PATCHES` argument to [`vcpkg_from_github()`](vcpkg_from_github.md) et al.** - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_apply_patches.md). - -Apply a set of patches to a source tree. - -```cmake -vcpkg_apply_patches( - SOURCE_PATH <${SOURCE_PATH}> - [QUIET] - PATCHES ... -) -``` - -## Source -[scripts/cmake/vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake) diff --git a/docs/maintainers/vcpkg_backup_restore_env_vars.md b/docs/maintainers/vcpkg_backup_restore_env_vars.md deleted file mode 100644 index d1591d06eb..0000000000 --- a/docs/maintainers/vcpkg_backup_restore_env_vars.md +++ /dev/null @@ -1,26 +0,0 @@ -# vcpkg_backup_restore_env_vars - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_backup_restore_env_vars.md). - -Backup or restore the environment variables - -## Usage: -```cmake -vcpkg_backup_env_variables(VARS [...]) -vcpkg_restore_env_variables(VARS [...]) -``` - -### VARS -The variables to back up or restore. -These are placed in the parent scope, so you must backup and restore -from the same scope. - -## Notes -One must always call `vcpkg_backup_env_variables` before -`vcpkg_restore_env_variables`; however, `vcpkg_restore_env_variables` -does not change the back up variables, and so you may call `restore` -multiple times for one `backup`. - - -## Source -[scripts/cmake/vcpkg\_backup\_restore\_env\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_backup_restore_env_vars.cmake) diff --git a/docs/maintainers/vcpkg_build_cmake.md b/docs/maintainers/vcpkg_build_cmake.md deleted file mode 100644 index 4163c6cc86..0000000000 --- a/docs/maintainers/vcpkg_build_cmake.md +++ /dev/null @@ -1,38 +0,0 @@ -# vcpkg_build_cmake - -**This function has been deprecated in favor of [`vcpkg_cmake_build`](vcpkg_cmake_build.md) from the vcpkg-cmake port.** - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_cmake.md). - -Build a cmake project. - -## Usage: -```cmake -vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET ]) -``` - -## Parameters: -### DISABLE_PARALLEL -The underlying buildsystem will be instructed to not parallelize - -### TARGET -The target passed to the cmake build command (`cmake --build . --target `). If not specified, no target will -be passed. - -### ADD_BIN_TO_PATH -Adds the appropriate Release and Debug `bin` directories to the path during the build such that executables can run against the in-tree DLLs. - -## Notes: -This command should be preceded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md). -You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the -"install" target - -## Examples: - -* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) -* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) -* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake) -* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_build\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_cmake.cmake) diff --git a/docs/maintainers/vcpkg_build_make.md b/docs/maintainers/vcpkg_build_make.md deleted file mode 100644 index 591062d650..0000000000 --- a/docs/maintainers/vcpkg_build_make.md +++ /dev/null @@ -1,57 +0,0 @@ -# vcpkg_build_make - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_make.md). - -Build a linux makefile project. - -## Usage: -```cmake -vcpkg_build_make([BUILD_TARGET ] - [INSTALL_TARGET ] - [ADD_BIN_TO_PATH] - [ENABLE_INSTALL] - [MAKEFILE ] - [LOGFILE_ROOT ] - [DISABLE_PARALLEL] - [SUBPATH ]) -``` - -### BUILD_TARGET -The target passed to the make build command (`./make `). If not specified, the 'all' target will -be passed. - -### INSTALL_TARGET -The target passed to the make build command (`./make `) if `ENABLE_INSTALL` is used. Defaults to 'install'. - -### ADD_BIN_TO_PATH -Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs. - -### ENABLE_INSTALL -IF the port supports the install target use vcpkg_install_make() instead of vcpkg_build_make() - -### MAKEFILE -Specifies the Makefile as a relative path from the root of the sources passed to `vcpkg_configure_make()` - -### LOGFILE_ROOT -Specifies a log file prefix. - -### DISABLE_PARALLEL -The underlying buildsystem will be instructed to not parallelize - -### SUBPATH -Additional subdir to invoke make in. Useful if only parts of a port should be built. - -## Notes: -This command should be preceded by a call to [`vcpkg_configure_make()`](vcpkg_configure_make.md). -You can use the alias [`vcpkg_install_make()`](vcpkg_install_make.md) function if your makefile supports the -"install" target - -## Examples - -* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake) -* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake) -* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake) -* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_build\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_make.cmake) diff --git a/docs/maintainers/vcpkg_build_msbuild.md b/docs/maintainers/vcpkg_build_msbuild.md deleted file mode 100644 index 4e86fd3b66..0000000000 --- a/docs/maintainers/vcpkg_build_msbuild.md +++ /dev/null @@ -1,66 +0,0 @@ -# vcpkg_build_msbuild - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_msbuild.md). - -Build a msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`. - -## Usage -```cmake -vcpkg_build_msbuild( - PROJECT_PATH <${SOURCE_PATH}/port.sln> - [RELEASE_CONFIGURATION ] - [DEBUG_CONFIGURATION ] - [TARGET ] - [TARGET_PLATFORM_VERSION <10.0.15063.0>] - [PLATFORM <${TRIPLET_SYSTEM_ARCH}>] - [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>] - [OPTIONS ...] - [OPTIONS_RELEASE ...] - [OPTIONS_DEBUG ...] - [USE_VCPKG_INTEGRATION] -) -``` - -## Parameters -### USE_VCPKG_INTEGRATION -Apply the normal `integrate install` integration for building the project. - -By default, projects built with this command will not automatically link libraries or have header paths set. - -### PROJECT_PATH -The path to the solution (`.sln`) or project (`.vcxproj`) file. - -### RELEASE_CONFIGURATION -The configuration (``/p:Configuration`` msbuild parameter) used for Release builds. - -### DEBUG_CONFIGURATION -The configuration (``/p:Configuration`` msbuild parameter) -used for Debug builds. - -### TARGET_PLATFORM_VERSION -The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter) - -### TARGET -The MSBuild target to build. (``/t:``) - -### PLATFORM -The platform (``/p:Platform`` msbuild parameter) used for the build. - -### PLATFORM_TOOLSET -The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build. - -### OPTIONS -Additional options passed to msbuild for all builds. - -### OPTIONS_RELEASE -Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`. - -### OPTIONS_DEBUG -Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`. - -## Examples - -* [chakracore](https://github.com/Microsoft/vcpkg/blob/master/ports/chakracore/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_build\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake) diff --git a/docs/maintainers/vcpkg_build_ninja.md b/docs/maintainers/vcpkg_build_ninja.md deleted file mode 100644 index de099a16d3..0000000000 --- a/docs/maintainers/vcpkg_build_ninja.md +++ /dev/null @@ -1,19 +0,0 @@ -# vcpkg_build_ninja - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_ninja.md). - -Build a ninja project - -## Usage: -```cmake -vcpkg_build_ninja( - [TARGETS ...] -) -``` - -## Parameters: -### TARGETS -Only build the specified targets. - -## Source -[scripts/cmake/vcpkg\_build\_ninja.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_ninja.cmake) diff --git a/docs/maintainers/vcpkg_build_nmake.md b/docs/maintainers/vcpkg_build_nmake.md deleted file mode 100644 index c950af4a58..0000000000 --- a/docs/maintainers/vcpkg_build_nmake.md +++ /dev/null @@ -1,89 +0,0 @@ -# vcpkg_build_nmake - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_nmake.md). - -Build a msvc makefile project. - -## Usage: -```cmake -vcpkg_build_nmake( - SOURCE_PATH <${SOURCE_PATH}> - [PROJECT_SUBPATH <${SUBPATH}>] - [PROJECT_NAME <${MAKEFILE_NAME}>] - [LOGFILE_ROOT ] - [CL_LANGUAGE ] - [PREFER_JOM] - [PRERUN_SHELL <${SHELL_PATH}>] - [PRERUN_SHELL_DEBUG <${SHELL_PATH}>] - [PRERUN_SHELL_RELEASE <${SHELL_PATH}>] - [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] - [OPTIONS_RELEASE <-DOPTIMIZE=1>...] - [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] - [TARGET ...] - [ENABLE_INSTALL] -) -``` - -## Parameters -### SOURCE_PATH -Specifies the directory containing the source files. -By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. - -### PROJECT_SUBPATH -Specifies the sub directory containing the makefile. - -### PROJECT_NAME -Specifies the name of the makefile. -Default is `makefile.vc` - -### LOGFILE_ROOT -Specifies a log file prefix. - -### CL_LANGUAGE -Specifies the language for setting up flags in the `_CL_` environment variable. -The default language is `CXX`. -To disable the modification of `_CL_`, use `NONE`. - -### PREFER_JOM -Specifies that a parallel build with `jom` should be attempted. -This is useful for faster builds of makefiles which process many independent targets -and which cannot benefit from the `/MP` cl option. -To mitigate issues with concurrency-unaware makefiles, a normal `nmake` build is run after `jom` errors. - -### PRERUN_SHELL -Script that needs to be called before build. - -### PRERUN_SHELL_DEBUG -Script that needs to be called before debug build. - -### PRERUN_SHELL_RELEASE -Script that needs to be called before release build. - -### OPTIONS -Additional options passed to the build command. - -### OPTIONS_RELEASE -Additional options passed to the build command for the release build. These are in addition to `OPTIONS`. - -### OPTIONS_DEBUG -Additional options passed to the build command for the debug build. These are in addition to `OPTIONS`. - -### TARGET -The list of targets passed to the build command. -If not specified, target `all` will be passed. - -### ENABLE_INSTALL -Adds `install` to the list of targets passed to the build command, -and passes the install prefix in the `INSTALLDIR` makefile variable. - -## Notes: -You can use the alias [`vcpkg_install_nmake()`](vcpkg_install_nmake.md) function if your makefile supports the -"install" target. - -## Examples - -* [librttopo](https://github.com/microsoft/vcpkg/blob/master/ports/librttopo/portfile.cmake) -* [openssl](https://github.com/microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_build\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_nmake.cmake) diff --git a/docs/maintainers/vcpkg_build_qmake.md b/docs/maintainers/vcpkg_build_qmake.md deleted file mode 100644 index e452388546..0000000000 --- a/docs/maintainers/vcpkg_build_qmake.md +++ /dev/null @@ -1,12 +0,0 @@ -# vcpkg_build_qmake - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_qmake.md). - -Build a qmake-based project, previously configured using vcpkg_configure_qmake. - -```cmake -vcpkg_build_qmake() -``` - -## Source -[scripts/cmake/vcpkg\_build\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_qmake.cmake) diff --git a/docs/maintainers/vcpkg_buildpath_length_warning.md b/docs/maintainers/vcpkg_buildpath_length_warning.md deleted file mode 100644 index c67dc64656..0000000000 --- a/docs/maintainers/vcpkg_buildpath_length_warning.md +++ /dev/null @@ -1,16 +0,0 @@ -# vcpkg_buildpath_length_warning - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_buildpath_length_warning.md). - -Warns the user if their vcpkg installation path might be too long for the package they're installing. - -```cmake -vcpkg_buildpath_length_warning() -``` - -`vcpkg_buildpath_length_warning` warns the user if the number of bytes in the -path to `buildtrees` is bigger than `N`. Note that this is simply a warning, -and isn't relied on for correctness. - -## Source -[scripts/cmake/vcpkg\_buildpath\_length\_warning.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_buildpath_length_warning.cmake) diff --git a/docs/maintainers/vcpkg_check_features.md b/docs/maintainers/vcpkg_check_features.md deleted file mode 100644 index 4503d19527..0000000000 --- a/docs/maintainers/vcpkg_check_features.md +++ /dev/null @@ -1,136 +0,0 @@ -# vcpkg_check_features - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_check_features.md). -Check if one or more features are a part of a package installation. - -```cmake -vcpkg_check_features( - OUT_FEATURE_OPTIONS - [PREFIX ] - [FEATURES - [ ]... - ] - [INVERTED_FEATURES - [ ]... - ] -) -``` - -The `` should be set to `FEATURE_OPTIONS` by convention. - -`vcpkg_check_features()` will: - -- for each `` passed in `FEATURES`: - - if the feature is set, add `-D=ON` to ``, - and set `_` to ON. - - if the feature is not set, add `-D=OFF` to ``, - and set `_` to OFF. -- for each `` passed in `INVERTED_FEATURES`: - - if the feature is set, add `-D=OFF` to ``, - and set `_` to OFF. - - if the feature is not set, add `-D=ON` to ``, - and set `_` to ON. - -If `` is not passed, then the feature vars set are simply ``, -not `_`. - -If `INVERTED_FEATURES` is not passed, then the `FEATURES` keyword is optional. -This behavior is deprecated. - -If the same `` is passed multiple times, -then `vcpkg_check_features` will cause a fatal error, -since that is a bug. - -## Examples - -### Example 1: Regular features - -```cmake -$ ./vcpkg install mimalloc[asm,secure] - -# ports/mimalloc/portfile.cmake -vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS - FEATURES - asm MI_SEE_ASM - override MI_OVERRIDE - secure MI_SECURE -) - -vcpkg_cmake_configure( - SOURCE_PATH "${SOURCE_PATH}" - OPTIONS - # Expands to "-DMI_SEE_ASM=ON;-DMI_OVERRIDE=OFF;-DMI_SECURE=ON" - ${FEATURE_OPTIONS} -) -``` - -### Example 2: Inverted features - -```cmake -$ ./vcpkg install cpprestsdk[websockets] - -# ports/cpprestsdk/portfile.cmake -vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS - INVERTED_FEATURES - brotli CPPREST_EXCLUDE_BROTLI - websockets CPPREST_EXCLUDE_WEBSOCKETS -) - -vcpkg_cmake_configure( - SOURCE_PATH "${SOURCE_PATH}" - OPTIONS - # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON;-DCPPREST_EXCLUDE_WEBSOCKETS=OFF" - ${FEATURE_OPTIONS} -) -``` - -### Example 3: Set multiple options for same feature - -```cmake -$ ./vcpkg install pcl[cuda] - -# ports/pcl/portfile.cmake -vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS - FEATURES - cuda WITH_CUDA - cuda BUILD_CUDA - cuda BUILD_GPU -) - -vcpkg_cmake_configure( - SOURCE_PATH "${SOURCE_PATH}" - OPTIONS - # Expands to "-DWITH_CUDA=ON;-DBUILD_CUDA=ON;-DBUILD_GPU=ON" - ${FEATURE_OPTIONS} -) -``` - -### Example 4: Use regular and inverted features - -```cmake -$ ./vcpkg install rocksdb[tbb] - -# ports/rocksdb/portfile.cmake -vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS - FEATURES - tbb WITH_TBB - INVERTED_FEATURES - tbb ROCKSDB_IGNORE_PACKAGE_TBB -) - -vcpkg_cmake_configure( - SOURCE_PATH "${SOURCE_PATH}" - OPTIONS - # Expands to "-DWITH_TBB=ON;-DROCKSDB_IGNORE_PACKAGE_TBB=OFF" - ${FEATURE_OPTIONS} -) -``` - -## Examples in portfiles - -* [cpprestsdk](https://github.com/microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) -* [pcl](https://github.com/microsoft/vcpkg/blob/master/ports/pcl/portfile.cmake) -* [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_check\_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake) diff --git a/docs/maintainers/vcpkg_check_linkage.md b/docs/maintainers/vcpkg_check_linkage.md deleted file mode 100644 index 8b73520e0a..0000000000 --- a/docs/maintainers/vcpkg_check_linkage.md +++ /dev/null @@ -1,38 +0,0 @@ -# vcpkg_check_linkage - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_check_linkage.md). - -Asserts the available library and CRT linkage options for the port. - -## Usage -```cmake -vcpkg_check_linkage( - [ONLY_STATIC_LIBRARY | ONLY_DYNAMIC_LIBRARY] - [ONLY_STATIC_CRT | ONLY_DYNAMIC_CRT] -) -``` - -## Parameters -### ONLY_STATIC_LIBRARY -Indicates that this port can only be built with static library linkage. - -Note: If the user requested a dynamic build ONLY_STATIC_LIBRARY will result in a note being printed, not a fatal error. - -### ONLY_DYNAMIC_LIBRARY -Indicates that this port can only be built with dynamic/shared library linkage. - -### ONLY_STATIC_CRT -Indicates that this port can only be built with static CRT linkage. - -### ONLY_DYNAMIC_CRT -Indicates that this port can only be built with dynamic/shared CRT linkage. - -## Notes -This command will either alter the settings for `VCPKG_LIBRARY_LINKAGE` or fail, depending on what was requested by the user versus what the library supports. - -## Examples - -* [abseil](https://github.com/Microsoft/vcpkg/blob/master/ports/abseil/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_check\_linkage.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_linkage.cmake) diff --git a/docs/maintainers/vcpkg_clean_executables_in_bin.md b/docs/maintainers/vcpkg_clean_executables_in_bin.md deleted file mode 100644 index b6df723ade..0000000000 --- a/docs/maintainers/vcpkg_clean_executables_in_bin.md +++ /dev/null @@ -1,25 +0,0 @@ -# vcpkg_clean_executables_in_bin - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_clean_executables_in_bin.md). - -Remove specified executables found in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`. If, after all specified executables have been removed, and the `bin` and `debug/bin` directories are empty, then also delete `bin` and `debug/bin` directories. - -## Usage -```cmake -vcpkg_clean_executables_in_bin( - FILE_NAMES ... -) -``` - -## Parameters -### FILE_NAMES -A list of executable filenames without extension. - -## Notes -Generally, there is no need to call this function manually. Instead, pass an extra `AUTO_CLEAN` argument when calling `vcpkg_copy_tools`. - -## Examples -* [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_clean\_executables\_in\_bin.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_executables_in_bin.cmake) diff --git a/docs/maintainers/vcpkg_clean_msbuild.md b/docs/maintainers/vcpkg_clean_msbuild.md deleted file mode 100644 index 3474076b53..0000000000 --- a/docs/maintainers/vcpkg_clean_msbuild.md +++ /dev/null @@ -1,17 +0,0 @@ -# vcpkg_clean_msbuild - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_clean_msbuild.md). - -Clean intermediate files generated by `vcpkg_install_msbuild()`. - -## Usage -```cmake -vcpkg_clean_msbuild() -``` - -## Examples - -* [python3](https://github.com/Microsoft/vcpkg/blob/master/ports/python3/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_clean\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_msbuild.cmake) diff --git a/docs/maintainers/vcpkg_cmake_build.md b/docs/maintainers/vcpkg_cmake_build.md deleted file mode 100644 index 047290ec16..0000000000 --- a/docs/maintainers/vcpkg_cmake_build.md +++ /dev/null @@ -1,68 +0,0 @@ -# vcpkg_cmake_build - -**The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_cmake_build.md).** - -Build a cmake project with a custom install target. - -Conventionally, CMake uses the target `install` to build and copy binaries into the [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html). In rare circumstances, a project might have more specific targets that should be used instead. - -Ports should prefer calling [`vcpkg_cmake_install()`](vcpkg_cmake_install.md) when possible. - -## Usage - -```cmake -vcpkg_cmake_build( - [TARGET ] - [LOGFILE_BASE ] - [DISABLE_PARALLEL] - [ADD_BIN_TO_PATH] -) -``` - -To use this function, you must depend on the helper port [`vcpkg-cmake`](ports/vcpkg-cmake.md): -```no-highlight -"dependencies": [ - { - "name": "vcpkg-cmake", - "host": true - } -] -``` - -## Parameters - -All supported parameters to [`vcpkg_cmake_install()`] are supported by `vcpkg_cmake_build()`. See [`vcpkg_cmake_install()`] for additional parameter documentation. - -[`vcpkg_cmake_install()`]: vcpkg_cmake_install.md#parameters - -### TARGET -The CMake target to build. - -If this parameter is not passed, no target will be passed to the build. - -### LOGFILE_BASE -An alternate root name for the logs. - -Defaults to `build-${TARGET_TRIPLET}`. It should not contain any path separators. Logs will be generated matching the pattern `${CURRENT_BUILDTREES_DIR}/${LOGFILE_BASE}-.log` - -## Examples - -```cmake -vcpkg_from_github(OUT_SOURCE_PATH source_path ...) -vcpkg_cmake_configure( - SOURCE_PATH "${source_path}" - OPTIONS - -DBUILD_EXAMPLES=OFF - -DBUILD_TESTS=OFF -) -vcpkg_cmake_build(TARGET my.install.target) -``` - -[Search microsoft/vcpkg for Examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_build+path%3A%2Fports) - -## Remarks - -This command replaces [`vcpkg_build_cmake()`](vcpkg_build_cmake.md). - -## Source -[ports/vcpkg-cmake/vcpkg\_cmake\_build.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_build.cmake) diff --git a/docs/maintainers/vcpkg_cmake_configure.md b/docs/maintainers/vcpkg_cmake_configure.md deleted file mode 100644 index c3ef188b61..0000000000 --- a/docs/maintainers/vcpkg_cmake_configure.md +++ /dev/null @@ -1,137 +0,0 @@ -# vcpkg_cmake_configure - -**The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_cmake_configure.md).** - -Configure a CMake-based project. - -## Usage - -```cmake -vcpkg_cmake_configure( - SOURCE_PATH - [DISABLE_PARALLEL_CONFIGURE] - [NO_CHARSET_FLAG] - [WINDOWS_USE_MSBUILD] - [GENERATOR ] - [LOGFILE_BASE ] - [OPTIONS - ...] - [OPTIONS_RELEASE - ...] - [OPTIONS_DEBUG - ...] - [MAYBE_UNUSED_VARIABLES - ...] -) -``` - -To use this function, you must depend on the helper port [`vcpkg-cmake`](ports/vcpkg-cmake.md): -```no-highlight -"dependencies": [ - { - "name": "vcpkg-cmake", - "host": true - } -] -``` - -## Parameters - -### SOURCE_PATH -Specifies the directory containing the `CMakeLists.txt`. - -This value is usually obtained as a result of calling a source acquisition command like [`vcpkg_from_github()`](vcpkg_from_github.md). - -### DISABLE_PARALLEL_CONFIGURE -Disables running the CMake configure step in parallel. - -By default vcpkg disables writing back to the source directory (via the undocumented CMake flag `CMAKE_DISABLE_SOURCE_CHANGES`) and (on Windows) configures Release and Debug in parallel. This flag instructs vcpkg to allow source directory writes and to execute the configure steps sequentially. - -### NO_CHARSET_FLAG -Disables passing `/utf-8` when using the [built-in Windows toolchain][VCPKG_CHAINLOAD_TOOLCHAIN_FILE]. - -This is needed for libraries that set their own source code's character set when targeting MSVC. See the [MSVC documentation for `/utf-8`](https://docs.microsoft.com/cpp/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8) for more information. - -### WINDOWS_USE_MSBUILD -Use MSBuild instead of another generator when targeting a Windows platform. - -By default vcpkg prefers to use Ninja as the CMake Generator for all platforms. However, there are edge cases where MSBuild has different behavior than Ninja. This flag should only be passed if the project requires MSBuild to build correctly. -This flag has no effect for MinGW targets. - -### GENERATOR -Specifies the Generator to use. - -By default vcpkg prefers to use Ninja as the CMake Generator for all platforms, -or "Unix Makefiles" for non-Windows platforms when Ninja is not available. -This parameter can be used for edge cases where project-specific buildsystems depend on a particular generator. - -### LOGFILE_BASE -An alternate root name for the configure logs. - -Defaults to `config-${TARGET_TRIPLET}`. It should not contain any path separators. Logs will be generated matching the pattern `${CURRENT_BUILDTREES_DIR}/${LOGFILE_BASE}-.log` - -### OPTIONS -Additional options to pass to CMake during the configuration. - -See also [Implicit Options](#implicit-options). - -### OPTIONS_RELEASE -Additional options to pass to CMake during the Release configuration. - -These are in addition to `OPTIONS`. - -### OPTIONS_DEBUG -Additional options to pass to CMake during the Debug configuration. - -These are in addition to `OPTIONS`. - -### MAYBE_UNUSED_VARIABLES -List of CMake options that may not be read during the configure step. - -vcpkg will warn about any options outside this list that were not read during the CMake configure step. This list should contain options that are only read during certain configurations (such as when `VCPKG_LIBRARY_LINKAGE` is `"static"` or when certain features are enabled). - -## Implicit Options -This command automatically provides several options to CMake. - -- [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html) is set to `"Release"` or `"Debug"` as appropriate. -- [`BUILD_SHARED_LIBS`](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html) is set according to the value of [`VCPKG_LIBRARY_LINKAGE`](../users/triplets.md#vcpkg_library_linkage). -- [`CMAKE_INSTALL_PREFIX=${CURRENT_PACKAGES_DIR}`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) as appropriate to the configuration -- [`CMAKE_TOOLCHAIN_FILE`](https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html) and `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` are set to include the [vcpkg toolchain file](../users/buildsystems/cmake-integration.md#cmake_toolchain_file) and the [triplet toolchain][VCPKG_CHAINLOAD_TOOLCHAIN_FILE]. -- [`CMAKE_SYSTEM_NAME=${VCPKG_CMAKE_SYSTEM_NAME}`](https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_NAME.html). If `VCPKG_CMAKE_SYSTEM_NAME` is unset, defaults to `"Windows"`. -- [`CMAKE_SYSTEM_VERSION=${VCPKG_CMAKE_SYSTEM_VERSION}`](https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_VERSION.html) if `VCPKG_CMAKE_SYSTEM_VERSION` is set. -- [`CMAKE_EXPORT_NO_PACKAGE_REGISTRY=ON`](https://cmake.org/cmake/help/latest/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.html) -- [`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY=ON`](https://cmake.org/cmake/help/latest/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.html) -- [`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY=ON`](https://cmake.org/cmake/help/latest/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.html) -- [`CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP=TRUE`](https://cmake.org/cmake/help/latest/module/InstallRequiredSystemLibraries.html) -- [`CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION=ON`](https://cmake.org/cmake/help/latest/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.html) -- [`CMAKE_INSTALL_LIBDIR:STRING=lib`](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html) -- [`CMAKE_INSTALL_BINDIR:STRING=bin`](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html) - -This command also passes all options in [`VCPKG_CMAKE_CONFIGURE_OPTIONS`](../users/triplets.md#vcpkg_cmake_configure_options) and the configuration-specific options from `VCPKG_CMAKE_CONFIGURE_OPTIONS_RELEASE` or `VCPKG_CMAKE_CONFIGURE_OPTIONS_DEBUG`. - -Finally, there are additional internal options passed in (with a `VCPKG_` prefix) that should not be depended upon. - -## Examples - -```cmake -vcpkg_from_github(OUT_SOURCE_PATH source_path ...) -vcpkg_cmake_configure( - SOURCE_PATH "${source_path}" - OPTIONS - -DBUILD_EXAMPLES=OFF - -DBUILD_TESTS=OFF -) -vcpkg_cmake_install() -``` - -[Search microsoft/vcpkg for Examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_configure+path%3A%2Fports) - -## Remarks - -This command replaces [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md). - -## Source -[ports/vcpkg-cmake/vcpkg\_cmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_configure.cmake) - -[ninja]: https://ninja-build.org/ -[VCPKG_CHAINLOAD_TOOLCHAIN_FILE]: ../users/triplets.md#VCPKG_CHAINLOAD_TOOLCHAIN_FILE diff --git a/docs/maintainers/vcpkg_cmake_install.md b/docs/maintainers/vcpkg_cmake_install.md deleted file mode 100644 index 5845fecc3f..0000000000 --- a/docs/maintainers/vcpkg_cmake_install.md +++ /dev/null @@ -1,53 +0,0 @@ -# vcpkg_cmake_install - -**The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_cmake_install.md).** - -Build and install a cmake project. - -## Usage - -```cmake -vcpkg_cmake_install( - [DISABLE_PARALLEL] - [ADD_BIN_TO_PATH] -) -``` - -To use this function, you must depend on the helper port [`vcpkg-cmake`](ports/vcpkg-cmake.md): -```no-highlight -"dependencies": [ - { - "name": "vcpkg-cmake", - "host": true - } -] -``` - -## Parameters - -### DISABLE_PARALLEL -Disables running the build in parallel. - -By default builds are run with up to [VCPKG_MAX_CONCURRENCY](../users/config-environment.md#VCPKG_MAX_CONCURRENCY) jobs. This option limits the build to a single job and should be used only if the underlying build is unable to run correctly with concurrency. - -### ADD_BIN_TO_PATH -Adds the configuration-specific `bin/` directory to the `PATH` during the build. - -When building for a Windows dynamic triplet, newly built executables may not be immediately executable because their dependency DLLs may not be findable from the build environment. This flag instructs vcpkg to add any additional paths needed to locate those dependency DLLs to the `PATH` environment variable. This is required if the project needs to execute newly built binaries as part of the build (such as to generate code). - -## Examples: - -```cmake -vcpkg_from_github(OUT_SOURCE_PATH source_path ...) -vcpkg_cmake_configure(SOURCE_PATH "${source_path}") -vcpkg_cmake_install() -``` - -[Search microsoft/vcpkg for Examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_install+path%3A%2Fports) - -## Remarks - -This command replaces [`vcpkg_install_cmake()`](vcpkg_install_cmake.md). - -## Source -[ports/vcpkg-cmake/vcpkg\_cmake\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_install.cmake) diff --git a/docs/maintainers/vcpkg_common_definitions.md b/docs/maintainers/vcpkg_common_definitions.md deleted file mode 100644 index 6818ae14bf..0000000000 --- a/docs/maintainers/vcpkg_common_definitions.md +++ /dev/null @@ -1,38 +0,0 @@ -# vcpkg_common_definitions - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_common_definitions.md). - -This file defines the following variables which are commonly needed or used in portfiles: - -```cmake -PORT The name of the port that is currently being built -VERSION The version of the port that is currently being built -VCPKG_TARGET_IS_ with being one of the following: WINDOWS, UWP, MINGW, LINUX, OSX, ANDROID, FREEBSD, OPENBSD, EMSCRIPTEN. only defined if -VCPKG_HOST_IS_ with being one of the following: WINDOWS, LINUX, OSX, FREEBSD, OPENBSD. only defined if -VCPKG_HOST_PATH_SEPARATOR Host specific path separator (USAGE: "${VCPKG_HOST_PATH_SEPARATOR}"; only use and pass variables with VCPKG_HOST_PATH_SEPARATOR within "") -VCPKG_HOST_EXECUTABLE_SUFFIX executable suffix of the host -VCPKG_TARGET_EXECUTABLE_SUFFIX executable suffix of the target -VCPKG_HOST_BUNDLE_SUFFIX bundle suffix of the host -VCPKG_TARGET_BUNDLE_SUFFIX bundle suffix of the target -VCPKG_TARGET_STATIC_LIBRARY_PREFIX static library prefix for target (same as CMAKE_STATIC_LIBRARY_PREFIX) -VCPKG_TARGET_STATIC_LIBRARY_SUFFIX static library suffix for target (same as CMAKE_STATIC_LIBRARY_SUFFIX) -VCPKG_TARGET_SHARED_LIBRARY_PREFIX shared library prefix for target (same as CMAKE_SHARED_LIBRARY_PREFIX) -VCPKG_TARGET_SHARED_LIBRARY_SUFFIX shared library suffix for target (same as CMAKE_SHARED_LIBRARY_SUFFIX) -VCPKG_TARGET_IMPORT_LIBRARY_PREFIX import library prefix for target (same as CMAKE_IMPORT_LIBRARY_PREFIX) -VCPKG_TARGET_IMPORT_LIBRARY_SUFFIX import library suffix for target (same as CMAKE_IMPORT_LIBRARY_SUFFIX) -VCPKG_FIND_LIBRARY_PREFIXES target dependent prefixes used for find_library calls in portfiles -VCPKG_FIND_LIBRARY_SUFFIXES target dependent suffixes used for find_library calls in portfiles -VCPKG_SYSTEM_LIBRARIES list of libraries are provide by the toolchain and are not managed by vcpkg -TARGET_TRIPLET the name of the current triplet to build for -CURRENT_INSTALLED_DIR the absolute path to the installed files for the current triplet -HOST_TRIPLET the name of the triplet corresponding to the host -CURRENT_HOST_INSTALLED_DIR the absolute path to the installed files for the host triplet -VCPKG_CROSSCOMPILING Whether vcpkg is cross-compiling: in other words, whether TARGET_TRIPLET and HOST_TRIPLET are different -``` - -CMAKE_STATIC_LIBRARY_(PREFIX|SUFFIX), CMAKE_SHARED_LIBRARY_(PREFIX|SUFFIX) and CMAKE_IMPORT_LIBRARY_(PREFIX|SUFFIX) are defined for the target -Furthermore the variables CMAKE_FIND_LIBRARY_(PREFIXES|SUFFIXES) are also defined for the target so that -portfiles are able to use find_library calls to discover dependent libraries within the current triplet for ports. - -## Source -[scripts/cmake/vcpkg\_common\_definitions.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_common_definitions.cmake) diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md deleted file mode 100644 index 5a5d02429b..0000000000 --- a/docs/maintainers/vcpkg_configure_cmake.md +++ /dev/null @@ -1,87 +0,0 @@ -# vcpkg_configure_cmake - -**This function has been deprecated in favor of [`vcpkg_cmake_configure`](vcpkg_cmake_configure.md) from the [`vcpkg-cmake`](ports/vcpkg-cmake.md) port.** - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_cmake.md). - -Configure CMake for Debug and Release builds of a project. - -## Usage -```cmake -vcpkg_configure_cmake( - SOURCE_PATH <${SOURCE_PATH}> - [PREFER_NINJA] - [DISABLE_PARALLEL_CONFIGURE] - [NO_CHARSET_FLAG] - [GENERATOR <"NMake Makefiles">] - [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] - [OPTIONS_RELEASE <-DOPTIMIZE=1>...] - [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] - [MAYBE_UNUSED_VARIABLES ...] -) -``` - -## Parameters -### SOURCE_PATH -Specifies the directory containing the `CMakeLists.txt`. -By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. - -### PREFER_NINJA -Indicates that, when available, Vcpkg should use Ninja to perform the build. -This should be specified unless the port is known to not work under Ninja. - -### DISABLE_PARALLEL_CONFIGURE -Disables running the CMake configure step in parallel. -This is needed for libraries which write back into their source directory during configure. - -This also disables CMAKE_DISABLE_SOURCE_CHANGES. - -### NO_CHARSET_FLAG -Disables passing `utf-8` as the default character set to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`. - -This is needed for libraries that set their own source code's character set. - -### GENERATOR -Specifies the precise generator to use. - -This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build. -If used for this purpose, it should be set to `"NMake Makefiles"`. - -### OPTIONS -Additional options passed to CMake during the configuration. - -### OPTIONS_RELEASE -Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`. - -### OPTIONS_DEBUG -Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`. - -### MAYBE_UNUSED_VARIABLES -Any CMake variables which are explicitly passed in, but which may not be used on all platforms. -For example: -```cmake -vcpkg_cmake_configure( - ... - OPTIONS - -DBUILD_EXAMPLE=OFF - ... - MAYBE_UNUSED_VARIABLES - BUILD_EXAMPLE -) -``` - -### LOGNAME -Name of the log to write the output of the configure call to. - -## Notes -This command supplies many common arguments to CMake. To see the full list, examine the source. - -## Examples - -* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) -* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) -* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake) -* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_configure\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_cmake.cmake) diff --git a/docs/maintainers/vcpkg_configure_gn.md b/docs/maintainers/vcpkg_configure_gn.md deleted file mode 100644 index cb300327c2..0000000000 --- a/docs/maintainers/vcpkg_configure_gn.md +++ /dev/null @@ -1,34 +0,0 @@ -# vcpkg_configure_gn - -**This function has been deprecated in favor of [`vcpkg_gn_configure`](ports/vcpkg-gn/vcpkg_gn_configure.md) from the vcpkg-gn port.** - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_gn.md). - -Generate Ninja (GN) targets - -## Usage: -```cmake -vcpkg_configure_gn( - SOURCE_PATH - [OPTIONS ] - [OPTIONS_DEBUG ] - [OPTIONS_RELEASE ] -) -``` - -## Parameters: -### SOURCE_PATH (required) -The path to the GN project. - -### OPTIONS -Options to be passed to both the debug and release targets. -Note: Must be provided as a space-separated string. - -### OPTIONS_DEBUG (space-separated string) -Options to be passed to the debug target. - -### OPTIONS_RELEASE (space-separated string) -Options to be passed to the release target. - -## Source -[scripts/cmake/vcpkg\_configure\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_gn.cmake) diff --git a/docs/maintainers/vcpkg_configure_make.md b/docs/maintainers/vcpkg_configure_make.md deleted file mode 100644 index da9346e23b..0000000000 --- a/docs/maintainers/vcpkg_configure_make.md +++ /dev/null @@ -1,97 +0,0 @@ -# vcpkg_configure_make - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_make.md). - -Configure configure for Debug and Release builds of a project. - -## Usage -```cmake -vcpkg_configure_make( - SOURCE_PATH <${SOURCE_PATH}> - [AUTOCONFIG] - [USE_WRAPPERS] [NO_WRAPPERS] - [DETERMINE_BUILD_TRIPLET] - [BUILD_TRIPLET "--host=x64 --build=i686-unknown-pc"] - [NO_ADDITIONAL_PATHS] - [CONFIG_DEPENDENT_ENVIRONMENT ...] - [CONFIGURE_ENVIRONMENT_VARIABLES ...] - [ADD_BIN_TO_PATH] - [DISABLE_VERBOSE_FLAGS] - [NO_DEBUG] - [SKIP_CONFIGURE] - [PROJECT_SUBPATH <${PROJ_SUBPATH}>] - [PRERUN_SHELL <${SHELL_PATH}>] - [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] - [OPTIONS_RELEASE <-DOPTIMIZE=1>...] - [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] -) -``` - -## Parameters -### SOURCE_PATH -Specifies the directory containing the `configure`/`configure.ac`. -By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. - -### PROJECT_SUBPATH -Specifies the directory containing the ``configure`/`configure.ac`. -By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. - -### SKIP_CONFIGURE -Skip configure process - -### USE_WRAPPERS -Use autotools ar-lib and compile wrappers (only applies to windows cl and lib) - -### NO_WRAPPERS -Deactivate the use of autotools ar-lib and compile wrappers (only applies to windows cl and lib) - -### BUILD_TRIPLET -Used to pass custom --build/--target/--host to configure. Can be globally overwritten by VCPKG_MAKE_BUILD_TRIPLET - -### DETERMINE_BUILD_TRIPLET -For ports having a configure script following the autotools rules for selecting the triplet - -### NO_ADDITIONAL_PATHS -Don't pass any additional paths except for --prefix to the configure call - -### AUTOCONFIG -Need to use autoconfig to generate configure file. - -### PRERUN_SHELL -Script that needs to be called before configuration (do not use for batch files which simply call autoconf or configure) - -### ADD_BIN_TO_PATH -Adds the appropriate Release and Debug `bin\` directories to the path during configure such that executables can run against the in-tree DLLs. - -### DISABLE_VERBOSE_FLAGS -Do not pass '--disable-silent-rules --verbose' to configure. - -### OPTIONS -Additional options passed to configure during the configuration. - -### OPTIONS_RELEASE -Additional options passed to configure during the Release configuration. These are in addition to `OPTIONS`. - -### OPTIONS_DEBUG -Additional options passed to configure during the Debug configuration. These are in addition to `OPTIONS`. - -### CONFIG_DEPENDENT_ENVIRONMENT -List of additional configuration dependent environment variables to set. -Pass SOMEVAR to set the environment and have SOMEVAR_(DEBUG|RELEASE) set in the portfile to the appropriate values -General environment variables can be set from within the portfile itself. - -### CONFIGURE_ENVIRONMENT_VARIABLES -List of additional environment variables to pass via the configure call. - -## Notes -This command supplies many common arguments to configure. To see the full list, examine the source. - -## Examples - -* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake) -* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake) -* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake) -* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_configure\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake) diff --git a/docs/maintainers/vcpkg_configure_meson.md b/docs/maintainers/vcpkg_configure_meson.md deleted file mode 100644 index ae8a07d87d..0000000000 --- a/docs/maintainers/vcpkg_configure_meson.md +++ /dev/null @@ -1,44 +0,0 @@ -# vcpkg_configure_meson - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_meson.md). - -Configure Meson for Debug and Release builds of a project. - -## Usage -```cmake -vcpkg_configure_meson( - SOURCE_PATH <${SOURCE_PATH}> - [NO_PKG_CONFIG] - [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] - [OPTIONS_RELEASE <-DOPTIMIZE=1>...] - [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] -) -``` - -## Parameters -### SOURCE_PATH -Specifies the directory containing the `meson.build`. -By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. - -### OPTIONS -Additional options passed to Meson during the configuration. - -### OPTIONS_RELEASE -Additional options passed to Meson during the Release configuration. These are in addition to `OPTIONS`. - -### OPTIONS_DEBUG -Additional options passed to Meson during the Debug configuration. These are in addition to `OPTIONS`. - -### NO_PKG_CONFIG -Disable pkg-config setup - -## Notes -This command supplies many common arguments to Meson. To see the full list, examine the source. - -## Examples - -* [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake) -* [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_configure\_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_meson.cmake) diff --git a/docs/maintainers/vcpkg_configure_qmake.md b/docs/maintainers/vcpkg_configure_qmake.md deleted file mode 100644 index 6b980b3c0f..0000000000 --- a/docs/maintainers/vcpkg_configure_qmake.md +++ /dev/null @@ -1,29 +0,0 @@ -# vcpkg_configure_qmake - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_qmake.md). - -Configure a qmake-based project. - -```cmake -vcpkg_configure_qmake( - SOURCE_PATH - [OPTIONS arg1 [arg2 ...]] - [OPTIONS_RELEASE arg1 [arg2 ...]] - [OPTIONS_DEBUG arg1 [arg2 ...]] - [BUILD_OPTIONS arg1 [arg2 ...]] - [BUILD_OPTIONS_RELEASE arg1 [arg2 ...]] - [BUILD_OPTIONS_DEBUG arg1 [arg2 ...]] -) -``` - -### SOURCE_PATH -The path to the *.pro qmake project file. - -### OPTIONS, OPTIONS\_RELEASE, OPTIONS\_DEBUG -The options passed to qmake to the configure step. - -### BUILD\_OPTIONS, BUILD\_OPTIONS\_RELEASE, BUILD\_OPTIONS\_DEBUG -The options passed to qmake to the build step. - -## Source -[scripts/cmake/vcpkg\_configure\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_qmake.cmake) diff --git a/docs/maintainers/vcpkg_copy_pdbs.md b/docs/maintainers/vcpkg_copy_pdbs.md deleted file mode 100644 index 9c379d2259..0000000000 --- a/docs/maintainers/vcpkg_copy_pdbs.md +++ /dev/null @@ -1,29 +0,0 @@ -# vcpkg_copy_pdbs - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_copy_pdbs.md). - -Automatically locate pdbs in the build tree and copy them adjacent to all DLLs. - -```cmake -vcpkg_copy_pdbs( - [BUILD_PATHS ...]) -``` - -The ``s are patterns which will be passed to `file(GLOB_RECURSE)`, -for locating DLLs. It defaults to using: - -- `${CURRENT_PACKAGES_DIR}/bin/*.dll` -- `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll` - -since that is generally where DLLs are located. - -## Notes -This command should always be called by portfiles after they have finished rearranging the binary output. - -## Examples - -* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) -* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_copy\_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake) diff --git a/docs/maintainers/vcpkg_copy_tool_dependencies.md b/docs/maintainers/vcpkg_copy_tool_dependencies.md deleted file mode 100644 index d34fa5d602..0000000000 --- a/docs/maintainers/vcpkg_copy_tool_dependencies.md +++ /dev/null @@ -1,23 +0,0 @@ -# vcpkg_copy_tool_dependencies - -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). - -Copy all DLL dependencies of built tools into the tool folder. - -## Usage -```cmake -vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>) -``` -## Parameters -The path to the directory containing the tools. - -## Notes -This command should always be called by portfiles after they have finished rearranging the binary output, if they have any tools. - -## Examples - -* [glib](https://github.com/Microsoft/vcpkg/blob/master/ports/glib/portfile.cmake) -* [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_copy\_tool\_dependencies.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tool_dependencies.cmake) diff --git a/docs/maintainers/vcpkg_copy_tools.md b/docs/maintainers/vcpkg_copy_tools.md deleted file mode 100644 index e5a950bde3..0000000000 --- a/docs/maintainers/vcpkg_copy_tools.md +++ /dev/null @@ -1,36 +0,0 @@ -# vcpkg_copy_tools - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_copy_tools.md). - -Copy tools and all their DLL dependencies into the `tools` folder. - -## Usage -```cmake -vcpkg_copy_tools( - TOOL_NAMES ... - [SEARCH_DIR <${CURRENT_PACKAGES_DIR}/bin>] - [DESTINATION <${CURRENT_PACKAGES_DIR}/tools/${PORT}>] - [AUTO_CLEAN] -) -``` -## Parameters -### TOOL_NAMES -A list of tool filenames without extension. - -### SEARCH_DIR -The path to the directory containing the tools. This will be set to `${CURRENT_PACKAGES_DIR}/bin` if omitted. - -### DESTINATION -Destination to copy the tools to. This will be set to `${CURRENT_PACKAGES_DIR}/tools/${PORT}` if omitted. - -### AUTO_CLEAN -Auto clean the copied executables from `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`. - -## Examples - -* [cpuinfo](https://github.com/microsoft/vcpkg/blob/master/ports/cpuinfo/portfile.cmake) -* [nanomsg](https://github.com/microsoft/vcpkg/blob/master/ports/nanomsg/portfile.cmake) -* [uriparser](https://github.com/microsoft/vcpkg/blob/master/ports/uriparser/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_copy\_tools.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tools.cmake) diff --git a/docs/maintainers/vcpkg_download_distfile.md b/docs/maintainers/vcpkg_download_distfile.md deleted file mode 100644 index 62fde14553..0000000000 --- a/docs/maintainers/vcpkg_download_distfile.md +++ /dev/null @@ -1,62 +0,0 @@ -# vcpkg_download_distfile - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_download_distfile.md). - -Download and cache a file needed for this port. - -This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command. - -## Usage -```cmake -vcpkg_download_distfile( - - URLS ... - FILENAME - SHA512 <5981de...> - [ALWAYS_REDOWNLOAD] -) -``` -## Parameters -### OUT_VARIABLE -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. - -### URLS -A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given. - -### FILENAME -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. - -### SHA512 -The expected hash for the file. - -If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch. - -### QUIET -Suppress output on cache hit - -### SKIP_SHA512 -Skip SHA512 hash check for file. - -This switch is only valid when building with the `--head` command line flag. - -### ALWAYS_REDOWNLOAD -Avoid caching; this is a REST call or otherwise unstable. - -Requires `SKIP_SHA512`. - -### HEADERS -A list of headers to append to the download request. This can be used for authentication during a download. - -Headers should be specified as ": ". - -## Notes -The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects. - -## Examples - -* [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake) -* [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake) -* [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_download\_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake) diff --git a/docs/maintainers/vcpkg_execute_build_process.md b/docs/maintainers/vcpkg_execute_build_process.md deleted file mode 100644 index 7eb6f8d46f..0000000000 --- a/docs/maintainers/vcpkg_execute_build_process.md +++ /dev/null @@ -1,38 +0,0 @@ -# vcpkg_execute_build_process - -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). - -Execute a required build process - -## Usage -```cmake -vcpkg_execute_build_process( - COMMAND [...] - [NO_PARALLEL_COMMAND [...]] - WORKING_DIRECTORY - LOGNAME -) -``` -## Parameters -### COMMAND -The command to be executed, along with its arguments. - -### NO_PARALLEL_COMMAND -Optional parameter which specifies a non-parallel command to attempt if a -failure potentially due to parallelism is detected. - -### WORKING_DIRECTORY -The directory to execute the command in. - -### LOGNAME -The prefix to use for the log files. - -This should be a unique name for different triplets so that the logs don't -conflict when building multiple at once. - -## Examples - -* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_execute\_build\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake) diff --git a/docs/maintainers/vcpkg_execute_in_download_mode.md b/docs/maintainers/vcpkg_execute_in_download_mode.md deleted file mode 100644 index a9fb5bffb8..0000000000 --- a/docs/maintainers/vcpkg_execute_in_download_mode.md +++ /dev/null @@ -1,21 +0,0 @@ -# vcpkg_execute_in_download_mode - -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). - -Execute a process even in download mode. - -## Usage -```cmake -vcpkg_execute_in_download_mode( - ... -) -``` - -The signature of this function is identical to `execute_process()`. - -See [`execute_process()`] for more details. - -[`execute_process()`]: https://cmake.org/cmake/help/latest/command/execute_process.html - -## Source -[scripts/cmake/vcpkg\_execute\_in\_download\_mode.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_in_download_mode.cmake) diff --git a/docs/maintainers/vcpkg_execute_required_process.md b/docs/maintainers/vcpkg_execute_required_process.md deleted file mode 100644 index ee4390eeae..0000000000 --- a/docs/maintainers/vcpkg_execute_required_process.md +++ /dev/null @@ -1,62 +0,0 @@ -# vcpkg_execute_required_process - -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). - -Execute a process with logging and fail the build if the command fails. - -## Usage -```cmake -vcpkg_execute_required_process( - COMMAND <${PERL}> [...] - WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg> - LOGNAME - [TIMEOUT ] - [OUTPUT_VARIABLE ] - [ERROR_VARIABLE ] - [SAVE_LOG_FILES [ALIAS ] [...]] -) -``` -## Parameters -### ALLOW_IN_DOWNLOAD_MODE -Allows the command to execute in Download Mode. -[See execute_process() override](../../scripts/cmake/execute_process.cmake). - -### COMMAND -The command to be executed, along with its arguments. - -### WORKING_DIRECTORY -The directory to execute the command in. - -### LOGNAME -The prefix to use for the log files. - -### TIMEOUT -Optional timeout after which to terminate the command. - -### OUTPUT_VARIABLE -Optional variable to receive stdout of the command. - -### ERROR_VARIABLE -Optional variable to receive stderr of the command. - -This should be a unique name for different triplets so that the logs don't conflict when building multiple at once. - -### SAVE_LOG_FILES - -Optional files to be moved from the working directory to `${CURRENT_BUILDTREES_DIR}`. -The files are copied even if the process failed. -This helps to collect relevant log files in CI setups. - -The target filename is constructed from the `LOGNAME` parameter and the parameter of the `ALIAS` keyword following the source path. -If `ALIAS` is absent, the target filename is constructed from the `LOGNAME` parameter, the source filename, -and the suffix `.log` if the source filename doesn't already end with this suffix. - -## Examples - -* [boost-build](https://github.com/Microsoft/vcpkg/blob/master/ports/boost-build/portfile.cmake) -* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake) -* [qt5-base](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5-base/cmake/configure_qt.cmake) -* [vcpkg-cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_configure.cmake) - -## Source -[scripts/cmake/vcpkg\_execute\_required\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake) diff --git a/docs/maintainers/vcpkg_execute_required_process_repeat.md b/docs/maintainers/vcpkg_execute_required_process_repeat.md deleted file mode 100644 index 22dcfc4afb..0000000000 --- a/docs/maintainers/vcpkg_execute_required_process_repeat.md +++ /dev/null @@ -1,19 +0,0 @@ -# vcpkg_execute_required_process_repeat - -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). - -Execute a process until the command succeeds, or until the COUNT is reached. - -## Usage -```cmake -vcpkg_execute_required_process_repeat( - COMMAND [] - COUNT - WORKING_DIRECTORY - LOGNAME - [ALLOW_IN_DOWNLOAD_MODE] -) -``` - -## Source -[scripts/cmake/vcpkg\_execute\_required\_process\_repeat.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process_repeat.cmake) diff --git a/docs/maintainers/vcpkg_extract_source_archive.md b/docs/maintainers/vcpkg_extract_source_archive.md deleted file mode 100644 index f800570351..0000000000 --- a/docs/maintainers/vcpkg_extract_source_archive.md +++ /dev/null @@ -1,154 +0,0 @@ -# vcpkg_extract_source_archive - -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). - -Extract an archive. - -## Usage -```cmake -vcpkg_extract_source_archive( - - ARCHIVE - [NO_REMOVE_ONE_LEVEL] - [SKIP_PATCH_CHECK] - [PATCHES ...] - [SOURCE_BASE ] - [BASE_DIRECTORY | WORKING_DIRECTORY ] -) -``` - -## Parameters - - - -### `` - -Name of the variable to set with the directory containing the extracted contents. - -### ARCHIVE - -Full path to the archive to extract. - -### NO_REMOVE_ONE_LEVEL - -Skip removing the top level directory of the archive. - -Most archives contain a single top-level directory, such as: - -``` -zlib-1.2.11/ - doc/ - ... - examples/ - ... - ChangeLog - CMakeLists.txt - README - zlib.h - ... -``` - -By default, `vcpkg_extract_source_archive` removes this directory and moves all contents into the directory returned in ``. If there is no top-level directory, it is an error. - -With this flag, the top-level directory will be preserved and it is not an error to not have one. - -### SKIP_PATCH_CHECK - -Silence and ignore errors when applying patches. - -This option should only be passed when operating in an unstable mode like `--head`. If the sources are pinned, failing to apply a patch should be considered a fatal error. - -### PATCHES - -List of patches to apply to the extracted source. - -Patches will be applied in order, after any top-level directories are removed (see [`NO_REMOVE_ONE_LEVEL`](#no_remove_one_level)). Relative paths are interpreted relative to the current port directory. - -If a patch should be conditionally applied based on target information, you can construct a list and splat it. - -```cmake -set(patches "") -if(VCPKG_TARGET_IS_WINDOWS) - list(APPEND patches only-windows.patch) -endif() -vcpkg_extract_source_archive(src - ARCHIVE "${archive}" - PATCHES - always-applied.patch - ${patches} -) -``` - -### SOURCE_BASE - -Pretty name for the extracted directory. - -Must not contain path separators (`/` or `\\`). - -See [`WORKING_DIRECTORY`](#working_directory) for more details. - -### BASE_DIRECTORY - -Root subfolder for the extracted directory. - -Defaults to `src`. Must be a relative path. - -See [`WORKING_DIRECTORY`](#working_directory) for more details. - -### WORKING_DIRECTORY - -Root folder for the extracted directory. - -Defaults to `${CURRENT_BUILDTREES_DIR}/`. Must be an absolute path. - -`vcpkg_extract_source_archive` extracts the archive into `/-.clean`. If the folder exists, it is deleted before extraction. Without specifying `SOURCE_BASE`, `BASE_DIRECTORY`, or `WORKING_DIRECTORY`, this will default to `${CURRENT_BUILDTREES_DIR}/src/-.clean`. - -In [`--editable`](../commands/install.md#editable) mode: -1. No `.clean` suffix is added to the extracted folder -2. The extracted folder is not deleted. If it exists, `vcpkg_extract_source_archive` does nothing. - -`` unambiguously identifies a particular set of archive and patch file contents. -Any modifications to the contents of the working directory after calling this function should be applied unconditionally -in order to avoid unexpected behavior in editable mode. - -## Examples - -```cmake -vcpkg_download_distfile( - archive # "archive" is set to the path to the downloaded file - URLS "https://nmap.org/dist/nmap-7.70.tar.bz2" - FILENAME "nmap-7.70.tar.bz2" - SHA512 084c148b022ff6550e269d976d0077f7932a10e2ef218236fe13aa3a70b4eb6506df03329868fc68cb3ce78e4360b200f5a7a491d3145028fed679ef1c9ecae5 -) -vcpkg_extract_source_archive( - src # "src" is set to the path to the extracted files - ARCHIVE "${archive}" - SOURCE_BASE nmap.org-nmap-7.70 - PATCHES - 0001-disable-werror.patch -) -vcpkg_cmake_configure(SOURCE_PATH "${src}") -``` - -* [GitHub Search](https://github.com/microsoft/vcpkg/search?q=vcpkg_extract_source_archive+path%3A%2Fports) - -## Remarks - -**Deprecated Syntax** - -This command also supports a deprecated overload: - -```cmake -vcpkg_extract_source_archive( []) -``` - -The deprecated overload extracts `` into `${working_directory}/.extracted` if the target does not exist. This incorrect behavior allows patches and other modifications to leak between different builds, resulting in hard-to-debug errors. - -All uses of the deprecated overload should be replaced with the syntax in [Usage](#usage) above by adding an explicit [`ARCHIVE`](#archive) parameter and replacing direct references to the extracted path with uses of the [``](#out-var). - -**Replacement** - -This command replaces [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md). - -## Source -[scripts/cmake/vcpkg\_extract\_source\_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake) diff --git a/docs/maintainers/vcpkg_extract_source_archive_ex.md b/docs/maintainers/vcpkg_extract_source_archive_ex.md deleted file mode 100644 index b6f685393b..0000000000 --- a/docs/maintainers/vcpkg_extract_source_archive_ex.md +++ /dev/null @@ -1,22 +0,0 @@ -# vcpkg_extract_source_archive_ex - -**This function has been deprecated in favor of [`vcpkg_extract_source_archive()`].** - -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). - -Extract an archive. - -## Usage -```cmake -vcpkg_extract_source_archive_ex( - [OUT_SOURCE_PATH ] - [...] -) -``` - -This command forwards all options to [`vcpkg_extract_source_archive()`], with `` as the first argument. Equivalent to `vcpkg_extract_source_archive( ...)`. See the documentation for [`vcpkg_extract_source_archive()`] for parameter help. - -[`vcpkg_extract_source_archive()`]: vcpkg_extract_source_archive.md - -## Source -[scripts/cmake/vcpkg\_extract\_source\_archive\_ex.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake) diff --git a/docs/maintainers/vcpkg_fail_port_install.md b/docs/maintainers/vcpkg_fail_port_install.md deleted file mode 100644 index 1d59fd8c18..0000000000 --- a/docs/maintainers/vcpkg_fail_port_install.md +++ /dev/null @@ -1,45 +0,0 @@ -# vcpkg_fail_port_install - -**This function has been deprecated in favor of the `supports` field in [`manifest file`](manifest-files.md#supports) et al.** - -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). - -Checks common requirements and fails the current portfile with a (default) error message - -## Usage -```cmake -vcpkg_fail_port_install( - [ALWAYS] - [MESSAGE <"Reason for failure">] - [ON_TARGET [ ...]] - [ON_ARCH [ ...]] - [ON_CRT_LINKAGE [ ...]]) - [ON_LIBRARY_LINKAGE [ ...]] -) -``` - -## Parameters -### MESSAGE -Additional failure message. If none is given, a default message will be displayed depending on the failure condition. - -### ALWAYS -Will always fail early - -### ON_TARGET -Targets for which the build should fail early. Valid targets are `` from `VCPKG_IS_TARGET_` (see `vcpkg_common_definitions.cmake`). - -### ON_ARCH -Architecture for which the build should fail early. - -### ON_CRT_LINKAGE -CRT linkage for which the build should fail early. - -### ON_LIBRARY_LINKAGE -Library linkage for which the build should fail early. - -## Examples - -* [aws-lambda-cpp](https://github.com/Microsoft/vcpkg/blob/master/ports/aws-lambda-cpp/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_fail\_port\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake) diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md deleted file mode 100644 index 1e8a9b8bb8..0000000000 --- a/docs/maintainers/vcpkg_find_acquire_program.md +++ /dev/null @@ -1,51 +0,0 @@ -# vcpkg_find_acquire_program - -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). - -Download or find a well-known tool. - -## Usage -```cmake -vcpkg_find_acquire_program() -``` -## Parameters -### program -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. - -## Notes -The current list of programs includes: - -* 7Z -* ARIA2 (Downloader) -* BISON -* CLANG -* DARK -* DOXYGEN -* FLEX -* GASPREPROCESSOR -* GPERF -* PERL -* PYTHON2 -* PYTHON3 -* GIT -* GN -* GO -* JOM -* MESON -* NASM -* NINJA -* NUGET -* SCONS -* SWIG -* YASM - -Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md). - -## Examples - -* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake) -* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake) -* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_find\_acquire\_program.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_acquire_program.cmake) diff --git a/docs/maintainers/vcpkg_find_fortran.md b/docs/maintainers/vcpkg_find_fortran.md deleted file mode 100644 index b02c0c51b6..0000000000 --- a/docs/maintainers/vcpkg_find_fortran.md +++ /dev/null @@ -1,25 +0,0 @@ -# vcpkg_find_fortran - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_find_fortran.md). - -Checks if a Fortran compiler can be found. -Windows(x86/x64) Only: If not it will switch/enable MinGW gfortran - and return required cmake args for building. - -## Usage -```cmake -vcpkg_find_fortran() -``` - -## Example -```cmake -vcpkg_find_fortran(fortran_args) -# ... -vcpkg_cmake_configure(... - OPTIONS - ${fortran_args} -) -``` - -## Source -[scripts/cmake/vcpkg\_find\_fortran.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_fortran.cmake) diff --git a/docs/maintainers/vcpkg_fixup_cmake_targets.md b/docs/maintainers/vcpkg_fixup_cmake_targets.md deleted file mode 100644 index b9ca9c4d7d..0000000000 --- a/docs/maintainers/vcpkg_fixup_cmake_targets.md +++ /dev/null @@ -1,62 +0,0 @@ -# vcpkg_fixup_cmake_targets - -**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.** - -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). - -Merge release and debug CMake targets and configs to support multiconfig generators. - -Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries. - -## Usage -```cmake -vcpkg_fixup_cmake_targets([CONFIG_PATH ] - [TARGET_PATH ] - [TOOLS_PATH ] - [DO_NOT_DELETE_PARENT_CONFIG_PATH]) -``` - -## Parameters - -### CONFIG_PATH -Subpath currently containing `*.cmake` files subdirectory (like `lib/cmake/${PORT}`). Should be relative to `${CURRENT_PACKAGES_DIR}`. - -Defaults to `share/${PORT}`. - -### TARGET_PATH -Subpath to which the above `*.cmake` files should be moved. Should be relative to `${CURRENT_PACKAGES_DIR}`. -This needs to be specified if the port name differs from the `find_package()` name. - -Defaults to `share/${PORT}`. - -### DO_NOT_DELETE_PARENT_CONFIG_PATH -By default the parent directory of CONFIG_PATH is removed if it is named "cmake". -Passing this option disable such behavior, as it is convenient for ports that install -more than one CMake package configuration file. - -### NO_PREFIX_CORRECTION -Disables the correction of_IMPORT_PREFIX done by vcpkg due to moving the targets. -Currently the correction does not take into account how the files are moved and applies -I rather simply correction which in some cases will yield the wrong results. - -### TOOLS_PATH -Define the base path to tools. Default: `tools/` - -## Notes -Transform all `/debug//*targets-debug.cmake` files and move them to `/`. -Removes all `/debug//*targets.cmake` and `/debug//*config.cmake`. - -Transform all references matching `/bin/*.exe` to `/${TOOLS_PATH}/*.exe` on Windows. -Transform all references matching `/bin/*` to `/${TOOLS_PATH}/*` on other platforms. - -Fix `${_IMPORT_PREFIX}` in auto generated targets to be one folder deeper. -Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targets. - -## Examples - -* [concurrentqueue](https://github.com/Microsoft/vcpkg/blob/master/ports/concurrentqueue/portfile.cmake) -* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake) -* [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_fixup\_cmake\_targets.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake) diff --git a/docs/maintainers/vcpkg_fixup_pkgconfig.md b/docs/maintainers/vcpkg_fixup_pkgconfig.md deleted file mode 100644 index e94453d729..0000000000 --- a/docs/maintainers/vcpkg_fixup_pkgconfig.md +++ /dev/null @@ -1,49 +0,0 @@ -# vcpkg_fixup_pkgconfig - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_fixup_pkgconfig.md). - -Fix common paths in *.pc files and make everything relative to $(prefix). -Additionally, on static triplets, private entries are merged with their non-private counterparts, -allowing pkg-config to be called without the ``--static`` flag. -Note that vcpkg is designed to never have to call pkg-config with the ``--static`` flag, -since a consumer cannot know if a dependent library has been built statically or not. - -## Usage -```cmake -vcpkg_fixup_pkgconfig( - [RELEASE_FILES ...] - [DEBUG_FILES ...] - [SKIP_CHECK] -) -``` - -## Parameters -### RELEASE_FILES -Specifies a list of files to apply the fixes for release paths. -Defaults to every *.pc file in the folder ${CURRENT_PACKAGES_DIR} without ${CURRENT_PACKAGES_DIR}/debug/ - -### DEBUG_FILES -Specifies a list of files to apply the fixes for debug paths. -Defaults to every *.pc file in the folder ${CURRENT_PACKAGES_DIR}/debug/ - -### SKIP_CHECK -Skips the library checks in vcpkg_fixup_pkgconfig. Only use if the script itself has unhandled cases. - -### SYSTEM_PACKAGES (deprecated) -This argument has been deprecated and has no effect. - -### SYSTEM_LIBRARIES (deprecated) -This argument has been deprecated and has no effect. - -### IGNORE_FLAGS (deprecated) -This argument has been deprecated and has no effect. - -## Notes -Still work in progress. If there are more cases which can be handled here feel free to add them - -## Examples - -* [brotli](https://github.com/Microsoft/vcpkg/blob/master/ports/brotli/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_fixup\_pkgconfig.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_pkgconfig.cmake) diff --git a/docs/maintainers/vcpkg_from_bitbucket.md b/docs/maintainers/vcpkg_from_bitbucket.md deleted file mode 100644 index 944d7769c9..0000000000 --- a/docs/maintainers/vcpkg_from_bitbucket.md +++ /dev/null @@ -1,60 +0,0 @@ -# vcpkg_from_bitbucket - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_bitbucket.md). - -Download and extract a project from Bitbucket. - -## Usage: -```cmake -vcpkg_from_bitbucket( - OUT_SOURCE_PATH - REPO - [REF ] - [SHA512 <45d0d7f8cc350...>] - [HEAD_REF ] - [PATCHES ...] -) -``` - -## Parameters: -### OUT_SOURCE_PATH -Specifies the out-variable that will contain the extracted location. - -This should be set to `SOURCE_PATH` by convention. - -### REPO -The organization or user and repository on GitHub. - -### REF -A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.** - -For repositories without official releases, this can be set to the full commit id of the current latest master. - -If `REF` is specified, `SHA512` must also be specified. - -### SHA512 -The SHA512 hash that should match the archive (https://bitbucket.com/${REPO}/get/${REF}.tar.gz). - -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. - -### HEAD_REF -The unstable git commit-ish (ideally a branch) to pull for `--head` builds. - -For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms. - -### PATCHES -A list of patches to be applied to the extracted sources. - -Relative paths are based on the port directory. - -## Notes: -At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present. - -This exports the `VCPKG_HEAD_VERSION` variable during head builds. - -## Examples: - -* [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_from\_bitbucket.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_bitbucket.cmake) diff --git a/docs/maintainers/vcpkg_from_git.md b/docs/maintainers/vcpkg_from_git.md deleted file mode 100644 index c7f9f2ead4..0000000000 --- a/docs/maintainers/vcpkg_from_git.md +++ /dev/null @@ -1,63 +0,0 @@ -# vcpkg_from_git - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_git.md). - -Download and extract a project from git - -## Usage: -```cmake -vcpkg_from_git( - OUT_SOURCE_PATH - URL - REF <59f7335e4d...> - [HEAD_REF ] - [PATCHES ...] - [LFS [url]] -) -``` - -## Parameters: -### OUT_SOURCE_PATH -Specifies the out-variable that will contain the extracted location. - -This should be set to `SOURCE_PATH` by convention. - -### URL -The url of the git repository. - -### REF -The git sha of the commit to download. - -### FETCH_REF -The git branch to fetch in non-HEAD mode. After this is fetched, -then `REF` is checked out. This is useful in cases where the git server -does not allow checking out non-advertised objects. - -### HEAD_REF -The git branch to use when the package is requested to be built from the latest sources. - -Example: `main`, `develop`, `HEAD` - -### PATCHES -A list of patches to be applied to the extracted sources. - -Relative paths are based on the port directory. - -### LFS -Enable fetching files stored using Git LFS. -Only files pointed to by `REF` are fetched. - -The LFS url is optional. By default the Git url is used. - -This makes Git LFS mandatory for the port. -It's a fatal error if the extension is not installed. - -## Notes: -`OUT_SOURCE_PATH`, `REF`, and `URL` must be specified. - -## Examples: - -* [fdlibm](https://github.com/Microsoft/vcpkg/blob/master/ports/fdlibm/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_from\_git.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_git.cmake) diff --git a/docs/maintainers/vcpkg_from_github.md b/docs/maintainers/vcpkg_from_github.md deleted file mode 100644 index 16a1d29f8a..0000000000 --- a/docs/maintainers/vcpkg_from_github.md +++ /dev/null @@ -1,78 +0,0 @@ -# vcpkg_from_github - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_github.md). - -Download and extract a project from GitHub. Enables support for `install --head`. - -This also works with Gitea by specifying the Gitea server with the `GITHUB_HOST` option. - -## Usage: -```cmake -vcpkg_from_github( - OUT_SOURCE_PATH - REPO - [REF ] - [SHA512 <45d0d7f8cc350...>] - [HEAD_REF ] - [PATCHES ...] - [GITHUB_HOST ] - [AUTHORIZATION_TOKEN <${SECRET_FROM_FILE}>] - [FILE_DISAMBIGUATOR ] -) -``` - -## Parameters: -### OUT_SOURCE_PATH -Specifies the out-variable that will contain the extracted location. - -This should be set to `SOURCE_PATH` by convention. - -### REPO -The organization or user and repository on GitHub. - -### REF -A stable git commit-ish (ideally a tag or commit) that will not change contents. **This should not be a branch.** - -For repositories without official releases, this can be set to the full commit id of the current latest master. - -If `REF` is specified, `SHA512` must also be specified. - -### SHA512 -The SHA512 hash that should match the archive (https://github.com/${REPO}/archive/${REF}.tar.gz). - -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. - -### HEAD_REF -The unstable git commit-ish (ideally a branch) to pull for `--head` builds. - -For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms. - -### PATCHES -A list of patches to be applied to the extracted sources. - -Relative paths are based on the port directory. - -### GITHUB_HOST -A replacement host for enterprise GitHub instances. - -This field should contain the scheme, host, and port of the desired URL without a trailing slash. - -### AUTHORIZATION_TOKEN -A token to be passed via the Authorization HTTP header as "token ${AUTHORIZATION_TOKEN}". - -### FILE_DISAMBIGUATOR -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. - -## Notes: -At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present. - -This exports the `VCPKG_HEAD_VERSION` variable during head builds. - -## Examples: - -* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) -* [ms-gsl](https://github.com/Microsoft/vcpkg/blob/master/ports/ms-gsl/portfile.cmake) -* [boost-beast](https://github.com/Microsoft/vcpkg/blob/master/ports/boost-beast/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_from\_github.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_github.cmake) diff --git a/docs/maintainers/vcpkg_from_gitlab.md b/docs/maintainers/vcpkg_from_gitlab.md deleted file mode 100644 index 42a9a8ac75..0000000000 --- a/docs/maintainers/vcpkg_from_gitlab.md +++ /dev/null @@ -1,71 +0,0 @@ -# vcpkg_from_gitlab - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_gitlab.md). - -Download and extract a project from Gitlab instances. Enables support for `install --head`. - -## Usage: -```cmake -vcpkg_from_gitlab( - GITLAB_URL - OUT_SOURCE_PATH - REPO - [REF ] - [SHA512 <45d0d7f8cc350...>] - [HEAD_REF ] - [PATCHES ...] - [FILE_DISAMBIGUATOR ] -) -``` - -## Parameters: - -### GITLAB_URL -The URL of the Gitlab instance to use. - -### OUT_SOURCE_PATH -Specifies the out-variable that will contain the extracted location. - -This should be set to `SOURCE_PATH` by convention. - -### REPO -The organization or user plus the repository name on the Gitlab instance. - -### REF -A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.** - -For repositories without official releases, this can be set to the full commit id of the current latest master. - -If `REF` is specified, `SHA512` must also be specified. - -### SHA512 -The SHA512 hash that should match the archive (${GITLAB_URL}/${REPO}/-/archive/${REF}/${REPO_NAME}-${REF}.tar.gz). -The REPO_NAME variable is parsed from the value of REPO. - -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. - -### HEAD_REF -The unstable git commit-ish (ideally a branch) to pull for `--head` builds. - -For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms. - -### PATCHES -A list of patches to be applied to the extracted sources. - -Relative paths are based on the port directory. - -### FILE_DISAMBIGUATOR -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. - -## Notes: -At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present. - -This exports the `VCPKG_HEAD_VERSION` variable during head builds. - -## Examples: -* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75) -* [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15) -* [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13) - -## Source -[scripts/cmake/vcpkg\_from\_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake) diff --git a/docs/maintainers/vcpkg_from_sourceforge.md b/docs/maintainers/vcpkg_from_sourceforge.md deleted file mode 100644 index 88379a8e21..0000000000 --- a/docs/maintainers/vcpkg_from_sourceforge.md +++ /dev/null @@ -1,73 +0,0 @@ -# vcpkg_from_sourceforge - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_sourceforge.md). - -Download and extract a project from sourceforge. - -This function automatically checks a set of sourceforge mirrors. -Additional mirrors can be injected through the `VCPKG_SOURCEFORGE_EXTRA_MIRRORS` -list variable in the triplet. - -## Usage: -```cmake -vcpkg_from_sourceforge( - OUT_SOURCE_PATH SOURCE_PATH - REPO - [REF <2.1-3>] - SHA512 <547b417109332...> - FILENAME - [DISABLE_SSL] - [NO_REMOVE_ONE_LEVEL] - [PATCHES ...] -) -``` - -## Parameters: -### OUT_SOURCE_PATH -Specifies the out-variable that will contain the extracted location. - -This should be set to `SOURCE_PATH` by convention. - -### REPO -The organization or user and repository (optional) on sourceforge. - -### REF -A stable version number that will not change contents. - -### FILENAME -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. - -For example, we can get the download link: -https://sourceforge.net/settings/mirror_choices?projectname=mad&filename=libmad/0.15.1b/libmad-0.15.1b.tar.gz&selected=nchc -So the REPO is `mad/libmad`, the REF is `0.15.1b`, and the FILENAME is `libmad-0.15.1b.tar.gz` - -For some special links: -https://sourceforge.net/settings/mirror_choices?projectname=soxr&filename=soxr-0.1.3-Source.tar.xz&selected=nchc -The REPO is `soxr`, REF is not exist, and the FILENAME is `soxr-0.1.3-Source.tar.xz` - -### SHA512 -The SHA512 hash that should match the archive. - -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. - -### WORKING_DIRECTORY -If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`. - -Note that the archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`). - -### PATCHES -A list of patches to be applied to the extracted sources. - -Relative paths are based on the port directory. - -### NO_REMOVE_ONE_LEVEL -Specifies that the default removal of the top level folder should not occur. - -## Examples: - -* [cunit](https://github.com/Microsoft/vcpkg/blob/master/ports/cunit/portfile.cmake) -* [polyclipping](https://github.com/Microsoft/vcpkg/blob/master/ports/polyclipping/portfile.cmake) -* [tinyfiledialogs](https://github.com/Microsoft/vcpkg/blob/master/ports/tinyfiledialogs/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_from\_sourceforge.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_sourceforge.cmake) diff --git a/docs/maintainers/vcpkg_get_program_files_platform_bitness.md b/docs/maintainers/vcpkg_get_program_files_platform_bitness.md deleted file mode 100644 index ed74869b80..0000000000 --- a/docs/maintainers/vcpkg_get_program_files_platform_bitness.md +++ /dev/null @@ -1,15 +0,0 @@ -# vcpkg_get_program_files_platform_bitness - -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). - -Get the Program Files directory of the current platform's bitness: -either `$ENV{ProgramW6432}` on 64-bit windows, -or `$ENV{PROGRAMFILES}` on 32-bit windows. - -## Usage: -```cmake -vcpkg_get_program_files_platform_bitness() -``` - -## Source -[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) diff --git a/docs/maintainers/vcpkg_get_windows_sdk.md b/docs/maintainers/vcpkg_get_windows_sdk.md deleted file mode 100644 index d3a3ee8175..0000000000 --- a/docs/maintainers/vcpkg_get_windows_sdk.md +++ /dev/null @@ -1,13 +0,0 @@ -# vcpkg_get_windows_sdk - -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). - -Get the Windows SDK number. - -## Usage: -```cmake -vcpkg_get_windows_sdk() -``` - -## Source -[scripts/cmake/vcpkg\_get\_windows\_sdk.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_windows_sdk.cmake) diff --git a/docs/maintainers/vcpkg_host_path_list.md b/docs/maintainers/vcpkg_host_path_list.md deleted file mode 100644 index d3f1998898..0000000000 --- a/docs/maintainers/vcpkg_host_path_list.md +++ /dev/null @@ -1,29 +0,0 @@ -# vcpkg_host_path_list - -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). - -Modify a host path list variable (PATH, INCLUDE, LIBPATH, etc.) - -```cmake -vcpkg_host_path_list(PREPEND [...]) -vcpkg_host_path_list(APPEND [...]) -vcpkg_host_path_list(SET [...]) -``` - -`` may be either a regular variable name, or `ENV{variable-name}`, -in which case `vcpkg_host_path_list` will modify the environment. - -`vcpkg_host_path_list` adds all of the paths passed to it to ``; -`PREPEND` puts them before the existing list, so that they are searched first; -`APPEND` places them after the existing list, -so they would be searched after the paths which are already in the variable, -and `SET` replaces the value of the existing list. - -For all of `APPEND`, `PREPEND`, and `SET`, -the paths are added (and thus searched) in the order received. - -If no paths are passed to `APPEND` or `PREPEND`, nothing will be done; -for `SET`, the variable will be set to the empty string. - -## Source -[scripts/cmake/vcpkg\_host\_path\_list.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_host_path_list.cmake) diff --git a/docs/maintainers/vcpkg_install_cmake.md b/docs/maintainers/vcpkg_install_cmake.md deleted file mode 100644 index e7388783d3..0000000000 --- a/docs/maintainers/vcpkg_install_cmake.md +++ /dev/null @@ -1,29 +0,0 @@ -# vcpkg_install_cmake - -**This function has been deprecated in favor of [`vcpkg_cmake_install`](vcpkg_cmake_install.md) from the vcpkg-cmake port.** - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_cmake.md). - -Build and install a cmake project. - -## Usage: -```cmake -vcpkg_install_cmake(...) -``` - -## Parameters: -See [`vcpkg_build_cmake()`](vcpkg_build_cmake.md). - -## Notes: -This command transparently forwards to [`vcpkg_build_cmake()`](vcpkg_build_cmake.md), adding a `TARGET install` -parameter. - -## Examples: - -* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) -* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) -* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake) -* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_install\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_cmake.cmake) diff --git a/docs/maintainers/vcpkg_install_copyright.md b/docs/maintainers/vcpkg_install_copyright.md deleted file mode 100644 index a7679766c6..0000000000 --- a/docs/maintainers/vcpkg_install_copyright.md +++ /dev/null @@ -1,69 +0,0 @@ -# vcpkg_install_copyright - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_copyright.md). - -Merges multiple copyright files into a single file and install it. -Installs a single copyright file. - -## Usage - -```cmake -vcpkg_install_copyright(FILE_LIST ... [COMMENT]) -``` - -## Parameters - -### FILE_LIST -Specifies a list of license files with absolute paths. You must provide at least one file. - -### COMMENT -This optional parameter adds a comment before at the top of the file. - -## Notes - -This function creates a file called `copyright` inside `${CURRENT_PACKAGES_DIR}/share/${PORT}` - -If more than one file is provided, this function concatenates the contents of multiple copyright files to a single file. - -The resulting `copyright` file looks similar to this: - -``` -LICENSE-LGPL2.txt: - -Lorem ipsum dolor... - -LICENSE-MIT.txt: - -Lorem ipsum dolor sit amet... -``` - -Or with `COMMENT`: - -``` -A meaningful comment - -LICENSE-LGPL2.txt: - -Lorem ipsum dolor... - -LICENSE-MIT.txt: - -Lorem ipsum dolor sit amet... -``` - -## Examples - -```cmake -vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE/license.md" "${SOURCE_PATH}/LICENSE/license_gpl.md" COMMENT "This is a comment") -``` - -You can also collect the required files using a `GLOB` pattern: - -```cmake -file(GLOB LICENSE_FILES "${SOURCE_PATH}/LICENSES/*") -vcpkg_install_copyright(FILE_LIST ${LICENSE_FILES}) -``` - -## Source - -[vcpkg_install_copyright.md](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_copyright.cmake) diff --git a/docs/maintainers/vcpkg_install_gn.md b/docs/maintainers/vcpkg_install_gn.md deleted file mode 100644 index ebc166ad25..0000000000 --- a/docs/maintainers/vcpkg_install_gn.md +++ /dev/null @@ -1,31 +0,0 @@ -# vcpkg_install_gn - -**This function has been deprecated in favor of [`vcpkg_gn_install`](ports/vcpkg-gn/vcpkg_gn_install.md) from the vcpkg-gn port.** - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_gn.md). - -Installs a GN project. - -In order to build a GN project without installing, use [`vcpkg_build_ninja()`]. - -## Usage: -```cmake -vcpkg_install_gn( - SOURCE_PATH - [TARGETS ...] -) -``` - -## Parameters: -### SOURCE_PATH -The path to the source directory - -### TARGETS -Only install the specified targets. - -Note: includes must be handled separately - -[`vcpkg_build_ninja()`]: vcpkg_build_ninja.md - -## Source -[scripts/cmake/vcpkg\_install\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_gn.cmake) diff --git a/docs/maintainers/vcpkg_install_make.md b/docs/maintainers/vcpkg_install_make.md deleted file mode 100644 index 19f4b5ca8f..0000000000 --- a/docs/maintainers/vcpkg_install_make.md +++ /dev/null @@ -1,26 +0,0 @@ -# vcpkg_install_make - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_make.md). - -Build and install a make project. - -## Usage: -```cmake -vcpkg_install_make(...) -``` - -## Parameters: -See [`vcpkg_build_make()`](vcpkg_build_make.md). - -## Notes: -This command transparently forwards to [`vcpkg_build_make()`](vcpkg_build_make.md), adding `ENABLE_INSTALL` - -## Examples - -* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake) -* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake) -* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake) -* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_install\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_make.cmake) diff --git a/docs/maintainers/vcpkg_install_meson.md b/docs/maintainers/vcpkg_install_meson.md deleted file mode 100644 index dcda9fb32a..0000000000 --- a/docs/maintainers/vcpkg_install_meson.md +++ /dev/null @@ -1,22 +0,0 @@ -# vcpkg_install_meson - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_meson.md). - -Builds a meson project previously configured with `vcpkg_configure_meson()`. - -## Usage -```cmake -vcpkg_install_meson([ADD_BIN_TO_PATH]) -``` - -## Parameters: -### ADD_BIN_TO_PATH -Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs. - -## Examples - -* [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake) -* [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_install\_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_meson.cmake) diff --git a/docs/maintainers/vcpkg_install_msbuild.md b/docs/maintainers/vcpkg_install_msbuild.md deleted file mode 100644 index 8d0a31051a..0000000000 --- a/docs/maintainers/vcpkg_install_msbuild.md +++ /dev/null @@ -1,95 +0,0 @@ -# vcpkg_install_msbuild - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_msbuild.md). - -Build and install a msbuild-based project. This replaces `vcpkg_build_msbuild()`. - -## Usage -```cmake -vcpkg_install_msbuild( - SOURCE_PATH <${SOURCE_PATH}> - PROJECT_SUBPATH - [INCLUDES_SUBPATH ] - [LICENSE_SUBPATH ] - [RELEASE_CONFIGURATION ] - [DEBUG_CONFIGURATION ] - [TARGET ] - [TARGET_PLATFORM_VERSION <10.0.15063.0>] - [PLATFORM <${TRIPLET_SYSTEM_ARCH}>] - [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>] - [OPTIONS ...] - [OPTIONS_RELEASE ...] - [OPTIONS_DEBUG ...] - [USE_VCPKG_INTEGRATION] - [ALLOW_ROOT_INCLUDES | REMOVE_ROOT_INCLUDES] -) -``` - -## Parameters -### SOURCE_PATH -The path to the root of the source tree. - -Because MSBuild uses in-source builds, the source tree will be copied into a temporary location for the build. This -parameter is the base for that copy and forms the base for all XYZ_SUBPATH options. - -### USE_VCPKG_INTEGRATION -Apply the normal `integrate install` integration for building the project. - -By default, projects built with this command will not automatically link libraries or have header paths set. - -### PROJECT_SUBPATH -The subpath to the solution (`.sln`) or project (`.vcxproj`) file relative to `SOURCE_PATH`. - -### LICENSE_SUBPATH -The subpath to the license file relative to `SOURCE_PATH`. - -### INCLUDES_SUBPATH -The subpath to the includes directory relative to `SOURCE_PATH`. - -This parameter should be a directory and should not end in a trailing slash. - -### ALLOW_ROOT_INCLUDES -Indicates that top-level include files (e.g. `include/zlib.h`) should be allowed. - -### REMOVE_ROOT_INCLUDES -Indicates that top-level include files (e.g. `include/Makefile.am`) should be removed. - -### SKIP_CLEAN -Indicates that the intermediate files should not be removed. - -Ports using this option should later call [`vcpkg_clean_msbuild()`](vcpkg_clean_msbuild.md) to manually clean up. - -### RELEASE_CONFIGURATION -The configuration (``/p:Configuration`` msbuild parameter) used for Release builds. - -### DEBUG_CONFIGURATION -The configuration (``/p:Configuration`` msbuild parameter) used for Debug builds. - -### TARGET_PLATFORM_VERSION -The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter) - -### TARGET -The MSBuild target to build. (``/t:``) - -### PLATFORM -The platform (``/p:Platform`` msbuild parameter) used for the build. - -### PLATFORM_TOOLSET -The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build. - -### OPTIONS -Additional options passed to msbuild for all builds. - -### OPTIONS_RELEASE -Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`. - -### OPTIONS_DEBUG -Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`. - -## Examples - -* [libirecovery](https://github.com/Microsoft/vcpkg/blob/master/ports/libirecovery/portfile.cmake) -* [libfabric](https://github.com/Microsoft/vcpkg/blob/master/ports/libfabric/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_install\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_msbuild.cmake) diff --git a/docs/maintainers/vcpkg_install_nmake.md b/docs/maintainers/vcpkg_install_nmake.md deleted file mode 100644 index 572ac6550e..0000000000 --- a/docs/maintainers/vcpkg_install_nmake.md +++ /dev/null @@ -1,79 +0,0 @@ -# vcpkg_install_nmake - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_nmake.md). - -Build and install a msvc makefile project. - -## Usage: -```cmake -vcpkg_install_nmake( - SOURCE_PATH <${SOURCE_PATH}> - [PROJECT_SUBPATH <${SUBPATH}>] - [PROJECT_NAME <${MAKEFILE_NAME}>] - [CL_LANGUAGE ] - [PREFER_JOM] - [PRERUN_SHELL <${SHELL_PATH}>] - [PRERUN_SHELL_DEBUG <${SHELL_PATH}>] - [PRERUN_SHELL_RELEASE <${SHELL_PATH}>] - [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] - [OPTIONS_RELEASE <-DOPTIMIZE=1>...] - [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] - [TARGET ...] -) -``` - -## Parameters -### SOURCE_PATH -Specifies the directory containing the source files. -By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. - -### PROJECT_SUBPATH -Specifies the sub directory containing the makefile. - -### PROJECT_NAME -Specifies the name of the makefile. -Default is `makefile.vc` - -### CL_LANGUAGE -Specifies the language for setting up flags in the `_CL_` environment variable. -The default language is `CXX`. -To disable the modification of `_CL_`, use `NONE`. - -### PREFER_JOM -Specifies that a parallel build with `jom` should be attempted. -This is useful for faster builds of makefiles which process many independent targets -and which cannot benefit from the `/MP` cl option. -To mitigate issues with concurrency-unaware makefiles, a normal `nmake` build is run after `jom` errors. - -### PRERUN_SHELL -Script that needs to be called before build. - -### PRERUN_SHELL_DEBUG -Script that needs to be called before debug build. - -### PRERUN_SHELL_RELEASE -Script that needs to be called before release build. - -### OPTIONS -Additional options passed to the build command. - -### OPTIONS_RELEASE -Additional options passed to the build command for the release build. These are in addition to `OPTIONS`. - -### OPTIONS_DEBUG -Additional options passed to the build command for the debug build. These are in addition to `OPTIONS`. - -### TARGET -The list of targets passed to the build command. -If not specified, target `all` will be passed. - -## Notes: -This command transparently forwards to [`vcpkg_build_nmake()`](vcpkg_build_nmake.md), adding `ENABLE_INSTALL`. - -## Examples - -* [libspatialite](https://github.com/microsoft/vcpkg/blob/master/ports/libspatialite/portfile.cmake) -* [tcl](https://github.com/microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_install\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_nmake.cmake) diff --git a/docs/maintainers/vcpkg_install_qmake.md b/docs/maintainers/vcpkg_install_qmake.md deleted file mode 100644 index 4efc157948..0000000000 --- a/docs/maintainers/vcpkg_install_qmake.md +++ /dev/null @@ -1,26 +0,0 @@ -# vcpkg_install_qmake - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_qmake.md). - -Build and install a qmake project. - -## Usage: -```cmake -vcpkg_install_qmake(...) -``` - -## Parameters: -See [`vcpkg_build_qmake()`](vcpkg_build_qmake.md). - -## Notes: -This command transparently forwards to [`vcpkg_build_qmake()`](vcpkg_build_qmake.md). - -Additionally, this command will copy produced .libs/.dlls/.as/.dylibs/.sos to the appropriate -staging directories. - -## Examples - -* [libqglviewer](https://github.com/Microsoft/vcpkg/blob/master/ports/libqglviewer/portfile.cmake) - -## Source -[scripts/cmake/vcpkg\_install\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_qmake.cmake) diff --git a/docs/maintainers/vcpkg_list.md b/docs/maintainers/vcpkg_list.md deleted file mode 100644 index 46aa7dabd3..0000000000 --- a/docs/maintainers/vcpkg_list.md +++ /dev/null @@ -1,94 +0,0 @@ -# vcpkg_list - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_list.md). - -A replacement for CMake's `list()` function, which correctly handles elements -with internal semicolons (in other words, escaped semicolons). -Use `vcpkg_list()` instead of `list()` whenever possible. - -```cmake -vcpkg_list(SET [...]) -vcpkg_list( [...]) -``` - -In addition to all of the commands from `list()`, `vcpkg_list` adds -a `vcpkg_list(SET)` command. -This command takes its arguments, escapes them, and then concatenates -them into a list; this should be used instead of `set()` for setting any -list variable. - -Otherwise, the `vcpkg_list()` function is the same as the built-in -`list()` function, with the following restrictions: - -- `GET`, `REMOVE_ITEM`, and `REMOVE_AT` support only one index/value -- `POP_BACK` and `POP_FRONT` do not support getting the value into - another out variable. Use C++ style `GET` then `POP_(BACK|FRONT)`. -- `FILTER` and `TRANSFORM` are unsupported. - -See the [CMake documentation for `list()`](https://cmake.org/cmake/help/latest/command/list.html) -for more information. - -## Notes: Some Weirdnesses - -The most major weirdness is due to `""` pulling double-duty as "list of zero elements", -and "list of one element, which is empty". `vcpkg_list` always uses the former understanding. -This can cause weird behavior, for example: - -```cmake -set(lst "") -vcpkg_list(APPEND lst "" "") -# lst = ";" -``` - -This is because you're appending two elements to the empty list. -One very weird behavior that comes out of this would be: - -```cmake -set(lst "") -vcpkg_list(APPEND lst "") -# lst = "" -``` - -since `""` is the empty list, we append the empty element and end up with a list -of one element, which is empty. This does not happen for non-empty lists; -for example: - -```cmake -set(lst "a") -vcpkg_list(APPEND lst "") -# lst = "a;" -``` - -only the empty list has this odd behavior. - -## Examples - -### Creating a list - -```cmake -vcpkg_list(SET foo_param) -if(DEFINED arg_FOO) - vcpkg_list(SET foo_param FOO "${arg_FOO}") -endif() -``` - -### Appending to a list - -```cmake -set(OPTIONS -DFOO=BAR) -if(VCPKG_TARGET_IS_WINDOWS) - vcpkg_list(APPEND OPTIONS "-DOS=WINDOWS;FOO") -endif() -``` - -### Popping the end off a list - -```cmake -if(NOT list STREQUAL "") - vcpkg_list(GET list end -1) - vcpkg_list(POP_BACK list) -endif() -``` - -## Source -[scripts/cmake/vcpkg\_list.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_list.cmake) diff --git a/docs/maintainers/vcpkg_minimum_required.md b/docs/maintainers/vcpkg_minimum_required.md deleted file mode 100644 index caf975f61e..0000000000 --- a/docs/maintainers/vcpkg_minimum_required.md +++ /dev/null @@ -1,17 +0,0 @@ -# vcpkg_minimum_required - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_minimum_required.md). - -Asserts that the version of the vcpkg program being used to build a port is later than the supplied date, inclusive. - -## Usage -```cmake -vcpkg_minimum_required(VERSION 2021-01-13) -``` - -## Parameters -### VERSION -The date-version to check against. - -## Source -[scripts/cmake/vcpkg\_minimum\_required.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_minimum_required.cmake) diff --git a/docs/maintainers/vcpkg_replace_string.md b/docs/maintainers/vcpkg_replace_string.md deleted file mode 100644 index 967dd3c01a..0000000000 --- a/docs/maintainers/vcpkg_replace_string.md +++ /dev/null @@ -1,12 +0,0 @@ -# vcpkg_replace_string - -The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_replace_string.md). - -Replace a string in a file. - -```cmake -vcpkg_replace_string( ) -``` - -## Source -[scripts/cmake/vcpkg\_replace\_string.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_replace_string.cmake) diff --git a/docs/specifications/binarycaching.md b/docs/specifications/binarycaching.md deleted file mode 100644 index d9c55d5d14..0000000000 --- a/docs/specifications/binarycaching.md +++ /dev/null @@ -1,159 +0,0 @@ -# Binary Caching v1.1 (Jul 14, 2020) - -**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** - -**Up-to-date documentation is available at [Binarycaching](../users/binarycaching.md).** - -## Motivation - -The primary motivation of binary caching is to accelerate two broad scenarios in an easily accessible way - -- Continuous Integration - -- Developer Environment Changes (first-time or branch change) - -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. - -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. - -## Key User Stories - -### CI -> CI - -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). - -### CI -> Developer - -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. - -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. - -### Single Developer (same machine reuse) - -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. - -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). - -### Developer <-> Developer (multi-machine / team scenario) - -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). - -## Solution Aspects - -### Tracking Compilers - -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: - -- All files in the port directory - -- The toolchain file contents - -- The triplet contents - -- All dependency binaries - -- The version of the CMake tool used to build - -and a few others. - -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. - -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. - -### Better control over source modifications - -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. - -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. - -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. - -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. - -### Protocols - -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. - -#### Backend #1: File-Based Archives - -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. - -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. - -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: - -- It uses the hardcoded directory `$VCPKG_ROOT/archives` (redirectable using symlinks, but unwieldy) - -- It cannot use multiple directories - -- There is no ability to treat directories as "read-only"/immutable - -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). - -#### Backend #2: NuGet (Azure DevOps Artifacts, GitHub Packages, etc) - -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. - -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. - -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: - -1. Vcpkg computes hashes of any potentially required packages and writes them to a file - -2. An unspecified service/task/etc can parse this file and download any appropriate packages - -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. - -4. Finally, another unspecified service/task/etc can take these output packages, sign them, and upload them. - -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. - -#### Configuration - -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. - -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. - -On the command line, a backend can be specified via `--binarysource=`. 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). - -The environment variable `VCPKG_BINARY_SOURCES` can be set to a semicolon-delimited list of ``. Empty `` 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"` - -`` can be any of: - -- `clear` - ignore all lower priority sources (lowest priority is default, then env, then command line) - -- `default[,]` - Reintroduce the default ~/.vcpkg/packages (as read-only or with uploading) - -- `files,[,]` - Add a file-based archive at `` - -- `nuget,[,]` - Add a nuget-based source at ``. This url has a similar semantic as `nuget.exe restore -source ` for reads and `nuget.exe push -source ` for writes; notably it can also be a local path. - -- `nugetconfig,[,]` - Add a nuget-based source using the NuGet.config file at ``. 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 ` and `nuget.exe restore -ConfigFile `. - -- `interactive` - Enables interactive mode (such as manual credential entry) for all other configured backends. - -`` can be any of `read`, `write`, or `readwrite` to control whether packages will be consumed or published. - -Backtick (`) can be used as an escape character within config strings, with double backtick (``) inserting a single backtick. All paths must be absolute. - -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). - -To enable the 4-step flow, `vcpkg install` will take a command `--write-nuget-packages-config=` which can be used in combination with `--dry-run`. This path can be relative and will resolve with respect to the current working directory. - -[1]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html - -#### Example 4-step flow - -``` -PS> vcpkg install --dry-run pkg1 pkg2 pkg3 --write-nuget-packages-config=packages.config -``` - -An unspecified process, such as `nuget.exe restore packages.config -packagedirectory $packages` or the [ADO task][2], restores the packages to `$packages`. - -``` -PS> vcpkg install pkg1 pkg2 pkg3 --binarysource=clear --binarysource=nuget,$outpkgs,upload --binarysource=nuget,$packages -``` - -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. - -[2]: https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/package/nuget?view=azure-devops diff --git a/docs/specifications/export-command.md b/docs/specifications/export-command.md deleted file mode 100644 index 5464e9408d..0000000000 --- a/docs/specifications/export-command.md +++ /dev/null @@ -1,174 +0,0 @@ -# Binary Export (Apr 28, 2017) - -**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** - -## 1. Motivation - -### A. Build once and share - -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 -- Enterprise environments, in which there are dedicated teams to acquire libraries and then share them with other teams to consume them -- Academic environments, in which the professor/teacher wants to build the required libraries and then provide them to all the students -- CI Systems, in which developers want to quickly distribute their exact set of dependencies to a cloud-based farm of build machines - -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`. - -### B. Very large libraries - -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. - -### C. Flexibility and uses without `vcpkg` - -`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: -- Use `vcpkg` for the build, then host the binaries in a website (similarly to nuget) -- Use `vcpkg` for the build, then put the binaries in an installer and distribute the installer - -Consuming the libraries outside of `vcpkg` forfeits the ability to install new libraries or update existing ones, but this can be: -- not a concern, like in a short term project or assignment -- explicitly desired, like in the development of a game where libraries and their versions are sealed for a particular release, never to be modified - -### D. Easy consumption in Visual Studio for NuGet users - -Customers have requested C++ NuGet packages to integrate into their project. This has come from: -- Customers than have used NuGet (e.g. in C#) and find it very convenient -- 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 - -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. - -[Qt]: https://www.qt.io/ - -## 2. Other design concerns - -- 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. -- 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. - -## 3. Proposed solution - -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. - -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. - -## 4. Proposed User experience - -### i. User knows what libraries he needs and wants to export them to an archive format (zip) -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. - -Bob tries to export the libraries: -```no-highlight -> vcpkg export gtest cpprestsdk --zip -The following packages are already built and will be exported: - * boost:x86-windows - * bzip2:x86-windows - cpprestsdk:x86-windows - * openssl:x86-windows - * websocketpp:x86-windows - * zlib:x86-windows -The following packages need to be built: - gtest:x86-windows -Additional packages (*) need to be exported to complete this operation. -There are packages that have not been built. -To build them, run: - vcpkg install gtest:x86-windows -``` - -Bob proceeds to install the missing libraries: -```no-highlight -> vcpkg install gtest:x86-windows -// -- omitted build information -- // -Package gtest:x86-windows is installed. -``` - -Bob then returns to export the libraries: -```no-highlight -> vcpkg export gtest cpprestsdk --zip -The following packages are already built and will be exported: - * boost:x86-windows - * bzip2:x86-windows - cpprestsdk:x86-windows - gtest:x86-windows - * openssl:x86-windows - * websocketpp:x86-windows - * zlib:x86-windows -Additional packages (*) need to be exported to complete this operation. -Exporting package zlib:x86-windows... -Exporting package zlib:x86-windows... done -Exporting package openssl:x86-windows... -Exporting package openssl:x86-windows... done -Exporting package bzip2:x86-windows... -Exporting package bzip2:x86-windows... done -Exporting package boost:x86-windows... -Exporting package boost:x86-windows... done -Exporting package websocketpp:x86-windows... -Exporting package websocketpp:x86-windows... done -Exporting package cpprestsdk:x86-windows... -Exporting package cpprestsdk:x86-windows... done -Exporting package gtest:x86-windows... -Exporting package gtest:x86-windows... done -Creating zip archive... -Creating zip archive... done -zip archive exported at: C:/vcpkg/vcpkg-export-20170428-155351.zip -``` - -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. - -### ii. User has a vcpkg root that works and wants to share it -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. -```no-highlight -> vcpkg export gtest zlib gtest:x64-windows zlib:x64-windows --nuget -The following packages are already built and will be exported: - gtest:x86-windows - gtest:x64-windows - zlib:x86-windows - zlib:x64-windows -Exporting package zlib:x86-windows... -Exporting package zlib:x86-windows... done -Exporting package zlib:x64-windows... -Exporting package zlib:x64-windows... done -Exporting package gtest:x86-windows... -Exporting package gtest:x86-windows... done -Exporting package gtest:x64-windows... -Exporting package gtest:x64-windows... done -Creating nuget package... -Creating nuget package... done -Nuget package exported at: C:/vcpkg/scripts/buildsystems/tmp/vcpkg-export-20170428-164312.nupkg -``` - -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. - -### iii. User has a vcpkg root that works and wants to share it #2 -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. -```no-highlight -> vcpkg export cpprestsdk zlib --zip -The following packages are already built and will be exported: - * boost:x86-windows - * bzip2:x86-windows - cpprestsdk:x86-windows - * openssl:x86-windows - * websocketpp:x86-windows - zlib:x86-windows -Additional packages (*) need to be exported to complete this operation. -Exporting package zlib:x86-windows... -Exporting package zlib:x86-windows... done -Exporting package openssl:x86-windows... -Exporting package openssl:x86-windows... done -Exporting package bzip2:x86-windows... -Exporting package bzip2:x86-windows... done -Exporting package boost:x86-windows... -Exporting package boost:x86-windows... done -Exporting package websocketpp:x86-windows... -Exporting package websocketpp:x86-windows... done -Exporting package cpprestsdk:x86-windows... -Exporting package cpprestsdk:x86-windows... done -Creating zip archive... -Creating zip archive... done -zip archive exported at: C:/vcpkg/vcpkg-export-20170428-155351.zip -``` - -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. - -## 5. Technical model - -- Each exported library, must be accompanied with all of its dependencies, even if they are not explicitly specified in the `vcpkg export` command. -- When exporting a library, a dependency graph will be built, similarly to install, to figure out which packages need to be exported. -- It is allowed to have packages from different triplets, so users can include 32/64-bit and dynamic/static binaries in the same export. -- The exported archives also include the files needed to integrate with MSBuild and/or CMake. \ No newline at end of file diff --git a/docs/specifications/feature-packages.md b/docs/specifications/feature-packages.md deleted file mode 100644 index 5737c650a6..0000000000 --- a/docs/specifications/feature-packages.md +++ /dev/null @@ -1,291 +0,0 @@ -# Proposal: Features / Feature packages (Feb 23 2017) - -**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** - -**Up-to-date documentation is available at [Selecting Library Features](../users/selecting-library-features.md).** - -## 1. Motivation - -### A. OpenCV + CUDA - -[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. - -Therefore, there is significant value in enabling users to choose whether they find CUDA support valuable for their particular scenario. - -### B. OpenCV + OpenCV\_contrib - -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. - -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. - -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. - -### C. C++ REST SDK + SignalR - -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). - -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. - -[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. - -[OpenCV]: http://opencv.org/ -[CUDA]: http://www.nvidia.com/object/cuda_home_new.html -[OpenCV_contrib]: https://github.com/opencv/opencv_contrib -[cpprestsdk]: https://github.com/Microsoft/cpprestsdk -[Websockets++]: https://www.zaphoyd.com/websocketpp/ -[SignalR]: https://github.com/aspnet/SignalR-Client-Cpp - -## 2. Other design concerns - -- 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. - -- 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. - -## 3. Proposed solution - -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. - -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. - -- Individual libraries within `boost` may be reasonably represented as features. -- Whether a graphics library is built on DirectX xor OpenGL (where one but not both must be chosen) is not representable as a feature. - -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. - -When using `vcpkg install `, some features will be enabled by default. These default features can be avoided by referring to the packages as `[core]` and features can be added by supplying them on the same installation line. - -### A. Proposed User experience - -#### i. User with no preference about options -Install of a library with default features: -```no-highlight -> vcpkg install cpprestsdk -// -- omitted build information -- // -Package cpprestsdk[core]:x86-windows is installed. -Package cpprestsdk[compression]:x86-windows is installed. -Package cpprestsdk[ws-client]:x86-windows is installed. -``` - -Removal of that library: -```no-highlight -> vcpkg remove cpprestsdk -The following packages will be removed: - cpprestsdk:x86-windows -Removing package cpprestsdk:x86-windows... -Removing package cpprestsdk:x86-windows... done -Purging package cpprestsdk:x86-windows... -Cleaned up D:\src\vcpkg\packages\cpprestsdk_x64-windows -Purging package cpprestsdk:x86-windows... done -``` - -Installation of a library with optional features: -```no-highlight -> vcpkg install opencv -// -- omitted build information -- // -Package opencv[core]:x86-windows is installed. -``` - -#### ii. User desires CUDA support for OpenCV directly, and is unfamiliar with feature packages -Developer Bob knows he wants OpenCV, so he guesses what the package is called -```no-highlight -> vcpkg install opencv -// -- omitted build information -- // -Package opencv[core]:x86-windows is installed. -``` - -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. -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`: -```no-highlight -> vcpkg search opencv -opencv 3.2.0 computer vision library -opencv[cuda] support for NVidia CUDA -opencv[contrib] community supported extensions for OpenCV - -If your library is not listed, please open an issue at: - https://github.com/Microsoft/vcpkg/issues -``` -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: -```no-highlight -> vcpkg install opencv[cuda] -The following packages will be rebuilt: - opencv:x86-windows - -To rebuild with this feature, use: - vcpkg remove opencv:x86-windows - vcpkg install opencv[core,cuda]:x86-windows -``` -Bob follows the instructions... -```no-highlight -> vcpkg remove opencv:x86-windows -// -- omitted results as above -- // -> vcpkg install opencv[core,cuda]:x86-windows -// -- omitted build information -- // -Package opencv[core]:x86-windows is installed. -Package opencv[cuda]:x86-windows is installed. -``` -and he can now use OpenCV's CUDA support in his application. - -#### iii. User is familiar with feature packages, and wants to opt-out of a feature -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: -``` -> vcpkg search cpprestsdk -cpprestsdk 2.9.0-2 C++11 JSON, REST, and OAuth library The C++ RES... -cpprestsdk[compression] Gzip compression support in the HTTP client. -cpprestsdk[ws-client] Websocket client support based on websocketspp. - -If your library is not listed, please open an issue at: - https://github.com/Microsoft/vcpkg/issues -``` - -She decided she only wants `cpprestsdk[compression]`, so she installs only that feature: -```no-highlight -> vcpkg install cpprestsdk[compression] -// -- omitted build information -- // -Package cpprestsdk[core]:x86-windows is installed. -Package cpprestsdk[compression]:x86-windows is installed. -``` -She receives a quick recursive build that only depends on `zlib`. - -She's now interested in some additional libraries built on top of cpprestsdk: `azure-storage-cpp` and `signalrclient`. -```no-highlight -> vcpkg install azure-storage-cpp -// -- omitted build information -- // -Package azure-storage-cpp[core]:x86-windows is installed. - -> vcpkg install signalrclient -Package signalrclient:x86-windows depends on cpprestsdk[ws-client]:x86-windows. - -The following packages will be rebuilt: - * azure-storage-cpp:x86-windows - * cpprestsdk:x86-windows - -To rebuild the current package graph with this feature, use: - vcpkg remove cpprestsdk:x86-windows azure-storage-cpp:x86-windows - vcpkg install cpprestsdk[core,compression,ws-client]:x86-windows - vcpkg install azure-storage-cpp[core]:x86-windows - vcpkg install signalrclient[core]:x86-windows -``` -She follows the above script and can use both `azure-storage-cpp` and `signalrclient` in her code. - -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`. -```no-highlight -> vcpkg remove boost openssl -The following packages and features will be removed: - * signalrclient[core]:x86-windows - * cpprestsdk[ws-client]:x86-windows - boost[core]:x86-windows - openssl[core]:x86-windows - -The following packages will be rebuilt: - * azure-storage-cpp:x86-windows - * cpprestsdk:x86-windows - -Removing features requires rebuilding packages. -To rebuild the current package graph without these features, use: - vcpkg remove cpprestsdk:x86-windows azure-storage-cpp:x86-windows signalrclient:x86-windows openssl:x86-windows boost:x86-windows - vcpkg install cpprestsdk[core,compression]:x86-windows - vcpkg install azure-storage-cpp[core]:x86-windows -``` -In the end, her final `vcpkg list` outputs: -```no-highlight -> vcpkg list -zlib[core]:x86-windows 1.2.11 A compression library -azure-storage-cpp[core]:x86-windows 2.6.0 Microsoft Azure Storage Client SDK for ... -cpprestsdk[core]:x86-windows 2.9.0-2 C++11 JSON, REST, and OAuth library -cpprestsdk[compression]:x86-windows Gzip compression support in the HTTP client. -``` - -### B. Technical model - -- Each package can have any number "features". -- Features follow the same naming conventions as packages, but when referenced are always "namespaced" by the parent package. - - `cpprestsdk[ws-client]` is a completely orthogonal feature from `poco[ws-client]`. -- Features are valid dependencies. - - `signalrclient` depends on `cpprestsdk[ws-client]` -- Features can have dependencies (including other features). - - `cpprestsdk[ws-client]` depends on `boost`, `openssl`, and `websocketspp` - - `opencv[cuda]` depends on `cuda` - - `opencv[contrib]` depends on `opencv[cuda]` - - `boost[python]` depends on `libpython` -- 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 - - `azure-storage-cpp` depends on `cpprestsdk[core]` - - `cpprestsdk[ws-client]` implicitly depends on `cpprestsdk[core]` -- 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. - - `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]`. - - `opencv` does not declare `cuda` nor `contrib` to be default features. - -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. - -### C. Proposed Control File Syntax - -#### OpenCV and CUDA -To add the feature CUDA to OpenCV, we will adopt the following syntax in the CONTROL file: -```no-highlight -# opencv/CONTROL -Source: opencv -Version: 3.2.0-1 -Build-Depends: zlib, libpng, libjpeg-turbo, tiff -Description: computer vision library -Default-Features: - -Feature: cuda -Build-Depends: cuda -Description: parallel computing platform - -Feature: contrib -Build-Depends: opencv[cuda] -Description: library of OpenCV Extensions -``` - -#### Signalrclient -```no-highlight -# signalrclient/CONTROL -Source: signalrclient -Version: 1.0.0-beta1 -Build-Depends: cpprestsdk[ws-client] -Description: C++ client for SignalR. -``` -```no-highlight -# cpprestsdk/CONTROL -Source: cpprestsdk -Version: 2.9.0-2 -Build-Depends: -Description: C++11 JSON, REST, and OAuth library ... -Default-Features: compression, ws-client - -Feature: compression -Build-Depends: zlib (windows) -Description: Gzip compression support in the HTTP client. - -Feature: ws-client -Build-Depends: boost (windows), openssl (windows), websocketpp (windows) -Description: Websocket client support based on websocketspp -``` - -### D. Additional Control File Technical Details - -- If any feature paragraphs exist, the field `Default-Features` must be present. - -## 4. Related Work - -### Cargo's Features (from Rust): -The proposed feature packages are exceedingly similar to Cargo's Features, with the following changes: - -- We avoid any collision problems because features are always namespaced by the owning package -- 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). -- 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). -- We do not intend feature packages to be used to express the curation relationship, beyond the notion of a "default" set within a package. - -### Gentoo's USE flags: -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. - -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". - -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. - -Problems with USE flags: - -- 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. -- 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. -- 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). -- 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. diff --git a/docs/specifications/manifests.md b/docs/specifications/manifests.md deleted file mode 100644 index a71db2d8b5..0000000000 --- a/docs/specifications/manifests.md +++ /dev/null @@ -1,302 +0,0 @@ -# Manifests -- `vcpkg.json` - -**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** - -**Up-to-date documentation is available at [Manifests](../users/manifests.md).** - -For many other language package managers, there exists a way of writing one's dependencies in a declarative -manifest format; we want something similar for vcpkg. What follows is the specification of that feature; -this should mean that vcpkg becomes far more user and enterprise-friendly, and is additionally an important -first step for versioning and package federation. Our primary concern, beyond implementability, is ease-of-use; -it is important that using this feature is all of: - -* Easy for existing users -* Easy for new users to set up -* Easy to extend later for new features like versioning and federation -* _Declarative_, not _Imperative_. - -## Reasoning - -### Why JSON? - -We choose JSON for five main reasons: - -* Everybody knows JSON, and if one doesn't, it's really easy to learn -* Every tool supports JSON in the standard library, or in a commonly used support library - * This means writing tooling should be trivial in any language one is comfortable with - * Most configuration formats don't have a COBOL implementation 😉 -* Specified in an international standard - * There is _one_ right way to parse JSON - * There are no ambiguities of what the parse tree _should_ be -* Simple and secure - * Unlike YAML, for example, there's no weird ACE issues - * Easy to write a parser -- important since we can't depend on external libraries -* Schemas are almost a necessity - -Some have suggested allowing comments or commas in our parser; we chose to use JSON proper -rather than JSON5 or JSON with comments because JSON is the everywhere-supported international -standard. That is not necessarily true of JSON with comments. Additionally, if one needs -to write a comment, they can do so via `"$reason"` or `"$comment"` fields. - -## Specification - -A manifest file shall have the name `vcpkg.json`, and shall be in the root directory of a package. -It also replaces CONTROL files, though existing CONTROL files will still be -supported; there will be no difference between ports and packages, except -that packages do not need to supply portfile.cmake (eventually we would like -to remove the requirement of portfile.cmake for ports that already use -CMake). - -The specification uses definitions from the [Definitions](#definitions) section in order -to specify the shape of a value. Note that any object may contain any directives, written as -a field key that starts with a `$`; these directives shall be ignored by `vcpkg`. Common -directives may include `"$schema"`, `"$comment"`, `"$reason"`. - -A manifest must be a top-level object, and must have at least: - -* `"name"`: a `` -* One (and only one) of the following version fields: - * `"version-string"`: A `string`. Has no semantic meaning. - Equivalent to `CONTROL`'s `Version:` field. - * Other version fields will be defined by the Versions RFC - -The simplest vcpkg.json looks like this: - -```json -{ - "name": "mypackage", - "version-string": "0.1.0-dev" -} -``` - -Additionally, it may contain the following properties: -* `"port-version"`: A non-negative integer. If this field doesn't exist, it's assumed to be `0`. - * Note that this is a change from existing CONTROL files, where versions were a part of the version string -* `"maintainers"`: An array of `string`s which contain the authors of a package - * `"maintainers": [ "Nicole Mazzuca ", "שלום עליכם " ]` -* `"description"`: A string or array of strings containing the description of a package - * `"description": "mypackage is a package of mine"` -* `"homepage"`: A url which points to the homepage of a package - * `"homepage": "https://github.com/strega-nil/mypackage"` -* `"documentation"`: A url which points to the documentation of a package - * `"documentation": "https://readthedocs.io/strega-nil/mypackage"` -* `"license"`: A `` - * `"license": "MIT"` -* `"dependencies"`: An array of ``s -* `"dev-dependencies"`: An array of ``s which are required only for developers (testing and the like) -* `"features"`: An array of ``s that the package supports -* `"default-features"`: An array of ``s that correspond to features, which will be used by default. -* `"supports"`: A `` - * `"supports": "windows & !arm"` - -Any properties which are not listed, and which do not start with a `$`, -will be warned against and are reserved for future use. - -The following is an example of an existing port CONTROL file rewritten as a vcpkg.json file: - -``` -Source: pango -Version: 1.40.11-6 -Homepage: https://ftp.gnome.org/pub/GNOME/sources/pango/ -Description: Text and font handling library. -Build-Depends: glib, gettext, cairo, fontconfig, freetype, harfbuzz[glib] (!(windows&static)&!osx) -``` - -```json -{ - "name": "pango", - "version-string": "1.40.11", - "port-version": 6, - "homepage": "https://ftp.gnome.org/pub/GNOME/sources/pango/", - "description": "Text and font handling library.", - "dependencies": [ - "glib", - "gettext", - "cairo", - "fontconfig", - "freetype", - { - "name": "harfbuzz", - "features": [ "glib" ], - "platform": "!(windows & static) & !osx" - } - ] -} -``` - -## Behavior of the Tool - -There will be two "modes" for vcpkg from this point forward: "classic", and "manifest". -The former will act exactly like the existing vcpkg workflow, so as to avoid breaking -anyone. The latter will be the mode only when the user either: - -* Passes `--manifest-root=` (initially, `x-manifest-root`) -* Runs `vcpkg` in a directory that contains a file named `vcpkg.json`, or in a - child directory of a directory containing `vcpkg.json`. - * For this, initially vcpkg will warn that the behavior will change in the - future, and simply run in classic mode, unless the feature flag `manifests` is - passed via: - * The environment variable `VCPKG_FEATURE_FLAGS` - * The option `--feature-flags` - * (e.g., `--feature-flags=binarycaching,manifests`) - * If someone wants to use classic mode and silence the warning, they can add the - `-manifests` feature flag to disable the mode. - -When in "manifest" mode, the `installed` directory will be changed to -`/vcpkg_installed` (name up for bikeshedding). -The following commands will change behavior: - -* `vcpkg install` without any port arguments will install the dependencies listed in - the manifest file, and will remove any dependencies - which are no longer in the dependency tree implied by the manifest file. -* `vcpkg install` with port arguments will give an error. - -The following commands will not work in manifest mode, at least initially: - -* `vcpkg x-set-installed`: `vcpkg install` serves the same function -* `vcpkg remove` -* `vcpkg export` - -We may add these features back for manifest mode once we understand how best to -implement them. - -### Behavior of the Toolchain - -Mostly, the toolchain file stays the same; however, we shall add -two public options: - -```cmake -VCPKG_MANIFEST_MODE:BOOL= -VCPKG_MANIFEST_INSTALL:BOOL=ON -``` - -The first option either explicitly turns on, or off, manifest mode; -otherwise, we default to looking for a manifest file in the directory -tree upwards from the source directory. - -The `VCPKG_MANIFEST_INSTALL` option tells the toolchain whether to -install the packages or not -- if you wish to install the manifest -dependencies manually, you can set this to off, and we also turn it -off for packages installed by vcpkg. - -Additionally, if `-manifests` is set in the feature flags environment -variable, we turn off manifest mode in the toolchain, and we act like -the classic toolchain. - -### Example - CMake Integration - -An example of using the new vcpkg manifests feature for a new -project follows: - -The filesystem structure should look something like: - -``` -example/ - src/ - main.cxx - CMakeLists.txt - vcpkg.json -``` - -Then, `main.cxx` might look like: - -```cpp -#include - -int main() { - fmt::print("Hello, {}!", "world"); -} -``` - -Therefore, in `vcpkg.json`, we'll need to depend on `fmt`: - -```json -{ - "name": "example", - "version-string": "0.0.1", - "dependencies": [ - "fmt" - ] -} -``` - -Then, let's write our `CMakeLists.txt`: - -```cmake -cmake_minimum_required(VERSION 3.14) - -project(example CXX) - -add_executable(example src/main.cxx) - -find_package(fmt REQUIRED) - -target_link_libraries(example - PRIVATE - fmt::fmt) -``` - -And finally, to configure and build: - -```sh -$ cd example -$ cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -... configuring and installing... -$ cmake --build build -``` - -and we're done! `fmt` will get installed into -`example/build/vcpkg_installed`, and we can run our executable with: - -```sh -$ build/example -Hello, world! -``` - -## Definitions - -* ``: A `string` which: - * Is entirely ASCII - * Contains only lowercase alphabetic characters, digits, and hyphen-minus - * Does not have multiple consecutive hyphens - * Does not begin nor end with a hyphen - * Is not a Windows filesystem reserved name - * Is not a vcpkg reserved name: "default" or "core". - * In other words, it must follow the regex `[a-z0-9]+(-[a-z0-9]+)*`, and must not be any of: - * `{ prn, aux, nul, con, lpt[1-9], com[1-9], core, default }` -* ``: A `string` consisting of a non-zero number of ``s, separated by `.`. - * `a.b.c` is valid - * `a` is valid - * `a/b` is not valid - * `Boost.Beast` is not valid, but `boost.beast` is -* ``: Either a ``, or an object: - * A dependency always contains the following: - * `"name"`: A `` - * Optionally, `"features"`: an array of ``s corresponding to features in the package. - * 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. - * Optionally, `"platform"`: a `` - * ``: No extra fields are required. -* ``: An SPDX license expression at version 3.9. -* ``: A specification of a set of platforms; used in platform-specific dependencies and supports fields. A string that is parsed as follows: - * ``: - * `` - * `` - * `` - * ``: - * `( )` - * `` - * ``: - * regex: `/^[a-z0-9]+$/` - * ``: - * `` - * `! ` - * `` - * `` - * ` & ` - * `` - * `` - * ` | ` -* ``: An object containing the following: - * `"name"`: An ``, the name of the feature - * `"description"`: A `string` or array of `string`s, the description of the feature - * Optionally, `"dependencies"`: An array of ``s, the dependencies used by this feature diff --git a/docs/specifications/ports-overlay.md b/docs/specifications/ports-overlay.md deleted file mode 100644 index 632954fc34..0000000000 --- a/docs/specifications/ports-overlay.md +++ /dev/null @@ -1,183 +0,0 @@ -# Ports Overlay (Jun 19, 2019) - -**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** - -## 1. Motivation - -### A. Allow users to override ports with alternate versions - -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. - -This proposal adds an alternative to solve this problem. By allowing `vcpkg` users to specify additional locations in their file system containing ports for: - - * older or newer versions of libraries, - * modified libraries, or - * libraries not available in `vcpkg`. - -These locations will be searched when resolving port names during package installation, and override ports in `/ports`. - -### B. Allow users to keep unmodified upstream ports - -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. - - -## 2. Other design concerns - -* Allow a set of `vcpkg` commands to optionally accept additional paths to be used when searching for ports. -* Additional paths must take precedence when resolving names of ports to install. -* Allow users to specify multiple additional paths. -* Provide a simple disambiguation mechanism to resolve ambiguous port names. -* After resolving a port name, the installation process has to work the same as for ports shipped by `vcpkg`. -* This **DOES NOT ENABLE MULTIPLE VERSIONS** of a same library to be **INSTALLED SIDE-BY-SIDE**. - - -## 3. Proposed solution - -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 `/ports` directory).` - -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. - -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: - -* an individual port (directory containing a `CONTROL` file), - * `vcpkg install sqlite3 --overlay-ports="C:\custom-ports\sqlite3"` - -* a directory containing ports, - * `vcpkg install sqlite3 --overlay-ports=\\share\org\custom-ports` - -* a file listing paths to the former two. - > 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. - - * `vcpkg install sqlite3 --overlay-ports=..\port-repos.txt` - - _port-repos.txt_ - - ``` - .\experimental-ports\sqlite3 - C:\custom-ports - \\share\team\custom-ports - \\share\org\custom-ports - ``` - *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.* - -_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._ - -### Multiple additional paths - -Users can provide multiple additional paths by repeating the `--overlay-ports` option. - -``` -vcpkg install sqlite3 - --overlay-ports="..\experimental-ports\sqlite3" - --overlay-ports="C:\custom-ports" - --overlay-ports="\\share\team\custom-ports -``` - -### Overlaying ports - -Port name resolution follows the order in which additional paths are specified, with the first match being selected for installation, and falling back to `/ports` if the port is not found in any of the additional paths. - -No effort is made to compare version numbers inside the `CONTROL` files, or to determine which port contains newer or older files. - -### Examples - -Given the following directory structure: - - ``` - team-ports/ - |-- sqlite3/ - |---- CONTROL - |-- rapidjson/ - |---- CONTROL - |-- curl/ - |---- CONTROL - - my-ports/ - |-- sqlite3/ - |---- CONTROL - |-- rapidjson/ - |---- CONTROL - - vcpkg - |-- ports/ - |---- - |-- vcpkg.exe - |-- preferred-ports.txt - ``` -* #### Example #1: - - Running: - - ``` - vcpkg/vcpkg.exe install sqlite3 --overlay-ports=my-ports --overlay-ports=team-ports - ``` - - Results in `my-ports/sqlite3` getting installed as that location appears first in the command line arguments. - -* #### Example #2: - - A specific version of a port can be given priority by adding its path first in the list of arguments: - - ``` - vcpkg/vcpkg.exe install sqlite3 rapidjson curl - --overlay-ports=my-ports/rapidjson - --overlay-ports=vcpkg/ports/curl - --overlay-ports=team-ports - ``` - - Installs: - * `sqlite3` from `team-ports/sqlite3` - * `rapidjson` from `my-ports/rapidjson` - * `curl` from `vcpkg/ports/curl` - -* #### Example #3: - - > 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. - - Given the content of `preferred-ports.txt` as: - - ``` - ./ports/curl - /my-ports/rapidjson - /team-ports - ``` - - A location can be appended or prepended to those included in `preferred-ports.txt` via the command line, like this: - - ``` - vcpkg/vcpkg.exe install sqlite3 curl --overlay-ports=my-ports --overlay-ports=vcpkg/preferred-ports.txt - ``` - - Which results in `my-ports/sqlite3` and `vcpkg/ports/curl` getting installed. - - -## 4. Proposed User experience - -### i. User wants to preserve an older version of a port - -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. - -Alice wants to update some packages available in `vcpkg`. Unfortunately, updating her project to use the latest **OpenCV** is not immediately possible. - -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. - -``` -mkdir vcpkg-custom-ports -cd vcpkg-custom-ports -git init -cp -r %VCPKG_ROOT%/ports/opencv . -git add . -git commit -m "[opencv] Add OpenCV 3 port" -git remote add origin https://github.com//vcpkg-custom-ports.git -git push -u origin master -``` - -Now her team is able to use: - -``` -git clone https://github.com//vcpkg-custom-ports.git -vcpkg update --overlay-ports=./vcpkg-custom-ports -vcpkg upgrade --no-dry-run --overlay-ports=./vcpkg-custom-ports -``` - -to upgrade their packages and preserve the old version of **OpenCV** they require. diff --git a/docs/specifications/prefab.md b/docs/specifications/prefab.md deleted file mode 100644 index 8b84874426..0000000000 --- a/docs/specifications/prefab.md +++ /dev/null @@ -1,160 +0,0 @@ -# Vcpkg: export Android prefab Archives (AAR files) - -**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** - -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). - -For more information on Prefab, refer to: -* The [official prefab documentation](https://google.github.io/prefab). -* 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) - -_Note for Android Studio users: prefab packages are supported on Android Studio 4+_ - -## Requirements - -1. `ndk ` - -Set environment variable `ANDROID_NDK_HOME` to your android ndk installation. For example: - -```` -export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle -```` - -2. `7zip ` or `zip ` - -3. `maven ` - -4. Android triplets - -See [android.md](../users/android.md) for instructions on how to install the triplets. - -*Please note that in order to use "prefab" (see below), the four architectures are required. If any is missing the export will fail* - - -## Example exporting [jsoncpp] - -First "vcpkg install" the 4 android architectures (it is mandatory to export all 4 of them) - -```` -./vcpkg install jsoncpp:arm-android jsoncpp:arm64-android jsoncpp:x64-android jsoncpp:x86-android -```` - - -Then, export the prefab: - -Note: -* The `--prefab-maven` flag is optional. Call it if you maven is installed. -* The `--prefab-debug` flag will output instructions on how to use the prefab archive via gradle. - -``` -./vcpkg export --triplet x64-android jsoncpp --prefab --prefab-maven --prefab-debug -``` - -You will see an output like this: -``` -The following packages are already built and will be exported: - jsoncpp:arm64-android - -Exporting package jsoncpp... -[DEBUG] Found 4 triplets - arm64-android - x64-android - x86-android - arm-android - -... -... Lots of output... -... - -[INFO] Scanning for projects... -Downloading from central: https://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-clean-plugin/2.5/maven-clean-plugin-2.5.pom - -... -... Lots of output... -... - -[INFO] BUILD SUCCESS -[INFO] Total time: 2.207 s -[INFO] Finished at: 2020-05-10T14:42:28+02:00 - - -... -... Lots of output... -... - -[DEBUG] Configuration properties in Android Studio -In app/build.gradle - - com.vcpkg.ndk.support:jsoncpp:1.9.2 - -And cmake flags - - externalNativeBuild { - cmake { - arguments '-DANDROID_STL=c++_shared' - cppFlags "-std=c++17" - } - } - -In gradle.properties - - android.enablePrefab=true - android.enableParallelJsonGen=false - android.prefabVersion=${prefab.version} - -Successfully exported jsoncpp. Checkout .../vcpkg/prefab - -``` - -#### The output directory after export - -```` -prefab -└── jsoncpp/ - ├── aar/ - │   ├── AndroidManifest.xml - │   ├── META-INF/ - │   │   └── LICENSE - │   └── prefab/ - │   ├── modules/ - │   │   └── jsoncpp/ - │   │   ├── libs/ - │   │   │   ├── android.arm64-v8a/ - │   │   │   │   ├── abi.json - │   │   │   │   ├── include/ - │   │   │   │   │   └── json/ - │   │   │   │   │   ├── json.h - │   │   │   │   │   └── .... - │   │   │   │   └── libjsoncpp.so - │   │   │   ├── android.armeabi-v7a/ - │   │   │   │   ├── abi.json - │   │   │   │   ├── include/ - │   │   │   │   │   └── json/ - │   │   │   │   │   ├── json.h - │   │   │   │   │   └── .... - │   │   │   │   └── libjsoncpp.so - │   │   │   ├── android.x86/ - │   │   │   │   ├── abi.json - │   │   │   │   ├── include/ - │   │   │   │   │   └── json/ - │   │   │   │   │   ├── json.h - │   │   │   │   │   └── .... - │   │   │   │   └── libjsoncpp.so - │   │   │   └── android.x86_64/ - │   │   │   ├── abi.json - │   │   │   ├── include/ - │   │   │   │   └── json/ - │   │   │   │   │   ├── json.h - │   │   │   │   │   └── .... - │   │   │   └── libjsoncpp.so - │   │   └── module.json - │   └── prefab.json - ├── jsoncpp-1.9.2.aar - └── pom.xml -```` - -## Example consuming [jsoncpp] via vcpkg and prefab - -See the example repo here: - -https://github.com/atkawa7/prefab-vpkg-integration-sample diff --git a/docs/specifications/registries-2.md b/docs/specifications/registries-2.md deleted file mode 100644 index e2663ca3c7..0000000000 --- a/docs/specifications/registries-2.md +++ /dev/null @@ -1,561 +0,0 @@ -# Registries: Take 2 (including Git Registries) - -**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** - -**Up-to-date documentation is available at [Registries](../users/registries.md).** - -Originally, the design of registries was decided upon and written up in the [Registries RFC](registries.md). -However, as we've gotten further into the design process of git registries and versioning, -and discussed the interaction of versioning with registries, -it's become clear that the existing design was lacking. -We need to have an on-disk port database that is not tied to the ports tree. - -This RFC is a new design for registries, that includes this registry database. -It also includes the design for git registries, -which are likely to be the predominant form of registries in the wild. -They are also what we will start to treat the default registry as, -to allow for updating ports without updating the vcpkg executable -(likely necessary for binary releases). - -## Design Considerations - -After internal discussions of the relationship between versioning and registries, -it was clear that the existing design of registries does not play well with versioning. -It was also clear that it was necessary to have metadata about ports in a separate place from the ports tree; -in fact, after discussion, it was clear that the ports tree should be considered an implementation detail; -a backing store for build process information (e.g., `portfile.cmake` and the patches) and the manifest. - -From this, it's clear that vcpkg needs to add a new set of metadata. -The versioning implementation has decided on `port_versions`, and thus that's what this RFC uses. - -Since we're replacing the existing ports directory with a new method of describing ports, -this means that the ports directory is no longer anything but a data store. -This also means that the existing rules around locations of ports is no longer required; -however, it will still keep getting followed for the main repository, -and it's recommended that other registries follow the same pattern to make contributing easier. - -## What does the registry database look like? - -We don't wish to have the same problem as we do right now, -where there are nearly 1500 entries in a single directory. -We solve this by placing each database entry into `port_versions/-/.json`. -For example, the database entry for 7zip is in `port_versions/7-/7zip.json`. - -Each of these database entries contains all of the versions of the port throughout history, -along with versioning and feature metadata, so that we do not have to check out old manifests or CONTROL files -to get at that information. - -Each database entry file must be a top-level array of port version objects, which contain the following entries: -* A version field: `"version-string"`, `"version"`, etc. Same as in the manifest. -* Optionally, `"port-version"`: Same as in the manifest. - -And also contain a description of where to find the build files for this port; the possibilities include: - -* `"git-tree"`: The [git object ID] of a tree object; this is only allowed for git registries. - Note that this ID must be an ID from the repository where the registry is located. -* `"path"`: A path describing where to find the build files. - The first entry in this path should be `$`, which means "this path starts at the root of the registry". - No other kinds of paths are allowed. - * For example: `$/foo/bar` gives you `foo/bar` underneath the folder containing the `port_versions` directory. - * `/foo/bar` and `foo/bar` are both disallowed. - -Using a `"git-tree"` as a backend in a non-git registry, and using a `"path"` in a git registry, -is not permitted. Future extensions may include things like remote archives or git repositories, -or may allow `"path"` in git registries. - -Note that a registry entry should _always_ be additive; -deleting existing entries is unsupported and may result in bad behavior. -The only modification to existing entries that is allowable is moving the backing store -for the build files, assuming that the new build files are equivalent to the old build files. -(For example, a filesystem registry might have a new way of laying out where ports are). - -Additionally, we'd like a new way of describing the set of ports that make up a "baseline". -This is currently done with the reference of the vcpkg git repository - -each reference has a set of versions that are tested against each other, -and this is a major feature of vcpkg. -We wish to have the same feature in the new versioning world, -and so we'll have a set of baseline versions in the registry database. - -Baselines act differently between git registries or the builtin registry, -and in filesystem registries. -In git registries and the builtin registry, -since there's a history that one can access, -a baseline is the `"default"` entry in the baseline at the reference specified. -In filesystem registries, since there is no accessible history, -the baseline identifiers are mapped directly to entries in the baseline file, -without translation; by default, the `"default"` entry is used. - -These baselines are placed in `port_versions/baseline.json`. -This is an object mapping baseline names to baseline objects, -where baseline objects map port names to version objects. -A version object contains `"baseline"`, which is un-schemed version, -and optionally `"port-version"`. - -[git object ID]: https://git-scm.com/book/en/v2/Git-Internals-Git-Objects - -### Example of a baseline file - -The following is a reasonable baseline.json for a filesystem registry that only has two ports: - -```json -{ - "default": { - "abseil": { "baseline": "2020-03-03" }, - "zlib": { "baseline": "1.2.11", "port-version": 9 } - }, - "old": { - "abseil": { "baseline": "2019-02-11" }, - "zlib": { "baseline": "1.2.11", "port-version": 3 } - }, - "really-old": { - "zlib": { "baseline": "1.2.9" } - } -} -``` - -### Example of a registry database entry file - -Note: This file assumes that the versions RFC has been implemented, -and thus that minimum versions are required; -the syntax may change in the time between now and finishing the implementation. - -This example is of `ogre`, since this port has both features and dependencies; -remember that this file would be `port_versions/o-/ogre.json`. - -```json -[ - { - "version-string": "1.12.7", - "git-tree": "466e96fd2e17dd2453aa31dc0bc61bdcf53e7f61", - }, - { - "version-string": "1.12.1", - "port-version": 1, - "git-tree": "0de81b4f7e0ec24966e929c2ea64e16c15e71d5e", - }, - ... -] -``` - -#### Filesystem Registry Databases - -Filesystem registries are the simplest possible registry; -they have a `port_versions` directory at the top-level, which contains the registry database. -It's expected that the filesystem registry would have a filesystem backing store: -something like the existing `ports` directory, except with separate versions. -There won't be a specific way to lay the ports tree out as mandated by the tool, -as we are treating the ports tree as an implementation detail of the registry; -it's simply a way to get the files for a port. -As an example, let's assume that the registry is laid out something like this: - -``` -/ - port_versions/ - baseline.json - a-/ - abseil.json - asmjit.json - o-/ - ogre.json - ports/ - a-/ - abseil/ - 2020-03-03_7/ - vcpkg.json - portfile.cmake - ... - 2020-03-03_8/ - vcpkg.json - portfile.cmake - ... - ... - asmjit/ - 2020-05-08/ - CONTROL - portfile.cmake - ... - 2020-07-22/ - vcpkg.json - portfile.cmake - ... - o-/ - ogre/ - 1.12.7/ - ... - 1.12.1/ - ... - ... - ... -``` - -Then, let's look at updating `asmjit` to latest. - -The current manifest file, in `asmjit/2020-07-22/vcpkg.json` looks like: - -```json -{ - "name": "asmjit", - "version-string": "2020-07-22", - "description": "Complete x86/x64 JIT and Remote Assembler for C++", - "homepage": "https://github.com/asmjit/asmjit", - "supports": "!arm" -} -``` - -while the current `port_versions/a-/asmjit.json` looks like: - -```json -[ - { - "version-string": "2020-07-22", - "path": "$/ports/a-/asmjit/2020-07-22" - }, - { - "version-string": "2020-05-08", - "path": "$/ports/a-/asmjit/2020-05-08" - } -] -``` - -with `port_versions/baseline.json` looking like: - -```json -{ - "default": { - ..., - "asmjit": { "baseline": "2020-07-22" }, - ... - } -} -``` - -and we'd like to update to `2020-10-08`. -We should first copy the existing implementation to a new folder: - -```sh -$ cp -r ports/a-/asmjit/2020-07-22 ports/a-/asmjit/2020-10-08 -``` - -then, we'll make the edits required to `ports/a-/asmjit/2020-10-08` to update to latest. -We should then update `port_versions/a-/asmjit.json`: - -```json -[ - { - "version-string": "2020-10-08", - "path": "$/ports/a-/asmjit/2020-10-08" - }, - { - "version-string": "2020-07-22", - "path": "$/ports/a-/asmjit/2020-07-22" - }, - { - "version-string": "2020-05-08", - "path": "$/ports/a-/asmjit/2020-05-08" - } -] -``` - -and update `port_versions/baseline.json`: - -```json -{ - "default": { - ..., - "asmjit": { "baseline": "2020-10-08" }, - ... - } -} -``` - -and we're done 😊. - -#### Git Registry Databases - -Git registries are not quite as simple as filesystem registries, -but they're still pretty simple, and are likely to be the most common: -the default registry is a git registry, for example. -There is not a specific way the tool requires one to lay out the backing store, -as long as it's possible to get an object hash that corresponds to a checked-in git tree -of the build information. -This allows, for example, the current vcpkg default registry way of laying out ports, -where the latest version of a port `

` is at `ports/

`, -and it also allows for any number of other designs. -One interesting design, for example, -is having an `old-ports` branch which is updated whenever someone want to backfill versions; -then, one could push the old version to the `old-ports` branch, -and then update the HEAD branch with the git tree of the old version in `port_versions/p-/

`. - -As above, we want to update `asmjit` to latest; let's assume we're working in the default vcpkg registry -(the repository): - -The current manifest file for `asmjit` looks like: - -```json -{ - "name": "asmjit", - "version-string": "2020-07-22", - "description": "Complete x86/x64 JIT and Remote Assembler for C++", - "homepage": "https://github.com/asmjit/asmjit", - "supports": "!arm" -} -``` - -and the current `port_versions/a-/asmjit.json` looks like: - -```json -[ - { - "version-string": "2020-07-22", - "git-tree": "fa0c36ba15b48959ab5a2df3463299e1d2473b6f" - } -] -``` - -Now, let's update it to the latest version: - -```json -{ - "name": "asmjit", - "version-string": "2020-10-08", - "description": "Complete x86/x64 JIT and Remote Assembler for C++", - "homepage": "https://github.com/asmjit/asmjit", - "supports": "!arm" -} -``` - -and make the proper edits to the portfile.cmake. Then, let's commit the changes: - -```cmd -> git add ./ports/asmjit -> git commit -m "[asmjit] update asmjit to 2020-10-08" -``` - -In `git-tree` mode, one needs to commit the new version of the port to get the git tree hash; -we use `git rev-parse` to do so: - -```cmd -> git rev-parse HEAD:ports/asmjit -2bb51d8ec8b43bb9b21032185ca8123da10ecc6c -``` - -and then modify `port_versions/a-/asmjit.json` as follows: - -```json -[ - { - "version-string": "2020-10-08", - "git-tree": "2bb51d8ec8b43bb9b21032185ca8123da10ecc6c" - }, - { - "version-string": "2020-07-22", - "git-tree": "fa0c36ba15b48959ab5a2df3463299e1d2473b6f" - } -] -``` - -Then we can commit and push this new database with: - -```sh -$ git add port_versions -$ git commit --amend --no-edit -$ git push -``` - -## Consuming Registries - -The `vcpkg-configuration.json` file from the [first registries RFC](registries.md) -is still the same, except that the registries have a slightly different layout. -A `` is still an object with the following fields: -* Optionally, `"default-registry"`: A `` or `null` -* Optionally, `"registries"`: An array of ``s - -Additionally, `` is still the same; -a `` object, plus the following properties: -* Optionally, `"baseline"`: A named baseline. Defaults to `"default"`. -* Optionally, `"packages"`: An array of ``s - -however, ``s are now slightly different: -* ``: - * `"kind"`: The string `"builtin"` -* ``: - * `"kind"`: The string `"filesystem"` - * `"path"`: A path -* ``: - * `"kind"`: The string `"git"` - * `"repository"`: A URI - -The `"packages"` field of distinct registries must be disjoint, -and each `` must have at the `"packages"` property, -since otherwise there's no point. - -As an example, a package which uses a different default registry, and a different registry for boost, -might look like the following: - -```json -{ - "default-registry": { - "kind": "filesystem", - "path": "vcpkg-ports" - }, - "registries": [ - { - "kind": "builtin", - "packages": [ "cppitertools" ] - } - ] -} -``` - -This will install `fmt` from `/vcpkg-ports`, -and `cppitertools` and the `boost` ports from the registry that ships with vcpkg. -Notably, this does not replace behavior up the tree -- only the `vcpkg-configuration.json`s -for the current invocation do anything. - -### Filesystem Registries - -A filesystem registry takes on the form: - -* `"kind"`: The string `"filesystem"` -* `"path"`: The path to the filesystem registry's root, i.e. the directory containing the `port_versions` directory. - -```json -{ - "kind": "filesystem", - "path": "vcpkg-registry" -} -``` - -Unlike git registries, where there's quite a bit of interesting stuff going on, -there isn't much stuff to do with filesystem registries. -We simply use the registry database at `/port_versions` to get information about ports. - -### Git Registries - -A git registry takes on the form: - -* `"kind"`: The string `"git"` -* `"repository"`: The URL at which the git repository lives. May be any kind of URL that git understands - -```json -{ - "kind": "git", - "repository": "https://github.com/microsoft/vcpkg" -} -``` - -Whenever the first vcpkg command is run with a git registry, -vcpkg notes down the exact commit that HEAD points to at the time of the run in the `vcpkg-lock.json` file. -This will be used as the commit which vcpkg takes the `"default"` baseline from, -and vcpkg will only update that commit when `vcpkg update` is run. - -Since the `"versions"` field is strictly additive, we don't consider older refs than `HEAD`. -We update the repository on some reasonable clip. -Likely, whenever a command is run that will change the set of installed ports. - -#### `vcpkg-lock.json` - -This file will contain metadata that we need to save across runs, -to allow us to keep a "state-of-the-world" that doesn't change unless one explicitly asks for it to change. -This means that, even across different machines, the same registries will be used. -We will also be able to write down version resolution in this file as soon as that feature is added. - -It is recommended that one adds this `vcpkg-lock.json` to one's version control. -This file is machine generated, and it is not specified how it's laid out; -however, for purposes of this RFC, we will define how it relates to git registries. - -In `vcpkg-lock.json`, in the top level object, -there will be a `"registries"` property that is an object. -This object will contain a `"git"` field, which is an array of git-registry objects, -that contain: - -* `"repository"`: The `"repository"` field from the git registry object -* `"baseline"`: The name of the baseline that we've used -* `"baseline-ref"`: The ref which we've gotten the specific baseline from. - -For example, a `vcpkg-lock.json` might look like: - -```json -{ - "registries": { - "git": [ - { - "repository": "https://github.com/microsoft/vcpkg", - "baseline": "default", - "baseline-ref": "6185aa76504a5025f36754324abf307cc776f3da" - } - ] - } -} -``` - -#### `vcpkg update` - -You'll notice that once the repository is added the first time, -there is only one way to update the repository to the tag at a later date - deleting the lock file. -We additionally want to add support for the user updating the registry by themselves - -they will be able to do this via the `vcpkg update` command. -The `vcpkg update` command will, for each git registry, -update the registry and repoint the `"commit"` field in `vcpkg-lock.json` to the latest `HEAD`. - -There is no way to update only one git registry to a later date, since versions are strictly additive. - -## Git Registries: Implementation on Disk - -There are two implementations on disk to consider here: the implementation of the registry database, -and once we have the database entries for the ports, accessing the port data from the git tree object. - -Both of these implementations are placed in the vcpkg cache home (shared by binary caching archives). -On unix, this is located at `$XDG_CACHE_HOME/vcpkg` if the environment variable exists, -otherwise `$HOME/.cache/vcpkg`; on Windows, it's located at `%LOCALAPPDATA%\vcpkg`. -In this document, we use the variable `$CACHE_ROOT` to refer to this folder. -We will add a new folder, `$CACHE_ROOT/registries`, which will contain all the data we need. - -First, we'll discuss the registry database. - -### Registry Database - -At `$CACHE_ROOT/registries/git`, -we'll create a new git repository root which contains all information from all git registries, -since the hashes should be unique, and this allows for deduplication -across repositories which have the same commits (e.g., for mirrors). -In order to get the data from git registries, we simply `fetch` the URL of the git registry. - -In order to grab a specific database entry from a git registry, `git show` is used to grab the -file from the right commit: `git show -- port_versions/-/.json`. - -One unfortunate thing about having one directory being used for all vcpkg instances on a machine is -that it's possible to have an issue with concurrency - for example, after `fetch`ing the latest HEAD -of `https://github.com/microsoft/vcpkg`, another vcpkg process might fetch the latest HEAD of -`https://github.com/meow/vcpkg` before the first vcpkg process has the chance to `git rev-parse FETCH_HEAD`. -Since the first vcpkg process will run `git rev-parse` after the second fetch is done, -instead of getting the `HEAD` of `microsoft/vcpkg`, they instead get the `HEAD` of `meow/vcpkg`. -We will solve this by having a mutex file in `$CACHE_ROOT/registries/git` -that vcpkg locks before any fetches (and unlocks after `rev-parse`ing). - -### Accessing Port Data from `git-tree`s - -Once we've done version resolution and everything with the database, -we then need to access the port data from the git history. -We will add a new folder, `$CACHE_ROOT/registries/git-trees`, into which we'll check out the port data. - -In this `git-trees` directory, we will have all of the trees we check out, at their hashes. -For example, the asmjit port data from above will be located at -`git-trees/2bb51d8ec8b43bb9b21032185ca8123da10ecc6c`. -We will add a mutex file in this `git-trees` directory as well which is taken whenever -we are checking out a new git tree. -We wish to allow multiple vcpkg instances to read port data at a time, -and thus we do the check outs semi-atomically - if `git-trees/` exists, -then the `` must be completely checked out. -vcpkg does this by first checking out to a temporary directory, -and then renaming to the actual hash. - -## Future Extensions - -The way forward for this is to allow the `"builtin"` registry to be a git registry, -in order to support packaging and shipping vcpkg as a binary. -This is currently our plan, although it definitely is still a ways out. -Git registries _are_ an important step on that road, -but are also a good way to support both enterprise, -and experimentation by our users. -They allow us a lot more flexibility than we've had in the past. \ No newline at end of file diff --git a/docs/specifications/registries.md b/docs/specifications/registries.md deleted file mode 100644 index 68be1409d0..0000000000 --- a/docs/specifications/registries.md +++ /dev/null @@ -1,289 +0,0 @@ -# Package Federation: Custom Registries - -**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** - -**Up-to-date documentation is available at [Registries](../users/registries.md).** - -As it is now, vcpkg has over 1400 ports in the default registry (the `/ports` directory). -For the majority of users, this repository of packages is enough. However, many enterprises -need to more closely control their dependencies for one reason or another, and this document -lays out a method which we will build into vcpkg for exactly that reason. - -## Background - -A registry is simply a set of packages. In fact, there is already a registry in vcpkg: the default one. -Package federation, implemented via custom registries, allows one to add new packages, -edit existing packages, and have as much or as little control as one likes over the dependencies that one uses. -It gives the control over dependencies that an enterprise requires. - -### How Does the Current Default Registry Work? - -Of course, the existing vcpkg tool does have packages in the official, -default registry. The way we describe these packages is in the ports tree – -at the base of the vcpkg install directory, there is a directory named ports, -which contains on the order of 1300 directories, one for each package. Then, -in each package directory, there are at least two files: a CONTROL or -vcpkg.json file, which contains the name, version, description, and features -of the package; and a portfile.cmake file which contains the information on -how to download and build the package. There may be other files in this -registry, like patches or usage instructions, but only those two files are -needed. - -### Existing vcpkg Registry-like Features - -There are some existing features in vcpkg that act somewhat like a custom -registry. The most obvious feature that we have is overlay ports – this -feature allows you to specify any number of directories as "overlays", which -either contain a package definition directly, or which contain some number of -package directories; these overlays will be used instead of the ports tree -for packages that exist in both places, and are specified exclusively on the -command line. Additionally, unfortunately, if one installs a package from -overlay ports that does not exist in the ports tree, one must pass these -overlays to every vcpkg installation command. - -There is also the less obvious "feature" which works by virtue of the ports -tree being user-editable: one can always edit the ports tree on their own -machine, and can even fork vcpkg and publish their own ports tree. -Unfortunately, this then means that any updates to the source tree require -merges, as opposed to being able to fast-forward to the newest sources. - -### Why Registries? - -There are many reasons to want custom registries; however, the most important reasons are: - -* Legal requirements – a company like Microsoft or Google - needs the ability to strictly control the code that goes into their products, - making certain that they are following the licenses strictly. - * There have been examples in the past where a library which is licensed under certain terms contains code - which is not legally allowed to be licensed under those terms (see [this example][legal-example], - where a person tried to merge Microsoft-owned, Apache-licensed code into the GPL-licensed libstdc++). -* Technical requirements – a company may wish to run their own tests on the packages they ship, - such as [fuzzing]. -* Other requirements – an organization may wish to strictly control its dependencies for a myriad of other reasons. -* Newer versions – vcpkg may not necessarily always be up to date for all libraries in our registry, - and an organization may require a newer version than we ship; - they can very easily update this package and have the version that they want. -* Port modifications – vcpkg has somewhat strict policies on port modifications, - and an organization may wish to make different modifications than we do. - It may allow that organization to make certain that the package works on triplets - that our team does not test as extensively. -* Testing – just like port modifications, if a team wants to do specific testing on triplets they care about, - they can do so via their custom registry. - -Then, there is the question of why vcpkg needs a new solution for custom registries, -beyond the existing overlay ports feature. There are two big reasons – -the first is to allow a project to define the registries that they use for their dependencies, -and the second is the clear advantage in the user experience of the vcpkg tool. -If a project requires specific packages to come from specific registries, -they can do so without worrying that a user accidentally misses the overlay ports part of a command. -Additionally, beyond a feature which makes overlay ports easier to use, -custom registries allow for more complex and useful infrastructure around registries. -In the initial custom registry implementation, we will allow overlay ports style paths, -as well as git repositories, which means that people can run and use custom registries -without writing their own infrastructure around getting people that registry. - -It is the intention of vcpkg to be the most user-friendly package manager for C++, -and this allows us to fulfill on that intention even further. -As opposed to having to write `--overlay-ports=path/to/overlay` for every command one runs, -or adding an environment variable `VCPKG_OVERLAY_PORTS`, -one can simply write vcpkg install and the registries will be taken care of for you. -As opposed to having to use git submodules, or custom registry code for every project, -one can write and run the infrastructure in one place, -and every project that uses that registry requires only a few lines of JSON. - -[legal-example]: https://gcc.gnu.org/legacy-ml/libstdc++/2019-09/msg00054.html -[fuzzing]: https://en.wikipedia.org/wiki/Fuzzing - -## Specification - -We will be adding a new file that vcpkg understands - `vcpkg-configuration.json`. -The way that vcpkg will find this file is different depending on what mode vcpkg is in: -in classic mode, vcpkg finds this file alongside the vcpkg binary, in the root directory. -In manifest mode, vcpkg finds this file alongside the manifest. For the initial implementation, -this is all vcpkg will look for; however, in the future, vcpkg will walk the tree and include -configuration all along the way: this allows for overriding defaults. -The specific algorithm for applying this is not yet defined, since currently only one -`vcpkg-configuration.json` is allowed. - -The only thing allowed in a `vcpkg-configuration.json` is a `` object. - -A `` is an object: -* Optionally, `"default-registry"`: A `` or `null` -* Optionally, `"registries"`: An array of ``s - -Since this is the first RFC that adds anything to this field, -as of now the only properties that can live in that object will be -these. - -A `` is an object matching one of the following: -* ``: - * `"kind"`: The string `"builtin"` -* ``: - * `"kind"`: The string `"directory"` - * `"path"`: A path -* ``: - * `"kind"`: The string `"git"` - * `"repository"`: A URI - * Optionally, `"path"`: An absolute path into the git repository - * Optionally, `"ref"`: A git reference - -A `` is a `` object, plus the following properties: -* Optionally, `"scopes"`: An array of ``s -* Optionally, `"packages"`: An array of ``s - -The `"packages"` and `"scopes"` fields of distinct registries must be disjoint, -and each `` must have at least one of the `"scopes"` and `"packages"` property, -since otherwise there's no point. - -As an example, a package which uses a different default registry, and a different registry for boost, -might look like the following: - -```json -{ - "default-registry": { - "kind": "directory", - "path": "vcpkg-ports" - }, - "registries": [ - { - "kind": "git", - "repository": "https://github.com/boostorg/vcpkg-ports", - "ref": "v1.73.0", - "scopes": [ "boost" ] - }, - { - "kind": "builtin", - "packages": [ "cppitertools" ] - } - ] -} -``` - -This will install `fmt` from `/vcpkg-ports`, -`cppitertools` from the registry that ships with vcpkg, -and any `boost` dependencies from `https://github.com/boostorg/vcpkg-ports`. -Notably, this does not replace behavior up the tree -- only the `vcpkg-configuration.json`s -for the current invocation do anything. - -### Behavior - -When a vcpkg command requires the installation of dependencies, -it will generate the initial list of dependencies from the package, -and then run the following algorithm on each dependency: - -1. Figure out which registry the package should come from by doing the following: - 1. If there is a registry in the registry set which contains the dependency name in the `"packages"` array, - then use that registry. - 2. For every scope, in order from most specific to least, - if there is a registry in the registry set which contains that scope in the `"scopes"` array, - then use that registry. - (For example, for `"cat.meow.cute"`, check first for `"cat.meow.cute"`, then `"cat.meow"`, then `"cat"`). - 3. If the default registry is not `null`, use that registry. - 4. Else, error. -2. Then, add that package's dependencies to the list of packages to find, and repeat for the next dependency. - -vcpkg will also rerun this algorithm whenever an install is run with different configuration. - -### How Registries are Laid Out - -There are three kinds of registries, but they only differ in how the registry gets onto one's filesystem. -Once the registry is there, package lookup runs the same, with each kind having it's own way of defining its -own root. - -In order to find a port `meow` in a registry with root `R`, vcpkg first sees if `R/meow` exists; -if it does, then the port root is `R/meow`. Otherwise, see if `R/m-` exists; if it does, -then the port root is `R/m-/meow`. (note: this algorithm may be extended further in the future). - -For example, given the following port root: - -``` -R/ - abseil/... - b-/ - boost/... - boost-build/... - banana/... - banana/... -``` - -The port root for `abseil` is `R/abseil`; the port root for `boost` is `R/b-/boost`; -the port root for `banana` is `R/banana` (although this duplication is not recommended). - -The reason we are making this change to allow more levels in the ports tree is that ~1300 -ports are hard to look through in a tree view, and this allows us to see only the ports we're -interested in. Additionally, no port name may end in a `-`, so this means that these port subdirectories -will never intersect with actual ports. Additionally, since we use only ASCII for port names, -we don't have to worry about graphemes vs. code units vs. code points -- in ASCII, they are equivalent. - -Let's now look at how different registry kinds work: - -#### `` - -For a ``, there is no configuration required. -The registry root is simply `/ports`. - -#### `` - -For a ``, it is again fairly simple. -Given `$path` the value of the `"path"` property, the registry root is either: - -* If `$path` is absolute, then the registry root is `$path`. -* If `$path` is drive-relative (only important on Windows), the registry root is - `(drive of vcpkg.json)/$path` -* If `$path` is relative, the registry root is `(directory of vcpkg.json)/$path` - -Note that the path to vcpkg.json is _not_ canonicalized; it is used exactly as it is seen by vcpkg. - -#### `` - -This registry is the most complex. We would like to cache existing registries, -but we don't want to ignore new updates to the registry. -It is the opinion of the author that we want to find more updates than not, -so we will update the registry whenever the `vcpkg.json` or `vcpkg-configuration.json` -is modified. We will do so by keeping a sha512 of the `vcpkg.json` and `vcpkg-configuration.json` -inside the `vcpkg-installed` directory. - -We will download the specific ref of the repository to a central location (and update as needed), -and the root will be either: ``, if the `"path"` property is not defined, -or else `/` if it is defined. -The `"path"` property must be absolute, without a drive, and will be treated as relative to -the path to the repository. For example: - -```json -{ - "kind": "git", - "repository": "https://github.com/microsoft/vcpkg", - "path": "/ports" -} -``` - -is the correct way to refer to the registry built in to vcpkg, at the latest version. - -The following are all incorrect: - -```json -{ - "$reason": "path can't be drive-absolute", - "kind": "git", - "repository": "https://github.com/microsoft/vcpkg", - "path": "F:/ports" -} -``` - -```json -{ - "$reason": "path can't be relative", - "kind": "git", - "repository": "https://github.com/microsoft/vcpkg", - "path": "ports" -} -``` - -```json -{ - "$reason": "path _really_ can't be relative like that", - "kind": "git", - "repository": "https://github.com/microsoft/vcpkg", - "path": "../../meow/ports" -} -``` diff --git a/docs/specifications/scripts-extraction.md b/docs/specifications/scripts-extraction.md deleted file mode 100644 index 396e2d4e02..0000000000 --- a/docs/specifications/scripts-extraction.md +++ /dev/null @@ -1,66 +0,0 @@ -# Scripts Tree Extraction - -**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** - -## Background - -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. - -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. - -To that end we are auditing the contents of the scripts tree to make sure it is a solid foundation for future work. - -The work list is contained in [Issue #16188]. - -[Issue #16188]: https://github.com/microsoft/vcpkg/issues/16188 - -## Audit Points - -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. - -These are design ideals that we may break in some limited cases where that makes sense. - -- We always use `cmake_parse_arguments` rather than function parameters, or referring to `${ARG}`. - - Exception: there are exclusively positional parameters. This should be _very rare_. - - In this case, positional parameters should be put in the function declaration - (rather than using `${ARG}`), and should be named according to local rules - (i.e. `snake_case`). - - Exception: positional parameters that are optional should be given a name via - `set(argument_name "${ARG}") after checking `${ARGC}`. - - Note: in cases where there are positional parameters along with non-positional parameters, positional parameters should be referred to by `arg_UNPARSED_ARGUMENTS`. -- All `cmake_parse_arguments` use `PARSE_ARGV` for resistance to embedded semicolons. -- All `foreach` loops use `IN LISTS` for resistance to embedded semicolons. -- The variable `${ARGV}` is unreferenced. -- We use functions, not macros or top level code. -- 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) -- All non-splat variable expansions are in quotes "". -- There are no "pointer" parameters (where a user passes a variable name rather than the contents) except for out parameters. -- Undefined names are not referenced. -- Out parameters only set `PARENT_SCOPE`. -- `CACHE` variables are not used. -- `include()`s are removed and fixes to `port.cmake` et al. are made as necessary to avoid this. -- `foreach(RANGE)`'s arguments _must always be_ natural numbers, and `` _must always be_ less than or equal to ``. - - This should be checked. - -### Naming Variables - -- `cmake_parse_arguments`: set prefix to `"arg"` -- local variables are named `snake_case` -- Internal global variable names are named `Z_VCPKG_`. -- External experimental global variable names are named `X_VCPKG_`. -- Internal functions are named `z_vcpkg_*` - - Functions which are internal to a single function (i.e., helper functions) - are named `[z_]_`, where `` is the name of the function they are - a helper to, and `` is what the helper function does. - - `z_` should be added to the front if `` doesn't have a `z_`, - but don't name a helper function `z_z_foo_bar`. -- Public global variables are named `VCPKG_`. - -## Prognosis - -Not everything should remain in the scripts tree. As part of this audit, each helper will be dealt with in one of several ways: - -- Stay in scripts tree -- Deleted outright -- Moved to a tool port -- Deprecated diff --git a/docs/specifications/versioning.md b/docs/specifications/versioning.md deleted file mode 100644 index 1ad9ef8dcf..0000000000 --- a/docs/specifications/versioning.md +++ /dev/null @@ -1,357 +0,0 @@ -# Versioning Specification - -**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.** - -**Up-to-date documentation is available at [Versioning](../users/versioning.md).** - -## Glossary -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. - -**Library**: A piece of software (source code, binary files, documentation, license, etc.) that is intended to be reused by other software. - -**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. - -**Port**: A vcpkg specific term, a port contains: - -* Metadata about a package: package version, supported features, dependencies, etc. -* Instructions to acquire, build if necessary, and install the package. - -## 1 Enabling package versioning -On launch, the versioning feature will be disabled by default. Users can enable this feature by setting the `versions` feature flag. - -Example: -``` -vcpkg --feature-flags=versions install -``` - -### 1.1 Proposed experience -This feature requires the use of manifests to declare project dependencies. To allow versioning, the following features are added to manifests: - -* Ability to declare a package's versioning scheme. -* Ability to declare version constraints on dependencies. -* Ability for a top-level manifest to override all other version constraints. -* Ability to declare a baseline for all versions. - -Example: A manifest (`vcpkg.json`) using versioning features. -```json -{ - "name": "versions-test", - "version": "1.0.0", - "dependencies": ["fmt", {"name": "zlib", "version>=": "1.2.11"}], - "$x-default-baseline": "9fd3bd594f41afb8747e20f6ac9619f26f333cbe" -} -``` - -The example above shows some new manifest properties: -* `"version"`: Declares a version using a dot-separated versioning scheme (`1.0.0`). -* `"version>="`: Declares a minimum version constraint on package `zlib`. -* `"$x-default-baseline"`: Declares a baseline version for all packages. - -All these new features are described in more detail in this document. - -## 2 Specifying package versions -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: -* Semantic versions -* Dates -* Repository commits -* Arbitrary strings - -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. - -### 2.1 Port versions -Package versioning information is divided in two parts: a version string and a port version. -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. - -Packages can also include the port version as part of a version constraint by using the “port-version” property on their dependencies. - -#### `port-version` - -An integer value that increases each time a vcpkg-specific change is made to the port. - -The rules for port versions are: -* Start at 0 for the original version of the port, -* increase by 1 each time a vcpkg-specific change is made to the port that does not increase the version of the package, -* and reset to 0 each time the version of the package is updated. - -Defaults to 0 if omitted. - -### 2.2 Package versions -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. - -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. - -The versioning schemes understood by vcpkg are: - -Manifest property | Versioning scheme -------------------|------------------------------------ -`version` | For dot-separated numeric versions -`version-semver` | For SemVer compliant versions -`version-date` | For dates in the format YYYY-MM-DD -`version-string` | For arbitrary strings - -A manifest must contain only one version declaration. - -#### `version` -Accepts version strings that follow a relaxed, dot-separated-, semver-like scheme. - -The version is logically composed of dot-separated (`.`) numeric sections. Each section must contain an integer positive number with no leading zeroes. - -The regex pattern for this versioning scheme is: `(0|[1-9]\d*)(\.(0|[1-9]\d*))*` - -_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. - -Example: -`0` < `0.1` < `0.1.0` < `1` < `1.0.0` < `1.0.1` < `1.1`< `2.0.0` - -#### `version-semver` -Accepts version strings that follow semantic versioning conventions as described in the [semantic versioning specification](https://semver.org/#semantic-versioning-specification-semver). - -_Sorting behavior_: Strings are sorted following the rules described in the semantic versioning specification. - -Example: -`1.0.0-1` < `1.0.0-alpha` < `1.0.0-beta` < `1.0.0` < `1.0.1` < `1.1.0` - -#### `version-date` - -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. - -The regex pattern for this versioning scheme is: `\d{4}-\d{2}-\d{2}(\.(0|[1-9]\d*))*`. - -_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. - -Examples: -`2020-01-01` < `2020-01-01.1` < `2020-02-01.1.2` < `2020-02-01.1.3` < `2020-02-01` - -#### `version-string` -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. - -_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. - -Examples: -`apple` <> `orange` <> `orange.2` <> `orange2` -`watermelon` (`port-version`: 0) < `watermelon` (`port-version`: 1) - -##### Example: Manifests using different versioning schemes -```json -{ - "name": "openssl", - "version": "1.1.1", - "port-version": 0 -} -``` -```json -{ - "name": "bzip2", - "version-semver": "1.0.8", -} -``` -```json -{ - "name": "abseil", - "version-date": "2020-03-03", - "port-version": 8 -} -``` -```json -{ - "name": "d3dx12", - "version-string": "may2020", - "port-version": 0 -} -``` - -## 3 Specifying dependency versions - -### 3.1 On manifest files -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. - -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**. - -#### Version constraints -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"`. - -#### Registry baseline -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. - -But what is a baseline? - -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: - -```json -{ - "default": [ - { - ... - "fmt": { "version-semver": "7.1.2", "port-version": 0}, - ... - } - ] -} -``` - -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. - -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. - -Baselines define a minimum version constraint an all packages contained in it. - -For example, if the baseline contains the entry: -``` -“fmt”: { “version-semver”: “7.1.2”, “port-version”: 0 } -``` - -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`. - -#### Overrides -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. - -## 4 Version constraints - -### 4.1 Declaring a baseline -For the initial implementation, the method to declare a baseline is to set the `“$x-default-baseline”` property. - -The use of `“$x-default-baseline”` is temporary and will very likely change in the future, as we work on implementing custom registries. - -#### `$x-default-baseline` -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. - -When resolving version constraints for a package, vcpkg will look for a baseline version: -* First by looking at the baseline file in the given commit ID. -* If the given commit ID does not contain a baseline file, vcpkg will fallback to use the local baseline file instead. -* If there’s no local baseline file, vcpkg will use the version currently available in the ports directory. - -_NOTE: If a baseline file is found, but it does not contain an entry for the package, the vcpkg invocation will fail._ - -Example: -```json -{ - "name": "project", - "version": "1.0.0", - "dependencies": ["zlib", "fmt"], - "$x-default-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe" -} -``` - -Baselines can be used without any other version constraints to obtain behavior close to using “classic” mode. - -### 4.2 Declaring minimum version constraints -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). - -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: -* Is predictable and easy to understand. -* User controls when upgrades happen, as in, no upgrades are performed automatically when a new version is released. -* Avoids using a SAT solver. - -Minimum version requirements are expressed by using the `"version>="` property in the dependencies list. - -Example: -```json -{ - "name": "project", - "version-semver": "1.0.0", - "dependencies": [ - { "name": "zlib", "version>=": "1.2" }, - { "name": "rapidjson", "version>=": "2020-02-01" } - ] -} -``` - -### 4.3 Declaring port version constraints -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. - -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. - -Example: -```json -{ - "name": "project", - "version-semver": "1.0.0", - "dependencies": [ - { "name": "zlib", "version>=": "1.2" }, - { "name": "rapidjson", "version=": "2020-02-01", "port-version": 2 } - ] -} -``` - -### 4.4 Declaring overrides -Overrides are declared as an array of package version declarations. - -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. - -Example: -```json -{ - "name": "project", - "version": "1.0.0", - "dependencies": ["cpprestsdk"], - "overrides": [{"name":"zlib", "version-semver":"1.2.10"}], - "$x-default-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe" -} -``` - -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`. - -## 5 Design considerations - -### 5.1 Constraint resolution -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. - -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. - -* Add all top-level constraints to the plan. -* Recursively add transitive constraints to the plan. -* Each time a constraint is added for a package, also add it’s baseline version as a minimum constraint. -* Each time a constraint is added: - * If an override exists for the package, select the version in the override. - * Otherwise: - * If there is no previous version selected. - * Select the minimal version that satisfies the constraint. - * If there is a previous version selected: - * If the versioning scheme of the new constraint does not match that of the previously selected version: - * Add a version conflict. - * If the constraint’s version is not comparable to the previously selected version. For example, comparing “version-string: apple” to “version-string: orange”: - * Add a version conflict. - * If the constraints version is higher than the previously selected version: - * Select the highest version. - * Otherwise, keep the previous selection. -* Review the plan: - * If there are no conflicts, install the selected packages. - * Otherwise, report the conflicts to the user. - -### 5.2 Acquiring port versions -Although the concept of package versions has always been present in vcpkg, the concept of version constraints has been not. - -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. - -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. - -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. - -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. - -Example: generated `zlib.json` -```json -{ - "versions": [ - { - "git-tree": "2dfc991c739ab9f2605c2ad91a58a7982eb15687", - "version-string": "1.2.11", - "port-version": 9 - }, - { “$truncated for brevity” }, - { - "git-tree": "a516e5ee220c8250f21821077d0e3dd517f02631", - "version-string": "1.2.10", - "port-version": 0 - }, - { - "git-tree": "3309ec82cd96d752ff890c441cb20ef49b52bf94", - "version-string": "1.2.8", - "port-version": 0 - } - ] -} -``` - -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`. -Aside from port version files, the current baseline file is located in `versions/baseline.json`. diff --git a/docs/users/android.md b/docs/users/android.md deleted file mode 100644 index 25fa274530..0000000000 --- a/docs/users/android.md +++ /dev/null @@ -1,221 +0,0 @@ -# Vcpkg and Android - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/android.md).** - -*Android is not tested as part of vcpkg repository's CI process, so regressions can occur as part of library updates. PRs improving support are welcome!* - -## Android build requirements - -1. Download the [android ndk](https://developer.android.com/ndk/downloads/) - -2. Set environment variable `ANDROID_NDK_HOME` to your android ndk installation. - For example: - -````bash -export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle -```` - -Or: -````bash -export ANDROID_NDK_HOME=/home/your-account/Android/android-ndk-r21b -```` - -3. Install [vcpkg](https://github.com/microsoft/vcpkg) - -4. Set environment variable `VCPKG_ROOT` to your vcpkg installation. -````bash -export VCPKG_ROOT=/path/to/vcpkg -```` - -## vcpkg triplets and their corresponding android ABI - -There are four different Android ABI, each of which maps to -a vcpkg triplet. The following table outlines the mapping from vcpkg architectures to android architectures - -|VCPKG_TARGET_TRIPLET | ANDROID_ABI | -|---------------------------|----------------------| -|arm64-android | arm64-v8a | -|arm-android | armeabi-v7a | -|x64-android | x86_64 | -|x86-android | x86 | - -## Install libraries for Android using vcpkg - -Example for jsoncpp: - -````bash -cd $VCPKG_ROOT - -# specify the triplet like this -./vcpkg install jsoncpp --triplet arm-android -# or like this -./vcpkg install jsoncpp:arm64-android -./vcpkg install jsoncpp:x86-android -./vcpkg install jsoncpp:x64-android -```` - -### Using Vulkan SDK - -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. - -```bash -export VULKAN_SDK=/usr/local -./vcpkg install vulkan -``` - -NDK already contains [Vulkan](https://developer.android.com/ndk/guides/graphics/getting-started) headers and `libvulkan.so` binaries for each of its architecture. -To expose them to VcPkg, you can consider `export VULKAN_SDK=...` for each installation. -But by placing `set(ENV{VULKAN_SDK} ...)` in the triplet files, you can skip the tedious work. - -If you are using NDK 21.3.6528147 or earlier version, it will be like the following. - -```cmake -# In android triplets... (e.g. arm64-android.cmake) -set(VCPKG_CMAKE_SYSTEM_NAME Android) -# ... -# If your API level is 30, libvulkan.so is at $ENV{ANDROID_NDK_HOME}/platforms/android-30/arch-arm64/usr/lib -set(ENV{VULKAN_SDK} $ENV{ANDROID_NDK_HOME}/sysroot/usr) -``` - -Notice that **the location of the sysroot has changed since NDK 22**. (see https://github.com/android/ndk/issues/1407) -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. - -For example, Mac OS users will use the path like this. - -```cmake -# In android triplets... (e.g. arm64-android.cmake) -set(VCPKG_CMAKE_SYSTEM_NAME Android) -# ... -# 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 -set(ENV{VULKAN_SDK} $ENV{ANDROID_NDK_HOME}/toolchains/llvm/prebuilt/darwin-x86_64/sysroot/usr) -``` - -By doing this for all android triplets, you can install `vulkan` and the packages that require it. (e.g. `vulkan-hpp`) - -

- `vcpkg install vulkan-hpp:arm64-android` - -```console -user@host$ ./vcpkg install vulkan-hpp:arm64-android -Computing installation plan... -The following packages will be built and installed: - * vulkan[core]:arm64-android -> 1.1.82.1-1 - vulkan-hpp[core]:arm64-android -> 2019-05-11-1 -Additional packages (*) will be modified to complete this operation. -Detecting compiler hash for triplet arm64-android... -... -Starting package 1/2: vulkan:arm64-android -Building package vulkan[core]:arm64-android... --- Using community triplet arm64-android. This triplet configuration is not guaranteed to succeed. --- [COMMUNITY] Loading triplet configuration from: /.../vcpkg/triplets/community/arm64-android.cmake --- Querying VULKAN_SDK Environment variable --- Searching /.../Library/Android/sdk/ndk/22.1.7171670/toolchains/llvm/prebuilt/darwin-x86_64/sysroot/usr/include/vulkan/ for vulkan.h --- Found vulkan.h --- Performing post-build validation --- Performing post-build validation done -... -Building package vulkan[core]:arm64-android... done -Installing package vulkan[core]:arm64-android... -Installing package vulkan[core]:arm64-android... done -Elapsed time for package vulkan:arm64-android: 35.9 ms -Starting package 2/2: vulkan-hpp:arm64-android -Building package vulkan-hpp[core]:arm64-android... --- Using community triplet arm64-android. This triplet configuration is not guaranteed to succeed. --- [COMMUNITY] Loading triplet configuration from: /.../vcpkg/triplets/community/arm64-android.cmake --- Using cached /.../vcpkg/downloads/KhronosGroup-Vulkan-Hpp-5ce8ae7fd0d9c0543d02f33cfa8a66e6a43e2150.tar.gz --- Cleaning sources at /.../vcpkg/buildtrees/vulkan-hpp/src/e6a43e2150-4f344cd911.clean. Use --editable to skip cleaning for the packages you specify. --- Extracting source /.../vcpkg/downloads/KhronosGroup-Vulkan-Hpp-5ce8ae7fd0d9c0543d02f33cfa8a66e6a43e2150.tar.gz --- Using source at /.../vcpkg/buildtrees/vulkan-hpp/src/e6a43e2150-4f344cd911.clean --- Performing post-build validation --- Performing post-build validation done -... -Building package vulkan-hpp[core]:arm64-android... done -Installing package vulkan-hpp[core]:arm64-android... -Installing package vulkan-hpp[core]:arm64-android... done -Elapsed time for package vulkan-hpp:arm64-android: 144.5 ms - -Total elapsed time: 1.013 s - -The package vulkan-hpp:arm64-android is header only and can be used from CMake via: - - find_path(VULKAN_HPP_INCLUDE_DIRS "vulkan/vulkan.hpp") - target_include_directories(main PRIVATE ${VULKAN_HPP_INCLUDE_DIRS}) - -``` - -
- - -## Consume libraries using vpckg, cmake and the android toolchain - -1. Combine vcpkg and Android toolchains - -vcpkg and android both provide dedicated toolchains: -````bash -vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake -```` - -When using vcpkg, the vcpkg toolchain shall be specified first. - -However, vcpkg provides a way to preload and additional toolchain, with the VCPKG_CHAINLOAD_TOOLCHAIN_FILE option. - -````bash -cmake \ - -DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \ - -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \ - ... -```` - -2. Specify the android abi and vcpkg triplet - -When compiling for android, you need to select a matching "android abi" / "vcpkg triplet" pair. - -For example: - -````bash -android_abi=armeabi-v7a -vcpkg_target_triplet=arm-android - -cmake - ... - -DVCPKG_TARGET_TRIPLET=$vcpkg_target_triplet \ - -DANDROID_ABI=$android_abi -```` - -### Test on an example - -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: - -*Details* - -* The [CMakeLists](../examples/vcpkg_android_example_cmake/CMakeLists.txt) simply uses `find_package` and `target_link_library` - -* 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 - -* The dummy [my_lib.cpp](../examples/vcpkg_android_example_cmake/my_lib.cpp) file uses the jsoncpp library - -*Note*: this example only compiles an Android library, as the compilation of a full fledged Android App is beyond the scope of this document. - -### Test on an example, using [vcpkg_android.cmake](../examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake) - -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. - -*Details* - -* 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: -````cmake -if (VCPKG_TARGET_ANDROID) - include("cmake/vcpkg_android.cmake") -endif() -```` -*Important: place these lines before calling project() !* - -* 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: -````bash -cmake .. -DVCPKG_TARGET_ANDROID=ON -DANDROID_ABI=armeabi-v7a -```` - -## Consume libraries using vcpkg, and Android prefab Archives (AAR files) - -See [prefab.md](../specifications/prefab.md) diff --git a/docs/users/assetcaching.md b/docs/users/assetcaching.md deleted file mode 100644 index 1328bb2fe9..0000000000 --- a/docs/users/assetcaching.md +++ /dev/null @@ -1,58 +0,0 @@ -# Asset Caching - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/assetcaching.md).** - -**Experimental feature: this may change or be removed at any time** - -Vcpkg can utilize mirrors to cache downloaded assets, ensuring continued operation even if the original source changes -or disappears. - -In-tool help is available via `vcpkg help assetcaching`. - -## Configuration - -Asset caching can be configured by setting the environment variable `X_VCPKG_ASSET_SOURCES` to a semicolon-delimited -list of source strings. Characters can be escaped using backtick (\`). - -### Valid source strings - -The `` optional parameter for certain strings controls how they will be accessed. It can be specified as `read`, -`write`, or `readwrite` and defaults to `read`. - -#### `clear` - -Syntax: `clear` - -Removes all previous sources - -#### `x-azurl` - -Syntax: `x-azurl,[,[,]]` - -Adds an Azure Blob Storage source, optionally using Shared Access Signature validation. URL should include the container -path and be terminated with a trailing `/`. SAS, if defined, should be prefixed with a `?`. Non-Azure servers will also -work if they respond to GET and PUT requests of the form: ``. As an example, if you set -`X_VCPKG_ASSET_SOURCES` to `x-azurl,https://mydomain.com/vcpkg/,token=abc123,readwrite` your server should respond to -`GET` and `PUT` requests of the form `https://mydomain.com/vcpkg/?token=abc123`. - -You can also use the filesystem (e.g. a network drive) via `file://` as asset cache. For example you then set -`X_VCPKG_ASSET_SOURCES` to `x-azurl,file:///Z:/vcpkg/assetcache/,,readwrite` when you have a network folder mounted at -`Z:/`. - -The workflow of this asset source is: - -1. Attemp to read from the mirror -2. (If step 1 failed) Read from the original url -3. (If step 2 succeeded) Write back to the mirror - -You can enable/disable steps 1 and 3 via the [``](#valid-source-strings) specifier and you can disable step 2 via -`x-block-origin` below. - -See also the [binary caching documentation for Azure Blob Storage](binarycaching.md#azure-blob-storage-experimental) for -more information on how to set up an `x-azurl` source. - -#### `x-block-origin` - -Syntax: `x-block-origin` - -Disables use of the original URLs in case the mirror does not have the file available. diff --git a/docs/users/authentication.md b/docs/users/authentication.md deleted file mode 100644 index 4c1d1b9f04..0000000000 --- a/docs/users/authentication.md +++ /dev/null @@ -1,91 +0,0 @@ -# Authentication for Source Code - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/authentication.md).** - -Registries and `vcpkg_from_git()` directly use the git command line tools to fetch remote resources. Some of these resources may be protected from anonymous access and need authentication or credentials. - -The strategies below all seek to achieve the same fundamental goal: `git clone https://....` should succeed without interaction. This enables vcpkg to be separated from the specifics of your authentication scheme, ensuring forwards compatibility with any additional security improvements in the future. - -## Pre-seed git credentials - -You can pre-seed git credentials via `git credential approve`: - -Powershell: -```powershell -"url=https://github.com`npath=Microsoft/vcpkg`nusername=unused`npassword=$MY_PAT`n" | git credential approve -``` -Bash: -```sh -echo "url=https://github.com"$'\n'"path=Microsoft/vcpkg"$'\n'"username=unused"$'\n'"password=$MY_PAT"$'\n' | git credential approve -``` - -## Bearer auth - -For systems which need bearer auth, you can use `git config`: - -**Note: you must make these config changes with `--global`** -``` -git config --global --unset-all http..extraheader -git config --global http..extraheader "AUTHORIZATION: bearer " -``` -The `` can be filled in with a variety of options, documented in https://git-scm.com/docs/git-config#Documentation/git-config.txt-httplturlgt. For example, `https://dev.azure.com/MYORG/`. - -(Original Source: https://github.com/Microsoft/azure-pipelines-agent/issues/1601#issuecomment-394511048). - -**Note for Azure DevOps users:** You may need to enable access via Job authorization scope https://docs.microsoft.com/en-us/azure/devops/pipelines/process/access-tokens?view=azure-devops&tabs=yaml#job-authorization-scope. You may also need to "reference" the repo in your yaml via: - -```yaml -resources: - repositories: - - repository: - type: git - name: / - tag: tags/ - -... - -jobs: - - job: Build - uses: - repositories: [] -``` - -## Pass credentials in an environment variable (not recommended) - -Using `VCPKG_KEEP_ENV_VARS` or `VCPKG_ENV_PASSTHROUGH_UNTRACKED`, we can smuggle credential info via another var like `MY_TOKEN_VAR`. -```sh -export VCPKG_KEEP_ENV_VARS=MY_TOKEN_VAR -export MY_TOKEN_VAR=abc123 -``` -This can then be used in your private ports: -```cmake -# some/private/portfile.cmake -set(MY_TOKEN_VAR "") -if(DEFINED ENV{MY_TOKEN_VAR}) - set(MY_TOKEN_VAR "$ENV{MY_TOKEN_VAR}@") -endif() -vcpkg_from_git( - URLS "https://${MY_TOKEN_VAR}host.com/normal/url/path" - ... -) -``` -```cmake -# some/other/private/portfile.cmake -vcpkg_from_github( - AUTHORIZATION_TOKEN "$ENV{MY_TOKEN_VAR}" -) -``` - -For private ports, we recommend using `vcpkg_from_git()` instead of `vcpkg_from_github()` and the pre-seeding method above. - -## Pass Jenkins gitUsernamePassword credentials - -The simplest and most secure option to Git authentication to GitHub from Jenkins is using [GitHub App](https://github.com/jenkinsci/github-branch-source-plugin/blob/master/docs/github-app.adoc) and the following: -```groovy -withCredentials([gitUsernamePassword(credentialsId: 'jenkins-github-app')]) { - withEnv(['VCPKG_KEEP_ENV_VARS=GIT_ASKPASS']) { - bat 'cmake' - } -} -``` -This sets the GIT_ASKPASS with a path to helper script which responds with git credentials query and instructs `vcpkg` to keep this environment variable. The password is a [GitHub App token](https://github.blog/2021-04-05-behind-githubs-new-authentication-token-formats/) with 1 hour lifetime. diff --git a/docs/users/binarycaching.md b/docs/users/binarycaching.md deleted file mode 100644 index 6f8a1cd037..0000000000 --- a/docs/users/binarycaching.md +++ /dev/null @@ -1,288 +0,0 @@ -# Binary Caching - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/binarycaching.md).** - -Libraries installed with vcpkg can always be built from source. However, that can duplicate work and waste time when working across multiple projects. - -Binary caching is a vcpkg feature that saves copies of library binaries in a shared location that can be accessed by vcpkg for future installs. This means that, as a user, you should only need to build dependencies from source once. If vcpkg is asked to install the same library with the same build configuration in the future, it will just copy the built binaries from the cache and finish the operation in seconds. - -Binary caching is especially effective when using Continuous Integration, since local developers can reuse the binaries produced during a CI run. It also greatly enhances the performance of "ephemeral" or "hosted" build agents, since all local changes are otherwise lost between runs. By using binary caching backed by a cloud service, such as GitHub, Azure, or many others, you can ensure your CI runs at maximum speed and only rebuilds your dependencies when they've changed. - -Caches can be hosted in a variety of environments. The most basic examples are a folder on the local machine or a network file share. Caches can also be stored in any NuGet feed (such as GitHub or Azure DevOps Artifacts), Azure Blob Storage*, or Google Cloud Storage*. - -\* (experimental) - -If your CI provider offers a native "caching" function, we recommend using both vcpkg binary caching and the native method for the most performant results. - -In-tool help is available via `vcpkg help binarycaching`. - -Table of Contents - - [Configuration](#configuration) - - [CI Examples](#ci-examples) - - [GitHub Packages](#github-packages) - - [Azure DevOps Artifacts](#azure-devops-artifacts) - - [Azure Blob Storage](#azure-blob-storage-experimental) - - [Google Cloud Storage](#google-cloud-storage-experimental) - - [NuGet Provider Configuration](#nuget-provider-configuration) - - [Implementation Notes](#implementation-notes-internal-details-subject-to-change-without-notice) - - -## Configuration - -Binary caching is configured via a combination of defaults, the environment variable `VCPKG_BINARY_SOURCES` (set to `;;...`), and the command line option `--binarysource=`. Source options are evaluated in order of defaults, then environment, then command line. Binary caching can be completely disabled by passing `--binarysource=clear` as the last command line option. - -By default, zip-based archives will be cached at the first valid location of: - -**Windows** -1. `%VCPKG_DEFAULT_BINARY_CACHE%` -2. `%LOCALAPPDATA%\vcpkg\archives` -3. `%APPDATA%\vcpkg\archives` - -**Non-Windows** -1. `$VCPKG_DEFAULT_BINARY_CACHE` -2. `$XDG_CACHE_HOME/vcpkg/archives` -3. `$HOME/.cache/vcpkg/archives` - -### Valid source strings (``) - -| form | description -|-----------------------------|--------------- -| `clear` | Disable read all previous sources (including the default) -| `default[,]` | Adds the default file-based location -| `files,[,]` | Adds a custom file-based location -| `nuget,[,]` | Adds a NuGet-based source; equivalent to the `-Source` parameter of the NuGet CLI -| `nugetconfig,[,]` | Adds a NuGet-config-file-based source; equivalent to the `-Config` parameter of the NuGet CLI. This config should specify `defaultPushSource` for uploads. -| `nugettimeout,` | Specifies a timeout for NuGet network operations; equivalent to the `-Timeout` parameter of the NuGet CLI. -| `x-azblob,,[,]` | **Experimental: will change or be removed without warning**
Adds an Azure Blob Storage source. Uses Shared Access Signature validation. URL should include the container path. -| `interactive` | Enables interactive credential management for NuGet (for debugging; requires `--debug` on the command line) - -The `` optional parameter for certain sources controls whether they will be consulted for -downloading binaries (`read`)(default), whether on-demand builds will be uploaded to that remote (`write`), or both (`readwrite`). - -Additional configuration details for NuGet-based providers can be found below in [NuGet Provider Configuration](#nuget-provider-configuration). - -## CI Examples - -If your CI system of choice is not listed, we welcome PRs to add them! - -### GitHub Packages - -To use vcpkg with GitHub Packages, we recommend using the `NuGet` backend. - ->**NOTE 2020-09-21**: GitHub's hosted agents come with an older, pre-installed copy of vcpkg on the path that does not support the latest binary caching. This means that direct calls to `bootstrap-vcpkg` or `vcpkg` without a path prefix may call an unintended vcpkg instance. We recommend taking the following two steps to avoid issues if you want to use your own copy of vcpkg: -> 1. Run the equivalent of `rm -rf "$VCPKG_INSTALLATION_ROOT"` using `shell: 'bash'` -> 2. Always call `vcpkg` and `bootstrap-vcpkg` with a path prefix, such as `./vcpkg`, `vcpkg/vcpkg`, `.\bootstrap-vcpkg.bat`, etc - -```yaml -# actions.yaml -# -# In this example, vcpkg has been added as a submodule (`git submodule add https://github.com/Microsoft/vcpkg`). -env: - VCPKG_BINARY_SOURCES: 'clear;nuget,GitHub,readwrite' - -matrix: - os: ['windows-2019', 'ubuntu-20.04'] - include: - - os: 'windows-2019' - triplet: 'x86-windows' - mono: '' - - os: 'ubuntu-20.04' - triplet: 'x64-linux' - # To run `nuget.exe` on non-Windows platforms, we must use `mono`. - mono: 'mono' - -steps: - # This step assumes `vcpkg` has been bootstrapped (run `./vcpkg/bootstrap-vcpkg`) - - name: 'Setup NuGet Credentials' - shell: 'bash' - # Replace with your organization name - run: | - ${{ matrix.mono }} `./vcpkg/vcpkg fetch nuget | tail -n 1` \ - sources add \ - -source "https://nuget.pkg.github.com//index.json" \ - -storepasswordincleartext \ - -name "GitHub" \ - -username "" \ - -password "${{ secrets.GITHUB_TOKEN }}" - ${{ matrix.mono }} `./vcpkg/vcpkg fetch nuget | tail -n 1` \ - setapikey "${{ secrets.GITHUB_TOKEN }}" \ - -source "https://nuget.pkg.github.com//index.json" - - # Omit this step if you're using manifests - - name: 'vcpkg package restore' - shell: 'bash' - run: > - ./vcpkg/vcpkg install sqlite3 cpprestsdk --triplet ${{ matrix.triplet }} -``` - -If you're using [manifests](../specifications/manifests.md), you can omit the `vcpkg package restore` step: it will be run automatically as part of your build. - -More information about GitHub Packages' NuGet support is available on [GitHub Docs][github-nuget]. - -[github-nuget]: https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages - -### Azure DevOps Artifacts - -To use vcpkg with Azure DevOps Artifacts, we recommend using the `NuGet` backend. - -First, you need to ensure Artifacts has been enabled on your DevOps instance; this can be done by an Administrator through `Project Settings > General > Overview > Azure DevOps Services > Artifacts`. - -Next, you will need to create a feed for your project; see the [Azure DevOps Artifacts Documentation][devops-nuget] for more information. Your feed URL will be an `https://` link ending with `/nuget/v3/index.json`. - -```yaml -# azure-pipelines.yaml -variables: -- name: VCPKG_BINARY_SOURCES - value: 'clear;nuget,,readwrite' - -steps: -# Remember to add this task to allow vcpkg to upload archives via NuGet -- task: NuGetAuthenticate@0 -``` - -If you are using custom agents with a non-Windows OS, you will need to install Mono to run `nuget.exe` (`apt install mono-complete`, `brew install mono`, etc). - -More information about Azure DevOps Artifacts' NuGet support is available in the [Azure DevOps Artifacts Documentation][devops-nuget]. - -[devops-nuget]: https://docs.microsoft.com/en-us/azure/devops/artifacts/get-started-nuget?view=azure-devops - -### Azure Blob Storage (experimental) - -> Note: This is an experimental feature and may change or be removed at any time - -Vcpkg supports interfacing with Azure Blob Storage via the `x-azblob` source type. - -``` -x-azblob,,[,] -``` - -First, you need to create an Azure Storage Account as well as a container ([Quick Start Documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal)]. - -Next, you will need to create a Shared Access Signature, which can be done from the storage account under Settings -> Shared access signature. This SAS will need: -- Allowed services: Blob -- Allowed resource types: Object -- Allowed permissions: Read, Create (if using `write` or `readwrite`) - -The blob endpoint plus the container must be passed as the `` and the generated SAS without the `?` prefix must be passed as the ``. - -Example: -``` -x-azblob,https://.blob.core.windows.net/,sv=2019-12-12&ss=b&srt=o&sp=rcx&se=2020-12-31T06:20:36Z&st=2020-12-30T22:20:36Z&spr=https&sig=abcd,readwrite -``` - -Vcpkg will attempt to avoid revealing the SAS during normal operations, however: -1. It will be printed in full if `--debug` is passed -2. It will be passed as a command line parameter to subprocesses, such as `curl.exe` - -Azure Blob Storage includes a feature to remove cache entries that haven't been accessed in a given number of days which can be used to reduce the size of your cache. See [Data Lifecycle Management on Microsoft Docs](https://docs.microsoft.com/en-us/azure/storage/blobs/lifecycle-management-overview) for more information, or look for "Data management > Lifecycle management" in the Azure Portal for your storage account. If you wish to be able to be resilient to upstream libraries' servers but still want to remove entries from the binary cache, consider using [asset caching](assetcaching.md#x-azurl) in a different storage account without a lifecycle management policy. - -### Google Cloud Storage (experimental) - -> Note: This is an experimental feature and may change or be removed at any time - -Vcpkg supports interfacing with Google Cloud Storage (GCS) via the `x-gcs` source type. - -``` -x-gcs,[,] -``` - -First, you need to create an Google Cloud Platform Account as well as a storage bucket ([GCS Quick Start](https://cloud.google.com/storage/docs/quickstart-gsutil)]. - -As part of this quickstart you would have configured the `gsutil` command-line tool to authenticate with Google Cloud. -Vcpkg will use this command-line tool, make sure it is in your search path for executables. - -Example 1 (using a bucket without a common prefix for the objects): - -``` -x-gcs,gs:///,readwrite -``` - -Example 2 (using a bucket and a prefix for the objects): - -``` -x-gcs,gs:///my-vcpkg-cache/maybe/with/many/slashes/,readwrite -x-gcs,gs:///my-vcpkg-cache/maybe/with`,commas/too!/,readwrite -``` - -Commas (`,`) are valid as part of a object prefix in GCS, just remember to escape them in the vcpkg configuration, as -shown in the previous example. Note that GCS does not have folders (some of the GCS tools simulate folders), it is not -necessary to create or otherwise manipulate the prefix used by your vcpkg cache. - -## NuGet Provider Configuration - -### Credentials - -Many NuGet servers require additional credentials to access. The most flexible way to supply credentials is via the `nugetconfig` provider with a custom `nuget.config` file. See https://docs.microsoft.com/en-us/nuget/consume-packages/consuming-packages-authenticated-feeds for more information on authenticating via `nuget.config`. - -However, it is still possible to authenticate against many servers using NuGet's built-in credential providers or via customizing your environment's default `nuget.config`. The default config can be extended via nuget client calls such as -``` -nuget sources add -Name MyRemote -Source https://... -Username $user -Password $pass -``` -and then passed to vcpkg via `--binarysource=nuget,MyRemote,readwrite`. You can get a path to the precise copy of NuGet used by vcpkg by running `vcpkg fetch nuget`, which will report something like: -``` -$ vcpkg fetch nuget -/vcpkg/downloads/tools/nuget-5.5.1-linux/nuget.exe -``` -Non-Windows users will need to call this through mono via `mono /path/to/nuget.exe sources add ...`. - -##### Credential Example for Azure Dev Ops -```bash -# On Linux or OSX -$ mono `vcpkg fetch nuget | tail -n1` sources add \ - -name ADO \ - -Source https://pkgs.dev.azure.com/$ORG/_packaging/$FEEDNAME/nuget/v3/index.json \ - -Username $USERNAME \ - -Password $PAT -$ export VCPKG_BINARY_SOURCES="nuget,ADO,readwrite" -``` -```powershell -# On Windows Powershell -PS> & $(vcpkg fetch nuget | select -last 1) sources add ` - -name ADO ` - -Source https://pkgs.dev.azure.com/$ORG/_packaging/$FEEDNAME/nuget/v3/index.json ` - -Username $USERNAME ` - -Password $PAT -PS> $env:VCPKG_BINARY_SOURCES="nuget,ADO,readwrite" -``` - -We recommend using a Personal Access Token (PAT) as the password for maximum security. You can generate a PAT in User Settings -> Personal Access Tokens or `https://dev.azure.com/$ORG/_usersSettings/tokens`. - -#### `metadata.repository` - -The `nuget` and `nugetconfig` source providers additionally respect certain environment variables while generating nuget packages. The `metadata.repository` field of any packages will be generated as: -``` - -``` -or -``` - -``` -if the appropriate environment variables are defined and non-empty. This is specifically used to associate packages in GitHub Packages with the _building_ project and not intended to associate with the original package sources. - -#### NuGet's cache - -NuGet's cache is not used by default. To use it for every nuget-based source, set the [environment variable](config-environment.md) `VCPKG_USE_NUGET_CACHE` to `true` (case-insensitive) or `1`. - -## Implementation Notes (internal details subject to change without notice) - -Binary caching relies on hashing everything that contributes to a particular package build. This includes: - -- Every file in the port directory -- The triplet file and name -- The C++ compiler executable -- The C compiler executable -- The set of features selected -- Every dependency's package hash (note: this is that package's input hash, not contents) -- All helper scripts referenced by `portfile.cmake` (heuristic) -- The version of CMake used -- The contents of any environment variables listed in `VCPKG_ENV_PASSTHROUGH` -- The hash of the toolchain file (builtin or `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`) - -Despite this extensive list, it is possible to defeat the cache and introduce nondeterminism. If you have additional details that you'd like to be tracked, the easiest resolution is to generate a triplet file with your additional information in a comment. That additional information will be included in the package's input set and ensure a unique universe of binaries. - -The hashes used are stored in the package and in the current installed directory at `/share//vcpkg_abi_info.txt`. - -The original specification for binary caching is available [here](../specifications/binarycaching.md). diff --git a/docs/users/buildsystems/cmake-integration.md b/docs/users/buildsystems/cmake-integration.md deleted file mode 100644 index 9d04648e29..0000000000 --- a/docs/users/buildsystems/cmake-integration.md +++ /dev/null @@ -1,231 +0,0 @@ -# CMake Integration - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/cmake-integration.md).** - -See [Installing and Using Packages Example: sqlite](../../examples/installing-and-using-packages.md) for a fully worked example using CMake. - -## Table of Contents - -- [`CMAKE_TOOLCHAIN_FILE`](#cmake_toolchain_file) -- [IDE Integration](#ide-integration) - - [Visual Studio Code (CMake Tools extension)](#visual-studio-code-cmake-tools-extension) - - [Visual Studio](#visual-studio) - - [CLion](#clion) -- [Using Multiple Toolchain Files](#using-multiple-toolchain-files) -- [Settings Reference](#settings-reference) - -## `CMAKE_TOOLCHAIN_FILE` - -Projects configured to use the vcpkg toolchain file (via the CMake setting `CMAKE_TOOLCHAIN_FILE`) can find libraries from vcpkg using the standard CMake functions: `find_package()`, `find_path()`, and `find_library()`. - -```no-highlight -cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=[vcpkg-root]/scripts/buildsystems/vcpkg.cmake -``` - -Since version 3.21, CMake will use the environment variable `CMAKE_TOOLCHAIN_FILE`[1] as the default value for `CMAKE_TOOLCHAIN_FILE`. - -**cmd** -```cmd -set CMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake -``` -**Powershell** -```powershell -$env:CMAKE_TOOLCHAIN_FILE="[vcpkg root]/scripts/buildsystems/vcpkg.cmake" -``` -**bash** -```sh -export CMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake -``` - -vcpkg does not automatically add any include or links paths into your project. To use a header-only library you can use `find_path()` which will correctly work on all platforms: - -```cmake -# To find and use catch2 -find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2) -include_directories(${CATCH_INCLUDE_DIR}) -``` - -[1]: https://cmake.org/cmake/help/latest/envvar/CMAKE_TOOLCHAIN_FILE.html - -## IDE Integration - -### Visual Studio Code (CMake Tools Extension) - -Adding the following to your workspace `settings.json` will make CMake Tools automatically use vcpkg for libraries: - -```json -{ - "cmake.configureSettings": { - "CMAKE_TOOLCHAIN_FILE": "[vcpkg root]/scripts/buildsystems/vcpkg.cmake" - } -} -``` - -### Visual Studio - -In the CMake Settings Editor, add the path to the vcpkg toolchain file under `CMake toolchain file`: - -``` -[vcpkg root]/scripts/buildsystems/vcpkg.cmake -``` - -### CLion - -Open the Toolchains settings (`File > Settings` on Windows and Linux, `CLion > Preferences` on macOS), and go to the CMake settings (`Build, Execution, Deployment > CMake`). In `CMake options`, add the following line: - -``` --DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake -``` - -You must add this line to each profile separately. - -## Using Multiple Toolchain Files - -To combine vcpkg's toolchain file with another toolchain file, you can set the cmake variable `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`: - -```no-highlight -cmake ../my/project \ - -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \ - -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/toolchain.cmake -``` - -Alternatively, you can include the vcpkg toolchain at the end of the primary toolchain file: - -```cmake -# MyToolchain.cmake -set(CMAKE_CXX_COMPILER ...) -set(VCPKG_TARGET_TRIPLET x64-my-custom-windows-triplet) -include(/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake) -``` - -**Note: vcpkg does not automatically apply your toolchain's settings, such as your compiler or compilation flags, while building libraries. To change vcpkg's library settings, you must make a [custom triplet file](../triplets.md) (which can [share your toolchain](../triplets.md#VCPKG_CHAINLOAD_TOOLCHAIN_FILE))** - -## Settings Reference - -All vcpkg-affecting variables must be defined before the first `project()` directive, such as via the command line or `set()` statements. - -### `VCPKG_TARGET_TRIPLET` - -This setting controls the [triplet](../triplets.md) vcpkg will install and consume libraries from. - -If unset, vcpkg will automatically detect an appropriate default triplet given the current compiler settings. If you change this CMake variable, you must delete your cache and reconfigure. - -### `VCPKG_HOST_TRIPLET` - -This variable controls which [triplet](../triplets.md) host dependencies will be installed for. - -If unset, vcpkg will automatically detect an appropriate native triplet (x64-windows, x64-osx, x64-linux). - -See also [Host Dependencies](../host-dependencies.md). - -### `VCPKG_INSTALLED_DIR` - -This variable sets the location where libraries will be installed and consumed from. - -In manifest mode, the default is `${CMAKE_BINARY_DIR}/vcpkg_installed`. - -In classic mode, the default is `${VCPKG_ROOT}/installed`. - -### `VCPKG_MANIFEST_MODE` - -This variable forces vcpkg to operate in either manifest mode or classic mode. - -Defaults to `ON` when `VCPKG_MANIFEST_DIR` is non-empty or `${CMAKE_SOURCE_DIR}/vcpkg.json` exists. - -To disable manifest mode while a `vcpkg.json` is detected, set this to `OFF`. - -### `VCPKG_MANIFEST_DIR` - -This variable specifies an alternate folder containing a `vcpkg.json` manifest. - -Defaults to `${CMAKE_SOURCE_DIR}` if `${CMAKE_SOURCE_DIR}/vcpkg.json` exists. - -### `VCPKG_MANIFEST_INSTALL` - -This variable controls whether vcpkg will be automatically run to install your dependencies during your configure step. - -Defaults to `ON` if `VCPKG_MANIFEST_MODE` is `ON`. - -### `VCPKG_BOOTSTRAP_OPTIONS` - -This variable can be set to additional command parameters to pass to `./bootstrap-vcpkg`. - -In manifest mode, vcpkg will be automatically bootstrapped if the executable does not exist. - -### `VCPKG_OVERLAY_TRIPLETS` - -This variable can be set to a list of paths to be passed on the command line as `--overlay-triplets=...` - -### `VCPKG_OVERLAY_PORTS` - -This variable can be set to a list of paths to be passed on the command line as `--overlay-ports=...` - -### `VCPKG_MANIFEST_FEATURES` - -This variable can be set to a list of features to activate when installing from your manifest. - -For example, features can be used by projects to control building with additional dependencies to enable tests or samples: - -```json -{ - "name": "mylibrary", - "version": "1.0", - "dependencies": [ "curl" ], - "features": { - "samples": { - "description": "Build Samples", - "dependencies": [ "fltk" ] - }, - "tests": { - "description": "Build Tests", - "dependencies": [ "gtest" ] - } - } -} -``` -```cmake -# CMakeLists.txt - -option(BUILD_TESTING "Build tests" OFF) -if(BUILD_TESTING) - list(APPEND VCPKG_MANIFEST_FEATURES "tests") -endif() - -option(BUILD_SAMPLES "Build samples" OFF) -if(BUILD_SAMPLES) - list(APPEND VCPKG_MANIFEST_FEATURES "samples") -endif() - -project(myapp) - -# ... -``` - -### `VCPKG_MANIFEST_NO_DEFAULT_FEATURES` - -This variable controls activation of default features in addition to those listed in `VCPKG_MANIFEST_FEATURES`. If set to `ON`, default features will not be automatically activated. - -Defaults to `OFF`. - -### `VCPKG_INSTALL_OPTIONS` - -This variable can be set to a list of additional command line parameters to pass to the vcpkg tool during automatic installation. - -### `VCPKG_PREFER_SYSTEM_LIBS` - -**This feature has been deprecated. Use empty overlay ports instead.** - -This variable controls whether vcpkg will append instead of prepend its paths to `CMAKE_PREFIX_PATH`, `CMAKE_LIBRARY_PATH` and `CMAKE_FIND_ROOT_PATH` so that vcpkg libraries/packages are found after toolchain/system libraries/packages. - -Defaults to `OFF`. - -### `VCPKG_FEATURE_FLAGS` - -This variable can be set to a list of feature flags to pass to the vcpkg tool during automatic installation to opt-in to experimental behavior. - -See the `--feature-flags=` command line option for more information. - -### `VCPKG_TRACE_FIND_PACKAGE` - -When this option is turned on, every call to `find_package` is printed. -Nested calls (e.g. via `find_dependency`) are indented according to nesting depth. diff --git a/docs/users/buildsystems/export-command.md b/docs/users/buildsystems/export-command.md deleted file mode 100644 index c591d18897..0000000000 --- a/docs/users/buildsystems/export-command.md +++ /dev/null @@ -1,20 +0,0 @@ -# `export` Command - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/export-command.md).** - -The `export` command creates a shrinkwrapped archive containing a specific set of libraries (and their dependencies) that can be quickly and reliably shared with build servers or other users in your organization. `export` only supports classic mode at this time. - -- `--nuget`: NuGet package -- `--zip`: Zip archive -- `--7zip`: 7Zip archive -- `--raw`: Raw, uncompressed folder - -Each of these have the same internal layout which mimics the layout of a full vcpkg instance: - -- `installed/` contains the library files -- `scripts/buildsystems/vcpkg.cmake` is the [CMake toolchain file](cmake-integration.md) -- `scripts/buildsystems/msbuild/vcpkg.props` and `scripts/buildsystems/msbuild/vcpkg.targets` are the [MSBuild integration files](msbuild-integration.md) - -NuGet package exports will also contain a `build\native\vcpkg.targets` that integrates with MSBuild projects using the NuGet package manager. - -Please also see our [blog post](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) for additional examples. diff --git a/docs/users/buildsystems/integration.md b/docs/users/buildsystems/integration.md deleted file mode 100644 index 67706600f1..0000000000 --- a/docs/users/buildsystems/integration.md +++ /dev/null @@ -1,10 +0,0 @@ -# Buildsystem Integration - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/integration.md).** - -vcpkg supports use from any buildsystem and has specific native integration into MSBuild and CMake. - -- [MSBuild Integration (Visual Studio)](msbuild-integration.md) -- [CMake Integration](cmake-integration.md) -- [Manual Integration](manual-integration.md) -- [`export` Command](export-command.md) diff --git a/docs/users/buildsystems/manual-integration.md b/docs/users/buildsystems/manual-integration.md deleted file mode 100644 index 5062123f15..0000000000 --- a/docs/users/buildsystems/manual-integration.md +++ /dev/null @@ -1,31 +0,0 @@ -# Manual Integration - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/manual-integration.md).** - -When installing libraries, vcpkg creates a single common layout partitioned by triplet. - -The root of the tree in classic mode is `[vcpkg root]/installed`. The root of the tree in manifest mode is `[vcpkg.json directory]/vcpkg_installed`. - -Underneath this root, in a subfolder named after the triplet: - -* Header files: `include/` -* Release `.lib`, `.a`, and `.so` files: `lib/` or `lib/manual-link/` -* Release `.dll` files: `bin/` -* Release `.pc` files: `lib/pkgconfig/` -* Debug `.lib`, `.a`, and `.so` files: `debug/lib/` or `debug/lib/manual-link/` -* Debug `.dll` files: `debug/bin/` -* Debug `.pc` files: `debug/lib/pkgconfig/` -* Tools: `tools/[portname]/` - -For example, `zlib.h` for `zlib:x64-windows` in classic mode is located at `[vcpkg root]/installed/x64-windows/include/zlib.h`. - -See your build system specific documentation for how to use prebuilt binaries. For example, `Makefile` projects often accept environment variables: - -```sh -export CXXFLAGS=-I$(pwd)/installed/x64-linux/include -export CFLAGS=-I$(pwd)/installed/x64-linux/include -export LDFLAGS=-L$(pwd)/installed/x64-linux/lib -export PKG_CONFIG_PATH=$(pwd)/installed/x64-linux/lib/pkgconfig:$PKG_CONFIG_PATH -``` - -_On Windows dynamic triplets, such as x64-windows:_ To run any produced executables you will also need to either copy the needed DLL files to the same folder as your executable or *prepend* the correct `bin\` directory to your path. diff --git a/docs/users/buildsystems/msbuild-integration.md b/docs/users/buildsystems/msbuild-integration.md deleted file mode 100644 index 3995e5bc66..0000000000 --- a/docs/users/buildsystems/msbuild-integration.md +++ /dev/null @@ -1,138 +0,0 @@ -# MSBuild Integration (Visual Studio) - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/msbuild-integration.md).** - -## Table of Contents - -- [Integration Methods](#integration-methods) - - [User-wide integration](#user-wide-integration) - - [Import `.props` and `.targets`](#import-props-and-targets) - - [Linked NuGet Package](#linked-nuget-package) -- [Common Configuration](#common-configuration) -- [Manifest Mode Configuration](#manifest-mode-configuration) - -## Integration Methods - -### User-wide integration - -```no-highlight -vcpkg integrate install -``` -This will implicitly add Include Directories, Link Directories, and Link Libraries for all packages installed with Vcpkg to all VS2015, VS2017 and VS2019 MSBuild projects. We also add a post-build action for executable projects that will analyze and copy any DLLs you need to the output folder, enabling a seamless F5 experience. - -For the vast majority of libraries, this is all you need to do -- just File -> New Project and write code! However, some libraries perform conflicting behaviors such as redefining `main()`. Since you need to choose per-project which of these conflicting options you want, you will need to add those libraries to your linker inputs manually. - -Here are some examples, though this is not an exhaustive list: - -- Gtest provides `gtest`, `gmock`, `gtest_main`, and `gmock_main` -- SDL2 provides `SDL2main` -- SFML provides `sfml-main` -- Boost.Test provides `boost_test_exec_monitor` - -To get a full list for all your installed packages, run `vcpkg owns manual-link`. - -### Import `.props` and `.targets` - -vcpkg can also be integrated into MSBuild projects by explicitly importing the `scripts/buildsystems/vcpkg.props` and `scripts/buildsystems/vcpkg.targets` files into each `.vcxproj`. By using relative paths, this enables vcpkg to be consumed by a submodule and automatically acquired by users when they run `git clone`. - -The easiest way to add these to every project in your solution is to create `Directory.Build.props` and `Directory.Build.targets` files at the root of your repository. - -The following examples assume they are at the root of your repository with a submodule of `microsoft/vcpkg` at `vcpkg`. - -**Example `Directory.Build.props`**: -```xml - - - -``` - -**Example `Directory.Build.targets`**: -```xml - - - -``` - -More information about `Directory.Build.targets` and `Directory.Build.props` can be found in the [Customize your build][1] section of the official MSBuild documentation. - -[1]: https://docs.microsoft.com/visualstudio/msbuild/customize-your-build#directorybuildprops-and-directorybuildtargets - -### Linked NuGet Package - -**Note: This approach is not recommended for new projects, since it makes them difficult to share with others. For a portable, self-contained NuGet package, see the [`export command`](export-command.md)** - -VS projects can also be integrated through a NuGet package. This will modify the project file, so we do not recommend this approach for open source projects. - -```no-highlight -PS D:\src\vcpkg> .\vcpkg integrate project -Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg - -With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste: - Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems" -``` - -*Note: The generated NuGet package does not contain the actual libraries. It instead acts like a shortcut (or symlink) to the vcpkg install and will "automatically" update with any changes (install/remove) to the libraries. You do not need to regenerate or update the NuGet package.* - -## Common Configuration - -### `VcpkgEnabled` (Use Vcpkg) - -This can be set to "false" to explicitly disable vcpkg integration for the project - -### `VcpkgConfiguration` (Vcpkg Configuration) - -If your configuration names are too complex for vcpkg to guess correctly, you can assign this property to `Release` or `Debug` to explicitly tell vcpkg what variant of libraries you want to consume. - -### `VcpkgEnableManifest` (Use Vcpkg Manifest) - -This property must be set to `true` in order to consume from a local `vcpkg.json` file. If set to `false`, any local `vcpkg.json` files will be ignored. - -This currently defaults to `false`, but will default to `true` in the future. - -### `VcpkgTriplet` (Triplet) - -This property controls the triplet to consume libraries from, such as `x64-windows-static` or `arm64-windows`. - -If this is not explicitly set, vcpkg will deduce the correct triplet based on your Visual Studio settings. vcpkg will only deduce triplets that use dynamic library linkage and dynamic CRT linkage; if you want static dependencies or to use the static CRT (`/MT`), you will need to set the triplet manually. - -You can see the automatically deduced triplet by setting your MSBuild verbosity to Normal or higher: - -> *Shortcut: Ctrl+Q "build and run"* -> -> Tools -> Options -> Projects and Solutions -> Build and Run -> MSBuild project build output verbosity - -See also [Triplets](../triplets.md) - -### `VcpkgHostTriplet` (Host Triplet) - -This can be set to a custom triplet to use for resolving host dependencies. - -If unset, this will default to the "native" triplet (x64-windows). - -See also [Host Dependencies](../host-dependencies.md). - -### `VcpkgInstalledDir` (Installed Directory) - -This property defines the location vcpkg will install and consume libraries from. - -In manifest mode, this defaults to `$(VcpkgManifestRoot)\vcpkg_installed\$(VcpkgTriplet)\`. In classic mode, this defaults to `$(VcpkgRoot)\installed\`. - -## Manifest Mode Configuration - -To use manifests (`vcpkg.json`) with MSBuild, first you need to use one of the integration methods above. Then, add a vcpkg.json above your project file (such as in the root of your source repository) and set the property `VcpkgEnableManifest` to `true`. You can set this property via the IDE in `Project Properties -> Vcpkg -> Use Vcpkg Manifest` (note: you may need to reload the IDE to see the vcpkg Property Page). - -vcpkg will automatically run during your project's build and install any listed dependencies to `vcpkg_installed/$(VcpkgTriplet)/` adjacent to the `vcpkg.json` file; these libraries will then automatically be included in and linked to your MSBuild projects. - -**Known issues** - -* Visual Studio 2015 does not correctly track edits to the `vcpkg.json` and `vcpkg-configuration.json` files, and will not respond to changes unless a `.cpp` is edited. - - - -### `VcpkgAdditionalInstallOptions` (Additional Options) - -When using a manifest, this option specifies additional command line flags to pass to the underlying vcpkg tool invocation. This can be used to access features that have not yet been exposed through another option. - -### `VcpkgManifestInstall` (Install Vcpkg Dependencies) - -This property can be set to `false` to disable automatic dependency restoration during project build. Dependencies must be manually restored via the vcpkg command line separately. diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md deleted file mode 100644 index de229aea51..0000000000 --- a/docs/users/config-environment.md +++ /dev/null @@ -1,105 +0,0 @@ -## Environment and Configuration - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/config-environment.md).** - -### Environment Variables - -#### VCPKG_DOWNLOADS - -This environment variable can be set to an existing directory to use for storing downloads instead of the internal -`downloads/` directory. It should always be set to an absolute path. - -#### VCPKG_FEATURE_FLAGS - -This environment variable can be set to a comma-separated list of off-by-default features in vcpkg. These features are -subject to change without notice and should be considered highly unstable. - -There are no off-by-default feature flags at this time. - -#### EDITOR - -This environment variable can be set to the full path of an executable to be used for `vcpkg edit`. Please see -`vcpkg help edit` for command-specific help. - -#### VCPKG_ROOT - -This environment variable can be set to a directory to use as the root of the vcpkg instance. This will only be used if -the vcpkg executable is not located within a valid root and the command line switch `--vcpkg-root` is unused. - -#### VCPKG_VISUAL_STUDIO_PATH - -This environment variable can be set to the full path to a Visual Studio instance on the machine. This Visual Studio instance -will be used if the triplet does not override it via the [`VCPKG_VISUAL_STUDIO_PATH`](triplets.md#VCPKG_VISUAL_STUDIO_PATH) triplet setting. - -Example: `D:\2017` - -#### VCPKG_DEFAULT_TRIPLET - -This environment variable can be set to a triplet name which will be used for unqualified triplet references in command lines. - -#### VCPKG_DEFAULT_HOST_TRIPLET - -This environment variable can be set to a triplet name which will be used for unqualified host port references in command lines and all host port references in dependency lists. See [the host-dependencies documentation](host-dependencies.md) for more information. - -#### VCPKG_OVERLAY_PORTS - -This environment variable allows users to override ports with alternate versions according to the -[ports overlay](../specifications/ports-overlay.md) specification. List paths to overlays using -the platform dependent PATH separator (Windows `;` | others `:`) - -Example (Windows): `C:\custom-ports\boost;C:\custom-ports\sqlite3` - -#### VCPKG_OVERLAY_TRIPLETS - -This environment variable allows users to add directories to search for triplets. -[Example: overlay triplets](../examples/overlay-triplets-linux-dynamic.md). -List paths to overlays using the platform dependent PATH separator (Windows `;`, others `:`) - -#### VCPKG_FORCE_SYSTEM_BINARIES - -This environment variable, if set, suppresses the downloading of CMake and Ninja and forces the use of the system binaries. - -#### VCPKG_FORCE_DOWNLOADED_BINARIES - -This environment variable, if set, ignores the use of the system binaries and will always download and use the version defined by vcpkg. - -#### VCPKG_KEEP_ENV_VARS - -This environment variable can be set to a list of environment variables, separated by `;`, which will be propagated to -the build environment. - -The values of the kept variables will not be tracked in package ABIs and will not cause rebuilds when they change. To -pass in environment variables that should cause rebuilds on change, see [`VCPKG_ENV_PASSTHROUGH`](triplets.md#VCPKG_ENV_PASSTHROUGH). - -Example: `FOO_SDK_DIR;BAR_SDK_DIR` - - -#### VCPKG_MAX_CONCURRENCY - -This environment variables limits the amount of concurrency used by underlying buildsystems. If unspecified, this defaults to logical cores + 1. - -#### VCPKG_DEFAULT_BINARY_CACHE - -This environment variable redirects the default location to store binary packages. See [Binary Caching](binarycaching.md#configuration) for more details. - -#### VCPKG_BINARY_SOURCES - -This environment variable adds or removes binary sources. See [Binary Caching](binarycaching.md#configuration) for more details. - -#### VCPKG_NUGET_REPOSITORY - -This environment variable changes the metadata of produced NuGet packages. See [Binary Caching](binarycaching.md#configuration) for more details. - -#### VCPKG_USE_NUGET_CACHE - -This environment variable allows using NuGet's cache for every nuget-based binary source. See [Binary Caching](binarycaching.md#nuget-provider-configuration) for more details. - -#### X_VCPKG_ASSET_SOURCES - -> Note: This is an experimental feature and may change or be removed at any time - -This environment variable allows using a private mirror for all SHA512-tagged assets. See [Asset Caching](assetcaching.md) for more details. - -#### VCPKG_NO_CI - -Setting `VCPKG_NO_CI` disables vcpkg's CI environment detection heuristics. diff --git a/docs/users/host-dependencies.md b/docs/users/host-dependencies.md deleted file mode 100644 index 4e7cf39a34..0000000000 --- a/docs/users/host-dependencies.md +++ /dev/null @@ -1,65 +0,0 @@ -# Host Dependencies - -Tools used at build time by other ports to generate code or implement a custom build system can be packaged inside vcpkg. - -## Consuming - -When consuming a port as a tool, you must set the dependency's `"host"` field to true. For example: -```json -{ - "name": "contoso-http-library", - "version-string": "1.0.0", - "description": "Contoso's http runtime library", - "dependencies": [ - "contoso-core-library", - { - "name": "contoso-code-generator", - "host": true - }, - { - "name": "contoso-build-system", - "host": true - } - ] -} -``` -In this case, the `contoso-code-generator` and `contoso-build-system` (including any transitive dependencies) will be built and installed for the host triplet before `contoso-http-library` is built. - ->Note: Consumers must use `vcpkg.json` instead of `CONTROL` as their metadata format. You can easily convert an existing `CONTROL` file using `vcpkg format-manifest /path/to/CONTROL`. - -Then, within the portfile of the consumer (`contoso-http-library` in the example), the CMake variable `CURRENT_HOST_INSTALLED_DIR` will be defined to `installed/` and should be used to locate any required assets. In the example, `contoso-code-generator` might have installed `tools/contoso-code-generator/ccg.exe` which the consumer would add to its local path via -```cmake -# ports/contoso-http-library/portfile.cmake -vcpkg_add_to_path(${CURRENT_HOST_INSTALLED_DIR}/tools/contoso-code-generator) -``` - -## Specifying the Host Triplet - -The default host triplets are chosen based on the host architecture and operating system, for example `x64-windows`, `x64-linux`, or `x64-osx`. They can be overridden via: - -1. In CMake-based manifest mode, calling `set(VCPKG_HOST_TRIPLET "" CACHE STRING "")` before the first `project()` directive -2. In MSBuild-based manifest mode, setting the `VcpkgHostTriplet` property -3. On the command line, via the flag `--host-triplet=...` -4. The `VCPKG_DEFAULT_HOST_TRIPLET` environment variable - -## Producing - -Producing a tool has no special requirements; tools should be authored as a standard port, following all the normal policies and practices. Notably, they should build against `TARGET_TRIPLET`, not `HOST_TRIPLET` within the context of their portfile. - -If the current context is cross-compiling (`TARGET_TRIPLET` is not `HOST_TRIPLET`), then `VCPKG_CROSSCOMPILING` will be set to a truthy value. - -```cmake -if(VCPKG_CROSSCOMPILING) - # This is a native build -else() - # This is a cross build -endif() -``` - -## Host-only ports - -Some ports should only be depended upon via a host dependency; script ports and -tool ports are common examples. In this case, you can use the `"native"` -supports expression to describe this. This supports expression is true when -`VCPKG_CROSSCOMPILING` is false (implying that `TARGET_TRIPLET == -HOST_TRIPLET`). diff --git a/docs/users/manifests.md b/docs/users/manifests.md deleted file mode 100644 index 96e40b736a..0000000000 --- a/docs/users/manifests.md +++ /dev/null @@ -1,356 +0,0 @@ -# Manifest Mode - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/manifests.md).** - -vcpkg has two modes of consuming dependencies - classic mode and manifest mode. - -In classic mode, vcpkg produces an "installed" tree, whose contents are changed by explicit calls to `vcpkg install` or -`vcpkg remove`. The installed tree is intended for consumption by any number of projects: for example, installing a -bunch of libraries and then using those libraries from Visual Studio, without additional configuration. Because the -installed tree is not associated with an individual project, it's similar to tools like `brew` or `apt`, except that the -installed tree is vcpkg-installation-local, rather than global to a system or user. - -In manifest mode, an installed tree is associated with a particular project rather than the vcpkg installation. The set -of installed ports is controlled by editing the project's "manifest file", and the installed tree is placed in the -project directory or build directory. This mode acts more similarly to language package managers like Cargo, or npm. We -recommend using this manifest mode whenever possible, because it allows one to encode a project's dependencies -explicitly in a project file, rather than in the documentation, making your project much easier to consume. - -Check out the [manifest cmake example](../examples/manifest-mode-cmake.md) for an example project using CMake and -manifest mode. - -## Table of Contents - -- [Simple Example Manifest](#simple-example-manifest) -- [Manifest Syntax Reference](#manifest-syntax-reference) - - [`"name"`](#name) - - [Version Fields](#version-fields) - - [`"description"`](#description) - - [`"builtin-baseline"`](#builtin-baseline) - - [`"dependencies"`](#dependencies) - - [`"name"`](#dependencies-name) - - [`"default-features"`](#dependencies-default-features) - - [`"features"`](#dependencies-features) - - [`"host"`](#host) - - [`"platform"`](#platform) - - [`"version>="`](#version-gt) - - [`"overrides"`](#overrides) - - [`"supports"`](#supports) - - [`"features"`](#features) - - [`"default-features"`](#default-features) - - [`"vcpkg-configuration"`](#vcpkg-configuration) - -## Simple Example Manifest - -```json -{ - "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json", - "name": "my-application", - "version": "0.15.2", - "dependencies": [ - "boost-system", - { - "name": "cpprestsdk", - "default-features": false - }, - "libxml2", - "yajl" - ] -} -``` - -## Manifest Syntax Reference - -A manifest is a JSON-formatted file named `vcpkg.json` which lies at the root of your project. -It contains all the information a person needs to know to get dependencies for your project, -as well as all the metadata about your project that a person who depends on you might be interested in. - -Manifests follow strict JSON: they can't contain C++-style comments (`//`) nor trailing commas. However -you can use field names that start with `$` to write your comments in any object that has a well-defined set of keys. -These comment fields are not allowed in any objects which permit user-defined keys (such as `"features"`). - -The latest JSON Schema is available at https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. IDEs with JSON Schema support such as Visual Studio and Visual Studio Code can use this file to provide IntelliSense and syntax checking. For most IDEs, you should set `"$schema"` in your `vcpkg.json` to this URL (like the above example). - -Each manifest contains a top level object with the following fields: - - - -### `"name"` - -This is the name of your project! It must be formatted in a way that vcpkg understands - in other words, -it must be lowercase alphabetic characters, digits, and hyphens, and it must not start nor end with a hyphen. -For example, `Boost.Asio` might be given the name `boost-asio`. - -### Version Fields - -There are four version field options, depending on how the port orders its -releases. - -* [`"version"`](versioning.md#version) - Generic, dot-separated numeric - sequence. -* [`"version-semver"`](versioning.md#version-semver) - [Semantic Version - 2.0.0](https://semver.org/#semantic-versioning-specification-semver) -* [`"version-date"`](versioning.md#version-date) - Used for packages which do - not have numeric releases (for example, Live-at-HEAD). Matches `YYYY-MM-DD` - with optional trailing dot-separated numeric sequence. -* [`"version-string"`](versioning.md#version-string) - Used for packages that - don't have orderable versions. This should be rarely used, however all ports - created before the other version fields were introduced use this scheme. - -Additionally, the optional `"port-version"` field is used to indicate revisions -to the port with the same upstream source version. For pure consumers, this -field should not be used. - -See [versioning](versioning.md#version-schemes) for more details. - - - -### `"description"` - -This is where you describe your project. Give it a good description to help in searching for it! -This can be a single string, or it can be an array of strings; -in the latter case, the first string is treated as a summary, -while the remaining strings are treated as the full description. - - - -### `"builtin-baseline"` - -This field indicates the commit of vcpkg which provides global minimum version -information for your manifest. - -It is required for top-level manifest files using versioning without a specified [`"default-registry"`](registries.md#configuration-default-registry). It has the same semantic as defining your default registry to be: -```json -{ - "default-registry": { - "kind": "builtin", - "baseline": "" - } -} -``` - -See [versioning](versioning.md#baselines) for more semantic details. - - - -### `"dependencies"` - -This field lists all the dependencies you'll need to build your library (as well as any your dependents might need, -if they were to use you). It's an array of strings and objects: - -* A string dependency (e.g., `"dependencies": [ "zlib" ]`) is the simplest way one can depend on a library; - it means you don't depend on a single version, and don't need to write down any more information. -* On the other hand, an object dependency (e.g., `"dependencies": [ { "name": "zlib" } ]`) - allows you to add that extra information. - -#### Example: - -```json -"dependencies": [ - { - "name": "arrow", - "default-features": false, - "features": [ "json" ] - }, - "boost-asio", - "openssl", - { - "name": "picosha2", - "platform": "!windows" - } -] -``` - - - -#### `"name"` Field - -The name of the dependency. This follows the same restrictions as the [`"name"`](#name) property for a project. - - - - -#### `"features"` and `"default-features"` Fields - -`"features"` is an array of feature names which tell you the set of features that the -dependencies need to have at a minimum, -while `"default-features"` is a boolean that tells vcpkg whether or not to -install the features the package author thinks should be "most common for most people to use". - -For example, `ffmpeg` is a library which supports many, many audio and video codecs; -however, for your specific project, you may only need mp3 encoding. -Then, you might just ask for: - -```json -{ - "name": "ffmpeg", - "default-features": false, - "features": [ "mp3lame" ] -} -``` - - - -#### `"host"` Field - -A boolean indicating that the dependency must be built for the [host triplet](host-dependencies.md) instead of the current port's triplet. Defaults to `false`. - -Any dependency that provides tools or scripts which should be "executed" during a build (such as buildsystems, code generators, or helpers) should be marked as `"host": true`. This enables correct cross-compilation in cases that the target is not executable -- such as when compiling for `arm64-android`. - -See [Host Dependencies](host-dependencies.md) for more information. - - - -#### `"platform"` Field - -The `"platform"` field defines the platforms where the dependency should be installed - for example, -you might need to use sha256, and so you use platform primitives on Windows, but `picosha2` on non-Windows platforms. - -```json -{ - "name": "picosha2", - "platform": "!windows" -} -``` - -This is a string field which takes boolean expressions of the form ``, -`!expression`, `expression { & expression & expression...}`, and `expression { | expression | expression...}`, -along with parentheses to denote precedence. -For example, a dependency that's only installed on the Windows OS, for the ARM64 architecture, -and on Linux on x64, would be written `(windows & arm64) | (linux & x64)`. - -The common identifiers are: - -- The operating system: `windows`, `uwp`, `linux`, `osx` (includes macOS), `android`, `emscripten` -- The architecture: `x86`, `x64`, `wasm32`, `arm64`, `arm` (includes both arm32 and arm64 due to backwards compatibility) - -although one can define their own. - - - -#### `"version>="` Field - -A minimum version constraint on the dependency. - -This field specifies the minimum version of the dependency, optionally using a -`#N` suffix to denote port-version if non-zero. - -See also [versioning](versioning.md#version-1) for more semantic details. - - - -### `"overrides"` - -This field pins exact versions for individual dependencies. - -`"overrides"` from transitive manifests (i.e. from dependencies) are ignored. - -See also [versioning](versioning.md#overrides) for more semantic details. - -#### Example: - -```json - "overrides": [ - { - "name": "arrow", "version": "1.2.3", "port-version": 7 - } - ] -``` - - - -### `"supports"` - -If your project doesn't support common platforms, you can tell your users this with the `"supports"` field. -It uses the same platform expressions as [`"platform"`](#platform), from dependencies, as well as the -`"supports"` field of features. -For example, if your library doesn't support linux, you might write `{ "supports": "!linux" }`. - - - - -### `"features"` and `"default-features"` - -The `"features"` field defines _your_ project's optional features, that others may either depend on or not. -It's an object, where the keys are the names of the features, and the values are objects describing the feature. -`"description"` is required, -and acts exactly like the [`"description"`](#description) field on the global package, -and `"dependencies"` are optional, -and again act exactly like the [`"dependencies"`](#dependencies) field on the global package. -There's also the `"supports"` field, -which again acts exactly like the [`"supports"`](#supports) field on the global package. - -You also have control over which features are default, if a person doesn't ask for anything specific, -and that's the `"default-features"` field, which is an array of feature names. - -#### Example: - -```json -{ - "name": "libdb", - "version": "1.0.0", - "description": [ - "An example database library.", - "Optionally can build with CBOR, JSON, or CSV as backends." - ], - "$default-features-explanation": "Users using this library transitively will get all backends automatically", - "default-features": [ "cbor", "csv", "json" ], - "features": { - "cbor": { - "description": "The CBOR backend", - "dependencies": [ - { - "$explanation": [ - "This is how you tell vcpkg that the cbor feature depends on the json feature of this package" - ], - "name": "libdb", - "default-features": false, - "features": [ "json" ] - } - ] - }, - "csv": { - "description": "The CSV backend", - "dependencies": [ - "fast-cpp-csv-parser" - ] - }, - "json": { - "description": "The JSON backend", - "dependencies": [ - "jsoncons" - ] - } - } -} -``` - -### `"vcpkg-configuration"` - -Allows to embed vcpkg configuration properties inside the `vcpkg.json` file. Everything inside -the `vcpkg-configuration` property is treated as if it were defined in a `vcpkg-configuration.json` file. -See the [`vcpkg-configuration.json` documentation](registries.md) for details. - -Having a `vcpkg-configuration` defined in `vcpkg.json` while also having a `vcpkg-configuration.json` -file is not allowed and will result in the vcpkg command terminating with an error message. - -#### Example: - -```json - "name": "test", - "version": "1.0.0", - "dependencies": [ "beison", "zlib" ], - "vcpkg-configuration": { - "registries": [ - { - "kind": "git", - "baseline": "dacf4de488094a384ca2c202b923ccc097956e0c", - "repository": "https://github.com/northwindtraders/vcpkg-registry", - "packages": [ "beicode", "beison" ] - } - ], - "overlay-ports": [ "./my-ports/fmt", - "./team-ports" - ] - } -``` diff --git a/docs/users/mingw.md b/docs/users/mingw.md deleted file mode 100644 index 2a0408f76b..0000000000 --- a/docs/users/mingw.md +++ /dev/null @@ -1,155 +0,0 @@ -# Vcpkg and Mingw-w64 - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/mingw.md).** - -*MinGW is not tested as part of vcpkg repository's CI process, so regressions can occur as part of library updates. PRs improving support are welcome!* - -## Table of Contents - - - [Mingw-w64 community triplets](#mingw-w64-community-triplets) - - [Using Mingw-w64 natively on Windows](#mingw-native) - - [How to avoid mixing different installations](#how-to-avoid-mixing-different-installations) - - [Using Mingw-w64 to build Windows programs on other systems](#mingw-cross) - -## Mingw-w64 community triplets - -Vcpkg includes -[x64, x86, arm64 and arm community triplets](https://github.com/microsoft/vcpkg/tree/master/triplets/community) -for [Mingw-w64](http://mingw-w64.org/). They don't depend on Visual Studio and -can be used natively on Windows as well as for cross-compiling on -other operating systems. There are two variants of each triplet, -selecting between static and dynamic linking. The actual tools -(g++ etc.) are expected to be named with particular prefixes. - -| architecture | vcpkg community triplets | tool name prefix | -|--------------|-----------------------------------------|----------------------| -| x64 | x64-mingw-dynamic, x64-mingw-static | x86_64-w64-mingw32- | -| x86 | x86-mingw-dynamic, x86-mingw-static | i686-w64-mingw32- | -| arm64 | arm64-mingw-dynamic, arm64-mingw-static | aarch64-w64-mingw32- | -| arm | arm-mingw-dynamic, arm-mingw-static | armv7-w64-mingw32- | - -These triplets are not tested by continuous integration, so many ports -do not build, and even existing ports may break on port updates. -Because of this, community involvement is paramount! - -- [Discussions](https://github.com/microsoft/vcpkg/discussions?discussions_q=mingw) -- [Open issues](https://github.com/microsoft/vcpkg/issues?q=is%3Aissue+is%3Aopen+mingw) -- [Open pull requests](https://github.com/microsoft/vcpkg/pulls?q=is%3Apr+is%3Aopen+mingw) - - -## Using Mingw-w64 natively on Windows - -With [MSYS2](https://www.msys2.org/), it is possible to easily create -a full environment for building ports with Mingw-w64 on a Windows PC. - -Note that for building software for native windows environments, you -must use a mingw subsystem of MSYS2, and install some packages -(with a specific prefix) for this subsystem. - -| architecture | vcpkg triplets | subsystem | package prefix | -|--------------|-------------------------------------|-----------|-------------------| -| x64 | x64-mingw-dynamic, x64-mingw-static | mingw64 | mingw-w64-x86_64- | -| x86 | x86-mingw-dynamic, x86-mingw-static | mingw32 | mingw-w64-i686- | - -After the basic installation of MSYS2, you will need to install a few -additional packages for software development, e.g. for x64: - -```bash -pacman -S --needed git base-devel mingw-w64-x86_64-toolchain -``` - -The active subsystem is selected by running the MSYS2 MinGW app, or -changed in a running terminal by - -```bash -source shell mingw64 # for x64, or "mingw32" for x86 -``` - -The bootstrapping of vcpkg shall be done by running bootstrap-vcpkg.bat. -This will download the official vcpkg.exe. - -```bash -git clone https://github.com/microsoft/vcpkg.git -cd vcpkg -./bootstrap-vcpkg.bat -``` - -For building packages, you need to tell vcpkg that you want to use the -mingw triplet. This can be done in different ways. When Visual Studio -is not installed, you must also set the host triplet to mingw. This is -needed to resolve host dependencies. For convenience, you can use -environment variables to set both triplets: - -```bash -export VCPKG_DEFAULT_TRIPLET=x64-mingw-dynamic -export VCPKG_DEFAULT_HOST_TRIPLET=x64-mingw-dynamic -``` - -Now you can test your setup: - -```bash -./vcpkg install zlib -``` - -### How to avoid mixing different installations - -[The MSYS2 project explicitly warns](https://www.msys2.org/wiki/MSYS2-introduction/#path) -that "mixing in programs from other MSYS2 installations, Cygwin installations, -compiler toolchains or even various other programs is not supported and will -probably break things in unexpected ways." For example, the proper passing of -command line arguments with quoting and escaping may fail. - -But Vcpkg ports implicitly create MSYS2 installations, e.g. for `pkg-config` -and for various other build tools needed to deal with packages based on -autoconf. In particular, when ports prepend the directory of tools to the -`PATH` environment variable, this may change which tool with a particular -name is actually invoked, and how arguments are passed between tools. - -To mitigate such issues when working with a full MSYS2 installation, -try to keep the directories of the msys subsystem (`/usr/bin`, `bin`) -out of the `PATH` environment variable as found by vcpkg. In bash, you -may modify the `PATH` just for a single call of vcpkg: - -```bash -PATH="${PATH/:\/usr\/bin:\/bin:/:}" ./vcpkg install libpq -``` - -Alternatively, you may run vcpkg from a regular Command Prompt, after -adding *only* the desired mingw directory (e.g. `C:\msys64\mingw64\bin`) -to the `PATH`. - -When using vcpkg for CI with standard images on Azure Pipelines, Github Actions -or similar, note that the default `PATH` might contain more directories -which create a mix of MSYS2 programs from different installations. You may -want to set the desired `PATH` manually, or remove directories which contain -`sh.exe`, `bash.exe`, `msys-2.0.dll` or `cygwin1.dll`. - - -## Using Mingw-w64 to build Windows programs on other systems - -You can use the vcpkg mingw community triplets with toolchains on -non-Windows computers to cross-compile software to be run on Windows. -Many Linux distributions offer such toolchains in optional packages -with a mingw-w64 [suffix](https://repology.org/projects/?search=-mingw-w64) -or [prefix](https://repology.org/projects/?search=mingw-w64-). -As an example, for Debian-based distributions, you would start with -this installation command for the x64 toolchain: - -``` -sudo apt-get install gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64 -``` - -Note that the packaged versions of Mingw-w64 toolchains on Linux distributions -might be older releases which lack some useful features or bug fixes. -An alternative independent toolchain is offered by [MXE](https://mxe.cc/). - -For vcpkg bootstrapping, clone the github repository and run the -`bootstrap-vcpkg.sh` script: - -```bash -git clone https://github.com/microsoft/vcpkg.git -cd vcpkg -./bootstrap-vcpkg.sh -./vcpkg install zlib:x64-mingw-dynamic -``` - diff --git a/docs/users/registries.md b/docs/users/registries.md deleted file mode 100644 index 2770843543..0000000000 --- a/docs/users/registries.md +++ /dev/null @@ -1,381 +0,0 @@ -# Using Registries - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/registries.md).** - -There are two parts to using registries; this documents the use side of the -relationship. In order to learn more about creating registries for others to -use, please read [this documentation](../maintainers/registries.md). - -## Table of Contents - -- [Using Registries](#using-registries) - - [Table of Contents](#table-of-contents) - - [`vcpkg-configuration.json`](#vcpkg-configurationjson) - - [Registry Objects](#registry-objects) - - [Registry Objects: `"kind"`](#registry-objects-kind) - - [Registry Objects: `"baseline"`](#registry-objects-baseline) - - [Registry Objects: `"repository"`](#registry-objects-repository) - - [Registry Objects: `"path"`](#registry-objects-path) - - [Registry Objects: `"packages"`](#registry-objects-packages) - - [Configuration: `"default-registry"`](#configuration-default-registry) - - [Configuration: `"registries"`](#configuration-registries) - - [Configuration: `"overlay-ports"`](#configuration-overlay-ports) - - [Configuration: `"overlay-triplets"`](#configuration-overlay-triplets) - - [Example Configuration File](#example-configuration-file) - - [Package Name Resolution](#package-name-resolution) - - [Overlays Resolution](#overlays-resolution) - - [Versioning Support](#versioning-support) - -## `vcpkg-configuration.json` - -From a high level perspective, everything that a project needs to define -about registries is contained in the vcpkg configuration file. In classic -mode, the configuration file lies in the vcpkg root; for manifest mode, -the file must exist next to the project's `vcpkg.json` file. -This file is named `vcpkg-configuration.json`, and it's a simple top-level -object file. - -### Registry Objects - -Registries are defined in JSON as objects. They must contain at least the -`"kind"` and `"baseline"` fields, and additionally the different kinds of -registry will have their own way of defining where the registry can be found: - -- git registries require the `"repository"` field -- filesystem registries require the `"path"` field -- built-in registries do not require a field, since there is only one - built-in registry. - -#### Registry Objects: `"kind"` - -The `"kind"` field must be a string: - -- For git registries: `"git"` -- For filesystem registries: `"filesystem"` -- For the builtin registry: `"builtin"` - -#### Registry Objects: `"baseline"` - -The `"baseline"` field must be a string. It defines a minimum version for all packages coming from this registry configuration. - -For [Git Registries](../maintainers/registries.md#git-registries) and for the [Builtin Registry](../maintainers/registries.md#builtin-registries), it should be a 40-character git commit sha in the registry's repository that contains a `versions/baseline.json`. - -For [Filesystem Registries](../maintainers/registries.md#filesystem-registries), it can be any valid baseline string that the registry defines. - -#### Registry Objects: `"repository"` - -This should be a string, of any repository format that git understands: - -- `"https://github.com/microsoft/vcpkg"` -- `"git@github.com:microsoft/vcpkg"` -- `"/dev/vcpkg-registry"` - -#### Registry Objects: `"path"` - -This should be a path; it can be either absolute or relative; relative paths -will be based at the directory the `vcpkg-configuration.json` lives in. - -#### Registry Objects: `"packages"` - -With exception of the default registry and artifacts registries. All registries -must declare the packages they provide using the `"packages"` array. - -Each entry in the array must be: -* a package name, or -* a package prefix. - -Package names may contain only lowercase letters, digits, and `-`. Package names cannot start or end with `-`. - -Package prefixes must follow these rules: -* Use the wildcard character: `*` - * `*` matches zero or more port name characters (lowercase letters, digits, and `-`). -* Contain only one wildcard (`*`) -* The wildcard (`*`) must be the last character in the pattern. -* All characters before the wildcard `*` must be valid port name characters. - -Examples of valid patterns: -* `*`: Matches all port names -* `b*`: Matches ports that start with the letter `b` -* `boost-*`: Matches ports that start with the prefix `boost-` - -Examples of invalid patterns: -* `*a` (`*` must be the last character in the prefix) -* `a**` (only one `*` is allowed) -* `a+` (`+` is not a valid wildcard) -* `a?` (`?` is not a valid wildcard) - -See [package name resolution](#package-name-resolution) for more details. - -### Configuration: `"default-registry"` - -The default registry is used as a fallback when resolving package names, -if no other registry matches the package name, the default registry will be selected. -Users can set the default registry to `null`, in which case, if no other registry matches -a package name the install will fail. - -The default registry is either a registry object without a `"packages"` array -(since it will automatically match any non-resolved package names) or `null`. - -If `vcpkg-configuration.json` does not declare a `"default-registry"`, vcpkg will -automatically set the default registry to the `"builtin-registry"`. - -The `"builtin-registry"` is the local instance of `https://github.com/Microsoft/vcpkg`. -This is necessary so that a manifest with no explicit registry configuration can resolve -port names in the official vcpkg catalog. The `"builtin-baseline"` property in `vcpkg.json` -can be used to set the baseline for the `"builtin-registry"`. - -### Configuration: `"registries"` - -The `"registries"` field is used to define additional port and/or artifact registries. - -Port registries are also required to declare a list of packages they provide using the `"packages"` array. - -Using additional port registries also requires that a baseline is provided for the default registry -or that the default registry is set to null. If using the `"builtin-registry"` you can set the baseline -using the `"builtin-baseline"` field in `vcpkg.json`. - -### Configuration: `"overlay-ports"` - -An array of port overlay paths. - -Each path in the array must point to etiher: -* a particular port directory (a directory containing `vcpkg.json` and `portfile.cmake`), or -* a directory containing port directories. -Relative paths are resolved relative to the `vcpkg-configuration.json` file. Absolute paths can be used but are discouraged. - -### Configuration: `"overlay-triplets"` - -An array of triplet overlay paths. - -Each path in the array must point to a directory of triplet files ([see triplets documentation](triplets.md)). -Relative paths are resolved relative to the `vcpkg-configuration.json` file. Absolute paths can be used but are discouraged. - -### Example Configuration File - -Let's assume that you have mirrored at -: this will be your default registry. -Additionally, you want to use North Wind Trader's registry for their -beison and beicode libraries, as well as configure overlay ports and -overlay triplets from your custom directories. The following -`vcpkg-configuration.json` will work: - -```json -{ - "default-registry": { - "kind": "git", - "repository": "https://internal/mirror/of/github.com/Microsoft/vcpkg", - "baseline": "eefee7408133f3a0fef711ef9c6a3677b7e06fd7" - }, - "registries": [ - { - "kind": "git", - "repository": "https://github.com/northwindtraders/vcpkg-registry", - "baseline": "dacf4de488094a384ca2c202b923ccc097956e0c", - "packages": [ "beicode", "beison" ] - } - ], - "overlay-ports": [ "./team-ports", - "c:/project/my-ports/fmt", - "./custom-ports" - ], - "overlay-triplets": [ "./my-triplets" ] -} -``` - -## Package Name Resolution - -Package name resolution in vcpkg is designed to be predictable and easy to understand. Given a -`vcpkg-configuration.json` file, it should be simple to tell which registry will provide any given port name. - -When resolving a port name to a registry, we prioritize as follows: -1. Exact match -2. Pattern match - * Longer prefixes have higher priority, e.g.: when resolving `boost`, `boost*` > `b*` > `*` -3. Default registry -4. If the default registry has been set to null, emit an error - -Package names have higher priority than prefixes even if they both match the same amount of characters. -For example, when resolving `boost`: `boost` > `boost*`. - -If there is a tie in priority, vcpkg will use the first registry that declares the package name or prefix. -_This makes the order in which registries are declared in the `"registries"` array important._ - -### Example #1: Package name resolution - -`vcpkg-configuration.json` -```json -{ - "registries": [ - { - "kind": "git", - "repository": "https://github.com/northwindtraders/vcpkg-registry", - "baseline": "dacf4de488094a384ca2c202b923ccc097956e0c", - "packages": ["bei*"] - }, - { - "kind": "git", - "repository": "https://github.com/vicroms/vcpkg-registry", - "baseline": "dacf4de488094a384ca2c202b923ccc097956e0c", - "packages": ["beicode", "bei*"] - } - ] -} - -``` - -`vcpkg.json` -```json -{ - "dependencies": [ - "beicode", - "beison", - "fmt" - ], - "builtin-baseline": "7e7c62d863b1bf599c1d104b76cd8b74475844d4" -} -``` - -Given this configuration, each package name resolves to: - -* `beicode`: from registry `https://github.com/vicroms/vcpkg-registry` (exact match on `beicode`) -* `beison`: from registry `https://github.com/northwindtraders/vcpkg-registry` (pattern match on `beison` and declared first in `"registries"` array) -* `fmt`: from default registry (no matches) - -Because multiple registries declare `bei*`, vcpkg will also emit the following warning: - -```no-highlight -Found the following problems in configuration (path/to/vcpkg-configuration.json): -$ (a configuration object): warning: Package "bei*" is duplicated. - First declared in: - location: $.registries[0].packages[0] - registry: https://github.com/northwindtraders/vcpkg-registry - - The following redeclarations will be ignored: - location: $.registries[1].packages[1] - registry: https://github.com/vicroms/vcpkg-registry -``` - -### Example #2: Overriding the default registry - -There are two ways for a user to override the default registry. - -One way is to use the `"default-registry"` object: -```json -{ - "default-registry": { - "kind": "git", - "repository": "https://github.com/Microsoft/vcpkg", - "baseline": "e79c0d2b5d72eb3063cf32a1f7de1a9cf19930f3" - } -} -``` - -The other way is to set the `"default-registry"` object to null and -use the `"*"` pattern in the first registry of the `"registries"` array. -```json -{ - "default-registry": null, - "registries": [ - { - "kind": "git", - "repository": "https://github.com/Microsoft/vcpkg", - "baseline": "e79c0d2b5d72eb3063cf32a1f7de1a9cf19930f3", - "packages": ["*"] - } - ] -} -``` - -An advantage of the second form is that you can add more entries to the packages array, while the -`"default-registry"` object doesn't allow you to define a packages array at all. This difference -becomes important in cases where you need to ensure that a package comes from the default registry, like -in the example below. - -### Example #3: Ensuring correct name resolution - -Let's consider a registry that provides the Qt Framework libraries. - -`vcpkg-configuration.json` -```json -{ - "default-registry": { - "kind": "git", - "repository": "https://github.com/Microsoft/vcpkg", - "baseline": "7e7c62d863b1bf599c1d104b76cd8b74475844d4" - }, - "registries": [ - { - "kind": "git", - "repository": "https://github.com/custom-qt/custom-qt-registry", - "baseline": "adfc4de488094a384ca2c202b923ccc097956e0c", - "packages": ["qt*"] - } - ] -} -``` - -And the following project dependencies: - -`vcpkg.json` -```json -{ - "dependencies": [ - "qt5", - "qt-advanced-docking-system", - "qtkeychain" - ] -} -``` - -The `"qt*"` pattern matches all port names in `vcpkg.json`. But there is a problem! -The ports `qt-advanced-docking-system` and `qtkeychain` are not part of the official Qt Framework libraries, -and since vcpkg won't be able to find the ports in the custom registry the installation will fail. - -The obvious solution is to make sure that these packages come from the default registry instead, -we can accomplish that by changing the way we declare the default registry and adding `qt-advanced-docking-system` -and `qtkeychain` to its `"packages"` array: - -`vcpkg-configuration.json` -```json -{ - "default-registry": null, - "registries": [ - { - "kind": "git", - "repository": "https://github.com/Microsoft/vcpkg", - "baseline": "e79c0d2b5d72eb3063cf32a1f7de1a9cf19930f3", - "packages": ["*", "qt-advanced-docking-system", "qtkeychain"] - }, - { - "kind": "git", - "repository": "https://github.com/custom-qt/custom-qt-registry", - "baseline": "adfc4de488094a384ca2c202b923ccc097956e0c", - "packages": ["qt*"] - } - ] -} -``` - -Because exact matches are preferred over pattern matches, this configuration will make -`qt-advanced-docking-system` and `qtkeychain` resolve to the default registry. - -### Overlays Resolution - -Overlay ports and triplets are evaluated in this order: - -1. Overlays from the [command line](../commands/common-options.md) -2. Overlays from `vcpkg-configuration.json` -3. Overlays from the `VCPKG_OVERLAY_[PORTS|TRIPLETS]` [environment](config-environment.md) variable. - -Additionaly, each method has its own evaluation order: - -* Overlays from the command line are evaluated from left-to-right in the order each argument is passed, with each `--overlay-[ports|triplets]` argument adding a new overlay location. -* Overlays from `vcpkg-configuration.json` are evaluated in the order of the `"overlay-[ports|triplets]"` array. -* Overlays set by `VCPKG_OVERLAY_[PORTS|TRIPLETS]` are evaluated from left-to-right. Overlay locations are separated by an OS-specific path separator (`;` on Windows and `:` on non-Windows). - -### Versioning Support - -Versioning with custom registries works exactly as it does in the built-in -registry. You can read more about that in the [versioning documentation]. - -[versioning documentation]: versioning.md diff --git a/docs/users/selecting-library-features.md b/docs/users/selecting-library-features.md deleted file mode 100644 index a780d64037..0000000000 --- a/docs/users/selecting-library-features.md +++ /dev/null @@ -1,92 +0,0 @@ -# Selecting Library Features - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/selecting-library-features.md).** - -## Installing a library - -We will look at [llvm](https://llvm.org/) as an example. You could install it using: - -```powershell -> vcpkg install llvm -``` -or via a manifest with -```json -{ - "dependencies": ["llvm"] -} -``` - -With llvm now installed, we can execute: - -```powershell -> installed\x86-windows\bin\llc.exe --version -``` - -we see: - -```powershell - Registered Targets: - x86 - 32-bit X86: Pentium-Pro and above - x86-64 - 64-bit X86: EM64T and AMD64 -``` - -## Installing additional features - -But [llvm supports many more targets](https://llvm.org/docs/GettingStarted.html#local-llvm-configuration), from ARM to SPARC to SystemZ. -However, clearly our current installation doesn't include ARM as a target; -thus, we need to learn how vcpkg allows us to install other LLVM targets. -The llvm port allows this via the "target-*" features. - -If we do: - -```powershell -> vcpkg search llvm -``` - -We can see: - -``` -llvm 10.0.0#6 The LLVM Compiler Infrastructure -llvm[clang] Build C Language Family Front-end. -llvm[clang-tools-extra] Build Clang tools. -... -llvm[target-all] Build with all backends. -llvm[target-amdgpu] Build with AMDGPU backend. -llvm[target-arm] Build with ARM backend. -... -``` - -We can install any of these targets by using the install-feature syntax: - -```powershell -> vcpkg install llvm[target-arm] # Installs LLVM with the ARM target -``` -```json -{ - "dependencies": [{ "name": "llvm", "features": ["target-arm"] }] -} -``` - -## Opting out of default features - -The llvm port includes a few default features that you as a user may not want: for example, -the `clang` feature is default, which means that `vcpkg install llvm` will also build and install clang. -If you are writing a compiler that uses LLVM as a backend, -you're likely not interested in installing clang as well, -and we can do that by disabling default features with the special `core` "feature": -```powershell -> vcpkg install llvm[core,target-arm] # removing the default-feature with "core" also removes all of the default targets you get -``` -or in manifest files: -```json -{ - "dependencies": [{ - "name": "llvm", - "default-features": false, - "features": ["target-arm"] - }] -} -``` - -# Further reading -- The [Feature Packages](../specifications/feature-packages.md) specification was the initial design for features. diff --git a/docs/users/triplets.md b/docs/users/triplets.md deleted file mode 100644 index 08a076517c..0000000000 --- a/docs/users/triplets.md +++ /dev/null @@ -1,247 +0,0 @@ -# Triplet Files - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/triplets.md).** - -Triplet is a standard term used in cross compiling as a way to completely capture the target environment (cpu, os, compiler, runtime, etc) in a single convenient name. - -In Vcpkg, we use triplets to describe an imaginary "target configuration set" for every library. Within a triplet, libraries are generally built with the same configuration, but it is not a requirement. For example, you could have one triplet that builds `openssl` statically and `zlib` dynamically, one that builds them both statically, and one that builds them both dynamically (all for the same target OS and architecture). A single build will consume files from a single triplet. - -We currently provide many triplets by default (run `vcpkg help triplet`). However, you can easily customize or add your own by copying a built-in triplet from the `triplets\` directory into a project local location. Then, use `--overlay-triplets=` (or equivalent such as [`$VCPKG_OVERLAY_TRIPLETS`](config-environment.md#vcpkg_overlay_triplets), [CMake `VCPKG_OVERLAY_TRIPLETS`](buildsystems/cmake-integration.md#vcpkg_overlay_triplets), or [MSBuild Additional Options](buildsystems/msbuild-integration.md#vcpkg-additional-install-options)) to add that directory to vcpkg. See our [overlay triplets example](../examples/overlay-triplets-linux-dynamic.md) for a more detailed walkthrough. - -To change the triplet used by your project, you can pass `--triplet=` on the command line or see our [Buildsystem-Specific Documentation](buildsystems/integration.md). - -## Community triplets - -Triplets contained in the `triplets\community` folder are not tested by continuous integration, but are commonly requested by the community. - -Because we do not have continuous coverage, port updates may break compatibility with community triplets. Because of this, community involvement is paramount! - -We will gladly accept and review contributions that aim to solve issues with these triplets. - -### Usage - -Community Triplets are enabled by default, when using a community triplet a message like the following one will be printed during a package install: - -```no-highlight --- Using community triplet x86-uwp. This triplet configuration is not guaranteed to succeed. --- [COMMUNITY] Loading triplet configuration from: D:\src\viromer\vcpkg\triplets\community\x86-uwp.cmake -``` - -## Variables -### VCPKG_TARGET_ARCHITECTURE -Specifies the target machine architecture. - -Valid options are `x86`, `x64`, `arm`, `arm64` and `wasm32`. - -### VCPKG_CRT_LINKAGE -Specifies the desired CRT linkage (for MSVC). - -Valid options are `dynamic` and `static`. - -### VCPKG_LIBRARY_LINKAGE -Specifies the preferred library linkage. - -Valid options are `dynamic` and `static`. Note that libraries can ignore this setting if they do not support the preferred linkage type. - -### VCPKG_BUILD_TYPE -You can set this value to `release` to only build release versions of the ports. By default this value is empty and release and debug versions of a port are built. - -### VCPKG_CMAKE_SYSTEM_NAME -Specifies the target platform. - -Valid options include any CMake system name, such as: -- Empty (Windows Desktop for legacy reasons) -- `WindowsStore` (Universal Windows Platform) -- `MinGW` (Minimalist GNU for Windows) -- `Darwin` (Mac OSX) -- `iOS` (iOS) -- `Linux` (Linux) -- `Emscripten` (WebAssembly) - -### VCPKG_CMAKE_SYSTEM_VERSION -Specifies the target platform system version. - -This field is optional and, if present, will be passed into the build as `CMAKE_SYSTEM_VERSION`. - -See also the CMake documentation for `CMAKE_SYSTEM_VERSION`: https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_VERSION.html. - - -### VCPKG_CHAINLOAD_TOOLCHAIN_FILE -Specifies an alternate CMake Toolchain file to use. - -This (if set) will override all other compiler detection logic. By default, a toolchain file is selected from `scripts/toolchains/` appropriate to the platform. - -See also the CMake documentation for toolchain files: https://cmake.org/cmake/help/v3.11/manual/cmake-toolchains.7.html. - -### VCPKG_CXX_FLAGS -Sets additional compiler flags to be used when not using `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`. - -This option also has forms for configuration-specific and C flags: -- `VCPKG_CXX_FLAGS` -- `VCPKG_CXX_FLAGS_DEBUG` -- `VCPKG_CXX_FLAGS_RELEASE` -- `VCPKG_C_FLAGS` -- `VCPKG_C_FLAGS_DEBUG` -- `VCPKG_C_FLAGS_RELEASE` - -### VCPKG_LINKER_FLAGS -Sets additional linker flags to be used while building dynamic libraries and -executables in the absence of `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`. - -This option also has forms for configuration-specific flags: -- `VCPKG_LINKER_FLAGS` -- `VCPKG_LINKER_FLAGS_DEBUG` -- `VCPKG_LINKER_FLAGS_RELEASE` - -### VCPKG_MESON_CONFIGURE_OPTIONS -Set additional Meson configure options that are appended to the configure command (in [`vcpkg_configure_meson`](../maintainers/vcpkg_configure_meson.md)). - -This field is optional. - -Also available as build-type specific `VCPKG_MESON_CONFIGURE_OPTIONS_DEBUG` and `VCPKG_MESON_CONFIGURE_OPTIONS_RELEASE` variables. - -### VCPKG_MESON_(CROSS|NATIVE)_FILE(_RELEASE|_DEBUG) -Provide an additional (configuration dependent) file as a meson cross/native file. Can be used to override settings provided by vcpkg since it will be passed after vcpkg's generated cross/native files are passed. - -Especially usefull to provide your own build_machine and host_machine entries. - -### VCPKG_CMAKE_CONFIGURE_OPTIONS -Set additional CMake configure options that are appended to the configure command (in [`vcpkg_cmake_configure`](../maintainers/vcpkg_cmake_configure.md)). - -This field is optional. - -Also available as build-type specific `VCPKG_CMAKE_CONFIGURE_OPTIONS_DEBUG` and `VCPKG_CMAKE_CONFIGURE_OPTIONS_RELEASE` variables. - -### VCPKG_MAKE_CONFIGURE_OPTIONS -Set additional automake / autoconf configure options that are appended to the configure command (in [`vcpkg_configure_make`](../maintainers/vcpkg_configure_make.md)). - -This field is optional. - -For example, to skip certain libtool checks that may errantly fail: -```cmake -set(VCPKG_MAKE_CONFIGURE_OPTIONS "lt_cv_deplibs_check_method=pass_all") -``` - -Also available as build-type specific `VCPKG_MAKE_CONFIGURE_OPTIONS_DEBUG` and `VCPKG_MAKE_CONFIGURE_OPTIONS_RELEASE` variables. - - -### VCPKG_DEP_INFO_OVERRIDE_VARS -Replaces the default computed list of triplet "Supports" terms. - -This option (if set) will override the default set of terms used for qualified dependency resolution and "Supports" field evaluation. - -See the [`"supports"`](../maintainers/manifest-files.md#supports) manifest file field documentation for more details. - -> Implementers' Note: this list is extracted via the `vcpkg_get_dep_info` mechanism. - -### VCPKG_DISABLE_COMPILER_TRACKING - -When this option is set to (true|1|on), the compiler is ignored in the abi tracking. - -## Windows Variables - - -### VCPKG_ENV_PASSTHROUGH -Instructs vcpkg to allow additional environment variables into the build process. - -On Windows, vcpkg builds packages in a special clean environment that is isolated from the current command prompt to -ensure build reliability and consistency. This triplet option can be set to a list of additional environment variables -that will be added to the clean environment. The values of these environment variables will be hashed into the package -abi -- to pass through environment variables without abi tracking, see `VCPKG_ENV_PASSTHROUGH_UNTRACKED`. - -See also the `vcpkg env` command for how you can inspect the precise environment that will be used. - -> Implementers' Note: this list is extracted via the `vcpkg_get_tags` mechanism. - -### VCPKG_ENV_PASSTHROUGH_UNTRACKED -Instructs vcpkg to allow additional environment variables into the build process without abi tracking. - -See `VCPKG_ENV_PASSTHROUGH`. - - -### VCPKG_VISUAL_STUDIO_PATH -Specifies the Visual Studio installation to use. - -To select the precise combination of Visual Studio instance and toolset version, we walk through the following algorithm: -1. Determine the setting for `VCPKG_VISUAL_STUDIO_PATH` from the triplet, or the environment variable `VCPKG_VISUAL_STUDIO_PATH`, or consider it unset -2. Determine the setting for `VCPKG_PLATFORM_TOOLSET` from the triplet or consider it unset -3. Gather a list of all pairs of Visual Studio Instances with all toolsets available in those instances - 1. This is ordered first by instance type (Stable, Prerelease, Legacy) and then by toolset version (v143, v142, v141, v140) -4. Filter the list based on the settings for `VCPKG_VISUAL_STUDIO_PATH` and `VCPKG_PLATFORM_TOOLSET`. -5. Select the best remaining option - -The path should be absolute, formatted with backslashes, and have no trailing slash: -```cmake -set(VCPKG_VISUAL_STUDIO_PATH "C:\\Program Files (x86)\\Microsoft Visual Studio\\Preview\\Community") -``` - -### VCPKG_PLATFORM_TOOLSET -Specifies the VS-based C/C++ compiler toolchain to use. - -See [`VCPKG_VISUAL_STUDIO_PATH`](#VCPKG_VISUAL_STUDIO_PATH) for the full selection algorithm. - -Valid settings: -* The Visual Studio 2022 platform toolset is `v143`. -* The Visual Studio 2019 platform toolset is `v142`. -* The Visual Studio 2017 platform toolset is `v141`. -* The Visual Studio 2015 platform toolset is `v140`. - -### VCPKG_PLATFORM_TOOLSET_VERSION -Specifies the detailed MSVC C/C++ compiler toolchain to use. - -By default, [`VCPKG_PLATFORM_TOOLSET`] always chooses the latest installed minor version of the selected toolset. -If you need more granularity, you can use this variable. -Valid values are, for example, `14.25` or `14.27.29110`. - -### VCPKG_LOAD_VCVARS_ENV -If `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` is used, VCPKG will not setup the Visual Studio environment. -Setting `VCPKG_LOAD_VCVARS_ENV` to (true|1|on) changes this behavior so that the Visual Studio environment is setup following the same rules as if `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` was not set. - -## Linux Variables - -### VCPKG_FIXUP_ELF_RPATH -When this option is set to (true|1|on), vcpkg will add `$ORIGIN` and `$ORIGIN/` to the `RUNPATH` header of executables and shared libraries. This allows packages to be relocated on Linux. - -## MacOS Variables - -### VCPKG_INSTALL_NAME_DIR -Sets the install name used when building macOS dynamic libraries. Default value is `@rpath`. See the CMake documentation for [CMAKE_INSTALL_NAME_DIR](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_NAME_DIR.html) for more information. - -### VCPKG_OSX_DEPLOYMENT_TARGET -Sets the minimum macOS version for compiled binaries. This also changes what versions of the macOS platform SDK that CMake will search for. See the CMake documentation for [CMAKE_OSX_DEPLOYMENT_TARGET](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_DEPLOYMENT_TARGET.html) for more information. - -### VCPKG_OSX_SYSROOT -Set the name or path of the macOS platform SDK that will be used by CMake. See the CMake documentation for [CMAKE_OSX_SYSROOT](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_SYSROOT.html) for more information. - - -### VCPKG_OSX_ARCHITECTURES -Set the macOS / iOS target architecture which will be used by CMake. See the CMake documentation for [CMAKE_OSX_ARCHITECTURES](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_ARCHITECTURES.html) for more information. - -## Per-port customization -The CMake Macro `PORT` will be set when interpreting the triplet file and can be used to change settings (such as `VCPKG_LIBRARY_LINKAGE`) on a per-port basis. - -Example: -```cmake -set(VCPKG_LIBRARY_LINKAGE static) -if(PORT MATCHES "qt5-") - set(VCPKG_LIBRARY_LINKAGE dynamic) -endif() -``` -This will build all the `qt5-*` libraries as DLLs, but every other library as a static library. - -For an example in a real project, see https://github.com/Intelight/vcpkg/blob/master/triplets/x86-windows-mixed.cmake. - -## Additional Remarks -The default triplet when running any vcpkg command is `%VCPKG_DEFAULT_TRIPLET%` or a platform-specific choice if that environment variable is undefined. - -- Windows: `x86-windows` -- Linux: `x64-linux` -- OSX: `x64-osx` - -We recommend using a systematic naming scheme when creating new triplets. The Android toolchain naming scheme is a good source of inspiration: https://developer.android.com/ndk/guides/standalone_toolchain.html. - -## Android triplets -See [android.md](android.md) - -## Mingw-w64 triplets -See [mingw.md](mingw.md) diff --git a/docs/users/versioning.implementation-details.md b/docs/users/versioning.implementation-details.md deleted file mode 100644 index e264e9ebfc..0000000000 --- a/docs/users/versioning.implementation-details.md +++ /dev/null @@ -1,134 +0,0 @@ -# Versioning: Implementation details - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/versioning.implementation-details.md).** - -## Contents - -* [Minimum versioning](#minimum-versioning) -* [Constraint resolution](#constraint-resolution) -* [Acquiring port versions](#acquiring-port-versions) - - -### Minimum versioning -Vcpkg uses a minimal selection approach to versioning, inspired by the one [used by Go](https://research.swtch.com/vgo-mvs). But modified in some ways: - -* Always starts from a fresh install, eliminates the need for upgrade/downgrade operations. -* Allow unconstrained dependencies by introducing baselines. - -The minimal selection principle, however, stays the same. Given a set of constraints, vcpkg will use the "oldest" possible versions of packages that can satisfy all the constraints. - -Using a minimum version approach has the following advantages: -* Is predictable and easy to understand. -* User controls when upgrades happen, as in, no upgrades are performed automatically when a new version is released. -* Avoids using a SAT solver. - -To give an example, consider the following package graph: -``` - (A 1.0) -> (B 1.0) - - (A 1.1) -> (B 1.0) - -> (C 3.0) - - (A 1.2) -> (B 2.0) - -> (C 3.0) - - (C 2.0) -``` - -And the following manifest: -``` -{ - "name": "example", - "version": "1.0.0", - "dependencies": [ - { "name": "A", "version>=": "1.1" }, - { "name": "C", "version>=": "2.0" } - ], - "builtin-baseline": "" -} -``` - -After accounting for transitive dependencies we have the following set of constraints: -* A >= 1.1 - * B >= 1.0 - * C >= 3.0 -* C >= 2.0 - -Since vcpkg has to satisfy all the constraints, the set of installed packages becomes: - -* `A 1.1`, even when `A 1.2` exists, there are no constraints higher than `1.1` so vcpkg selects the minimum version possible. -* `B 1.0`, transitively required by `A 1.1`. -* `C 3.0`, upgraded by the transitive constraint added by `B 1.0` in order to satisfy version constraints. - -## Constraint resolution -Given a manifest with a set of versioned dependencies, vcpkg will attempt to calculate a package installation plan that satisfies all the constraints. - -Version constraints come in the following flavors: -* **Declared constraints**: Constraints declared explicitly in the top-level manifest using `version>=`. -* **Baseline constraints**: Constraints added implicitly by the `builtin-baseline`. -* **Transitive constraints**: Constraints added indirectly by dependencies of your dependencies. -* **Overridden constraints**: Constraints overridden in the top-level manifest using `overrides` declarations. - -To compute an installation plan, vcpkg follows roughly these steps: - -* Add all top-level constraints to the plan. -* Recursively add transitive constraints to the plan. - * Each time a new package is added to the plan, also add its baseline constraint to the plan. - * Each time a constraint is added: - * If an override exists for the package - * Select the version in the override. - * Otherwise: - * If there is no previous version selected. - * Select the minimal version that satisfies the constraint. - * If there is a previous version selected: - * If the versioning scheme of the new constraint does not match that of the previously selected version: - * Add a version conflict. - * If the constraint's version is not comparable to the previously selected version. For example, comparing "version-string: apple" to "version-string: orange": - * Add a version conflict. - * If the constraints version is higher than the previously selected version: - * Select the highest version. - * Otherwise: - * Keep the previous selection. -* Review the plan: - * If there are no conflicts - * Install the selected packages - * Otherwise: - * Report the conflicts to the user - -## Acquiring port versions -Although the concept of package versions has always been present in vcpkg, the concept of version constraints has been not. - -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. - -To solve this problem, a new set of metadata files was introduced. These files are located in the `versions/` directory at the root level of the vcpkg repository. - -The `versions/` directory, 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. - -Example: `zlib.json` - -``` -{ - "versions": [ - { - "git-tree": "2dfc991c739ab9f2605c2ad91a58a7982eb15687", - "version-string": "1.2.11", - "port-version": 9 - }, - ... - { - "git-tree": "a516e5ee220c8250f21821077d0e3dd517f02631", - "version-string": "1.2.10", - "port-version": 0 - }, - { - "git-tree": "3309ec82cd96d752ff890c441cb20ef49b52bf94", - "version-string": "1.2.8", - "port-version": 0 - } - ] -} -``` - -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`. Aside from port version files, the current baseline file is located in `versions/baseline.json`. - - diff --git a/docs/users/versioning.md b/docs/users/versioning.md deleted file mode 100644 index 2fe23832e9..0000000000 --- a/docs/users/versioning.md +++ /dev/null @@ -1,174 +0,0 @@ -# Versioning - -**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/versioning.md).** - -Versioning allows you to deterministically control the precise revisions of dependencies used by -your project from within your manifest file. Versioning only applies to [Manifest Mode](manifests.md). - -For an example with context, see our guide to [getting started with versioning](../examples/versioning.getting-started.md). - -## Contents - -* [Version schemes](#version-schemes) - * [`version`](#version) - * [`version-semver`](#version-semver) - * [`version-date`](#version-date) - * [`version-string`](#version-string) -* [Version constraints](#version-constraints) - * [Baselines](#baselines) - * [`version>=`](#version-gte) - * [`overrides`](#overrides) - -## Version schemes -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. - -Each versioning scheme defines its own rules on what is a valid version string and more importantly the rules for how to sort versions using the same scheme. - -The versioning schemes understood by vcpkg are: - -Manifest property | Versioning scheme -------------------|------------------------------------ -`version` | For dot-separated numeric versions -`version-semver` | For SemVer compliant versions -`version-date` | For dates in the format YYYY-MM-DD -`version-string` | For arbitrary strings - -A manifest must contain only one version declaration. - -_NOTE: By design, vcpkg does not compare versions that use different schemes. For example, a package -that has a `version-string: 7.1.3` cannot be compared with the same package using `version: 7.1.4`, even if the -conversion seems obvious._ - -#### `version` -Accepts version strings that follow a relaxed, dot-separated-, semver-like scheme. - -The version is logically composed of dot-separated (`.`) numeric sections. Each section must contain an integer positive number with no leading zeroes. - -The regex pattern for this versioning scheme is: `(0|[1-9]\d*)(\.(0|[1-9]\d*))*` - -_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. - -Example: -`0` < `0.1` < `0.1.0` < `1` < `1.0.0` < `1.0.1` < `1.1`< `2.0.0` - -#### `version-semver` -Accepts version strings that follow semantic versioning conventions as described in the [semantic versioning specification](https://semver.org/#semantic-versioning-specification-semver). - -_Sorting behavior_: Strings are sorted following the rules described in the semantic versioning specification. - -Example: -`1.0.0-1` < `1.0.0-alpha` < `1.0.0-beta` < `1.0.0` < `1.0.1` < `1.1.0` - -#### `version-date` - -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. - -This is the recommended versioning scheme for "Live at HEAD" libraries that don't have established release versions. - -The regex pattern for this versioning scheme is: `\d{4}-\d{2}-\d{2}(\.(0|[1-9]\d*))*` - -_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. - -Examples: -`2021-01-01` < `2021-01-01.1` < `2021-02-01.1.2` < `2021-02-01.1.3` < `2021-02-01` - -#### `version-string` -For packages using version strings that do not fit any of the other schemes, it accepts most arbitrary strings. The `#` which is used to denote port versions is disallowed. - -_Sorting behavior_: No sorting is attempted on the version string itself. However, if the strings match exactly, their port versions can be compared and sorted. - -Examples: -* `apple` <> `orange` <> `orange.2` <> `orange2` -* `watermelon#0`< `watermelon#1` - -#### `port-version` -A positive integer value that increases each time the port changes without updating the sources. - -The rules for port versions are: -* Start at 0 for the original version of the port, -* increase by 1 each time a vcpkg-specific change is made to the port that does not increase the version of the package, -* and reset to 0 each time the version of the package is updated. - -_NOTE: Whenever vcpkg output a version it follows the format `#`. For example `1.2.0#2` means version `1.2.0` port version `2`. When the port version is `0` the `#0` suffix is omitted (`1.2.0` implies version `1.2.0` port version `0`)._ - -_Sorting behavior_: If two versions compare equally, their port versions are compared by their numeric value, lower port versions take precedence. - -Examples: -* `1.2.0` < `1.2.0#1` < `1.2.0#2` < `1.2.0#10` -* `2021-01-01#20` < `2021-01-01.1` -* `windows#7` < `windows#8` - -## Version constraints - -### Baselines - -Baselines define a global version floor for what versions will be considered. This enables top-level manifests to keep the entire graph of dependencies up-to-date without needing to individually specify direct [`"version>="`][version-gte] constraints. - -Every configured registry has an associated baseline. For manifests that don't configure any registries, the [`"builtin-baseline"`][builtin-baseline] field defines the baseline for the built-in registry. If a manifest does not configure any registries and does not have a [`"builtin-baseline"`][builtin-baseline], the install operates according to the Classic Mode algorithm and ignores all versioning information. - -Baselines, like other registry settings, are ignored from ports consumed as a dependency. If a minimum version is required during transitive version resolution the port should use [`"version>="`][version-gte]. - -**Example** -```json -{ - "name": "project", - "version": "1.0.0", - "dependencies": ["zlib", "fmt"], - "builtin-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe" -} -``` - -To add an initial `"builtin-baseline"`, use [`vcpkg x-update-baseline --add-initial-baseline`](../commands/update-baseline.md#add-initial-baseline). To update baselines in a manifest, use [`vcpkg x-update-baseline`](../commands/update-baseline.md). - - - -### `version>=` -Expresses a minimum version requirement, `version>=` declarations put a lower boundary on the versions that can be used to satisfy a dependency. - -**Note: Vcpkg selects the lowest version that matches all constraints, so a less-than constraint is not required.** - -Example: -```json -{ - "name": "project", - "version-semver": "1.0.0", - "dependencies": [ - { "name": "zlib", "version>=": "1.2.11#9" }, - { "name": "fmt", "version>=": "7.1.3#1" } - ], - "builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc" -} -``` - -As part of a version constraint declaration, a port version can be specified by adding the suffix `#`, in the previous example `1.2.11#9` refers to version `1.2.11` port version `9`. - - -### `overrides` -Declaring an override forces vcpkg to ignore all other version constraints and use the version specified in the override. This is useful for pinning exact versions and for resolving version conflicts. - -Overrides are declared as an array of package version declarations. - -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. - -```json -{ - "name": "project", - "version-semver": "1.0.0", - "dependencies": [ - { "name": "zlib", "version>=": "1.2.11#9" }, - "fmt" - ], - "builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc", - "overrides": [ - { "name": "fmt", "version": "6.0.0" } - ] -} -``` - -## See Also - -* The [implementation details](versioning.implementation-details.md) -* The [original specification](../specifications/versioning.md) - -[version-gte]: #version-gte -[builtin-baseline]: manifests.md#builtin-baseline