├── .gitattributes ├── vcpkg ├── examples │ ├── vcpkg_android_example_cmake │ │ ├── .gitignore │ │ ├── my_lib.cpp │ │ ├── CMakeLists.txt │ │ └── compile.sh │ ├── vcpkg_android_example_cmake_script │ │ ├── .gitignore │ │ ├── my_lib.cpp │ │ ├── CMakeLists.txt │ │ └── compile.sh │ ├── snippets │ │ ├── manifest-mode-cmake │ │ │ ├── vcpkg.json │ │ │ ├── CMakeLists.txt │ │ │ └── main.cxx │ │ └── get-started │ │ │ ├── helloworld.cpp │ │ │ ├── CMakeLists.txt │ │ │ ├── CMakeUserPresets.json │ │ │ └── CMakePresets.json │ ├── adding-usage.md │ └── packaging-github-repos.md ├── breadcrumb │ └── toc.yml ├── resources │ ├── clr-retarget-project.png │ ├── ports-overlay-example.png │ ├── mixedlibrary-properties.png │ ├── pkg_ado_dep │ │ ├── ado-get-url.png │ │ ├── ado-add-public-key-1.png │ │ ├── ado-add-public-key-2.png │ │ └── ado-new-private-project.md.png │ ├── vs-enable-vcpkg-manifest.png │ ├── get_started │ │ ├── vscode-c-extension.png │ │ ├── vscode-cmake-extension.png │ │ ├── vscode-command-build.png │ │ ├── vscode-terminal-vcpkg.png │ │ ├── visual-studio-developer-cmd.png │ │ ├── visual-studio-name-project.png │ │ ├── visual-studio-run-project.png │ │ ├── vscode-command-build-preset.png │ │ ├── visual-studio-create-project.png │ │ ├── visual-studio-msbuild-output.png │ │ ├── visual-studio-msbuild-project.png │ │ ├── visual-studio-helloworld-output.png │ │ ├── visual-studio-manifest-msbuild.png │ │ ├── visual-studio-developer-powershell.png │ │ ├── visual-studio-name-project-msbuild.png │ │ ├── visual-studio-create-project-msbuild.png │ │ ├── visual-studio-environment-variable-setup-cmd.png │ │ └── visual-studio-environment-variable-setup-powershell.png │ ├── support-channels.md │ └── vcpkg-mark-primary-36px.svg ├── consume │ ├── snippets │ │ ├── versioning-main.cpp │ │ ├── versioning-cmakelists.txt │ │ └── git-registries │ │ │ ├── main.cpp │ │ │ └── CMakeLists.txt │ ├── binary-caching-default.md │ ├── binary-caching-overview.md │ └── binary-caching-github-actions-cache.md ├── users │ ├── buildsystems │ │ ├── snippets │ │ │ └── cmake-integration │ │ │ │ ├── CMakeUserPresets.json │ │ │ │ └── CMakePresets.json │ │ └── manual-integration.md │ ├── platforms │ │ └── all.md │ └── examples │ │ └── selecting-llvm-features.md ├── contributing │ ├── vcpkg_catalog_release_process.md │ └── vcpkg_tool_release_process.md ├── maintainers │ ├── functions │ │ ├── vcpkg_get_windows_sdk.md │ │ ├── vcpkg_build_qmake.md │ │ ├── vcpkg_build_ninja.md │ │ ├── internal │ │ │ ├── z_vcpkg_restore_pkgconfig_path.md │ │ │ ├── z_vcpkg_apply_patches.md │ │ │ ├── z_vcpkg_get_cmake_vars.md │ │ │ ├── z_vcpkg_prettify_command_line.md │ │ │ ├── z_vcpkg_function_arguments.md │ │ │ ├── z_vcpkg_forward_output_variable.md │ │ │ └── z_vcpkg_setup_pkgconfig_path.md │ │ ├── vcpkg_clean_msbuild.md │ │ ├── vcpkg_minimum_required.md │ │ ├── vcpkg_restore_env_variables.md │ │ ├── vcpkg_get_program_files_platform_bitness.md │ │ ├── vcpkg_execute_in_download_mode.md │ │ ├── vcpkg_apply_patches.md │ │ ├── vcpkg_execute_required_process_repeat.md │ │ ├── vcpkg_install_qmake.md │ │ ├── vcpkg_find_fortran.md │ │ ├── vcpkg_copy_tool_dependencies.md │ │ ├── vcpkg_gn_install.md │ │ ├── vcpkg_install_cmake.md │ │ ├── vcpkg_buildpath_length_warning.md │ │ ├── vcpkg_add_to_path.md │ │ ├── vcpkg_install_gn.md │ │ ├── vcpkg_install_meson.md │ │ ├── vcpkg_extract_archive.md │ │ ├── vcpkg_replace_string.md │ │ ├── vcpkg_copy_pdbs.md │ │ ├── vcpkg_backup_env_variables.md │ │ ├── vcpkg_install_make.md │ │ ├── vcpkg_gn_configure.md │ │ ├── vcpkg_extract_source_archive_ex.md │ │ ├── vcpkg_qmake_install.md │ │ ├── vcpkg_configure_qmake.md │ │ ├── vcpkg_clean_executables_in_bin.md │ │ ├── vcpkg_configure_gn.md │ │ ├── vcpkg_execute_build_process.md │ │ ├── vcpkg_find_acquire_program.md │ │ ├── vcpkg_get_python_packages.md │ │ ├── vcpkg_host_path_list.md │ │ ├── vcpkg_copy_tools.md │ │ ├── vcpkg_qmake_build.md │ │ ├── vcpkg_cmake_get_vars.md │ │ ├── vcpkg_fail_port_install.md │ │ ├── vcpkg_configure_meson.md │ │ ├── vcpkg_pkgconfig_get_modules.md │ │ ├── vcpkg_build_cmake.md │ │ ├── vcpkg_cmake_install.md │ │ ├── vcpkg_fixup_pkgconfig.md │ │ ├── vcpkg_build_make.md │ │ ├── vcpkg_acquire_msys.md │ │ ├── vcpkg_make_install.md │ │ ├── vcpkg_install_copyright.md │ │ ├── vcpkg_cmake_build.md │ │ ├── vcpkg_download_sourceforge.md │ │ ├── vcpkg_qmake_configure.md │ │ ├── vcpkg_from_bitbucket.md │ │ ├── vcpkg_build_msbuild.md │ │ ├── vcpkg_from_git.md │ │ ├── vcpkg_fixup_cmake_targets.md │ │ ├── vcpkg_execute_required_process.md │ │ ├── vcpkg_from_gitlab.md │ │ ├── vcpkg_list.md │ │ ├── vcpkg_install_nmake.md │ │ ├── vcpkg_cmake_config_fixup.md │ │ ├── vcpkg_from_sourceforge.md │ │ ├── vcpkg_configure_cmake.md │ │ ├── vcpkg_download_distfile.md │ │ ├── vcpkg_build_nmake.md │ │ └── vcpkg_check_linkage.md │ └── handling-usage-files.md ├── commands │ ├── format-feature-baseline.md │ ├── version.md │ ├── contact.md │ ├── license-report.md │ ├── owns.md │ ├── list.md │ ├── search.md │ ├── hash.md │ ├── format-manifest.md │ ├── update.md │ ├── remove.md │ ├── update-baseline.md │ ├── add.md │ ├── edit.md │ ├── upgrade.md │ ├── add-version.md │ └── integrate.md ├── zone-pivot-groups.json ├── concepts │ ├── classic-mode.md │ ├── system-package-managers.md │ ├── asset-caching.md │ └── build-system-integration.md ├── get_started │ └── includes │ │ └── setup-vcpkg.md └── docfx.json ├── includes ├── experimental.md ├── debug.md ├── removed.md ├── internal-helper.md ├── env-vars.md └── env-vars-bash.md ├── .gitignore ├── README.md ├── .devcontainer └── devcontainer.json ├── .markdownlint.jsonc ├── .openpublishing.redirection.json ├── LICENSE-CODE ├── ThirdPartyNotices.md ├── LICENSE ├── .openpublishing.publish.config.json ├── .github └── ISSUE_TEMPLATE │ └── z-learn-feedback-tool.yml └── SECURITY.md /.gitattributes: -------------------------------------------------------------------------------- 1 | * text=false 2 | -------------------------------------------------------------------------------- /vcpkg/examples/vcpkg_android_example_cmake/.gitignore: -------------------------------------------------------------------------------- 1 | build 2 | -------------------------------------------------------------------------------- /vcpkg/examples/vcpkg_android_example_cmake_script/.gitignore: -------------------------------------------------------------------------------- 1 | build 2 | -------------------------------------------------------------------------------- /vcpkg/breadcrumb/toc.yml: -------------------------------------------------------------------------------- 1 | - name: vcpkg 2 | tocHref: /vcpkg/ 3 | topicHref: /vcpkg/ 4 | -------------------------------------------------------------------------------- /includes/experimental.md: -------------------------------------------------------------------------------- 1 | > [!NOTE] 2 | > This section covers an experimental feature of vcpkg which may change or be removed at any time. 3 | -------------------------------------------------------------------------------- /vcpkg/resources/clr-retarget-project.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/clr-retarget-project.png -------------------------------------------------------------------------------- /vcpkg/resources/ports-overlay-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/ports-overlay-example.png -------------------------------------------------------------------------------- /vcpkg/resources/mixedlibrary-properties.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/mixedlibrary-properties.png -------------------------------------------------------------------------------- /vcpkg/resources/pkg_ado_dep/ado-get-url.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/pkg_ado_dep/ado-get-url.png -------------------------------------------------------------------------------- /vcpkg/resources/vs-enable-vcpkg-manifest.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/vs-enable-vcpkg-manifest.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | log/ 2 | obj/ 3 | _site/ 4 | .optemp/ 5 | _themes*/ 6 | _repo.*/ 7 | .DS_Store 8 | .vscode 9 | 10 | .openpublishing.buildcore.ps1 -------------------------------------------------------------------------------- /vcpkg/examples/snippets/manifest-mode-cmake/vcpkg.json: -------------------------------------------------------------------------------- 1 | { 2 | "dependencies": [ 3 | "cxxopts", 4 | "fmt", 5 | "range-v3" 6 | ] 7 | } -------------------------------------------------------------------------------- /vcpkg/examples/snippets/get-started/helloworld.cpp: -------------------------------------------------------------------------------- 1 | #include 2 | 3 | int main() 4 | { 5 | fmt::print("Hello World!\n"); 6 | return 0; 7 | } -------------------------------------------------------------------------------- /vcpkg/resources/get_started/vscode-c-extension.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/vscode-c-extension.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/vscode-cmake-extension.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/vscode-cmake-extension.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/vscode-command-build.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/vscode-command-build.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/vscode-terminal-vcpkg.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/vscode-terminal-vcpkg.png -------------------------------------------------------------------------------- /vcpkg/resources/pkg_ado_dep/ado-add-public-key-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/pkg_ado_dep/ado-add-public-key-1.png -------------------------------------------------------------------------------- /vcpkg/resources/pkg_ado_dep/ado-add-public-key-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/pkg_ado_dep/ado-add-public-key-2.png -------------------------------------------------------------------------------- /includes/debug.md: -------------------------------------------------------------------------------- 1 | > [!IMPORTANT] 2 | > Update your vcpkg tool to the latest release. Additionally, enable [debug output](#debug-output) for comprehensive error logs. 3 | -------------------------------------------------------------------------------- /includes/removed.md: -------------------------------------------------------------------------------- 1 | > [!CAUTION] 2 | > This section covers a feature that has been removed from vcpkg. 3 | > The documentation for this feature is no longer maintained. 4 | -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-developer-cmd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-developer-cmd.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-name-project.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-name-project.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-run-project.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-run-project.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/vscode-command-build-preset.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/vscode-command-build-preset.png -------------------------------------------------------------------------------- /vcpkg/resources/pkg_ado_dep/ado-new-private-project.md.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/pkg_ado_dep/ado-new-private-project.md.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-create-project.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-create-project.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-msbuild-output.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-msbuild-output.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-msbuild-project.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-msbuild-project.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-helloworld-output.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-helloworld-output.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-manifest-msbuild.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-manifest-msbuild.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-developer-powershell.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-developer-powershell.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-name-project-msbuild.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-name-project-msbuild.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-create-project-msbuild.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-create-project-msbuild.png -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-environment-variable-setup-cmd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-environment-variable-setup-cmd.png -------------------------------------------------------------------------------- /vcpkg/examples/vcpkg_android_example_cmake/my_lib.cpp: -------------------------------------------------------------------------------- 1 | #include 2 | 3 | int answer() 4 | { 5 | Json::Value meaning_of; 6 | meaning_of["everything"] = 42; 7 | return meaning_of["everything"].asInt(); 8 | } 9 | -------------------------------------------------------------------------------- /vcpkg/resources/get_started/visual-studio-environment-variable-setup-powershell.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/vcpkg-docs/HEAD/vcpkg/resources/get_started/visual-studio-environment-variable-setup-powershell.png -------------------------------------------------------------------------------- /includes/internal-helper.md: -------------------------------------------------------------------------------- 1 | > [!WARNING] 2 | > This is an internal helper function used internally to implement vcpkg. 3 | > Behavior and arguments will change in breaking ways without notice. 4 | > Do not use this function. 5 | -------------------------------------------------------------------------------- /vcpkg/examples/vcpkg_android_example_cmake/CMakeLists.txt: -------------------------------------------------------------------------------- 1 | cmake_minimum_required(VERSION 3.0) 2 | project(test) 3 | find_package(jsoncpp CONFIG REQUIRED) 4 | add_library(my_lib my_lib.cpp) 5 | target_link_libraries(my_lib jsoncpp_lib) 6 | -------------------------------------------------------------------------------- /vcpkg/examples/vcpkg_android_example_cmake_script/my_lib.cpp: -------------------------------------------------------------------------------- 1 | #include 2 | 3 | int answer() 4 | { 5 | Json::Value meaning_of; 6 | meaning_of["everything"] = 42; 7 | return meaning_of["everything"].asInt(); 8 | } 9 | -------------------------------------------------------------------------------- /includes/env-vars.md: -------------------------------------------------------------------------------- 1 | > [!NOTE] 2 | > Setting environment variables in this manner only affects the current terminal 3 | > session. To make these changes permanent across all sessions, set them through 4 | > the Windows System Environment Variables panel. 5 | -------------------------------------------------------------------------------- /vcpkg/consume/snippets/versioning-main.cpp: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main() 5 | { 6 | fmt::print("fmt version is {}\n" 7 | "zlib version is {}\n", 8 | FMT_VERSION, ZLIB_VERSION); 9 | return 0; 10 | } -------------------------------------------------------------------------------- /vcpkg/consume/snippets/versioning-cmakelists.txt: -------------------------------------------------------------------------------- 1 | cmake_minimum_required(VERSION 3.18) 2 | 3 | project(versionstest CXX) 4 | 5 | add_executable(main main.cpp) 6 | 7 | find_package(ZLIB REQUIRED) 8 | find_package(fmt CONFIG REQUIRED) 9 | target_link_libraries(main PRIVATE ZLIB::ZLIB fmt::fmt) -------------------------------------------------------------------------------- /vcpkg/examples/snippets/get-started/CMakeLists.txt: -------------------------------------------------------------------------------- 1 | cmake_minimum_required(VERSION 3.10) 2 | 3 | project(HelloWorld) 4 | 5 | find_package(fmt CONFIG REQUIRED) 6 | 7 | add_executable(HelloWorld helloworld.cpp) 8 | 9 | target_link_libraries(HelloWorld PRIVATE fmt::fmt) 10 | 11 | -------------------------------------------------------------------------------- /includes/env-vars-bash.md: -------------------------------------------------------------------------------- 1 | > [!NOTE] 2 | > Setting environment variables using the `export` command only 3 | > affects the current shell session. To make this change permanent across 4 | > sessions, add the `export` command to your shell's profile 5 | > script (e.g., `~/.bashrc` or `~/.zshrc`). 6 | -------------------------------------------------------------------------------- /vcpkg/consume/snippets/git-registries/main.cpp: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | int main() 5 | { 6 | beison::Object obj; 7 | obj.insert("name", beison::Value::string("demo")); 8 | std::cout << beison::stringify(obj) << std::endl; 9 | return 0; 10 | } 11 | -------------------------------------------------------------------------------- /vcpkg/examples/snippets/get-started/CMakeUserPresets.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": 2, 3 | "configurePresets": [ 4 | { 5 | "name": "default", 6 | "inherits": "vcpkg", 7 | "environment": { 8 | "VCPKG_ROOT": "" 9 | } 10 | } 11 | ] 12 | } 13 | -------------------------------------------------------------------------------- /vcpkg/consume/snippets/git-registries/CMakeLists.txt: -------------------------------------------------------------------------------- 1 | cmake_minimum_required(VERSION 3.18) 2 | 3 | project(demo CXX) 4 | 5 | add_executable(main main.cpp) 6 | 7 | find_package(beicode CONFIG REQUIRED) 8 | find_package(beison CONFIG REQUIRED) 9 | target_link_libraries(main PRIVATE beicode::beicode beison::beison) 10 | -------------------------------------------------------------------------------- /vcpkg/users/buildsystems/snippets/cmake-integration/CMakeUserPresets.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": 2, 3 | "configurePresets": [ 4 | { 5 | "name": "default", 6 | "inherits": "debug", 7 | "environment": { 8 | "VCPKG_ROOT": "" 9 | } 10 | } 11 | ] 12 | } 13 | -------------------------------------------------------------------------------- /vcpkg/users/buildsystems/snippets/cmake-integration/CMakePresets.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": 3, 3 | "configurePresets": [ 4 | { 5 | "name": "debug", 6 | "cacheVariables": { 7 | "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake" 8 | } 9 | } 10 | ] 11 | } 12 | 13 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Microsoft Open Source Code of Conduct 2 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 3 | For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. -------------------------------------------------------------------------------- /vcpkg/examples/snippets/get-started/CMakePresets.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": 2, 3 | "configurePresets": [ 4 | { 5 | "name": "vcpkg", 6 | "generator": "Ninja", 7 | "binaryDir": "${sourceDir}/build", 8 | "cacheVariables": { 9 | "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake" 10 | } 11 | } 12 | ] 13 | } 14 | -------------------------------------------------------------------------------- /vcpkg/contributing/vcpkg_catalog_release_process.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Microsoft/vcpkg catalog release process 3 | description: Internal process guide for creating a new curated catalog release of vcpkg. 4 | ms.date: 01/10/2024 5 | ROBOTS: NOINDEX 6 | --- 7 | 8 | # Microsoft/vcpkg catalog release process 9 | 10 | > [!WARNING] 11 | > This article is obsolete and is no longer being updated. 12 | -------------------------------------------------------------------------------- /vcpkg/contributing/vcpkg_tool_release_process.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Microsoft/vcpkg-tool release process 3 | description: Internal process guide for creating a new tool release of vcpkg. 4 | ms.date: 01/10/2024 5 | ROBOTS: NOINDEX 6 | --- 7 | # Microsoft/vcpkg-tool release process 8 | 9 | > [!WARNING] 10 | > This content has been removed due to being intended for the vcpkg development team rather than for vcpkg users. 11 | -------------------------------------------------------------------------------- /.devcontainer/devcontainer.json: -------------------------------------------------------------------------------- 1 | // For format details, see https://aka.ms/devcontainer.json. For config options, see the 2 | // README at: https://github.com/devcontainers/templates/tree/main/src/alpine 3 | { 4 | "name": "vcpkg-docs Container", 5 | "image": "mcr.microsoft.com/devcontainers/base:alpine-3.17", 6 | 7 | "customizations": { 8 | "vscode": { 9 | "extensions": ["docsmsft.docs-authoring-pack"] 10 | } 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /vcpkg/examples/snippets/manifest-mode-cmake/CMakeLists.txt: -------------------------------------------------------------------------------- 1 | cmake_minimum_required(VERSION 3.15) 2 | 3 | project(fibonacci CXX) 4 | 5 | find_package(fmt CONFIG REQUIRED) 6 | find_package(range-v3 CONFIG REQUIRED) 7 | find_package(cxxopts CONFIG REQUIRED) 8 | 9 | set(CMAKE_CXX_STANDARD 17) 10 | 11 | add_executable(fibo main.cxx) 12 | 13 | target_link_libraries(fibo 14 | PRIVATE 15 | fmt::fmt 16 | range-v3::range-v3 17 | cxxopts::cxxopts) 18 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_get_windows_sdk.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_get_windows_sdk 3 | description: Learn how to use vcpkg_get_windows_sdk. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_get_windows_sdk 7 | 8 | Get the Windows SDK number. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_get_windows_sdk() 14 | ``` 15 | 16 | ## Source 17 | 18 | [scripts/cmake/vcpkg\_get\_windows\_sdk.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_windows_sdk.cmake) 19 | -------------------------------------------------------------------------------- /vcpkg/examples/vcpkg_android_example_cmake_script/CMakeLists.txt: -------------------------------------------------------------------------------- 1 | cmake_minimum_required(VERSION 3.0) 2 | 3 | # if -DVCPKG_TARGET_ANDROID=ON is specified when invoking cmake, load cmake/vcpkg_android.cmake 4 | # !!! Important: place this line before calling project() !!! 5 | if (VCPKG_TARGET_ANDROID) 6 | include("cmake/vcpkg_android.cmake") 7 | endif() 8 | 9 | project(test) 10 | 11 | find_package(jsoncpp CONFIG REQUIRED) 12 | add_library(my_lib my_lib.cpp) 13 | target_link_libraries(my_lib JsonCpp::JsonCpp) 14 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_build_qmake.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_build_qmake 3 | description: Use vcpkg_build_qmake to build a qmake-based project. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_build_qmake 7 | 8 | Build a qmake-based project, previously configured using [`vcpkg_configure_qmake()`](vcpkg_configure_qmake.md). 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_build_qmake() 14 | ``` 15 | 16 | ## Source 17 | 18 | [scripts/cmake/vcpkg\_build\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_qmake.cmake) 19 | -------------------------------------------------------------------------------- /vcpkg/commands/format-feature-baseline.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg format-feature-baseline 3 | description: Reference for the vcpkg format-feature-baseline command. Formats ci.feature.baseline.txt files. 4 | author: BillyONeal 5 | ms.author: bion 6 | ms.date: 03/07/2025 7 | ms.topic: reference 8 | --- 9 | 10 | # vcpkg format-feature-baseline 11 | 12 | ## Synopsis 13 | 14 | ```console 15 | vcpkg format-feature-baseline [] 16 | ``` 17 | 18 | ## Description 19 | 20 | Formats "ci.feature.baseline.txt" files intended for use with [`x-test-features --ci-feature-baseline`](./test-features.md) 21 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_build_ninja.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_build_ninja 3 | description: Use vcpkg_build_ninja to build a ninja project. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_build_ninja 7 | 8 | Build a ninja project. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_build_ninja( 14 | [TARGETS ...] 15 | ) 16 | ``` 17 | 18 | ## Parameters 19 | 20 | ### TARGETS 21 | 22 | Only build the specified targets. 23 | 24 | ## Source 25 | 26 | [scripts/cmake/vcpkg\_build\_ninja.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_ninja.cmake) 27 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/internal/z_vcpkg_restore_pkgconfig_path.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: z_vcpkg_restore_pkgconfig_path 3 | description: Use z_vcpkg_restore_pkgconfig_path to restore the environment. 4 | ms.date: 11/30/2022 5 | --- 6 | # z_vcpkg_restore_pkgconfig_path 7 | 8 | [!INCLUDE [internal-helper](../../../../includes/internal-helper.md)] 9 | 10 | Restore environment modified by [`z_vcpkg_setup_pkgconfig_path`](z_vcpkg_setup_pkgconfig_path.md). 11 | 12 | ## Usage 13 | 14 | ```cmake 15 | z_vcpkg_restore_pkgconfig_path() 16 | ``` 17 | 18 | ## Examples 19 | 20 | - [`z_vcpkg_setup_pkgconfig_path`](z_vcpkg_setup_pkgconfig_path.md). 21 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_clean_msbuild.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_clean_msbuild 3 | description: Use vcpkg_clean_msbuild to remove MSBuild intermediate files. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_clean_msbuild 7 | 8 | > [!WARNING] 9 | > This function has been deprecated in favor of [`vcpkg_msbuild_install`](vcpkg_msbuild_install.md). 10 | 11 | Clean intermediate files generated by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md). 12 | 13 | ## Usage 14 | 15 | ```cmake 16 | vcpkg_clean_msbuild() 17 | ``` 18 | 19 | ## Source 20 | 21 | [scripts/cmake/vcpkg\_clean\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_msbuild.cmake) 22 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_minimum_required.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_minimum_required 3 | description: Learn how to use vcpkg_minimum_required. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_minimum_required 7 | 8 | Asserts that the version of the vcpkg program being used to build a port is later than the supplied date, inclusive. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_minimum_required(VERSION 2021-01-13) 14 | ``` 15 | 16 | ## Parameters 17 | 18 | ### VERSION 19 | 20 | The date-version to check against. 21 | 22 | ## Source 23 | 24 | [scripts/cmake/vcpkg\_minimum\_required.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_minimum_required.cmake) 25 | -------------------------------------------------------------------------------- /vcpkg/commands/version.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg version 3 | description: Command line reference for the vcpkg version command. Displays the version of the vcpkg executable. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg version 7 | 8 | ## Synopsis 9 | 10 | ```console 11 | vcpkg version 12 | ``` 13 | 14 | ## Description 15 | 16 | Displays the version of the vcpkg executable. 17 | 18 | ## Example 19 | 20 | ```console 21 | $ vcpkg version 22 | vcpkg package management program version 2022-09-01-dfb82802c8cc562ce3b665a904a65b22314de724 23 | 24 | See LICENSE.txt for license information. 25 | ``` 26 | 27 | ## Options 28 | 29 | All vcpkg commands support a set of [common options](common-options.md). 30 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_restore_env_variables.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_restore_env_variables 3 | description: Learn how to use vcpkg_restore_env_variables. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_restore_env_variables 7 | 8 | Restore a set of environment variables. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_restore_env_variables(VARS [...]) 14 | ``` 15 | 16 | ### VARS 17 | 18 | The variables to restore. 19 | 20 | ## Notes 21 | 22 | See [`vcpkg_backup_env_variables()`](vcpkg_backup_env_variables.md). 23 | 24 | ## Source 25 | 26 | [scripts/cmake/vcpkg\_backup\_restore\_env\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_backup_restore_env_vars.cmake) 27 | -------------------------------------------------------------------------------- /vcpkg/resources/support-channels.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Support channels and social media 3 | description: List of vcpkg's technical support channels and social media links. 4 | author: vicroms 5 | ms.author: viromer 6 | ms.date: 01/11/2024 7 | --- 8 | # Support channels and social media 9 | 10 | For technical support, feedback, or any other inquiries; please reach us at any of our support channels: 11 | 12 | * Email to [vcpkg@microsoft.com]() 13 | * vcpkg's [GitHub discussions]() 14 | * Discord: [#include](), on the #vcpkg channel 15 | * Slack: [C++ alliance](), on the #vcpkg channel 16 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_get_program_files_platform_bitness.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_get_program_files_platform_bitness 3 | description: Learn how to use vcpkg_get_program_files_platform_bitness. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_get_program_files_platform_bitness 7 | 8 | Get the Program Files directory of the current platform's bitness: 9 | either `$ENV{ProgramW6432}` on 64-bit windows, 10 | or `$ENV{PROGRAMFILES}` on 32-bit windows. 11 | 12 | ## Usage 13 | 14 | ```cmake 15 | vcpkg_get_program_files_platform_bitness() 16 | ``` 17 | 18 | ## Source 19 | 20 | [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) 21 | -------------------------------------------------------------------------------- /.markdownlint.jsonc: -------------------------------------------------------------------------------- 1 | { 2 | "MD013": { 3 | "line_length": 120, 4 | // Increase code block lenght since some command-line examples are extremely long 5 | "code_blocks": false, 6 | "tables": false 7 | }, 8 | // Some documentation sections repeat headings, allow this as long as the parent heading is different 9 | "MD024": { 10 | "siblings_only": true 11 | }, 12 | // Disable "Multiple top level headings in the same document" triggered by metadata and top-level 13 | // heading on articles 14 | "MD025": false, 15 | // We use inline to simplify anchor links 16 | // We use inline
for line breaks inside tables 17 | "MD033": { 18 | "allowed_elements": [ "a", "br" ] 19 | } 20 | } -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_execute_in_download_mode.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_execute_in_download_mode 3 | description: Learn how to use vcpkg_execute_in_download_mode. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_execute_in_download_mode 7 | 8 | Execute a process even in download mode. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_execute_in_download_mode( 14 | ... 15 | ) 16 | ``` 17 | 18 | The signature of this function is identical to `execute_process()`. 19 | 20 | For more details, see [`execute_process()`](https://cmake.org/cmake/help/latest/command/execute_process.html). 21 | 22 | ## Source 23 | 24 | [`scripts/cmake/vcpkg_execute_in_download_mode.cmake`](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_in_download_mode.cmake) 25 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_apply_patches.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_apply_patches 3 | description: Use vcpkg_apply_patches to apply a set of patches to a source tree. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_apply_patches 7 | 8 | > [!WARNING] 9 | > This function has been deprecated in favor of the `PATCHES` argument to [`vcpkg_from_github()`](vcpkg_from_github.md#patches) and similar functions. 10 | 11 | Apply a set of patches to a source tree. 12 | 13 | ## Usage 14 | 15 | ```cmake 16 | vcpkg_apply_patches( 17 | SOURCE_PATH <${SOURCE_PATH}> 18 | [QUIET] 19 | PATCHES ... 20 | ) 21 | ``` 22 | 23 | ## Source 24 | 25 | [scripts/cmake/vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake) 26 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_execute_required_process_repeat.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_execute_required_process_repeat 3 | description: Learn how to use vcpkg_execute_required_process_repeat. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_execute_required_process_repeat 7 | 8 | Execute a process until the command succeeds, or until the COUNT is reached. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_execute_required_process_repeat( 14 | COMMAND [] 15 | COUNT 16 | WORKING_DIRECTORY 17 | LOGNAME 18 | [ALLOW_IN_DOWNLOAD_MODE] 19 | ) 20 | ``` 21 | 22 | ## Source 23 | 24 | [scripts/cmake/vcpkg\_execute\_required\_process\_repeat.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process_repeat.cmake) 25 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_install_qmake.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_install_qmake 3 | description: Learn how to use vcpkg_install_qmake. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_install_qmake 7 | 8 | Build and install a qmake project. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_install_qmake(...) 14 | ``` 15 | 16 | ## Parameters 17 | 18 | See [`vcpkg_build_qmake()`](vcpkg_build_qmake.md). 19 | 20 | ## Notes 21 | 22 | This command transparently forwards to [`vcpkg_build_qmake()`](vcpkg_build_qmake.md). 23 | 24 | Additionally, this command will copy produced .libs/.dlls/.as/.dylibs/.sos to the appropriate 25 | staging directories. 26 | 27 | ## Source 28 | 29 | [scripts/cmake/vcpkg\_install\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_qmake.cmake) 30 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_find_fortran.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_find_fortran 3 | description: Learn how to use vcpkg_find_fortran. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_find_fortran 7 | 8 | Checks if a Fortran compiler can be found. 9 | Windows(x86/x64) Only: If not it will switch/enable MinGW gfortran 10 | and return required cmake args for building. 11 | 12 | ## Usage 13 | 14 | ```cmake 15 | vcpkg_find_fortran() 16 | ``` 17 | 18 | ## Example 19 | 20 | ```cmake 21 | vcpkg_find_fortran(fortran_args) 22 | # ... 23 | vcpkg_cmake_configure(... 24 | OPTIONS 25 | ${fortran_args} 26 | ) 27 | ``` 28 | 29 | ## Source 30 | 31 | [scripts/cmake/vcpkg\_find\_fortran.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_fortran.cmake) 32 | -------------------------------------------------------------------------------- /.openpublishing.redirection.json: -------------------------------------------------------------------------------- 1 | { 2 | "redirections": [ 3 | { 4 | "source_path": "vcpkg/examples/manifest-mode-cmake.md", 5 | "redirect_url": "/vcpkg/consume/manifest-mode", 6 | "redirect_document_id": true 7 | }, 8 | { 9 | "source_path": "vcpkg/users/registries.md", 10 | "redirect_url": "/vcpkg/concepts/registries", 11 | "redirect_document_id": true 12 | }, 13 | { 14 | "source_path": "vcpkg/users/classic-mode.md", 15 | "redirect_url": "/vcpkg/concepts/classic-mode", 16 | "redirect_document_id": true 17 | }, 18 | { 19 | "source_path": "vcpkg/users/manifests.md", 20 | "redirect_url": "/vcpkg/concepts/manifest-mode" 21 | } 22 | ] 23 | } -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_copy_tool_dependencies.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_copy_tool_dependencies 3 | description: Learn how to use vcpkg_copy_tool_dependencies. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_copy_tool_dependencies 7 | 8 | Copy all DLL dependencies of built tools into the tool folder. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>) 14 | ``` 15 | 16 | ## Parameters 17 | 18 | The path to the directory containing the tools. 19 | 20 | ## Notes 21 | 22 | This command should always be called by portfiles after they have finished rearranging the binary output, if they have any tools. 23 | 24 | ## Source 25 | 26 | [scripts/cmake/vcpkg\_copy\_tool\_dependencies.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tool_dependencies.cmake) 27 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_gn_install.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_gn_install 3 | description: Learn how to use vcpkg_gn_install. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_gn_install 7 | 8 | Installs a GN project. 9 | 10 | In order to build a GN project without installing, use [`vcpkg_build_ninja()`](vcpkg_build_ninja.md). 11 | 12 | ## Usage 13 | 14 | ```cmake 15 | vcpkg_gn_install( 16 | SOURCE_PATH 17 | [TARGETS ...] 18 | ) 19 | ``` 20 | 21 | ## Parameters 22 | 23 | ### SOURCE_PATH 24 | 25 | The path to the source directory 26 | 27 | ### TARGETS 28 | 29 | Only install the specified targets. 30 | 31 | Include files must be handled separately. 32 | 33 | ## Source 34 | 35 | [ports/vcpkg-gn/vcpkg\_gn\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_install.cmake) 36 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_install_cmake.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_install_cmake 3 | description: Learn how to use vcpkg_install_cmake. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_install_cmake 7 | 8 | > [!WARNING] 9 | > This function has been deprecated in favor of [`vcpkg_cmake_install`](vcpkg_cmake_install.md) from the vcpkg-cmake port. 10 | 11 | Build and install a cmake project. 12 | 13 | ## Usage 14 | 15 | ```cmake 16 | vcpkg_install_cmake(...) 17 | ``` 18 | 19 | ## Parameters 20 | 21 | See [`vcpkg_build_cmake()`](vcpkg_build_cmake.md). 22 | 23 | ## Notes 24 | 25 | This command transparently forwards to [`vcpkg_build_cmake()`](vcpkg_build_cmake.md), adding a `TARGET install` 26 | parameter. 27 | 28 | ## Source 29 | 30 | [scripts/cmake/vcpkg\_install\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_cmake.cmake) 31 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_buildpath_length_warning.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_buildpath_length_warning 3 | description: Enable a warning if the vcpkg installation path is too long for a package. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_buildpath_length_warning 7 | 8 | Warns the user if their vcpkg installation path might be too long for the package they're installing. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_buildpath_length_warning() 14 | ``` 15 | 16 | ## Parameters 17 | 18 | ### `` 19 | 20 | Warns the user if the number of bytes in the path to `buildtrees` is bigger than `N`. 21 | 22 | ## Notes 23 | 24 | This function only emits a warning and must not be used for correctness. 25 | 26 | ## Source 27 | 28 | [scripts/cmake/vcpkg\_buildpath\_length\_warning.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_buildpath_length_warning.cmake) 29 | -------------------------------------------------------------------------------- /vcpkg/examples/snippets/manifest-mode-cmake/main.cxx: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | namespace view = ranges::views; 6 | 7 | int fib(int x) 8 | { 9 | int a = 0, b = 1; 10 | 11 | for (int it : view::repeat(0) | view::take(x)) 12 | { 13 | (void)it; 14 | int tmp = a; 15 | a += b; 16 | b = tmp; 17 | } 18 | 19 | return a; 20 | } 21 | 22 | int main(int argc, char **argv) 23 | { 24 | cxxopts::Options options("fibo", "Print the fibonacci sequence up to a value 'n'"); 25 | options.add_options()("n,value", "The value to print to", cxxopts::value()->default_value("10")); 26 | 27 | auto result = options.parse(argc, argv); 28 | auto n = result["value"].as(); 29 | 30 | for (int x : view::iota(1) | view::take(n)) 31 | { 32 | fmt::print("fib({}) = {}\n", x, fib(x)); 33 | } 34 | } -------------------------------------------------------------------------------- /vcpkg/commands/contact.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg contact 3 | description: Reference for the vcpkg contact command. Provides an official contact (vcpkg@microsoft.com) 4 | author: JavierMatosD 5 | ms.author: javiermat 6 | ms.date: 01/10/2024 7 | ms.service: vcpkg 8 | --- 9 | # vcpkg contact 10 | 11 | ## Synopsis 12 | 13 | ```console 14 | vcpkg contact 15 | ``` 16 | 17 | ## Description 18 | 19 | Provides users with an email address to reach out to the vcpkg team for support or inquiries. 20 | 21 | ## Example 22 | 23 | ```console 24 | $ vcpkg contact 25 | 26 | Send an email to vcpkg@microsoft.com with any feedback. 27 | ``` 28 | 29 | ## Options 30 | 31 | All vcpkg commands support a set of [common options](common-options.md). 32 | 33 | ### `--survey` 34 | 35 | > [!CAUTION] 36 | > This option is defunct and has been removed from vcpkg in current versions. 37 | 38 | Opens the vcpkg feedback survey in a web-browser window. 39 | -------------------------------------------------------------------------------- /vcpkg/commands/license-report.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg license-report 3 | description: Reference for the vcpkg license-report command. Prints licenses of all installed packages. 4 | author: BillyONeal 5 | ms.author: bion 6 | ms.date: 06/04/2025 7 | --- 8 | # vcpkg license-report 9 | 10 | ## Synopsis 11 | 12 | ```console 13 | vcpkg license-report 14 | ``` 15 | 16 | ## Description 17 | 18 | The `vcpkg license-report` command prints the licenses of all installed packages. 19 | 20 | ### Examples 21 | 22 | ```console 23 | > vcpkg install zlib 24 | [...] 25 | > vcpkg license-report 26 | Installed contents are licensed to you by owners. Microsoft is not responsible for, nor does it grant any licenses to, third-party packages. 27 | Installed packages declare the following licenses: 28 | MIT 29 | Zlib 30 | ``` 31 | 32 | ## Options 33 | 34 | All vcpkg commands support a set of [common options](common-options.md). 35 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_add_to_path.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_add_to_path 3 | description: Use vcpkg_add_to_path to add directories to the PATH. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_add_to_path 7 | 8 | Add a directory or directories to the PATH environment variable. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_add_to_path([PREPEND] [...]) 14 | ``` 15 | 16 | ## Parameters 17 | 18 | ### PREPEND 19 | 20 | Prepend items to the PATH environment variable instead of appending. 21 | 22 | ### `...` 23 | 24 | Paths to append to the PATH environment variable. 25 | 26 | ## Examples 27 | 28 | - [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake) 29 | - [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake) 30 | 31 | ## Source 32 | 33 | [scripts/cmake/vcpkg\_add\_to\_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake) 34 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_install_gn.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_install_gn 3 | description: Learn how to use vcpkg_install_gn. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_install_gn 7 | 8 | > [!WARNING] 9 | > This function has been deprecated in favor of [`vcpkg_gn_install`](vcpkg_gn_install.md). 10 | 11 | Installs a GN project. 12 | 13 | To build a GN project without installing, use [`vcpkg_build_ninja()`](vcpkg_build_ninja.md). 14 | 15 | ## Usage 16 | 17 | ```cmake 18 | vcpkg_install_gn( 19 | SOURCE_PATH 20 | [TARGETS ...] 21 | ) 22 | ``` 23 | 24 | ## Parameters 25 | 26 | ### SOURCE_PATH 27 | 28 | The path to the source directory 29 | 30 | ### TARGETS 31 | 32 | Only install the specified targets. 33 | 34 | Include files must be handled separately. 35 | 36 | ## Source 37 | 38 | [`scripts/cmake/vcpkg_install_gn.cmake`](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_gn.cmake) 39 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_install_meson.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_install_meson 3 | description: Learn how to use vcpkg_install_meson. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_install_meson 7 | 8 | Builds a meson project previously configured with `vcpkg_configure_meson()`. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_install_meson([ADD_BIN_TO_PATH]) 14 | ``` 15 | 16 | ## Parameters 17 | 18 | ### ADD_BIN_TO_PATH 19 | 20 | Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs. 21 | 22 | ## Examples 23 | 24 | - [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake) 25 | - [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake) 26 | 27 | ## Source 28 | 29 | [scripts/cmake/vcpkg\_install\_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_meson.cmake) 30 | -------------------------------------------------------------------------------- /vcpkg/zone-pivot-groups.json: -------------------------------------------------------------------------------- 1 | { 2 | "groups": [ 3 | { 4 | "id": "shell-selections", 5 | "title": "Shell Selections", 6 | "prompt": "Terminal options", 7 | "pivots": [ 8 | { 9 | "id": "shell-powershell", 10 | "title": "PowerShell" 11 | }, 12 | { 13 | "id": "shell-cmd", 14 | "title": "CMD" 15 | }, 16 | { 17 | "id": "shell-bash", 18 | "title": "Bash" 19 | } 20 | ] 21 | }, 22 | { 23 | "id": "os-runner", 24 | "title": "OS Runner", 25 | "prompt": "Operating System Runner", 26 | "pivots": [ 27 | { 28 | "id": "windows-runner", 29 | "title": "Windows runner" 30 | }, 31 | { 32 | "id": "linux-runner", 33 | "title": "Linux runner" 34 | } 35 | ] 36 | } 37 | ] 38 | } -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_extract_archive.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_extract_archive 3 | description: Learn how to use vcpkg_extract_archive. 4 | author: vicroms 5 | ms.author: viromer 6 | ms.date: 01/10/2024 7 | ms.topic: reference 8 | --- 9 | # vcpkg_extract_archive 10 | 11 | Extract an archive. 12 | 13 | Archives can be MSIs, 7zip self extracting executables, or any archive format accepted by CMake's 14 | built-in `tar`. 15 | 16 | ## Usage 17 | 18 | ```cmake 19 | vcpkg_extract_archive( 20 | ARCHIVE 21 | DESTINATION 22 | ) 23 | ``` 24 | 25 | ## Parameters 26 | 27 | ### ARCHIVE 28 | 29 | Full path to the archive to extract. 30 | 31 | ### DESTINATION 32 | 33 | Full path to a nonexistent path which will be created as a directory, into which the contents of 34 | `ARCHIVE` are extracted. 35 | 36 | ## Source 37 | 38 | [scripts/cmake/vcpkg\_extract\_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_archive.cmake) 39 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_replace_string.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_replace_string 3 | description: Learn how to use vcpkg_replace_string. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_replace_string 7 | 8 | Replace a string in a file. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_replace_string( [REGEX] [IGNORE_UNCHANGED]) 14 | ``` 15 | 16 | ## Parameters 17 | 18 | ### `` 19 | 20 | The path to the file to modify. 21 | 22 | ### `` 23 | 24 | The string to match. 25 | 26 | ### `` 27 | 28 | The string to replace all matched sequences with. 29 | 30 | ### `[REGEX]` 31 | 32 | If this argument is present, the `` argument is treated as a regular expression. 33 | 34 | ### `[IGNORE_UNCHANGED]` 35 | 36 | Disable the warning if the file is not changed. 37 | 38 | ## Source 39 | 40 | [scripts/cmake/vcpkg\_replace\_string.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_replace_string.cmake) 41 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_copy_pdbs.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_copy_pdbs 3 | description: Learn how to use vcpkg_copy_pdbs. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_copy_pdbs 7 | 8 | Automatically locate pdbs in the build tree and copy them adjacent to all DLLs. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_copy_pdbs( 14 | [BUILD_PATHS ...]) 15 | ``` 16 | 17 | ## Parameters 18 | 19 | ### BUILD_PATHS 20 | 21 | Patterns which will be passed to `file(GLOB_RECURSE)`, for locating DLLs. 22 | 23 | Defaults to: 24 | 25 | - `${CURRENT_PACKAGES_DIR}/bin/*.dll` 26 | - `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll` 27 | 28 | ## Notes 29 | 30 | This command should be called by all portfiles after they have finished rearranging the binary output. 31 | 32 | ## Examples 33 | 34 | - [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) 35 | 36 | ## Source 37 | 38 | [scripts/cmake/vcpkg\_copy\_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake) 39 | -------------------------------------------------------------------------------- /vcpkg/users/platforms/all.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Supported target platforms 3 | description: An overview of platforms that can be targeted with vcpkg. 4 | ms.date: 07/11/2024 5 | ms.topic: concept-article 6 | --- 7 | # Supported target platforms 8 | 9 | vcpkg can build libraries for a virtually limitless number of target platforms thanks to its customizable [triplets feature](../../concepts/triplets.md). While [dozens of triplets](https://github.com/microsoft/vcpkg/tree/master/triplets) ship with vcpkg by default, including a multitude of community-provided options, you can also define your own. For instance, you can target Windows, macOS, Linux, Android, iOS, or your preferred embedded operating system. Target architectures and other compilation options can also be set using triplets. 10 | 11 | vcpkg also supports cross-compilation to targets different than the host operating system. We include dedicated articles for some of these with more tailored guidance, including [Android](android.md), [MinGW](mingw.md), and [Xbox](xbox.md). 12 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_backup_env_variables.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_backup_env_variables 3 | description: Use vcpkg_backup_env_variables to backup a set of environment variables. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_backup_env_variables 7 | 8 | Backup a set of environment variables. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_backup_env_variables(VARS [...]) 14 | ``` 15 | 16 | ### VARS 17 | 18 | The variables to backup. 19 | 20 | ## Notes 21 | 22 | Variables are backed up into the current scope. You must call [`vcpkg_restore_env_variables()`](vcpkg_restore_env_variables.md) from the same scope as `vcpkg_backup_env_variables()`. 23 | 24 | `vcpkg_restore_env_variables()` does not destroy the variables backed up with `vcpkg_backup_env_variables()` and so can be called multiple times within the same scope to reset back to the original values. 25 | 26 | ## Source 27 | 28 | [scripts/cmake/vcpkg\_backup\_restore\_env\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_backup_restore_env_vars.cmake) 29 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_install_make.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_install_make 3 | description: Learn how to use vcpkg_install_make. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_install_make 7 | 8 | Build and install a make project. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_install_make(...) 14 | ``` 15 | 16 | ## Parameters 17 | 18 | See [`vcpkg_build_make()`](vcpkg_build_make.md). 19 | 20 | ## Notes 21 | 22 | This command transparently forwards to [`vcpkg_build_make()`](vcpkg_build_make.md), adding `ENABLE_INSTALL` 23 | 24 | ## Examples 25 | 26 | - [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake) 27 | - [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake) 28 | - [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake) 29 | - [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake) 30 | 31 | ## Source 32 | 33 | [scripts/cmake/vcpkg\_install\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_make.cmake) 34 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_gn_configure.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_gn_configure 3 | description: Learn how to use vcpkg_gn_configure. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_gn_configure 7 | 8 | Generate Ninja (GN) targets 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_gn_configure( 14 | SOURCE_PATH 15 | [OPTIONS ] 16 | [OPTIONS_DEBUG ] 17 | [OPTIONS_RELEASE ] 18 | ) 19 | ``` 20 | 21 | ## Parameters 22 | 23 | ### SOURCE_PATH (required) 24 | The path to the GN project. 25 | 26 | ### OPTIONS 27 | 28 | Options to be passed to both the debug and release targets. 29 | The options must be provided as a space-separated string. 30 | 31 | ### OPTIONS_DEBUG (space-separated string) 32 | 33 | Options to be passed to the debug target. 34 | 35 | ### OPTIONS_RELEASE (space-separated string) 36 | 37 | Options to be passed to the release target. 38 | 39 | ## Source 40 | 41 | [ports/vcpkg-gn/vcpkg\_gn\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_configure.cmake) 42 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_extract_source_archive_ex.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_extract_source_archive_ex 3 | description: Learn how to use vcpkg_extract_source_archive_ex. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_extract_source_archive_ex 7 | 8 | > [!WARNING] 9 | > This function has been deprecated in favor of [`vcpkg_extract_source_archive()`](vcpkg_extract_source_archive.md). 10 | 11 | Extract an archive. 12 | 13 | ## Usage 14 | 15 | ```cmake 16 | vcpkg_extract_source_archive_ex( 17 | [OUT_SOURCE_PATH ] 18 | [...] 19 | ) 20 | ``` 21 | 22 | This command forwards all options to [`vcpkg_extract_source_archive()`](vcpkg_extract_source_archive.md), with `` as the first argument. Equivalent to `vcpkg_extract_source_archive( ...)`. For parameter help, see the documentation for [`vcpkg_extract_source_archive()`](vcpkg_extract_source_archive.md). 23 | 24 | ## Source 25 | 26 | [`scripts/cmake/vcpkg_extract_source_archive_ex.cmake`](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake) 27 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_qmake_install.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_qmake_install 3 | description: Use vcpkg_qmake_install to build a QMake project. 4 | ms.date: 01/10/2024 5 | --- 6 | 7 | # vcpkg_qmake_install 8 | 9 | _Added in `vcpkg-qmake` version `2022-11-16`_. 10 | 11 | Build and install a qmake project previously configured with [`vcpkg_qmake_configure()`](vcpkg_qmake_configure.md). 12 | 13 | ```cmake 14 | vcpkg_qmake_install(...) 15 | ``` 16 | 17 | To use this function, you must depend on the helper port `vcpkg-qmake`: 18 | 19 | ```json 20 | "dependencies": [ 21 | { 22 | "name": "vcpkg-qmake", 23 | "host": true 24 | } 25 | ] 26 | ``` 27 | 28 | ### Parameters: 29 | [See `vcpkg_qmake_install()`](vcpkg_qmake_install.md). 30 | 31 | ### Notes: 32 | This command transparently forwards to [`vcpkg_qmake_install()`](vcpkg_qmake_install.md) and appends the 'install' target 33 | 34 | ## Source 35 | [ports/vcpkg-qmake/vcpkg\_qmake\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-qmake/vcpkg_qmake_install.cmake) 36 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_configure_qmake.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_configure_qmake 3 | description: Learn how to use vcpkg_configure_qmake. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_configure_qmake 7 | 8 | Configure a qmake-based project. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_configure_qmake( 14 | SOURCE_PATH 15 | [OPTIONS arg1 [arg2 ...]] 16 | [OPTIONS_RELEASE arg1 [arg2 ...]] 17 | [OPTIONS_DEBUG arg1 [arg2 ...]] 18 | [BUILD_OPTIONS arg1 [arg2 ...]] 19 | [BUILD_OPTIONS_RELEASE arg1 [arg2 ...]] 20 | [BUILD_OPTIONS_DEBUG arg1 [arg2 ...]] 21 | ) 22 | ``` 23 | 24 | ## Parameters 25 | 26 | ### SOURCE_PATH 27 | 28 | The path to the *.pro qmake project file. 29 | 30 | ### OPTIONS, OPTIONS\_RELEASE, OPTIONS\_DEBUG 31 | 32 | The options passed to qmake to the configure step. 33 | 34 | ### BUILD\_OPTIONS, BUILD\_OPTIONS\_RELEASE, BUILD\_OPTIONS\_DEBUG 35 | 36 | The options passed to qmake to the build step. 37 | 38 | ## Source 39 | 40 | [scripts/cmake/vcpkg\_configure\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_qmake.cmake) 41 | -------------------------------------------------------------------------------- /LICENSE-CODE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | Copyright (c) Microsoft Corporation 3 | 4 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 5 | associated documentation files (the "Software"), to deal in the Software without restriction, 6 | including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 7 | and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, 8 | subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in all copies or substantial 11 | portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT 14 | NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 15 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 16 | WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 17 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_clean_executables_in_bin.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_clean_executables_in_bin 3 | description: Use vcpkg_clean_executables_in_bin to remove specified executables. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_clean_executables_in_bin 7 | 8 | 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. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_clean_executables_in_bin( 14 | FILE_NAMES ... 15 | ) 16 | ``` 17 | 18 | ## Parameters 19 | 20 | ### FILE_NAMES 21 | 22 | A list of executable filenames without extension. 23 | 24 | ## Notes 25 | 26 | Generally, there is no need to call this function manually. Instead, pass an extra `AUTO_CLEAN` argument when calling [`vcpkg_copy_tools()`](vcpkg_copy_tools.md#auto_clean). 27 | 28 | ## Source 29 | 30 | [scripts/cmake/vcpkg\_clean\_executables\_in\_bin.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_executables_in_bin.cmake) 31 | -------------------------------------------------------------------------------- /vcpkg/commands/owns.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg owns 3 | description: Reference for the vcpkg owns command. Determines which installed package owns a particular file or files matching a substring. 4 | author: JavierMatosD 5 | ms.author: javiermat 6 | ms.date: 01/10/2024 7 | --- 8 | # vcpkg owns 9 | 10 | ## Synopsis 11 | 12 | ```console 13 | vcpkg owns 14 | ``` 15 | 16 | ## Description 17 | 18 | The `owns` command is used to search for installed packages that own a particular file or files that match a substring (``). 19 | 20 | The command outputs a list of packages that have files matching the given substring. Each entry is in the format: 21 | 22 | ```console 23 | : 24 | ``` 25 | 26 | ## Examples 27 | 28 | To search for installed packages that own a file matching the substring `zlib.h`. 29 | 30 | ```console 31 | vcpkg owns zlib.h 32 | 33 | -- zlib:x86-windows: x86-windows/include/zlib.h 34 | -- zlib:x64-windows: x64-windows/include/zlib.h 35 | -- bzip2:x64-windows: x64-windows/include/bzlib.h 36 | ``` 37 | 38 | ## Options 39 | 40 | All vcpkg commands support a set of [common options](common-options.md). 41 | -------------------------------------------------------------------------------- /vcpkg/commands/list.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg list 3 | description: Command line reference for the vcpkg list command. Shows a list of the packages in the installed tree, along with the version and description of each. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg list 7 | 8 | ## Synopsis 9 | 10 | ```console 11 | vcpkg list [options] 12 | ``` 13 | 14 | ## Description 15 | 16 | Shows a list of the packages in the installed tree, along with the version and description of each. 17 | 18 | ## Example 19 | 20 | ```console 21 | $ vcpkg list 22 | 23 | cxxopts:x64-windows 3.0.0 This is a lightweight C++ option parser library... 24 | fmt:x64-windows 9.0.0 Formatting library for C++. It can be used as a... 25 | range-v3:x64-windows 0.12.0 Range library for C++11/14/17/20. 26 | vcpkg-cmake-config:x64-windows 2022-02-06#1 27 | vcpkg-cmake:x64-windows 2022-08-18 28 | ``` 29 | 30 | ## Options 31 | 32 | All vcpkg commands support a set of [common options](common-options.md). 33 | 34 | ### `--x-full-desc` 35 | 36 | Print the full, untruncated description of each package. 37 | -------------------------------------------------------------------------------- /ThirdPartyNotices.md: -------------------------------------------------------------------------------- 1 | ## Legal Notices 2 | Microsoft and any contributors grant you a license to the Microsoft documentation and other content 3 | in this repository under the [Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/legalcode), 4 | see the [LICENSE](LICENSE) file, and grant you a license to any code in the repository under the [MIT License](https://opensource.org/licenses/MIT), see the 5 | [LICENSE-CODE](LICENSE-CODE) file. 6 | 7 | Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation 8 | may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. 9 | The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. 10 | Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653. 11 | 12 | Privacy information can be found at https://privacy.microsoft.com/en-us/ 13 | 14 | Microsoft and any contributors reserve all others rights, whether under their respective copyrights, patents, 15 | or trademarks, whether by implication, estoppel or otherwise. -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/internal/z_vcpkg_apply_patches.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: z_vcpkg_apply_patches 3 | description: Internal helper to apply a set of patches to a source tree. 4 | ms.date: 11/30/2022 5 | --- 6 | # z_vcpkg_apply_patches 7 | 8 | [!INCLUDE [internal-helper](../../../../includes/internal-helper.md)] 9 | 10 | Apply a set of patches to a source tree. 11 | 12 | ## Usage 13 | 14 | ```cmake 15 | z_vcpkg_apply_patches( 16 | SOURCE_PATH 17 | [QUIET] 18 | PATCHES ... 19 | ) 20 | ``` 21 | 22 | ## Parameters 23 | 24 | ### SOURCE_PATH 25 | 26 | The path to apply patches into. 27 | 28 | ### PATCHES 29 | 30 | The list of patches to apply. 31 | 32 | Relative paths are interpreted from the root of the port directory. 33 | 34 | ### QUIET 35 | 36 | Do not print any messages and do not fatal error on failure to apply patches. 37 | 38 | ## Notes 39 | 40 | A common pattern for large patches is to download them with `vcpkg_download_distfile()` and pass the downloaded path into `PATCHES`. 41 | 42 | ## Source 43 | 44 | [scripts/cmake/z\_vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_apply_patches.cmake) 45 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_configure_gn.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_configure_gn 3 | description: Use vcpkg_configure_gn to generate ninja targets. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_configure_gn 7 | 8 | > [!WARNING] 9 | > This function has been deprecated in favor of [`vcpkg_gn_configure`](vcpkg_gn_configure.md). 10 | 11 | Generate Ninja (GN) targets 12 | 13 | ## Usage 14 | 15 | ```cmake 16 | vcpkg_configure_gn( 17 | SOURCE_PATH 18 | [OPTIONS ] 19 | [OPTIONS_DEBUG ] 20 | [OPTIONS_RELEASE ] 21 | ) 22 | ``` 23 | 24 | ## Parameters 25 | 26 | ### SOURCE_PATH (required) 27 | 28 | The path to the GN project. 29 | 30 | ### OPTIONS 31 | 32 | Options to be passed to both the debug and release targets. The options must be provided as a space-separated string. 33 | 34 | ### OPTIONS_DEBUG (space-separated string) 35 | 36 | Options to be passed to the debug target. 37 | 38 | ### OPTIONS_RELEASE (space-separated string) 39 | 40 | Options to be passed to the release target. 41 | 42 | ## Source 43 | 44 | [scripts/cmake/vcpkg\_configure\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_gn.cmake) 45 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) Microsoft Corporation. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE 22 | -------------------------------------------------------------------------------- /vcpkg/concepts/classic-mode.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Classic mode 3 | description: Use vcpkg in Classic mode to share a central instance of installed libraries. 4 | author: vicroms 5 | ms.author: viromer 6 | ms.date: 07/29/2024 7 | ms.topic: concept-article 8 | --- 9 | 10 | # Classic mode 11 | 12 | vcpkg has two operation modes: classic mode and 13 | [manifest mode](manifest-mode.md). For most users, we recommend manifest mode. 14 | 15 | In classic mode, vcpkg maintains a central *installed tree* inside the vcpkg 16 | instance built up by individual [`vcpkg install`](../commands/install.md) and 17 | [`vcpkg remove`](../commands/remove.md) commands. This central set of packages 18 | can then be shared by any number of projects. 19 | 20 | Because the set of installed packages is not associated with an individual 21 | project, classic mode operates similarly to tools like `brew` or `apt`. However, 22 | the set is still associated with a vcpkg instance, and each instance of vcpkg 23 | (such as separate `git clone` copies) will have its own set of classic mode 24 | packages installed. 25 | 26 | To learn how to install dependencies in classic mode, see [Tutorial: Install a dependency from the command line](../consume/classic-mode.md). 27 | -------------------------------------------------------------------------------- /vcpkg/commands/search.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg search 3 | description: Command line reference for the vcpkg search command. Search for available packages by name and description. 4 | ms.date: 01/10/2024 5 | --- 6 | 7 | # vcpkg search 8 | 9 | ## Synopsis 10 | 11 | ```console 12 | vcpkg search [options] [query] 13 | ``` 14 | 15 | ## Description 16 | 17 | Search for available packages by name and description. 18 | 19 | Search performs a case-insensitive search through all available package names and descriptions. The results are displayed in a tabular format. 20 | 21 | ## Example 22 | 23 | ```console 24 | $ vcpkg search zlib 25 | miniz 2.2.0#1 Single C source file zlib-replacement library 26 | zlib 1.2.12#1 A compression library 27 | zlib-ng 2.0.6 zlib replacement with optimizations for 'next generation' systems 28 | ``` 29 | 30 | ## Options 31 | 32 | All vcpkg commands support a set of [common options](common-options.md). 33 | 34 | ### `--x-full-desc` 35 | 36 | [!INCLUDE [experimental](../../includes/experimental.md)] 37 | 38 | Do not truncate long descriptions. 39 | 40 | By default, long descriptions will be truncated to keep the tabular output browsable. 41 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_execute_build_process.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_execute_build_process 3 | description: Learn how to use vcpkg_execute_build_process. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_execute_build_process 7 | 8 | Execute a required build process 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_execute_build_process( 14 | COMMAND [...] 15 | [NO_PARALLEL_COMMAND [...]] 16 | WORKING_DIRECTORY 17 | LOGNAME 18 | ) 19 | ``` 20 | 21 | ## Parameters 22 | 23 | ### COMMAND 24 | 25 | The command to be executed, along with its arguments. 26 | 27 | ### NO_PARALLEL_COMMAND 28 | 29 | Optional parameter which specifies a non-parallel command to attempt if a 30 | failure potentially due to parallelism is detected. 31 | 32 | ### WORKING_DIRECTORY 33 | 34 | The directory to execute the command in. 35 | 36 | ### LOGNAME 37 | 38 | The prefix to use for the log files. 39 | 40 | This should be a unique name for different triplets so that the logs don't 41 | conflict when building multiple at once. 42 | 43 | ## Source 44 | 45 | [scripts/cmake/vcpkg\_execute\_build\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake) 46 | -------------------------------------------------------------------------------- /vcpkg/examples/vcpkg_android_example_cmake_script/compile.sh: -------------------------------------------------------------------------------- 1 | # 1. Install the library via vcpkg 2 | # This install jsoncpp for the 4 android target ABIs and for the host computer. 3 | # see the correspondence between ABIs and vcpkg triplets in the table below: 4 | # 5 | # |VCPKG_TARGET_TRIPLET | ANDROID_ABI | 6 | # |---------------------------|----------------------| 7 | # |arm64-android | arm64-v8a | 8 | # |arm-android | armeabi-v7a | 9 | # |x64-android | x86_64 | 10 | # |x86-android | x86 | 11 | $VCPKG_ROOT/vcpkg install \ 12 | jsoncpp \ 13 | jsoncpp:arm-android \ 14 | jsoncpp:arm64-android \ 15 | jsoncpp:x86-android \ 16 | jsoncpp:x64-android 17 | 18 | 19 | # 2. Test the build 20 | # 21 | # First, select an android ABI 22 | # Uncomment one of the four possibilities below 23 | # 24 | android_abi=armeabi-v7a 25 | # android_abi=x86 26 | # android_abi=arm64-v8a 27 | # android_abi=x86_64 28 | 29 | rm -rf build 30 | mkdir build && cd build 31 | 32 | # DVCPKG_TARGET_ANDROID will load vcpkg_android.cmake, 33 | # which will then load the android + vcpkg toolchains. 34 | cmake .. \ 35 | -DVCPKG_TARGET_ANDROID=ON \ 36 | -DANDROID_ABI=$android_abi 37 | make 38 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_find_acquire_program.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_find_acquire_program 3 | description: Learn how to use vcpkg_find_acquire_program. 4 | ms.date: 01/22/2025 5 | --- 6 | # vcpkg_find_acquire_program 7 | 8 | Download or find a well-known tool. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_find_acquire_program() 14 | ``` 15 | 16 | ## Parameters 17 | 18 | ### program 19 | 20 | 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. 21 | 22 | ## Notes 23 | 24 | The current list of programs includes: 25 | 26 | - 7Z 27 | - BISON 28 | - CLANG 29 | - DARK 30 | - DOXYGEN 31 | - FLEX 32 | - GASPREPROCESSOR 33 | - GPERF 34 | - PERL 35 | - PYTHON2 36 | - PYTHON3 37 | - GIT 38 | - GN 39 | - GO 40 | - JOM 41 | - MESON 42 | - NASM 43 | - NINJA 44 | - NUGET 45 | - SCONS 46 | - SWIG 47 | - YASM 48 | 49 | msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md). 50 | 51 | ## Examples 52 | 53 | - [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake) 54 | 55 | ## Source 56 | 57 | [`scripts/cmake/vcpkg_find_acquire_program.cmake`](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_acquire_program.cmake) 58 | -------------------------------------------------------------------------------- /vcpkg/commands/hash.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg hash 3 | description: Reference for the vcpkg hash command. Computes the hash of a specified file. 4 | author: JavierMatosD 5 | ms.author: javiermat 6 | ms.date: 01/10/2024 7 | --- 8 | 9 | # vcpkg hash 10 | 11 | ## Synopsis 12 | 13 | ```console 14 | vcpkg hash [algorithm] 15 | ``` 16 | 17 | ## Description 18 | 19 | Computes the hash of a specified file. By default, it computes the SHA-512 hash, but another algorithm can be optionally specified. The output will be the computed hash for the given file displayed directly on the console. 20 | 21 | ## Examples 22 | 23 | To compute the SHA-512 for the `boost_1_83_0.tar.bz2`: 24 | 25 | ```console 26 | vcpkg hash boost_1_83_0.tar.bz2 27 | 28 | -- d133b521bd754dc35a9bd30d8032bd2fd866026d90af2179e43bfd7bd816841f7f3b84303f52c0e54aebc373f4e4edd601a8f5a5e0c47500e0e852e04198a711 29 | ``` 30 | 31 | To compute the hash for the file `boost_1_83_0.tar.bz2` using a specific algorithm (e.g., SHA-256): 32 | 33 | ```console 34 | vcpkg hash boost_1_83_0.tar.bz2 sha256 35 | 36 | -- 6478edfe2f3305127cffe8caf73ea0176c53769f4bf1585be237eb30798c3b8e 37 | ``` 38 | 39 | ## Options 40 | 41 | All vcpkg commands support a set of [common options](common-options.md). 42 | 43 | ### Algorithms 44 | 45 | - SHA-512 46 | - SHA-256 47 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_get_python_packages.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_get_python_packages 3 | description: Learn how to use vcpkg_get_python_packages. 4 | ms.date: 01/10/2024 5 | --- 6 | # x_vcpkg_get_python_packages 7 | 8 | [!INCLUDE [experimental](../../../includes/experimental.md)] 9 | 10 | Retrieve needed python packages. 11 | 12 | ## Usage 13 | 14 | ```cmake 15 | x_vcpkg_get_python_packages( 16 | [PYTHON_VERSION (2|3)] 17 | PYTHON_EXECUTABLE 18 | REQUIREMENTS_FILE 19 | PACKAGES ... 20 | [OUT_PYTHON_VAR some_var] 21 | ) 22 | ``` 23 | 24 | ## Parameters 25 | 26 | ### PYTHON_VERSION 27 | 28 | Python version to be used. 29 | 30 | Must be either 2 or 3. 31 | 32 | ### PYTHON_EXECUTABLE 33 | 34 | Full path to the python executable 35 | 36 | ### REQUIREMENTS_FILE 37 | 38 | Requirement file with the list of python packages 39 | 40 | ### PACKAGES 41 | 42 | List of python packages to acquire 43 | 44 | ### OUT_PYTHON_VAR 45 | 46 | Variable to store the path to the python binary inside the virtual environment 47 | 48 | ## Source 49 | 50 | [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) 51 | -------------------------------------------------------------------------------- /vcpkg/commands/format-manifest.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg format-manifest 3 | description: Reference for the vcpkg format-manifest command. Formats vcpkg.json files and converts CONTROL files to vcpkg.json format. 4 | author: JavierMatosD 5 | ms.author: javiermat 6 | ms.date: 07/16/2024 7 | --- 8 | 9 | # vcpkg format-manifest 10 | 11 | ## Synopsis 12 | 13 | ```console 14 | vcpkg format-manifest [--all] [--convert-control] [...] 15 | ``` 16 | 17 | ## Description 18 | 19 | Formats [manifest (`vcpkg.json`)](../reference/vcpkg-json.md) files 20 | and converts control (`CONTROL`) files into the manifest format. 21 | If both `CONTROL` and `vcpkg.json` file are present in the same directory, the command will exit with an error. 22 | 23 | ## Examples 24 | 25 | To format a specific manifest or control file: 26 | 27 | ```console 28 | vcpkg format-manifest /path/to/vcpkg.json 29 | ``` 30 | 31 | To format all manifest files in the `${VCPKG_ROOT}/ports` directory: 32 | 33 | ```console 34 | vcpkg format-manifest --all 35 | ``` 36 | 37 | ## Options 38 | 39 | All vcpkg commands support a set of [common options](common-options.md). 40 | 41 | ### `--all` 42 | 43 | Formats all manifest files in the `${VCPKG_ROOT}/ports` directory. 44 | 45 | ### `--convert-control` 46 | 47 | Converts `CONTROL` files into `vcpkg.json` format when found in the ports 48 | directory. 49 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/internal/z_vcpkg_get_cmake_vars.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: z_vcpkg_get_cmake_vars 3 | description: Run a cmake configure with a dummy project to extract certain cmake variables. 4 | ms.date: 11/30/2022 5 | --- 6 | # z_vcpkg_get_cmake_vars 7 | 8 | [!INCLUDE [internal-helper](../../../../includes/internal-helper.md)] 9 | 10 | Runs a cmake configure with a dummy project to extract certain cmake variables 11 | 12 | ## Usage 13 | 14 | ```cmake 15 | z_vcpkg_get_cmake_vars() 16 | ``` 17 | 18 | `z_vcpkg_get_cmake_vars(cmake_vars_file)` sets `` to 19 | a path to a generated CMake file, with the detected `CMAKE_*` variables 20 | re-exported as `VCPKG_DETECTED_*`. 21 | 22 | ## Notes 23 | 24 | Avoid usage in portfiles. 25 | 26 | All calls to `z_vcpkg_get_cmake_vars` will result in the same output file; 27 | the output file is not generated multiple times. 28 | 29 | ## Examples 30 | 31 | ```cmake 32 | z_vcpkg_get_cmake_vars(cmake_vars_file) 33 | include("${cmake_vars_file}") 34 | message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CXX_FLAGS}") 35 | ``` 36 | 37 | See also [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake). 38 | 39 | ## Source 40 | 41 | [scripts/cmake/z\_vcpkg\_get\_cmake\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_get_cmake_vars.cmake) 42 | -------------------------------------------------------------------------------- /vcpkg/examples/vcpkg_android_example_cmake/compile.sh: -------------------------------------------------------------------------------- 1 | # 2 | # 1. Check the presence of required environment variables 3 | # 4 | if [ -z ${ANDROID_NDK_HOME+x} ]; then 5 | echo "Please set ANDROID_NDK_HOME" 6 | exit 1 7 | fi 8 | if [ -z ${VCPKG_ROOT+x} ]; then 9 | echo "Please set VCPKG_ROOT" 10 | exit 1 11 | fi 12 | 13 | # 14 | # 2. Set the path to the toolchains 15 | # 16 | vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake 17 | android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake 18 | 19 | 20 | # 21 | # 3. Select a pair "Android abi" / "vcpkg triplet" 22 | # Uncomment one of the four possibilities below 23 | # 24 | 25 | android_abi=armeabi-v7a 26 | vcpkg_target_triplet=arm-android 27 | 28 | # android_abi=x86 29 | # vcpkg_target_triplet=x86-android 30 | 31 | # android_abi=arm64-v8a 32 | # vcpkg_target_triplet=arm64-android 33 | 34 | # android_abi=x86_64 35 | # vcpkg_target_triplet=x64-android 36 | 37 | 38 | # 39 | # 4. Install the library via vcpkg 40 | # 41 | $VCPKG_ROOT/vcpkg install jsoncpp:$vcpkg_target_triplet 42 | 43 | # 44 | # 5. Test the build 45 | # 46 | rm -rf build 47 | mkdir build 48 | cd build 49 | cmake .. \ 50 | -DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \ 51 | -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \ 52 | -DVCPKG_TARGET_TRIPLET=$vcpkg_target_triplet \ 53 | -DANDROID_ABI=$android_abi 54 | make 55 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_host_path_list.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_host_path_list 3 | description: Learn how to use vcpkg_host_path_list. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_host_path_list 7 | 8 | Modify a host path list variable (PATH, INCLUDE, LIBPATH, etc.) 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_host_path_list(PREPEND [...]) 14 | vcpkg_host_path_list(APPEND [...]) 15 | vcpkg_host_path_list(SET [...]) 16 | ``` 17 | 18 | `` may be either a regular variable name, or `ENV{variable-name}`, 19 | in which case `vcpkg_host_path_list` will modify the environment. 20 | 21 | `vcpkg_host_path_list` adds all of the paths passed to it to ``; 22 | `PREPEND` puts them before the existing list, so that they are searched first; 23 | `APPEND` places them after the existing list, 24 | so they would be searched after the paths which are already in the variable, 25 | and `SET` replaces the value of the existing list. 26 | 27 | For all of `APPEND`, `PREPEND`, and `SET`, 28 | the paths are added (and thus searched) in the order received. 29 | 30 | If no paths are passed to `APPEND` or `PREPEND`, nothing will be done; 31 | for `SET`, the variable will be set to the empty string. 32 | 33 | ## Source 34 | 35 | [scripts/cmake/vcpkg\_host\_path\_list.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_host_path_list.cmake) 36 | -------------------------------------------------------------------------------- /vcpkg/commands/update.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg update 3 | description: Command line reference for the vcpkg update command. 4 | ms.date: 01/10/2023 5 | --- 6 | # vcpkg update 7 | 8 | ## Synopsis 9 | 10 | ```console 11 | vcpkg update [options] 12 | ``` 13 | 14 | ## Description 15 | 16 | Compares the set of [Classic mode] installed packages against the current available versions. 17 | 18 | To remove outdated versions without installing replacements, use [`vcpkg remove --outdated`](remove.md). To remove and install the newer versions, use [`vcpkg upgrade`](upgrade.md). 19 | 20 | ## Example 21 | 22 | ```console 23 | $ vcpkg update 24 | Using local portfile versions. To update the local portfiles, use `git pull`. 25 | The following packages differ from their port versions: 26 | corrade:x64-windows 2020.06#4 -> 2020.06#5 27 | magnum:x64-windows 2020.06#11 -> 2020.06#12 28 | openal-soft:x64-windows 1.22.2#5 -> 1.23.0 29 | ragel:x64-windows 6.10#4 -> 6.10#5 30 | sdl2:x64-windows 2.26.3#1 -> 2.26.4 31 | To update these packages and all dependencies, run 32 | .\vcpkg upgrade' 33 | To only remove outdated packages, run 34 | .\vcpkg remove --outdated 35 | ``` 36 | 37 | ## Options 38 | 39 | All vcpkg commands support a set of [common options](common-options.md). 40 | 41 | [Classic mode]: ../concepts/classic-mode.md 42 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/internal/z_vcpkg_prettify_command_line.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: z_vcpkg_prettify_command_line 3 | description: Use z_vcpkg_prettify_command_line to format a command line into a string. 4 | ms.date: 11/30/2022 5 | --- 6 | # z_vcpkg_prettify_command_line 7 | 8 | [!INCLUDE [internal-helper](../../../../includes/internal-helper.md)] 9 | 10 | Format a command line into a string. 11 | 12 | ## Usage 13 | 14 | ```cmake 15 | z_vcpkg_prettify_command_line( ...) 16 | ``` 17 | 18 | ## Parameters 19 | 20 | ### `` 21 | 22 | Variable to set to the formatted command line 23 | 24 | ### `...` 25 | 26 | The command line to format. 27 | 28 | This argument should be the same form as the [`COMMAND` argument of `vcpkg_execute_required_process()`](../vcpkg_execute_required_process.md#command). 29 | 30 | ## Examples 31 | 32 | - [vcpkg_execute_build_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake) 33 | - [vcpkg_execute_required_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake) 34 | - [vcpkg_execute_required_process_repeat.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process_repeat.cmake) 35 | 36 | ## Source 37 | 38 | [`scripts/cmake/z_vcpkg_prettify_command_line.cmake`](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_prettify_command_line.cmake) 39 | -------------------------------------------------------------------------------- /vcpkg/get_started/includes/setup-vcpkg.md: -------------------------------------------------------------------------------- 1 | 1. Clone the repository 2 | 3 | The first step is to clone the vcpkg repository from GitHub. The repository contains scripts to acquire the vcpkg executable and a registry of curated open-source libraries maintained by the vcpkg community. To do this, run: 4 | 5 | ```console 6 | git clone https://github.com/microsoft/vcpkg.git 7 | ``` 8 | 9 | The vcpkg curated registry is a set of over 2,000 open-source libraries. These libraries have been validated by vcpkg's continuous integration pipelines to work together. While the vcpkg repository does not contain the source code for these libraries, it holds recipes and metadata to build and install them in your system. 10 | 11 | 2. Run the bootstrap script 12 | 13 | Now that you have cloned the vcpkg repository, navigate to the `vcpkg` directory and execute the bootstrap script: 14 | 15 | ::: zone pivot="shell-cmd" 16 | 17 | ```console 18 | cd vcpkg && bootstrap-vcpkg.bat 19 | ``` 20 | 21 | ::: zone-end 22 | ::: zone pivot="shell-powershell" 23 | 24 | ```console 25 | cd vcpkg; .\bootstrap-vcpkg.bat 26 | ``` 27 | 28 | ::: zone-end 29 | ::: zone pivot="shell-bash" 30 | 31 | ```console 32 | cd vcpkg && ./bootstrap-vcpkg.sh 33 | ``` 34 | 35 | ::: zone-end 36 | 37 | The bootstrap script performs prerequisite checks and downloads the vcpkg executable. 38 | 39 | That's it! vcpkg is set up and ready to use. 40 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_copy_tools.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_copy_tools 3 | description: Learn how to use vcpkg_copy_tools. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_copy_tools 7 | 8 | Copy tools and all their DLL dependencies into the `tools` folder. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_copy_tools( 14 | TOOL_NAMES ... 15 | [SEARCH_DIR <${CURRENT_PACKAGES_DIR}/bin>] 16 | [DESTINATION <${CURRENT_PACKAGES_DIR}/tools/${PORT}>] 17 | [AUTO_CLEAN] 18 | ) 19 | ``` 20 | 21 | ## Parameters 22 | 23 | ### TOOL_NAMES 24 | 25 | A list of tool filenames without extension. 26 | 27 | ### SEARCH_DIR 28 | 29 | The path to the directory containing the tools. This will be set to `${CURRENT_PACKAGES_DIR}/bin` if omitted. 30 | 31 | ### DESTINATION 32 | 33 | Destination to copy the tools to. This will be set to `${CURRENT_PACKAGES_DIR}/tools/${PORT}` if omitted. 34 | 35 | ### AUTO_CLEAN 36 | 37 | Auto clean the copied executables from `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`. 38 | 39 | ## Examples 40 | 41 | - [cpuinfo](https://github.com/microsoft/vcpkg/blob/master/ports/cpuinfo/portfile.cmake) 42 | - [nanomsg](https://github.com/microsoft/vcpkg/blob/master/ports/nanomsg/portfile.cmake) 43 | - [uriparser](https://github.com/microsoft/vcpkg/blob/master/ports/uriparser/portfile.cmake) 44 | 45 | ## Source 46 | 47 | [scripts/cmake/vcpkg\_copy\_tools.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tools.cmake) 48 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_qmake_build.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_qmake_build 3 | description: Use vcpkg_qmake_build to build a QMake project. 4 | ms.date: 01/10/2024 5 | --- 6 | 7 | # vcpkg_qmake_build 8 | 9 | _Added in `vcpkg-qmake` version `2022-11-16`_. 10 | 11 | Build a qmake-based project, previously configured using [vcpkg_qmake_configure](vcpkg_qmake_configure.md). 12 | 13 | ```cmake 14 | vcpkg_qmake_build( 15 | [SKIP_MAKEFILES] 16 | [BUILD_LOGNAME arg1] 17 | [TARGETS arg1 [arg2 ...]] 18 | [RELEASE_TARGETS arg1 [arg2 ...]] 19 | [DEBUG_TARGETS arg1 [arg2 ...]] 20 | ) 21 | ``` 22 | 23 | To use this function, you must depend on the helper port `vcpkg-qmake`: 24 | 25 | ```json 26 | "dependencies": [ 27 | { 28 | "name": "vcpkg-qmake", 29 | "host": true 30 | } 31 | ] 32 | ``` 33 | 34 | ### SKIP_MAKEFILES 35 | 36 | Skip Makefile fixup to redirect _installed_ references to _packages_. 37 | 38 | ### BUILD_LOGNAME 39 | 40 | Configuration independent prefix for the build log files. 41 | 42 | Defaults to `build`. 43 | 44 | ### TARGETS, RELEASE\_TARGETS, DEBUG\_TARGETS 45 | Targets to build for a certain configuration. 46 | 47 | ## Examples 48 | 49 | [Search microsoft/vcpkg for Examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_build+path%3A%2Fports) 50 | 51 | ## Source 52 | 53 | [ports/vcpkg-qmake/vcpkg\_qmake\_build.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-qmake/vcpkg_qmake_build.cmake) -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/internal/z_vcpkg_function_arguments.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: z_vcpkg_function_arguments 3 | description: Get a list of function arguments suitable for perfect forwarding. 4 | ms.date: 11/30/2022 5 | --- 6 | # z_vcpkg_function_arguments 7 | 8 | [!INCLUDE [internal-helper](../../../../includes/internal-helper.md)] 9 | 10 | Get a list of function arguments suitable for perfect forwarding to another function. 11 | 12 | ## Usage 13 | 14 | ```cmake 15 | z_vcpkg_function_arguments( []) 16 | ``` 17 | 18 | ## Parameters 19 | 20 | ### `` 21 | 22 | The variable to set to the list of arguments 23 | 24 | ### `` 25 | 26 | The index to start accumulating arguments. 27 | 28 | Defaults to `0` so all arguments will be gathered. 29 | 30 | ## Notes 31 | 32 | This macro improves over `ARGV` by making it possible to distinguish list arguments. 33 | 34 | | Form | `ARGV` | `z_vcpkg_function_arguments()` | 35 | |--------------|---------------|--------------------------------| 36 | | `fun(A B)` | `"A;B"` | `"A;B"` | 37 | | `fun("A;B")` | `"A;B"` | `"A\;B"` | 38 | 39 | ## Examples 40 | 41 | ```cmake 42 | function(fun) 43 | z_vcpkg_function_arguments(ARGS) 44 | message("fun() is deprecated, use fun_replacement()") 45 | fun_replacement(${ARGS}) 46 | endfunction() 47 | ``` 48 | 49 | ## Source 50 | 51 | [`scripts/cmake/z_vcpkg_function_arguments.cmake`](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_function_arguments.cmake) 52 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_cmake_get_vars.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_cmake_get_vars 3 | description: Use vcpkg_cmake_get_vars to extract certain CMake variables. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_cmake_get_vars 7 | 8 | Runs a cmake configure with a dummy project to extract certain cmake variables 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_cmake_get_vars() 14 | ``` 15 | 16 | `vcpkg_cmake_get_vars()` sets `` to 17 | a path to a generated CMake file, with the detected `CMAKE_*` variables 18 | re-exported as `VCPKG_DETECTED_CMAKE_*`. 19 | 20 | Additionally sets, for `RELEASE` and `DEBUG`: 21 | 22 | - `VCPKG_COMBINED_CXX_FLAGS_` 23 | - `VCPKG_COMBINED_C_FLAGS_` 24 | - `VCPKG_COMBINED_SHARED_LINKER_FLAGS_` 25 | - `VCPKG_COMBINED_STATIC_LINKER_FLAGS_` 26 | - `VCPKG_COMBINED_EXE_LINKER_FLAGS_` 27 | 28 | Most users should use these pre-combined flags instead of attempting 29 | to read the `VCPKG_DETECTED_*` flags directly. 30 | 31 | ## Notes 32 | 33 | Avoid usage in portfiles. 34 | 35 | All calls to `vcpkg_cmake_get_vars` will result in the same output file; 36 | the output file is not generated multiple times. 37 | 38 | ### Basic Usage 39 | 40 | ```cmake 41 | vcpkg_cmake_get_vars(cmake_vars_file) 42 | include("${cmake_vars_file}") 43 | message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CMAKE_CXX_FLAGS}") 44 | ``` 45 | 46 | ## Source 47 | 48 | [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) 49 | -------------------------------------------------------------------------------- /vcpkg/commands/remove.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg remove 3 | description: Command line reference for the vcpkg remove command. Remove port packages from Classic mode. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg remove 7 | 8 | ## Synopsis 9 | 10 | ```console 11 | vcpkg remove [options] ... 12 | ``` 13 | 14 | ```console 15 | vcpkg remove --outdated [options] 16 | ``` 17 | 18 | ## Description 19 | 20 | Remove port packages from Classic mode. 21 | 22 | `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. 23 | 24 | This command is not currently supported in [Manifest mode](../concepts/manifest-mode.md). 25 | 26 | ## Options 27 | 28 | All vcpkg commands support a set of [common options](common-options.md). 29 | 30 | ### `--recurse` 31 | 32 | Allow removing packages not specified on the command line. 33 | 34 | By default, vcpkg refuses to execute a removal plan that would remove packages not listed on the command line. 35 | 36 | ### `--dry-run` 37 | 38 | Print the packages to be removed, but do not remove them. 39 | 40 | ### `--outdated` 41 | 42 | Remove all packages that do not match the available port versions. 43 | 44 | 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. 45 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_fail_port_install.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_fail_port_install 3 | description: Learn how to use vcpkg_fail_port_install. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_fail_port_install 7 | 8 | > [!WARNING] 9 | > This function has been deprecated in favor of the [`supports` field](../../reference/vcpkg-json.md#supports). 10 | 11 | Checks common requirements and fails the current portfile with a (default) error message 12 | 13 | ## Usage 14 | 15 | ```cmake 16 | vcpkg_fail_port_install( 17 | [ALWAYS] 18 | [MESSAGE <"Reason for failure">] 19 | [ON_TARGET [ ...]] 20 | [ON_ARCH [ ...]] 21 | [ON_CRT_LINKAGE [ ...]] 22 | [ON_LIBRARY_LINKAGE [ ...]] 23 | ) 24 | ``` 25 | 26 | ## Parameters 27 | 28 | ### MESSAGE 29 | 30 | Additional failure message. If none is given, a default message will be displayed depending on the failure condition. 31 | 32 | ### ALWAYS 33 | 34 | Will always fail early 35 | 36 | ### ON_TARGET 37 | 38 | Targets for which the build should fail early. Valid targets are `` from `VCPKG_IS_TARGET_` (see `vcpkg_common_definitions.cmake`). 39 | 40 | ### ON_ARCH 41 | 42 | Architecture for which the build should fail early. 43 | 44 | ### ON_CRT_LINKAGE 45 | 46 | CRT linkage for which the build should fail early. 47 | 48 | ### ON_LIBRARY_LINKAGE 49 | 50 | Library linkage for which the build should fail early. 51 | 52 | ## Source 53 | 54 | [scripts/cmake/vcpkg\_fail\_port\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake) 55 | -------------------------------------------------------------------------------- /vcpkg/concepts/system-package-managers.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Using vcpkg compared to system package managers 3 | description: Concepts on system package managers 4 | author: data-queue 5 | ms.author: danshaw2 6 | ms.date: 01/10/2024 7 | ms.topic: concept-article 8 | --- 9 | 10 | # System package managers 11 | 12 | C++ libraries are available in C++ package managers such as vcpkg or in system package managers such as apt. How you choose to acquire your libraries depends on your specific use case. You can also have vcpkg dependencies [depend on system package manager dependencies](https://devblogs.microsoft.com/cppblog/using-system-package-manager-dependencies-with-vcpkg/). 13 | 14 | ## Reasons to use dependencies from a system package manager 15 | - Overall deployment size will be reduced, as different programs can share the same shared libraries. 16 | - Your program will respond to policy decisions configured on that system. For example, DNS policy tends to be implemented in glibc, or trusted certificates implemented in OpenSSL, or UI / themeing bits from UI libraries, etc. 17 | - It's usually faster to download binaries from a system package manager than it is to build them from source. 18 | 19 | ## Reasons to use dependencies from vcpkg 20 | - It will easier for development: vcpkg builds from source, meaning you will have debug information for libraries. Additionally, libraries build both release and debug versions. 21 | - You have complete control over the versions of those dependencies. With a system package manager, you may be limited to only certain versions. 22 | - The way you get dependencies can be the same for all platforms that you target. 23 | -------------------------------------------------------------------------------- /.openpublishing.publish.config.json: -------------------------------------------------------------------------------- 1 | { 2 | "docsets_to_publish": [ 3 | { 4 | "docset_name": "vcpkg-docs", 5 | "build_source_folder": "vcpkg", 6 | "build_output_subfolder": "vcpkg-docs", 7 | "locale": "en-us", 8 | "monikers": [], 9 | "moniker_ranges": [], 10 | "open_to_public_contributors": true, 11 | "type_mapping": { 12 | "ZonePivotGroups": "Toc", 13 | "Conceptual": "Content" 14 | }, 15 | "build_entry_point": "docs", 16 | "template_folder": "_themes" 17 | } 18 | ], 19 | "notification_subscribers": [ 20 | "twhitney@microsoft.com", 21 | "roschuma@microsoft.com", 22 | "viromer@microsoft.com", 23 | "aupopa@microsoft.com" 24 | ], 25 | "sync_notification_subscribers": [], 26 | "branches_to_filter": [], 27 | "git_repository_url_open_to_public_contributors": "https://github.com/MicrosoftDocs/vcpkg-docs", 28 | "git_repository_branch_open_to_public_contributors": "main", 29 | "need_preview_pull_request": true, 30 | "dependent_repositories": [ 31 | { 32 | "path_to_root": "_themes", 33 | "url": "https://github.com/Microsoft/templates.docs.msft", 34 | "branch": "main", 35 | "branch_mapping": {} 36 | }, 37 | { 38 | "path_to_root": "_themes.pdf", 39 | "url": "https://github.com/Microsoft/templates.docs.msft.pdf", 40 | "branch": "main", 41 | "branch_mapping": {} 42 | } 43 | ], 44 | "branch_target_mapping": { 45 | "live": [ 46 | "Publish", 47 | "Pdf" 48 | ] 49 | }, 50 | "targets": { 51 | "pdf": { 52 | "template_folder": "_themes.pdf" 53 | } 54 | } 55 | } 56 | -------------------------------------------------------------------------------- /vcpkg/commands/update-baseline.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg x-update-baseline 3 | description: Command line reference for the vcpkg x-update-baseline command. Update baselines for all configured registries. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg x-update-baseline 7 | 8 | [!INCLUDE [experimental](../../includes/experimental.md)] 9 | 10 | ## Synopsis 11 | 12 | ```console 13 | vcpkg x-update-baseline [options] [--add-initial-baseline] [--dry-run] 14 | ``` 15 | 16 | ## Description 17 | 18 | Update baselines for all configured [registries](../reference/vcpkg-configuration-json.md#registries). 19 | 20 | In [Manifest mode](../concepts/manifest-mode.md), this command operates on all 21 | registries in the [`vcpkg.json`](../reference/vcpkg-json.md) and the 22 | [`vcpkg-configuration.json`](../reference/vcpkg-configuration-json.md). In 23 | Classic mode, this command operates on the `vcpkg-configuration.json` in the 24 | vcpkg instance (`$VCPKG_ROOT`). 25 | 26 | See the [versioning documentation](../users/versioning.md#baselines) for more information about baselines. 27 | 28 | ## Options 29 | 30 | All vcpkg commands support a set of [common options](common-options.md). 31 | 32 | ### `--dry-run` 33 | 34 | Print the planned baseline upgrades, but do not modify the files on disk. 35 | 36 | ### `--add-initial-baseline` 37 | 38 | - **Manifest mode only** 39 | 40 | Add a [`"builtin-baseline"`](../reference/vcpkg-json.md#builtin-baseline) field to the `vcpkg.json` if it does not already have one. 41 | 42 | Without this flag, it is an error to run this command on a manifest that does not have any [registries](../reference/vcpkg-configuration-json.md#registries) configured. 43 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_configure_meson.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_configure_meson 3 | description: Learn how to use vcpkg_configure_meson. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_configure_meson 7 | 8 | Configure Meson for Debug and Release builds of a project. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_configure_meson( 14 | SOURCE_PATH <${SOURCE_PATH}> 15 | [NO_PKG_CONFIG] 16 | [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] 17 | [OPTIONS_RELEASE <-DOPTIMIZE=1>...] 18 | [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] 19 | ) 20 | ``` 21 | 22 | ## Parameters 23 | 24 | ### SOURCE_PATH 25 | 26 | Specifies the directory containing the `meson.build`. 27 | By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. 28 | 29 | ### OPTIONS 30 | 31 | Additional options passed to Meson during the configuration. 32 | 33 | ### OPTIONS_RELEASE 34 | 35 | Additional options passed to Meson during the Release configuration. These are in addition to `OPTIONS`. 36 | 37 | ### OPTIONS_DEBUG 38 | 39 | Additional options passed to Meson during the Debug configuration. These are in addition to `OPTIONS`. 40 | 41 | ### NO_PKG_CONFIG 42 | 43 | Disable pkg-config setup. 44 | 45 | ## Notes 46 | 47 | This command supplies many common arguments to Meson. To see the full list, examine the source. 48 | 49 | ## Examples 50 | 51 | - [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake) 52 | - [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake) 53 | 54 | ## Source 55 | 56 | [scripts/cmake/vcpkg\_configure\_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_meson.cmake) 57 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_pkgconfig_get_modules.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: x_vcpkg_pkgconfig_get_modules 3 | description: Learn how to use x_vcpkg_pkgconfig_get_modules. 4 | ms.date: 01/10/2024 5 | --- 6 | # x_vcpkg_pkgconfig_get_modules 7 | 8 | [!INCLUDE [experimental](../../../includes/experimental.md)] 9 | 10 | Retrieve required module information from pkgconfig modules 11 | 12 | ## Usage 13 | 14 | ```cmake 15 | x_vcpkg_pkgconfig_get_modules( 16 | PREFIX 17 | MODULES ... 18 | [CFLAGS] 19 | [LIBS] 20 | [LIBRARIES] 21 | [LIBRARIES_DIRS] 22 | [INCLUDE_DIRS] 23 | ) 24 | ``` 25 | 26 | ## Parameters 27 | 28 | ### PREFIX 29 | 30 | Prefix to use for all output variables. 31 | 32 | ### MODULES 33 | 34 | List of pkgconfig modules to retrieve information for. 35 | 36 | ### LIBS 37 | 38 | Returns `"${PKGCONFIG}" --libs` as `_LIBS_RELEASE` and `_LIBS_DEBUG`. 39 | 40 | ### LIBRARIES 41 | 42 | Returns `"${PKGCONFIG}" --libs-only-l` in `_LIBRARIES_RELEASE` and `_LIBRARIES_DEBUG`. 43 | 44 | ### LIBRARIES_DIRS 45 | 46 | Returns `"${PKGCONFIG}" --libs-only-L` in `_LIBRARIES_DIRS_RELEASE` and `_LIBRARIES_DIRS_DEBUG`. 47 | 48 | ### INCLUDE_DIRS 49 | 50 | Returns `"${PKGCONFIG}" --cflags-only-I` in `_INCLUDE_DIRS_RELEASE` and `_INCLUDE_DIRS_DEBUG`. 51 | 52 | ## Examples 53 | 54 | - [qt5-base](https://github.com/microsoft/vcpkg/blob/master/ports/qt5-base/portfile.cmake) 55 | 56 | ## Source 57 | 58 | [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) 59 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/internal/z_vcpkg_forward_output_variable.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: z_vcpkg_forward_output_variable 3 | description: Forward values from inner function calls into pointer out parameters. 4 | ms.date: 11/30/2022 5 | --- 6 | # z_vcpkg_forward_output_variable 7 | 8 | [!INCLUDE [internal-helper](../../../../includes/internal-helper.md)] 9 | 10 | Forward values from inner function calls into pointer out parameters through a local function scope. 11 | 12 | ## Usage 13 | 14 | ```cmake 15 | z_vcpkg_forward_output_variable( ) 16 | ``` 17 | 18 | ## Parameters 19 | 20 | ### `` 21 | 22 | The name of a local variable set to the desired parent variable name. 23 | 24 | Most commonly, this local is the result of a pointer-out parameter to a function. 25 | 26 | ### `` 27 | 28 | The name of a local variable that will be propagated out. 29 | 30 | ## Notes 31 | 32 | The following two snippets are equivalent: 33 | 34 | ```cmake 35 | z_vcpkg_forward_output_variable(ptr_to_parent_var value_var) 36 | ``` 37 | 38 | ```cmake 39 | if(DEFINED ptr_to_parent_var) 40 | if(DEFINED value_var) 41 | set("${ptr_to_parent_var}" "${value_var}" PARENT_SCOPE) 42 | else() 43 | unset("${ptr_to_parent_var}" PARENT_SCOPE) 44 | endif() 45 | endif() 46 | ``` 47 | 48 | ## Examples 49 | 50 | ```cmake 51 | function(my_function out_var) 52 | file(SHA512 "somefile.txt" local_var) 53 | z_vcpkg_forward_output_variable(out_var local_var) 54 | endfunction() 55 | ``` 56 | 57 | ## Source 58 | 59 | [`scripts/cmake/z_vcpkg_forward_output_variable.cmake`](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_forward_output_variable.cmake) 60 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_build_cmake.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_build_cmake 3 | description: Use vcpkg_build_cmake to build a cmake project. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_build_cmake 7 | 8 | > [!WARNING] 9 | > This function has been deprecated in favor of [`vcpkg_cmake_build`](vcpkg_cmake_build.md). 10 | 11 | Build a cmake project. 12 | 13 | ## Usage 14 | 15 | ```cmake 16 | vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET ]) 17 | ``` 18 | 19 | ## Parameters 20 | 21 | ### DISABLE_PARALLEL 22 | 23 | The underlying buildsystem will be instructed to not parallelize 24 | 25 | ### TARGET 26 | 27 | The target passed to the cmake build command (`cmake --build . --target `). If not specified, no target will 28 | be passed. 29 | 30 | ### ADD_BIN_TO_PATH 31 | 32 | Adds the appropriate Release and Debug `bin` directories to the path during the build such that executables can run against the in-tree DLLs. 33 | 34 | ## Notes 35 | 36 | This command should be preceded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md). 37 | You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the 38 | "install" target 39 | 40 | ## Examples 41 | 42 | - [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) 43 | - [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) 44 | - [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake) 45 | - [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake) 46 | 47 | ## Source 48 | 49 | [scripts/cmake/vcpkg\_build\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_cmake.cmake) 50 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/internal/z_vcpkg_setup_pkgconfig_path.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: z_vcpkg_setup_pkgconfig_path 3 | description: Use z_vcpkg_setup_pkgconfig_path to set up the environment to use pkgconfig. 4 | ms.date: 11/30/2022 5 | --- 6 | # z_vcpkg_setup_pkgconfig_path 7 | 8 | [!INCLUDE [internal-helper](../../../../includes/internal-helper.md)] 9 | 10 | Set up the environment to use `pkgconfig`. 11 | 12 | ## Usage 13 | 14 | ```cmake 15 | z_vcpkg_setup_pkgconfig_path(BASE_DIRS ) 16 | ``` 17 | 18 | ## Parameters 19 | 20 | ### BASE_DIRS 21 | 22 | List of base directories to use. 23 | 24 | Typically `${CURRENT_INSTALLED_DIR}` or `${CURRENT_INSTALLED_DIR}/debug`, but not both. 25 | 26 | ## Notes 27 | 28 | Acquires and sets `PKG_CONFIG` to a valid `pkg-config` program. 29 | 30 | For each entry of `BASE_DIRS`, prepends `/lib` and `/share` to `PKG_CONFIG_PATH` in an unspecified order. 31 | 32 | See also [`z_vcpkg_restore_pkgconfig_path`](z_vcpkg_restore_pkgconfig_path.md). 33 | 34 | ## Examples 35 | 36 | ```cmake 37 | z_vcpkg_setup_pkgconfig_path(BASE_DIRS "${CURRENT_INSTALLED_DIR}") 38 | # Build process that may internally invoke pkgconfig 39 | vcpkg_execute_build_process(COMMAND my-buildsystem.py -release ...) 40 | z_vcpkg_restore_pkgconfig_path() 41 | if(NOT VCPKG_BUILD_TYPE) 42 | z_vcpkg_setup_pkgconfig_path(BASE_DIRS "${CURRENT_INSTALLED_DIR}/debug") 43 | # Build process that may internally invoke pkgconfig 44 | vcpkg_execute_build_process(COMMAND my-buildsystem.py -debug ...) 45 | z_vcpkg_restore_pkgconfig_path() 46 | endi() 47 | ``` 48 | 49 | ## Source 50 | 51 | [scripts/cmake/z\_vcpkg\_setup\_pkgconfig\_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_setup_pkgconfig_path.cmake) 52 | -------------------------------------------------------------------------------- /vcpkg/users/buildsystems/manual-integration.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Manual Integration 3 | description: Integrate vcpkg into any buildsystem, such as meson or autoconf. 4 | ms.date: 01/10/2024 5 | ms.topic: concept-article 6 | --- 7 | # Manual Integration 8 | 9 | When installing libraries, vcpkg creates a single common layout partitioned by triplet. 10 | 11 | The root of the tree in [Classic mode](../../concepts/classic-mode.md) is 12 | `/installed`. The root of the tree in [Manifest 13 | mode](../../concepts/manifest-mode.md) is `/vcpkg_installed`. 15 | 16 | Underneath this root, in a subfolder named after the triplet: 17 | 18 | - Header files: `include/` 19 | - Release `.lib`, `.a`, and `.so` files: `lib/` or `lib/manual-link/` 20 | - Release `.dll` files: `bin/` 21 | - Release `.pc` files: `lib/pkgconfig/` or `share/pkgconfig/` 22 | - Debug `.lib`, `.a`, and `.so` files: `debug/lib/` or `debug/lib/manual-link/` 23 | - Debug `.dll` files: `debug/bin/` 24 | - Debug `.pc` files: `debug/lib/pkgconfig/` or `debug/share/pkgconfig/` 25 | - Tools: `tools//` 26 | 27 | For example, `zlib.h` for `zlib:x64-windows` in classic mode is located at `/installed/x64-windows/include/zlib.h`. 28 | 29 | See your build system specific documentation for how to use prebuilt binaries. For example, Makefile projects often accept environment variables: 30 | 31 | ```sh 32 | export CXXFLAGS=-I$(pwd)/installed/x64-linux/include 33 | export CFLAGS=-I$(pwd)/installed/x64-linux/include 34 | export LDFLAGS=-L$(pwd)/installed/x64-linux/lib 35 | export PKG_CONFIG_PATH=$(pwd)/installed/x64-linux/lib/pkgconfig:$(pwd)/installed/x64-linux/share/pkgconfig:$PKG_CONFIG_PATH 36 | ``` 37 | 38 | On Windows dynamic triplets (such as x64-windows) 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 to run any produced executables. 39 | -------------------------------------------------------------------------------- /vcpkg/examples/adding-usage.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Add an explicit usage file to a port. 3 | description: Learn about supplying specific usage instructions in ports 4 | ms.date: 01/10/2024 5 | ROBOTS: NOINDEX 6 | is_archived: true 7 | # Replaced by: maintainers/handling-usage-files.md 8 | --- 9 | # Add an explicit usage file to a port. 10 | 11 | `vcpkg` generates usage text for users who install particular ports, if the user names that specific port. For example: 12 | 13 | ``` 14 | $> vcpkg install zlib:x64-windows 15 | Computing installation plan... 16 | The following packages will be built and installed: 17 | * vcpkg-cmake[core]:x64-windows -> 2022-09-26 18 | zlib[core]:x64-windows -> 1.2.12#2 19 | Additional packages (*) will be modified to complete this operation. 20 | Detecting compiler hash for triplet x64-windows... 21 | Restored 2 package(s) from C:\Users\username\AppData\Local\vcpkg\archives in 77.46 ms. Use --debug to see more details. 22 | Installing 1/2 vcpkg-cmake:x64-windows... 23 | Elapsed time to handle vcpkg-cmake:x64-windows: 10.32 ms 24 | Installing 2/2 zlib:x64-windows... 25 | Elapsed time to handle zlib:x64-windows: 20.89 ms 26 | Total elapsed time: 2.747 s 27 | 28 | The package zlib is compatible with built-in CMake targets: 29 | 30 | find_package(ZLIB REQUIRED) 31 | target_link_libraries(main PRIVATE ZLIB::ZLIB) 32 | ``` 33 | 34 | Ports can explicitly supply usage instructions by creating a file in their package at `share/${PORT}/usage`. If there is no explicit usage installed by the port, vcpkg will generate default usage text by inspecting the installed files. 35 | 36 | 1. Create a file named `usage` in the port directory with the content you want displayed. 37 | 2. To `portfile.cmake`, add 38 | ``` 39 | file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}") 40 | ``` 41 | 3. Update the `"port-version"` and run `vcpkg x-add-version`. 42 | -------------------------------------------------------------------------------- /vcpkg/commands/add.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg add 3 | description: Reference for the vcpkg add command. Adds packages to the manifest. 4 | author: JavierMatosD 5 | ms.author: javiermat 6 | ms.date: 01/26/2024 7 | --- 8 | # vcpkg add 9 | 10 | ## Synopsis 11 | 12 | ```console 13 | vcpkg add port [options] ... 14 | ``` 15 | 16 | ## Description 17 | 18 | The `vcpkg add port` command allows you to update the `vcpkg.json` manifest file by adding new package dependencies to your C++ project. 19 | 20 | You can specify one or multiple port names to add. It's also possible to define specific features of a port that you would like to include as a dependency. The manifest (`vcpkg.json`) will then be updated to reflect these changes. 21 | 22 | ### Examples 23 | 24 | Sample manifest: 25 | 26 | ```json 27 | { 28 | "name": "Example", 29 | "version": "1.0" 30 | } 31 | ``` 32 | 33 | To add ports - `fmt`, `sqlitecpp`, `zlib`: 34 | 35 | ```console 36 | vcpkg add port fmt sqlitecpp zlib 37 | ``` 38 | 39 | ```json 40 | { 41 | "name": "Example", 42 | "version": "1.0", 43 | "dependencies": [ 44 | "fmt", 45 | "zlib", 46 | "sqlitecpp" 47 | ] 48 | } 49 | ``` 50 | 51 | To specify port with feature - `sqlitecpp[sqlcipher]` 52 | 53 | ```console 54 | vcpkg add port sqlitecpp[sqlcipher] 55 | ``` 56 | 57 | ```json 58 | { 59 | "name": "Example", 60 | "version": "1.0", 61 | "dependencies": [ 62 | "fmt", 63 | { 64 | "name": "sqlitecpp", 65 | "features": [ 66 | "sqlcipher" 67 | ] 68 | }, 69 | "zlib" 70 | ] 71 | } 72 | ``` 73 | 74 | > [!NOTE] 75 | > The `vcpkg add port` command does not validate the existence of specified features for a port. Ensure that the feature exists before adding it to the manifest. 76 | 77 | ## Options 78 | 79 | All vcpkg commands support a set of [common options](common-options.md). 80 | 81 | ### port 82 | 83 | `vcpkg add port ...` adds the specified ports to the manifest if it's not already present. 84 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_cmake_install.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_cmake_install 3 | description: Use vcpkg_cmake_install to build and install a CMake project. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_cmake_install 7 | 8 | Build and install a CMake project. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_cmake_install( 14 | [DISABLE_PARALLEL] 15 | [ADD_BIN_TO_PATH] 16 | ) 17 | ``` 18 | 19 | To use this function, you must depend on the helper port `vcpkg-cmake`: 20 | 21 | ```json 22 | "dependencies": [ 23 | { 24 | "name": "vcpkg-cmake", 25 | "host": true 26 | } 27 | ] 28 | ``` 29 | 30 | ## Parameters 31 | 32 | ### DISABLE_PARALLEL 33 | 34 | Disables running the build in parallel. 35 | 36 | 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. 37 | 38 | ### ADD_BIN_TO_PATH 39 | 40 | Adds the configuration-specific `bin/` directory to the `PATH` during the build. 41 | 42 | 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). 43 | 44 | ## Examples 45 | 46 | ```cmake 47 | vcpkg_from_github(OUT_SOURCE_PATH source_path ...) 48 | vcpkg_cmake_configure(SOURCE_PATH "${source_path}") 49 | vcpkg_cmake_install() 50 | ``` 51 | 52 | [Search microsoft/vcpkg for examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_install+path%3A%2Fports) 53 | 54 | ## Remarks 55 | 56 | This command replaces [`vcpkg_install_cmake()`](vcpkg_install_cmake.md). 57 | 58 | ## Source 59 | 60 | [ports/vcpkg-cmake/vcpkg\_cmake\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_install.cmake) 61 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_fixup_pkgconfig.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_fixup_pkgconfig 3 | description: Learn how to use vcpkg_fixup_pkgconfig. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_fixup_pkgconfig 7 | 8 | Fix common paths in *.pc files and make everything relative to `$(prefix)`. 9 | 10 | Additionally, on static triplets, private entries are merged with their non-private counterparts, allowing pkg-config to be called without the ``--static`` flag. 11 | 12 | Since a consumer cannot know if a dependent library has been built statically or not, vcpkg is designed to never have to call pkg-config with the ``--static`` flag. 13 | 14 | ## Usage 15 | 16 | ```cmake 17 | vcpkg_fixup_pkgconfig( 18 | [RELEASE_FILES ...] 19 | [DEBUG_FILES ...] 20 | [SKIP_CHECK] 21 | ) 22 | ``` 23 | 24 | ## Parameters 25 | 26 | ### RELEASE_FILES 27 | 28 | 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/` 29 | 30 | ### DEBUG_FILES 31 | 32 | Specifies a list of files to apply the fixes for debug paths. Defaults to every *.pc file in the folder `${CURRENT_PACKAGES_DIR}/debug/` 33 | 34 | ### SKIP_CHECK 35 | 36 | Skips the library checks in `vcpkg_fixup_pkgconfig`. Only use if the script itself has unhandled cases. 37 | 38 | ### SYSTEM_PACKAGES (deprecated) 39 | 40 | > [!WARNING] 41 | > This argument has been deprecated and has no effect. 42 | 43 | ### SYSTEM_LIBRARIES (deprecated) 44 | 45 | > [!WARNING] 46 | > This argument has been deprecated and has no effect. 47 | 48 | ### IGNORE_FLAGS (deprecated) 49 | 50 | > [!WARNING] 51 | > This argument has been deprecated and has no effect. 52 | 53 | ## Notes 54 | 55 | Still a work in progress. If there are more cases which can be handled here feel free to add them. 56 | 57 | ## Examples 58 | 59 | - [brotli](https://github.com/Microsoft/vcpkg/blob/master/ports/brotli/portfile.cmake) 60 | 61 | ## Source 62 | 63 | [`scripts/cmake/vcpkg_fixup_pkgconfig.cmake`](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_pkgconfig.cmake) 64 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_build_make.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_build_make 3 | description: Use vcpkg_build_make to build a Makefile project. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_build_make 7 | 8 | Build a Makefile project. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_build_make([BUILD_TARGET ] 14 | [INSTALL_TARGET ] 15 | [ADD_BIN_TO_PATH] 16 | [ENABLE_INSTALL] 17 | [MAKEFILE ] 18 | [LOGFILE_ROOT ] 19 | [DISABLE_PARALLEL] 20 | [SUBPATH ]) 21 | ``` 22 | 23 | ### BUILD_TARGET 24 | 25 | The target passed to the make build command (`./make `). If not specified, the 'all' target will 26 | be passed. 27 | 28 | ### INSTALL_TARGET 29 | 30 | The target passed to the make build command (`./make `) if `ENABLE_INSTALL` is used. Defaults to 'install'. 31 | 32 | ### ADD_BIN_TO_PATH 33 | 34 | Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs. 35 | 36 | ### ENABLE_INSTALL 37 | 38 | If the port supports the `install` target, use [`vcpkg_install_make()`](vcpkg_install_make.md) instead. 39 | 40 | ### MAKEFILE 41 | 42 | Specifies the Makefile as a relative path from the root of the sources passed to [`vcpkg_configure_make()`](vcpkg_configure_make.md). 43 | 44 | ### LOGFILE_ROOT 45 | 46 | Specifies a log file prefix. 47 | 48 | ### DISABLE_PARALLEL 49 | 50 | The underlying buildsystem will be instructed to not parallelize. 51 | 52 | ### SUBPATH 53 | 54 | Additional subdirectory to invoke `make` in. Useful if only parts of a port should be built. 55 | 56 | ## Notes 57 | 58 | This command should be preceded by a call to [`vcpkg_configure_make()`](vcpkg_configure_make.md). 59 | 60 | You can use the alias [`vcpkg_install_make()`](vcpkg_install_make.md) function if your makefile supports the "install" target. 61 | 62 | ## Source 63 | 64 | [scripts/cmake/vcpkg\_build\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_make.cmake) 65 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_acquire_msys.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_acquire_msys 3 | description: Use vcpkg_acquire_msys to download and prepare an MSYS2 instance. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_acquire_msys 7 | 8 | Download and prepare an MSYS2 instance. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_acquire_msys( 14 | PACKAGES ... 15 | [NO_DEFAULT_PACKAGES] 16 | [DIRECT_PACKAGES ...] 17 | ) 18 | ``` 19 | 20 | ## Parameters 21 | 22 | ### MSYS_ROOT_VAR 23 | 24 | An out-variable that will be set to the path to MSYS2. 25 | 26 | ### PACKAGES 27 | 28 | A list of packages to acquire in msys. 29 | 30 | To ensure a package is available: `vcpkg_acquire_msys(MSYS_ROOT PACKAGES make automake1.16)` 31 | 32 | ### NO_DEFAULT_PACKAGES 33 | 34 | Exclude the normal base packages. 35 | 36 | The list of base packages includes: bash, coreutils, sed, grep, gawk, gzip, diffutils, make, and pkg-config 37 | 38 | ### DIRECT_PACKAGES 39 | 40 | A list of URL/SHA512 pairs to acquire in msys. 41 | 42 | This parameter can be used by a port to privately extend the list of msys packages to be acquired. 43 | The URLs can be found on the [msys2 website](https://packages.msys2.org/search) and should be a direct archive link: 44 | 45 | > `https://mirror.msys2.org/msys/x86_64/gettext-0.22.4-1-x86_64.pkg.tar.zst` 46 | 47 | ## Notes 48 | 49 | A call to `vcpkg_acquire_msys` will usually be followed by a call to `bash.exe`: 50 | 51 | ```cmake 52 | vcpkg_acquire_msys(MSYS_ROOT) 53 | set(BASH "${MSYS_ROOT}/usr/bin/bash.exe") 54 | 55 | vcpkg_execute_required_process( 56 | COMMAND "${BASH}" --noprofile --norc "${CMAKE_CURRENT_LIST_DIR}\\build.sh" 57 | WORKING_DIRECTORY "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel" 58 | LOGNAME "build-${TARGET_TRIPLET}-rel" 59 | ) 60 | ``` 61 | 62 | ## Examples 63 | 64 | - [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake) 65 | - [libvpx](https://github.com/Microsoft/vcpkg/blob/master/ports/libvpx/portfile.cmake) 66 | 67 | ## Source 68 | 69 | [scripts/cmake/vcpkg\_acquire\_msys.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_acquire_msys.cmake) 70 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_make_install.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_make_install 3 | description: Use vcpkg_make_install to build and install a Make-based project. 4 | ms.date: 01/31/2024 5 | --- 6 | # vcpkg_make_install 7 | 8 | Build and install a Make-based project. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_make_install( 14 | [DISABLE_PARALLEL] 15 | [LOGFILE_ROOT ] 16 | [MAKEFILE ] 17 | [TARGETS ...] 18 | [OPTIONS ...] 19 | [OPTIONS_RELEASE ...] 20 | [OPTIONS_DEBUG ...] 21 | ) 22 | ``` 23 | 24 | To use this function, you must depend on the helper port `vcpkg-make`: 25 | 26 | ```json 27 | "dependencies": [ 28 | { 29 | "name": "vcpkg-make", 30 | "host": true 31 | } 32 | ] 33 | ``` 34 | 35 | ## Parameters 36 | 37 | ### ADD_BIN_TO_PATH 38 | 39 | Adds the configure dependent `(debug/)bin` directory to the system path. This is useful if configure builds and runs executables with shared dependencies. 40 | 41 | ### DISABLE_PARALLEL 42 | 43 | By default, `vcpkg_make_install` runs make with the `-j` option to enable parallel building. If your project does not support parallel builds or you encounter issues with it, set this flag to disable parallel building. This causes `make` to be executed without the `-j` option, running build steps sequentially. 44 | 45 | ### LOGFILE_ROOT 46 | 47 | Specifies the base name for log files generated by the build. Defaults to "make". 48 | 49 | ### MAKEFILE 50 | 51 | Specifies the name of the makefile to use. Defaults to "Makefile". 52 | 53 | ### TARGETS 54 | 55 | Specifies the targets to pass to make. Defaults to "all;install". 56 | 57 | ### OPTIONS 58 | 59 | Additional options to pass to `make` during the build. 60 | 61 | ### OPTIONS_RELEASE 62 | 63 | Additional options to pass to `make` during the release build. 64 | 65 | ### OPTIONS_DEBUG 66 | 67 | Additional options to pass to `make` during the debug build. 68 | 69 | ## Examples 70 | 71 | ```cmake 72 | vcpkg_from_github(OUT_SOURCE_PATH source_path ...) 73 | vcpkg_make_configure(SOURCE_PATH "${source_path}") 74 | vcpkg_make_install() 75 | ``` 76 | 77 | ## Remarks 78 | 79 | This command replaces [`vcpkg_install_make()`](vcpkg_install_make.md). -------------------------------------------------------------------------------- /vcpkg/maintainers/handling-usage-files.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Provide usage documentation for your ports 3 | description: Guidance for adding usage documentation to vcpkg ports 4 | author: JavierMatosD 5 | ms.author: javiermat 6 | ms.date: 01/10/2024 7 | ms.topic: concept-article 8 | --- 9 | # Provide usage documentation for your ports 10 | 11 | ## Overview 12 | 13 | Providing usage documentation for ports allows users to easily adopt them in their 14 | projects. We highly encourage providing a `usage` file within the port's directory (`ports//usage`) that describes the minimal steps necessary to integrate with a build system. 16 | 17 | ### Supplying a usage file 18 | 19 | To provide usage documentation create a text file named `usage` in the port's `share` 20 | installation directory. The recommended method is to call the `file(INSTALL ...)` function in 21 | `portfile.cmake`. 22 | 23 | For example: 24 | 25 | ```cmake 26 | file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}") 27 | ``` 28 | 29 | After installing ports, vcpkg detects files installed to `${CURRENT_PACKAGES_DIR}/share/${PORT}/usage` and prints their usage instructions. 30 | 31 | ### Content format 32 | 33 | Provide clear instructions on how to use the package. The content should be concise, well-structured, and emphasize the minimum build system integration required to use the library. 34 | 35 | Be clear and concise about how to utilize the package effectively. Avoid 36 | overwhelming users with code snippets, command-line instructions, or 37 | configuration details. Instead, use the [`"documentation"` property in the 38 | port's `vcpkg.json` file](../concepts/manifest-mode.md) so users can learn more 39 | about your library. 40 | 41 | Use the following templates as a pattern for your `usage` files: 42 | 43 | Packages with CMake targets: 44 | 45 | ```text 46 | provides CMake targets: 47 | 48 | 49 | ``` 50 | 51 | Header-only libraries: 52 | 53 | ```text 54 | is header-only and can be used from CMake via: 55 | 56 | 57 | ``` 58 | 59 | #### Example of `usage` file 60 | 61 | ```text 62 | proj provides CMake targets: 63 | 64 | find_package(PROJ CONFIG REQUIRED) 65 | target_link_libraries(main PRIVATE PROJ::proj) 66 | ``` 67 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/z-learn-feedback-tool.yml: -------------------------------------------------------------------------------- 1 | name: Learn feedback control 2 | description: | 3 | ⛔ This template is hooked into the feedback control on the bottom of every page on the live site. It automatically fills in several fields for you. Don't use for other purposes. ⛔ 4 | body: 5 | - type: markdown 6 | attributes: 7 | value: "## Issue information" 8 | - type: markdown 9 | attributes: 10 | value: Select the issue type, and describe the issue in the text box below. Add as much detail as needed to help us resolve the issue. 11 | - type: dropdown 12 | id: issue-type 13 | attributes: 14 | label: Type of issue 15 | options: 16 | - Typo 17 | - Code doesn't work 18 | - Missing information 19 | - Outdated article 20 | - Other (describe below) 21 | validations: 22 | required: true 23 | - type: textarea 24 | id: feedback 25 | validations: 26 | required: true 27 | attributes: 28 | label: Description 29 | - type: markdown 30 | attributes: 31 | value: "## 🚧 Article information 🚧" 32 | - type: markdown 33 | attributes: 34 | value: "*Don't modify the following fields*. They are automatically filled in for you. Doing so will disconnect your issue from the affected article. *Don't edit them*." 35 | - type: input 36 | id: pageUrl 37 | validations: 38 | required: true 39 | attributes: 40 | label: Page URL 41 | - type: input 42 | id: contentSourceUrl 43 | validations: 44 | required: true 45 | attributes: 46 | label: Content source URL 47 | - type: input 48 | id: documentVersionIndependentId 49 | validations: 50 | required: true 51 | attributes: 52 | label: Document Version Independent Id 53 | - type: input 54 | id: platformId 55 | validations: 56 | required: true 57 | attributes: 58 | label: Platform Id 59 | - type: input 60 | id: author 61 | validations: 62 | required: true 63 | attributes: 64 | label: Article author 65 | - type: textarea 66 | id: metadata 67 | validations: 68 | required: false 69 | attributes: 70 | label: Metadata 71 | description: >- 72 | Documentation metadata will be applied here for the PRMerger tool 73 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_install_copyright.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_install_copyright 3 | description: Learn how to use vcpkg_install_copyright. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_install_copyright 7 | 8 | Merges multiple copyright files into a single file and install it. 9 | Installs a single copyright file. 10 | 11 | >[!NOTE] 12 | > The licensing information provided for each package in the vcpkg registry represents Microsoft's best understanding of the licensing requirements. However, this information may not be definitive. Users are advised to verify the exact licensing requirements for each package they intend to use, as it is ultimately their responsibility to ensure compliance with the applicable licenses. 13 | 14 | ## Usage 15 | 16 | ```cmake 17 | vcpkg_install_copyright(FILE_LIST ... [COMMENT]) 18 | ``` 19 | 20 | ## Parameters 21 | 22 | ### FILE_LIST 23 | 24 | Specifies a list of license files with absolute paths. You must provide at least one file. 25 | 26 | ### COMMENT 27 | 28 | This optional parameter adds a comment before at the top of the file. 29 | 30 | ## Notes 31 | 32 | This function creates a file called `copyright` inside `${CURRENT_PACKAGES_DIR}/share/${PORT}` 33 | 34 | If more than one file is provided, this function concatenates the contents of multiple copyright files to a single file. 35 | 36 | The resulting `copyright` file looks similar to this: 37 | 38 | ``` 39 | LICENSE-LGPL2.txt: 40 | 41 | Lorem ipsum dolor... 42 | 43 | LICENSE-MIT.txt: 44 | 45 | Lorem ipsum dolor sit amet... 46 | ``` 47 | 48 | Or with `COMMENT`: 49 | 50 | ``` 51 | A meaningful comment 52 | 53 | LICENSE-LGPL2.txt: 54 | 55 | Lorem ipsum dolor... 56 | 57 | LICENSE-MIT.txt: 58 | 59 | Lorem ipsum dolor sit amet... 60 | ``` 61 | 62 | ## Examples 63 | 64 | ```cmake 65 | vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE/license.md" "${SOURCE_PATH}/LICENSE/license_gpl.md" COMMENT "This is a comment") 66 | ``` 67 | 68 | You can also collect the required files using a `GLOB` pattern: 69 | 70 | ```cmake 71 | file(GLOB LICENSE_FILES "${SOURCE_PATH}/LICENSES/*") 72 | vcpkg_install_copyright(FILE_LIST ${LICENSE_FILES}) 73 | ``` 74 | 75 | ## Source 76 | 77 | [vcpkg_install_copyright.md](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_copyright.cmake) 78 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_cmake_build.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_cmake_build 3 | description: Use vcpkg_cmake_build to build a CMake project with a custom install target. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_cmake_build 7 | 8 | Build a cmake project with a custom install target. 9 | 10 | 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. 11 | 12 | Ports should prefer calling [`vcpkg_cmake_install()`](vcpkg_cmake_install.md) when possible. 13 | 14 | ## Usage 15 | 16 | ```cmake 17 | vcpkg_cmake_build( 18 | [TARGET ] 19 | [LOGFILE_BASE ] 20 | [DISABLE_PARALLEL] 21 | [ADD_BIN_TO_PATH] 22 | ) 23 | ``` 24 | 25 | To use this function, you must depend on the helper port `vcpkg-cmake`: 26 | 27 | ```json 28 | "dependencies": [ 29 | { 30 | "name": "vcpkg-cmake", 31 | "host": true 32 | } 33 | ] 34 | ``` 35 | 36 | ## Parameters 37 | 38 | All supported parameters to `vcpkg_cmake_install()` are supported by `vcpkg_cmake_build()`. For more information on its parameters, see [`vcpkg_cmake_install()`](vcpkg_cmake_install.md#parameters). 39 | 40 | ### TARGET 41 | 42 | The CMake target to build. 43 | 44 | If this parameter is not passed, no target will be passed to the build. 45 | 46 | ### LOGFILE_BASE 47 | 48 | An alternate root name for the logs. 49 | 50 | 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` 51 | 52 | ## Examples 53 | 54 | ```cmake 55 | vcpkg_from_github(OUT_SOURCE_PATH source_path ...) 56 | vcpkg_cmake_configure( 57 | SOURCE_PATH "${source_path}" 58 | OPTIONS 59 | -DBUILD_EXAMPLES=OFF 60 | -DBUILD_TESTS=OFF 61 | ) 62 | vcpkg_cmake_build(TARGET my.install.target) 63 | ``` 64 | 65 | [Search microsoft/vcpkg for Examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_build+path%3A%2Fports) 66 | 67 | ## Remarks 68 | 69 | This command replaces [`vcpkg_build_cmake()`](vcpkg_build_cmake.md). 70 | 71 | ## Source 72 | 73 | [ports/vcpkg-cmake/vcpkg\_cmake\_build.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_build.cmake) 74 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_download_sourceforge.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_download_sourceforge 3 | description: Learn how to use vcpkg_download_sourceforge. 4 | author: vicroms 5 | ms.author: viromer 6 | ms.date: 01/10/2024 7 | ms.topic: reference 8 | --- 9 | # vcpkg_download_sourceforge 10 | 11 | Download a file from a project in SourceForge. 12 | 13 | This function automatically checks a set of SourceForge mirrors. 14 | Additional mirrors can be injected through the `VCPKG_SOURCEFORGE_EXTRA_MIRRORS` 15 | list variable in the triplet. 16 | 17 | To use the file as source code, use [`vcpkg_from_sourceforge`](vcpkg_from_sourceforge.md) rather than this function plus 18 | `vcpkg_extract_source_archive`. 19 | 20 | ## Usage 21 | 22 | ```cmake 23 | vcpkg_download_sourceforge( 24 | 25 | REPO 26 | [REF <2.1-3>] 27 | SHA512 <547b417109332...> 28 | FILENAME 29 | ) 30 | ``` 31 | 32 | ## Parameters 33 | 34 | ### OUT_VARIABLE 35 | 36 | This variable will be set to the full path to the downloaded file. 37 | 38 | ### REPO 39 | 40 | The organization or user and repository (optional) on SourceForge. 41 | 42 | ### REF 43 | 44 | A stable version number that will not change contents. 45 | 46 | ### FILENAME 47 | 48 | The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly 49 | attributed to this port and avoid conflicts. 50 | 51 | For example, we can get the download link: 52 | https://sourceforge.net/settings/mirror_choices?projectname=mad&filename=libmad/0.15.1b/libmad-0.15.1b.tar.gz&selected=nchc 53 | So the REPO is `mad/libmad`, the REF is `0.15.1b`, and the FILENAME is `libmad-0.15.1b.tar.gz` 54 | 55 | For some special links: 56 | https://sourceforge.net/settings/mirror_choices?projectname=soxr&filename=soxr-0.1.3-Source.tar.xz&selected=nchc 57 | The REPO is `soxr`, REF is empty, and the FILENAME is `soxr-0.1.3-Source.tar.xz` 58 | 59 | ### SHA512 60 | 61 | The SHA512 hash that should match the archive. 62 | 63 | This is most easily determined by first setting it to `0`, then trying to build the port. The error message will 64 | contain the full hash, which can be copied back into the portfile. 65 | 66 | ## Source 67 | 68 | [scripts/cmake/vcpkg\_download\_sourceforge.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_sourceforge.cmake) 69 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_qmake_configure.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_qmake_configure 3 | description: Learn how to use vcpkg_qmake_configure. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_qmake_configure 7 | 8 | Configure a qmake-based project. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_qmake_configure( 14 | SOURCE_PATH 15 | [QMAKE_OPTIONS arg1 [arg2 ...]] 16 | [QMAKE_OPTIONS_RELEASE arg1 [arg2 ...]] 17 | [QMAKE_OPTIONS_DEBUG arg1 [arg2 ...]] 18 | [OPTIONS arg1 [arg2 ...]] 19 | [OPTIONS_RELEASE arg1 [arg2 ...]] 20 | [OPTIONS_DEBUG arg1 [arg2 ...]] 21 | ) 22 | ``` 23 | 24 | To use this function, you must depend on the helper port `vcpkg-qmake`: 25 | 26 | ```json 27 | "dependencies": [ 28 | { 29 | "name": "vcpkg-qmake", 30 | "host": true 31 | } 32 | ] 33 | ``` 34 | 35 | ## Parameters 36 | 37 | ### SOURCE_PATH 38 | 39 | The path to the *.pro qmake project file. 40 | 41 | ### QMAKE_OPTIONS, QMAKE_OPTIONS_RELEASE, QMAKE_OPTIONS_DEBUG 42 | 43 | Additional options to pass to qmake before `--`. 44 | 45 | Typically, these should have the form QMAKE_X=_\_ or CONFIG=_\_ 46 | 47 | ### OPTIONS, OPTIONS_RELEASE, OPTIONS_DEBUG 48 | 49 | Additional options to pass to qmake after `--`. 50 | 51 | ## Triplet Parameters 52 | 53 | ### VCPKG_OSX_DEPLOYMENT_TARGET 54 | 55 | Determines `QMAKE_MACOSX_DEPLOYMENT_TARGET` 56 | 57 | ### VCPKG_QMAKE_COMMAND 58 | 59 | Path to qmake. 60 | 61 | Defaults to `"${CURRENT_HOST_INSTALLED_DIR}/tools/Qt6/bin/qmake${VCPKG_HOST_EXECUTABLE_SUFFIX}"`. 62 | 63 | ### VCPKG_QT_CONF_RELEASE 64 | 65 | Path to the `qt.config` being used for release mode. 66 | 67 | Defaults to `"${CURRENT_INSTALLED_DIR}/tools/Qt6/qt_release.conf"`. 68 | 69 | ### VCPKG_QT_CONF_DEBUG 70 | 71 | Path to the `qt.config` being used for debug mode. 72 | 73 | Defaults to `"${CURRENT_INSTALLED_DIR}/tools/Qt6/qt_debug.conf"` 74 | 75 | ### VCPKG_QT_TARGET_MKSPEC 76 | 77 | _Added in `vcpkg-qmake` version `2022-11-16`_. 78 | 79 | Qt mkspec to use 80 | 81 | ### VCPKG_QMAKE_OPTIONS_RELEASE 82 | 83 | Extra options to pass to `qmake` in release mode. 84 | 85 | ### VCPKG_QMAKE_OPTIONS_DEBUG 86 | 87 | Extra options to pass to `qmake` in debug mode. 88 | 89 | ## Source 90 | 91 | [ports/vcpkg-qmake/vcpkg\_qmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-qmake/vcpkg_qmake_configure.cmake) 92 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_from_bitbucket.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_from_bitbucket 3 | description: Learn how to use vcpkg_from_bitbucket. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_from_bitbucket 7 | 8 | Download and extract a project from Bitbucket. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_from_bitbucket( 14 | OUT_SOURCE_PATH 15 | REPO 16 | [REF ] 17 | [SHA512 <45d0d7f8cc350...>] 18 | [HEAD_REF ] 19 | [PATCHES ...] 20 | ) 21 | ``` 22 | 23 | ## Parameters 24 | 25 | ### OUT_SOURCE_PATH 26 | 27 | Specifies the out-variable that will contain the extracted location. 28 | 29 | This should be set to `SOURCE_PATH` by convention. 30 | 31 | ### REPO 32 | 33 | The organization or user and repository on Bitbucket. 34 | 35 | ### REF 36 | 37 | A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.** 38 | 39 | For repositories without official releases, this can be set to the full commit id of the current latest master. `vcpkg_from_bitbucket()` will download a stable snapshot of the commit without any history information at `https://bitbucket.com//get/.tar.gz`. 40 | 41 | If `REF` is specified, `SHA512` must also be specified. 42 | 43 | ### SHA512 44 | 45 | The SHA512 hash of the source archive. 46 | 47 | 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. 48 | 49 | ### HEAD_REF 50 | 51 | The unstable git commit-ish (ideally a branch) to pull for `--head` builds. 52 | 53 | For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms. 54 | 55 | ### PATCHES 56 | 57 | A list of patches to be applied to the extracted sources. 58 | 59 | Relative paths are based on the port directory. 60 | 61 | ## Notes 62 | 63 | At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present. 64 | 65 | This exports the `VCPKG_HEAD_VERSION` variable during head builds. 66 | 67 | ## Examples 68 | 69 | - [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake) 70 | 71 | ## Source 72 | 73 | [scripts/cmake/vcpkg\_from\_bitbucket.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_bitbucket.cmake) 74 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_build_msbuild.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_build_msbuild 3 | description: Use vcpkg_build_msbuild to build an MSBuild-based project. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_build_msbuild 7 | 8 | > [!WARNING] 9 | > This function has been deprecated in favor of [`vcpkg_msbuild_install`](vcpkg_msbuild_install.md). 10 | 11 | Builds a MSBuild project. 12 | 13 | ## Usage 14 | 15 | ```cmake 16 | vcpkg_build_msbuild( 17 | PROJECT_PATH <${SOURCE_PATH}/port.sln> 18 | [RELEASE_CONFIGURATION ] 19 | [DEBUG_CONFIGURATION ] 20 | [TARGET ] 21 | [TARGET_PLATFORM_VERSION <10.0.15063.0>] 22 | [PLATFORM ] 23 | [PLATFORM_TOOLSET ] 24 | [OPTIONS ...] 25 | [OPTIONS_RELEASE ...] 26 | [OPTIONS_DEBUG ...] 27 | [USE_VCPKG_INTEGRATION] 28 | ) 29 | ``` 30 | 31 | ## Parameters 32 | 33 | ### USE_VCPKG_INTEGRATION 34 | 35 | Apply the normal `integrate install` integration for building the project. 36 | 37 | By default, projects built with this command will not automatically link libraries or have header paths set. 38 | 39 | ### PROJECT_PATH 40 | 41 | The path to the solution (`.sln`) or project (`.vcxproj`) file. 42 | 43 | ### RELEASE_CONFIGURATION 44 | 45 | The configuration (`/p:Configuration` msbuild parameter) used for Release builds. 46 | 47 | ### DEBUG_CONFIGURATION 48 | 49 | The configuration (`/p:Configuration` msbuild parameter) used for Debug builds. 50 | 51 | ### TARGET_PLATFORM_VERSION 52 | 53 | The WindowsTargetPlatformVersion (`/p:WindowsTargetPlatformVersion` msbuild parameter). 54 | 55 | ### TARGET 56 | 57 | The MSBuild target to build (`/t:`). 58 | 59 | ### PLATFORM 60 | 61 | The platform (`/p:Platform` msbuild parameter) used for the build. 62 | 63 | See the [`vcpkg_install_msbuild()` documentation](vcpkg_install_msbuild.md#platform) for this parameter. 64 | 65 | ### PLATFORM_TOOLSET 66 | 67 | The platform toolset (`/p:PlatformToolset` msbuild parameter) used for the build. 68 | 69 | ### OPTIONS 70 | 71 | Additional options passed to msbuild for all builds. 72 | 73 | ### OPTIONS_RELEASE 74 | 75 | Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`. 76 | 77 | ### OPTIONS_DEBUG 78 | 79 | Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`. 80 | 81 | ## Source 82 | 83 | [scripts/cmake/vcpkg\_build\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake) 84 | -------------------------------------------------------------------------------- /vcpkg/commands/edit.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg edit 3 | description: Command-line reference for the vcpkg edit command. Opens a port's contents in a text editor window. 4 | author: vicroms 5 | ms.author: viromer 6 | ms.date: 01/10/2024 7 | --- 8 | # vcpkg edit 9 | 10 | ## Synopsis 11 | 12 | ```Console 13 | vcpkg edit [--all] [--buildtrees] [options] 14 | ``` 15 | 16 | ## Examples 17 | 18 | ### Open multiple ports 19 | 20 | ```Console 21 | vcpkg edit fmt zlib 22 | ``` 23 | 24 | ### Open related folders 25 | 26 | ```Console 27 | vcpkg install fmt 28 | vcpkg edit fmt --all 29 | ``` 30 | 31 | ## Description 32 | 33 | Opens a port for editing in a text editor window (defaults to Visual Studio Code). 34 | 35 | If multiple port names are provided, all ports are opened in the same window. 36 | This command does not work with ports from external registries. Only ports from the built-in 37 | registry can be opened. 38 | 39 | The `--buildtrees` option opens the package's `buildtrees` folder instead of the port's contents. 40 | The `--all` option also opens the port's related `packages` and `buildtrees` folders in the same window. 41 | 42 | By default, vcpkg will search for Visual Studio Code in well-known installation paths. 43 | Set the `EDITOR` environment variable to specify a text editor program to use. 44 | 45 | On Windows, vcpkg searches for a Visual Studio Code or Visual Studio Code Insiders installation in: 46 | 47 | * the `%ProgramFiles%` and `%ProgramFiles(x86)%` folders 48 | * the `%APPDATA%\Local\Programs` folder 49 | * the Windows Registry 50 | 51 | On Linux, vcpkg searches for the Visual Studio Code executable in: 52 | 53 | * `/usr/bin/code` 54 | * `/usr/share/code/bin/code` 55 | 56 | On MacOS, vcpkg searches for a Visual Studio Code or Visual Studio Code Insiders installation in the `Applications` folder. 57 | 58 | If Visual Studio Code is not found, vcpkg attempts to use the default text editor configured for 59 | your system. 60 | 61 | ## Options 62 | 63 | All vcpkg commands support a set of [common options](common-options.md). 64 | 65 | ### `--all` 66 | 67 | Opens the port's related `buildtrees` and `packages` folders. 68 | 69 | ### `--buildtrees` 70 | 71 | Opens the port's `buildtrees` folder instead of the port's contents. The `buildtrees` folder 72 | is created during the installation process and contains the package's extracted source code and log files. 73 | 74 | Use in combination with the `vcpkg install --editable ` command to get a clean copy of the 75 | package's source code suitable for debugging and creating patch files. 76 | -------------------------------------------------------------------------------- /vcpkg/commands/upgrade.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg upgrade 3 | description: Command line reference for the vcpkg upgrade command. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg upgrade 7 | 8 | ## Synopsis 9 | 10 | ```console 11 | vcpkg upgrade [options] 12 | ``` 13 | 14 | ## Description 15 | 16 | Removes and reinstalls [Classic mode] packages that have different current available versions. 17 | 18 | > [!WARNING] 19 | > This command does not save the previous install state. If an error occurs while building replacement packages, the previous set of packages will not be restored. 20 | > 21 | > For robust version management, use [Manifest mode]. 22 | 23 | By default, `upgrade` prints the plan of what will be modified. Pass [`--no-dry-run`](#no-dry-run) to perform that plan. 24 | 25 | ## Example 26 | 27 | ```console 28 | $ vcpkg upgrade 29 | The following packages will be rebuilt: 30 | * corrade[core,interconnect,pluginmanager,testsuite,utility]:x64-windows -> 2020.06#5 31 | * magnum[al-info,anyaudioimporter,anyimageconverter,anyimageimporter,anysceneconverter,anysceneimporter,anyshaderconverter,audio,cglcontext,core,debugtools,distancefieldconverter,eglcontext,fontconverter,gl,gl-info,glfwapplication,glxcontext,imageconverter,magnumfont,magnumfontconverter,meshtools,objimporter,opengltester,primitives,sceneconverter,scenegraph,sdl2application,shaderconverter,shaders,shadertools,text,texturetools,tgaimageconverter,tgaimporter,trade,wglcontext,windowlesscglapplication,windowlesseglapplication,windowlessglxapplication,windowlesswglapplication]:x64-windows -> 2020.06#12 32 | * openal-soft[core]:x64-windows -> 1.23.0 33 | * ragel[core]:x64-windows -> 6.10#5 34 | * sdl2[base,core]:x64-windows -> 2.26.4 35 | Additional packages (*) will be modified to complete this operation. 36 | If you are sure you want to rebuild the above packages, run this command with the --no-dry-run option. 37 | ``` 38 | 39 | ## Options 40 | 41 | All vcpkg commands support a set of [common options](common-options.md). 42 | 43 | ### `--no-dry-run` 44 | 45 | Removes the packages that are outdated and reinstalls them at the versions listed in the user's local copy of the public vcpkg registry. 46 | 47 | ### `--no-keep-going` 48 | 49 | Stop at the first failure. 50 | 51 | By default, on a package install failure, vcpkg will continue to attempt to install other unrelated packages. 52 | 53 | ### `--allow-unsupported` 54 | 55 | Allow performing upgrades to unsupported packages. 56 | 57 | [Classic mode]: ../concepts/classic-mode.md 58 | [Manifest mode]: ../concepts/manifest-mode.md 59 | -------------------------------------------------------------------------------- /vcpkg/concepts/asset-caching.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Asset caching with vcpkg 3 | description: Use asset caching with vcpkg to mirror your downloaded artifacts, reduce external network reliance and improve build reliability. 4 | author: vicroms 5 | ms.author: viromer 6 | ms.topic: concept-article 7 | ms.date: 03/20/2025 8 | --- 9 | # Asset caching with vcpkg 10 | 11 | [!INCLUDE [experimental](../../includes/experimental.md)] 12 | 13 | A fundamental operation of vcpkg is downloading files from the Internet, such as source code archives, tool executables, 14 | and source code patches. These files, referred to as **assets**, are obtained through simple file transfers over a network. 15 | Each asset has a known SHA512 hash, to check for integrity, before the download begins. 16 | 17 | Asset caching enables you to set up mirror locations, known as caches, to retrieve these assets. If enabled, vcpkg first 18 | tries to fetch assets from known caches. If the asset is unavailable, vcpkg falls back to the original download source. 19 | Additionally, vcpkg can save the asset to the cache for future use. 20 | 21 | The primary goal of asset caching is to minimize reliance on external networks, offering several advantages: 22 | 23 | * **Reduced download times and bandwidth usage**: By retrieving assets from a local or nearby cache, builds complete 24 | faster and consume less network bandwidth. 25 | * **Support for air-gapped or offline environments**: Assets can be mirrored in trusted locations, enabling builds in 26 | environments without internet access. 27 | * **Improved reliability and continuity**: Ensures access to critical assets even if third-party hosts modify or remove 28 | them, reducing the risk of disruptions. 29 | 30 | ## Configuration 31 | 32 | Asset caching is configured via: 33 | 34 | * The `X_VCPKG_ASSET_SOURCES` environment variable, or 35 | * The `--x-asset-sources` command-line option. 36 | 37 | In both cases, the expected value is a semicolon-delimited list of sources. Each source has a specific syntax depending 38 | on its storage backend. See the [asset caching reference documentation](../users/assetcaching.md) to learn how to 39 | configure asset caching sources. 40 | 41 | ### Example using Azure Blob Storage 42 | 43 | ```PowerShell 44 | vcpkg install zlib --x-asset-sources="clear;x-azurl,mystorageaccount.blob.core.windows.net,${SAS_TOKEN},readwrite;x-azurl,file:///Z:/vcpkg-cache/assets,,readwrite" 45 | ``` 46 | 47 | ## Next step 48 | 49 | Here are some tasks to try next: 50 | 51 | * [Set up an asset cache](../consume/asset-caching.md) 52 | * [Use a custom script as an asset caching source](../examples/asset-caching-source-nuget.md) 53 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_from_git.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_from_git 3 | description: Learn how to use vcpkg_from_git. 4 | author: vicroms 5 | ms.author: viromer 6 | ms.topic: reference 7 | ms.date: 01/10/2024 8 | --- 9 | # vcpkg_from_git 10 | 11 | Download and extract a project from git. 12 | 13 | This helper reuses `git` CLI credentials. See [Authentication](../../users/authentication.md) to 14 | configure credentials for your private git hosts. 15 | 16 | If the git repo is hosted on BitBucket, on GitHub, or in GitLab, their specific functions should 17 | be used rather than this function: 18 | 19 | * [`vcpkg_from_bitbucket`](vcpkg_from_bitbucket.md) 20 | * [`vcpkg_from_github`](vcpkg_from_github.md) 21 | * [`vcpkg_from_gitlab`](vcpkg_from_gitlab.md) 22 | 23 | ## Usage 24 | 25 | ```cmake 26 | vcpkg_from_git( 27 | OUT_SOURCE_PATH 28 | URL 29 | REF <59f7335e4d...> 30 | [HEAD_REF ] 31 | [PATCHES ...] 32 | [LFS []] 33 | ) 34 | ``` 35 | 36 | ## Parameters 37 | 38 | ### OUT_SOURCE_PATH 39 | 40 | Specifies the out-variable that will contain the extracted location. 41 | 42 | This should be set to `SOURCE_PATH` by convention. 43 | 44 | ### URL 45 | 46 | The url of the git repository. 47 | 48 | ### REF 49 | 50 | The git sha of the commit to download. 51 | 52 | ### FETCH_REF 53 | 54 | The git branch to fetch in non-HEAD mode. After this is fetched, 55 | then `REF` is checked out. This is useful in cases where the git server 56 | does not allow checking out non-advertised objects. 57 | 58 | ### HEAD_REF 59 | 60 | The git branch to use when the package is requested to be built from the latest sources. 61 | 62 | Example: `main`, `develop`, `HEAD` 63 | 64 | ### PATCHES 65 | 66 | A list of patches to be applied to the extracted sources. 67 | 68 | Relative paths are based on the port directory. 69 | 70 | ### LFS 71 | 72 | _Added in vcpkg version 2022.11.14_ 73 | 74 | Enable fetching files stored using Git LFS. 75 | Only files pointed to by `REF` are fetched. 76 | 77 | This makes Git LFS mandatory for the port. 78 | It's a fatal error if the extension is not installed. 79 | 80 | _Added in vcpkg version 2023.01.23_ 81 | 82 | If specified, `` will be used instead of the original git URL for LFS. 83 | 84 | ## Notes 85 | 86 | `OUT_SOURCE_PATH`, `REF`, and `URL` must be specified. 87 | 88 | ## Examples 89 | 90 | - [fdlibm](https://github.com/Microsoft/vcpkg/blob/master/ports/fdlibm/portfile.cmake) 91 | 92 | ## Source 93 | 94 | [scripts/cmake/vcpkg\_from\_git.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_git.cmake) 95 | -------------------------------------------------------------------------------- /vcpkg/consume/binary-caching-default.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Default local vcpkg binary cache" 3 | description: Learn about the default vcpkg binary cache 4 | author: vicroms 5 | ms.author: viromer 6 | ms.date: 5/1/2024 7 | ms.topic: concept-article 8 | zone_pivot_group_filename: zone-pivot-groups.json 9 | zone_pivot_groups: shell-selections 10 | --- 11 | # Default local vcpkg binary cache 12 | 13 | By default, vcpkg creates a local binary cache. This saves time when installing a package that has been previously installed in the same machine. 14 | 15 | The location of the default binary cache depends on your operating system. 16 | 17 | ::: zone pivot="shell-cmd, shell-powershell" 18 | 19 | By default, binary caching is enabled at the first valid location among the following: 20 | 21 | * The location specified by the `VCPKG_DEFAULT_BINARY_CACHE` environment variable 22 | * `%LOCALAPPDATA%\vcpkg\archives` 23 | * `%APPDATA%\vcpkg\archives` 24 | 25 | ::: zone-end 26 | 27 | ::: zone pivot="shell-bash" 28 | 29 | By default, binary caching is enabled at the first valid location among the following: 30 | 31 | * The location specified by the `VCPKG_DEFAULT_BINARY_CACHE` environment variable 32 | * `$XDG_CACHE_HOME/vcpkg/archives` 33 | * `$HOME/.cache/vcpkg/archives` 34 | 35 | ::: zone-end 36 | 37 | Use the `VCPKG_DEFAULT_BINARY_CACHE` environment variable to change the default binary cache 38 | location. 39 | 40 | The default binary cache uses a [`files` provider](../reference/binarycaching.md#files). This 41 | type of binary cache provider stores binary packages as compressed archives in a filesystem 42 | directory. 43 | 44 | ## Disabling the default binary cache 45 | 46 | To disable the default binary cache, set the [`VCPKG_BINARY_SOURCES` environment 47 | variable](../reference/binarycaching.md#configuration-syntax) to `clear`. 48 | 49 | ::: zone pivot="shell-powershell" 50 | 51 | ```PowerShell 52 | $env:VCPKG_BINARY_SOURCES="clear" 53 | ``` 54 | 55 | ::: zone-end 56 | ::: zone pivot="shell-cmd" 57 | 58 | ```console 59 | set VCPKG_BINARY_SOURCES=clear 60 | ``` 61 | 62 | ::: zone-end 63 | ::: zone pivot="shell-bash" 64 | 65 | ```bash 66 | export VCPKG_BINARY_SOURCES=clear 67 | ``` 68 | 69 | ::: zone-end 70 | 71 | ## Next steps 72 | 73 | > [!div class="nextstepaction"] 74 | > [Set up a local binary cache](binary-caching-local.md) 75 | 76 | Here are other tasks to try next: 77 | 78 | * [Change the default binary cache location](binary-caching-default.md) 79 | * [Set up a local binary cache](binary-caching-local.md) 80 | * [Set up a binary cache using a NuGet feed](binary-caching-nuget.md) 81 | * [Set up a binary cache in your GitHub Actions workflow using GitHub Packages](binary-caching-github-packages.md) 82 | -------------------------------------------------------------------------------- /vcpkg/examples/packaging-github-repos.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Packaging libogg for vcpkg 3 | description: Learn how to package the libogg GitHub repo in vcpkg. 4 | ms.date: 01/10/2024 5 | ms.topic: tutorial 6 | --- 7 | # Packaging GitHub repos example: libogg 8 | 9 | ## Create the manifest file 10 | 11 | The manifest file (called `vcpkg.json`) is a json file describing the package's metadata. 12 | 13 | For libogg, we'll create the file `ports/libogg/vcpkg.json` with the following content: 14 | 15 | ```json 16 | { 17 | "name": "libogg", 18 | "version-string": "1.3.3", 19 | "description": "Ogg is a multimedia container format, and the native file and stream format for the Xiph.org multimedia codecs.", 20 | "homepage": "https://www.xiph.org/ogg/" 21 | } 22 | ``` 23 | 24 | You can format the manifest file to our specifications with `vcpkg format-manifest ports/libogg/vcpkg.json`. 25 | 26 | ## Create the portfile 27 | 28 | `portfile.cmake` describes how to build and install the package. First we download the project from Github with [`vcpkg_from_github`](../maintainers/functions/vcpkg_from_github.md): 29 | 30 | ```cmake 31 | vcpkg_from_github( 32 | OUT_SOURCE_PATH SOURCE_PATH 33 | REPO xiph/ogg 34 | REF v1.3.3 35 | SHA512 0bd6095d647530d4cb1f509eb5e99965a25cc3dd9b8125b93abd6b248255c890cf20710154bdec40568478eb5c4cde724abfb2eff1f3a04e63acef0fbbc9799b 36 | HEAD_REF master 37 | ) 38 | ``` 39 | 40 | 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). 41 | 42 | Finally, we configure the project with CMake, install the package, and copy over the license file: 43 | 44 | ```cmake 45 | vcpkg_cmake_configure(SOURCE_PATH ${SOURCE_PATH}) 46 | vcpkg_cmake_install() 47 | vcpkg_install_copyright("${SOURCE_PATH}/COPYING") 48 | ``` 49 | 50 | Check the documentation for [`vcpkg_cmake_configure`](../maintainers/functions/vcpkg_cmake_configure.md) and [`vcpkg_cmake_install`](../maintainers/functions/vcpkg_cmake_install.md) if your package needs additional options. 51 | 52 | Now you can run `vcpkg install libogg` to build and install the package. 53 | 54 | ## Suggested example portfiles 55 | 56 | In the [`ports/`](https://github.com/Microsoft/vcpkg/tree/master/ports) directory are many libraries that can be used as examples, including many that are not based on CMake. 57 | 58 | - Header only libraries 59 | - rapidjson 60 | - range-v3 61 | - MSBuild-based 62 | - chakracore 63 | - Non-CMake, custom buildsystem 64 | - openssl 65 | - ffmpeg 66 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_fixup_cmake_targets.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_fixup_cmake_targets 3 | description: Learn how to use vcpkg_fixup_cmake_targets. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_fixup_cmake_targets 7 | 8 | > [!WARNING] 9 | > This function has been deprecated in favor of [`vcpkg_cmake_config_fixup`](vcpkg_cmake_config_fixup.md). 10 | 11 | Merge release and debug CMake targets and configs to support multiconfig generators. 12 | 13 | Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries. 14 | 15 | ## Usage 16 | 17 | ```cmake 18 | vcpkg_fixup_cmake_targets([CONFIG_PATH ] 19 | [TARGET_PATH ] 20 | [TOOLS_PATH ] 21 | [DO_NOT_DELETE_PARENT_CONFIG_PATH]) 22 | ``` 23 | 24 | ## Parameters 25 | 26 | ### CONFIG_PATH 27 | 28 | Subpath currently containing `*.cmake` files subdirectory (like `lib/cmake/${PORT}`). Should be relative to `${CURRENT_PACKAGES_DIR}`. 29 | 30 | Defaults to `share/${PORT}`. 31 | 32 | ### TARGET_PATH 33 | 34 | Subpath to which the above `*.cmake` files should be moved. Should be relative to `${CURRENT_PACKAGES_DIR}`. 35 | This needs to be specified if the port name differs from the `find_package()` name. 36 | 37 | Defaults to `share/${PORT}`. 38 | 39 | ### DO_NOT_DELETE_PARENT_CONFIG_PATH 40 | 41 | By default the parent directory of CONFIG_PATH is removed if it is named "cmake". 42 | Passing this option disable such behavior, as it is convenient for ports that install 43 | more than one CMake package configuration file. 44 | 45 | ### NO_PREFIX_CORRECTION 46 | 47 | Disables the correction of_IMPORT_PREFIX done by vcpkg due to moving the targets. 48 | Currently the correction does not take into account how the files are moved and applies 49 | I rather simply correction which in some cases will yield the wrong results. 50 | 51 | ### TOOLS_PATH 52 | 53 | Define the base path to tools. Default: `tools/` 54 | 55 | ## Notes 56 | 57 | Transform all `/debug//*targets-debug.cmake` files and move them to `/`. 58 | Removes all `/debug//*targets.cmake` and `/debug//*config.cmake`. 59 | 60 | Transform all references matching `/bin/*.exe` to `/${TOOLS_PATH}/*.exe` on Windows. 61 | Transform all references matching `/bin/*` to `/${TOOLS_PATH}/*` on other platforms. 62 | 63 | Fix `${_IMPORT_PREFIX}` in auto generated targets to be one folder deeper. 64 | Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targets. 65 | 66 | ## Source 67 | 68 | [scripts/cmake/vcpkg\_fixup\_cmake\_targets.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake) 69 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_execute_required_process.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_execute_required_process 3 | description: Execute a process with logging and fail the build if the command fails. 4 | ms.date: 06/27/2024 5 | --- 6 | # vcpkg_execute_required_process 7 | 8 | Execute a process with logging and fail the build if the command fails. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_execute_required_process( 14 | COMMAND <${PERL}> [...] 15 | WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg> 16 | LOGNAME 17 | [TIMEOUT ] 18 | [OUTPUT_VARIABLE ] 19 | [ERROR_VARIABLE ] 20 | [SAVE_LOG_FILES [ [ALIAS ]]...] 21 | ) 22 | ``` 23 | 24 | ## Parameters 25 | 26 | ### ALLOW_IN_DOWNLOAD_MODE 27 | 28 | Allows the command to execute in Download Mode. 29 | 30 | ### COMMAND 31 | 32 | The command to be executed, along with its arguments. 33 | 34 | ### WORKING_DIRECTORY 35 | 36 | The directory to execute the command in. 37 | 38 | ### LOGNAME 39 | 40 | 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. 41 | 42 | ### TIMEOUT 43 | 44 | Optional timeout after which to terminate the command. 45 | 46 | ### OUTPUT_VARIABLE 47 | 48 | Optional variable to receive stdout of the command. 49 | 50 | ### OUTPUT_STRIP_TRAILING_WHITESPACE 51 | 52 | Removes trailing whitespace before setting `OUTPUT_VARIABLE`. 53 | 54 | ### ERROR_VARIABLE 55 | 56 | Optional variable to receive stderr of the command. 57 | 58 | ### ERROR_STRIP_TRAILING_WHITESPACE 59 | 60 | Removes trailing whitespace before setting `ERROR_VARIABLE`. 61 | 62 | ### SAVE_LOG_FILES 63 | 64 | Optional files to be moved from the working directory to `${CURRENT_BUILDTREES_DIR}`. 65 | 66 | This helps to collect relevant log files in CI setups. The files are copied even if the process failed. 67 | The target file names are constructed from the `LOGNAME` parameter and the source filename. 68 | If the target file name doesn't end in `.log`, this suffix is appended. 69 | 70 | _Added in vcpkg version 2023.01.10_ 71 | 72 | The `ALIAS` parameter after a relative path name replaces the target file name generation with the value of ``. 73 | 74 | ## Examples 75 | 76 | - [boost-build](https://github.com/Microsoft/vcpkg/blob/master/ports/boost-build/portfile.cmake) 77 | - [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake) 78 | - [vcpkg-cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_configure.cmake) 79 | 80 | ## Source 81 | 82 | [scripts/cmake/vcpkg\_execute\_required\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake) 83 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_from_gitlab.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_from_gitlab 3 | description: Learn how to use vcpkg_from_gitlab. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_from_gitlab 7 | 8 | Download and extract a project from Gitlab instances. Enables support for `install --head`. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_from_gitlab( 14 | GITLAB_URL 15 | OUT_SOURCE_PATH 16 | REPO 17 | [REF ] 18 | [SHA512 <45d0d7f8cc350...>] 19 | [HEAD_REF ] 20 | [PATCHES ...] 21 | [AUTHORIZATION_TOKEN <${SECRET_FROM_FILE}>] 22 | [FILE_DISAMBIGUATOR ] 23 | ) 24 | ``` 25 | 26 | ## Parameters 27 | 28 | ### GITLAB_URL 29 | 30 | The URL of the Gitlab instance to use. 31 | 32 | ### OUT_SOURCE_PATH 33 | 34 | Specifies the out-variable that will contain the extracted location. 35 | 36 | This should be set to `SOURCE_PATH` by convention. 37 | 38 | ### REPO 39 | 40 | The organization or user plus the repository name on the Gitlab instance. 41 | 42 | ### REF 43 | 44 | A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.** 45 | 46 | For repositories without official releases, this can be set to the full commit id of the current latest master. 47 | 48 | If `REF` is specified, `SHA512` must also be specified. 49 | 50 | ### SHA512 51 | 52 | The SHA512 hash that should match the archive (${GITLAB_URL}/${REPO}/-/archive/${REF}/${REPO_NAME}-${REF}.tar.gz). 53 | The REPO_NAME variable is parsed from the value of REPO. 54 | 55 | 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. 56 | 57 | ### HEAD_REF 58 | 59 | The unstable git commit-ish (ideally a branch) to pull for `--head` builds. 60 | 61 | For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms. 62 | 63 | ### PATCHES 64 | 65 | A list of patches to be applied to the extracted sources. 66 | 67 | Relative paths are based on the port directory. 68 | 69 | ### AUTHORIZATION_TOKEN 70 | 71 | A token to be passed via the Authorization HTTP header "PRIVATE-TOKEN". 72 | 73 | ### FILE_DISAMBIGUATOR 74 | 75 | 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. 76 | 77 | ## Notes 78 | 79 | At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present. 80 | 81 | This exports the `VCPKG_HEAD_VERSION` variable during head builds. 82 | 83 | ## Source 84 | 85 | [scripts/cmake/vcpkg\_from\_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake) 86 | -------------------------------------------------------------------------------- /vcpkg/consume/binary-caching-overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "What is binary caching?" 3 | description: Learn what is a vcpkg binary cache and why you should be using one. 4 | author: vicroms 5 | ms.author: viromer 6 | ms.date: 07/30/2024 7 | ms.topic: concept-article 8 | #CustomerIntent: As a beginner vcpkg user, I want to learn what is binary caching and why should I use it 9 | --- 10 | # What is binary caching? 11 | 12 | Binary caching is a feature that lets vcpkg save the compiled files of a package in a shared 13 | location and reuse them when asked to build the same package with the same configuration. We call 14 | the output produced by each package build a "binary package". 15 | 16 | ## Why use binary caching? 17 | 18 | Most ports in the [vcpkg curated registry]() are built from 19 | source. Building from source ensures maximum compatibility by using the same environment, build tools, 20 | and configurations you use for your project in your dependencies. However, this can also 21 | result in duplicated builds when multiple projects, developers, or machines require the same 22 | dependencies. 23 | 24 | Binary caches can be hosted in a variety of environments. The most basic form of binary caching is a 25 | directory that holds zipped archives of a package's build output. More advanced scenarios include 26 | NuGet package feeds hosted in [GitHub Packages](), [Azure 27 | DevOps 28 | Artifacts](/azure/devops/artifacts/start-using-azure-artifacts?view=azure-devops&tabs=nuget&preserve-view=true), 29 | or other such services. 30 | 31 | Binary caching is especially effective in scenarios where dependencies and configuration 32 | don't change often, such as in CI (Continuous Integration) or build servers. Binary packages are 33 | particularly susceptible to configuration changes (compiler version, compilation flags, installed 34 | tools, or vcpkg-specific script changes) which makes sharing them between developer machines 35 | difficult. See [`vcpkg export`](../commands/export.md) for a different option to share built 36 | packages. 37 | 38 | See the [binary caching reference documentation](../reference/binarycaching.md) to learn about 39 | the different [storage backends](../reference/binarycaching.md#providers). 40 | 41 | ## Next steps 42 | 43 | > [!div class="nextstepaction"] 44 | > [Set up a local binary cache](binary-caching-local.md) 45 | 46 | Here are other tasks to try next: 47 | 48 | * [Change the default binary cache location](binary-caching-default.md) 49 | * [Set up a local binary cache](binary-caching-local.md) 50 | * [Set up a binary cache using a NuGet feed](binary-caching-nuget.md) 51 | * [Set up a binary cache in your GitHub Actions workflow using GitHub Packages](binary-caching-github-packages.md) 52 | * [Authenticate to private NuGet feeds](../reference/binarycaching.md#nuget-credentials) 53 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Security 4 | 5 | Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). 6 | 7 | If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below. 8 | 9 | ## Reporting Security Issues 10 | 11 | **Please do not report security vulnerabilities through public GitHub issues.** 12 | 13 | Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report). 14 | 15 | If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey). 16 | 17 | You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). 18 | 19 | Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: 20 | 21 | * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) 22 | * Full paths of source file(s) related to the manifestation of the issue 23 | * The location of the affected source code (tag/branch/commit or direct URL) 24 | * Any special configuration required to reproduce the issue 25 | * Step-by-step instructions to reproduce the issue 26 | * Proof-of-concept or exploit code (if possible) 27 | * Impact of the issue, including how an attacker might exploit the issue 28 | 29 | This information will help us triage your report more quickly. 30 | 31 | If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs. 32 | 33 | ## Preferred Languages 34 | 35 | We prefer all communications to be in English. 36 | 37 | ## Policy 38 | 39 | Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd). 40 | 41 | 42 | -------------------------------------------------------------------------------- /vcpkg/concepts/build-system-integration.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Build system integration 3 | description: This article explains the different mechanisms vcpkg uses to integrate with build systems. 4 | author: vicroms 5 | ms.author: viromer 6 | ms.date: 06/03/2024 7 | ms.topic: concept-article 8 | --- 9 | # Build system integration 10 | 11 | vcpkg integrates seamlessly with MSBuild and CMake to restore your project's 12 | dependencies at build time. vcpkg also makes it easy to integrate with other 13 | build systems by providing a standard installation layout. 14 | 15 | ## MSBuild integration 16 | 17 | vcpkg provides user-wide MSBuild integration via the 18 | [`vcpkg integrate install`](../commands/integrate.md#vcpkg-integrate-install) 19 | command and per-project integration via the `vcpkg.props` and `vcpkg.target` 20 | files. 21 | 22 | When you enable this integration, all MSBuild and Visual Studio projects will automatically link their dependencies. 23 | 24 | Read more about how this integration works in the [MSBuild integration 25 | documentation](../users/buildsystems/msbuild-integration.md). 26 | 27 | Visual Studio MSBuild projects also support vcpkg. See [Tutorial: Install and use packages with MSBuild in Visual Studio](../get_started/get-started-msbuild.md) to get started. 28 | 29 | ## CMake integration 30 | 31 | vcpkg provides seamless `find_package()` integration for your projects via a 32 | custom toolchain file. You can enable this integration by adding the provided 33 | toolchain file in `/scripts/buildsystems/vcpkg.cmake` in your CMake 34 | configure calls via `CMAKE_TOOLCHAIN_FILE` or with a `CMakePresets.json` file. 35 | 36 | Once this integration is activated, functions like `find_package()`, `find_library()`, and `find_path()` will automatically search through the vcpkg installation directories to find the required dependencies. Furthermore, vcpkg is also able to install your dependencies 37 | declared in a manifest file automatically. 38 | 39 | Read more about how this integration works in the [CMake integration 40 | documentation](../users/buildsystems/cmake-integration.md). 41 | 42 | Several IDEs/editors with CMake support also explicitly support vcpkg. See the corresponding documentation articles for more information: 43 | 44 | - [Tutorial: Install and use packages with CMake in Visual Studio](../get_started/get-started-vs.md) 45 | - [Tutorial: Install and use packages with CMake in Visual Studio Code](../get_started/get-started-vscode.md) 46 | - [CLion vcpkg integration](https://www.jetbrains.com/help/clion/package-management.html) 47 | 48 | ## Manual integration 49 | 50 | You can also use vcpkg with other build systems generically using the standard [installation layout](../reference/installation-tree-layout.md) vcpkg provides. 51 | 52 | Read more about how to integrate vcpkg with your build system using [manual 53 | integration](../users/buildsystems/manual-integration.md). 54 | -------------------------------------------------------------------------------- /vcpkg/commands/add-version.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg x-add-version 3 | description: Reference for the vcpkg x-add-version command. Update version database of vcpkg ports. 4 | author: JavierMatosD 5 | ms.author: javiermat 6 | ms.date: 01/10/2024 7 | --- 8 | 9 | # vcpkg x-add-version 10 | 11 | [!INCLUDE [experimental](../../includes/experimental.md)] 12 | 13 | ## Synopsis 14 | 15 | ```console 16 | vcpkg x-add-version [port-name] [options] [--all] [--overwrite-version] [--skip-formatting-check] [--skip-version-format-check] [--verbose] 17 | ``` 18 | 19 | ## Description 20 | 21 | The `x-add-version` command updates the [version database](../users/versioning.concepts.md#acquiring-port-versions) for vcpkg ports. By default, it operates on a specified port. With the appropriate switches, users can choose to process all ports or change the default behavior regarding formatting checks and version updates. 22 | 23 | To use the command: 24 | 25 | 1. After making changes to a port, navigate to the vcpkg directory. 26 | 1. Run `vcpkg x-add-version `, replacing `` with the name of the port you've edited. 27 | 28 | This will add or update the version entry for your port in the version database. 29 | 30 | > [!NOTE] 31 | > The hash used in the version database is computed from the complete file contents of the port. Any untracked files in the port directory will affect the resulting hash. Users should ensure that any files they do not intend to track are removed before invoking this command. 32 | 33 | ## Options 34 | 35 | All vcpkg commands support a set of [common options](common-options.md). 36 | 37 | ### `[port-name]` 38 | 39 | Specifies the name of the port to be updated. If not provided, the user should use the `--all` option to process all ports. 40 | 41 | ### `--all` 42 | 43 | Process all the ports in the [built-in](../concepts/registries.md#built-in-registry) `ports` directory. 44 | 45 | ### `--overwrite-version` 46 | 47 | Allows overwriting an existing version in the database. 48 | 49 | Without this flag, vcpkg will refuse to overwrite existing versions. 50 | 51 | > [!NOTE] 52 | > This option is designed for ongoing development when preparing a version for registry inclusion. For example, consider addressing an issue in the `foo` port and executing `vcpkg x-add-version foo`. For subsequent modifications to the port, utilize `vcpkg x-add-version foo --overwrite-version` to refresh the version entry prior to registry inclusion. 53 | 54 | ### `--skip-formatting-check` 55 | 56 | Skips the check for proper formatting in the manifest file (`vcpkg.json`) of the port. By default, proper formatting is checked and required. 57 | 58 | ### `--skip-version-format-check` 59 | 60 | Skips the version format check. By default, versions are checked to ensure they adhere to a specific [format](../users/versioning.md#version-schemes). 61 | 62 | ### `--verbose` 63 | 64 | Provides verbose output, giving more details about the operations being carried out. 65 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_list.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_list 3 | description: A replacement for CMake's list function which improves handling of elements with internal semicolons, such as other lists. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_list 7 | 8 | A replacement for CMake's `list()` function which improves handling of elements with internal semicolons, such as other lists. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_list(SET [...]) 14 | vcpkg_list( [...]) 15 | ``` 16 | 17 | ## Notes 18 | 19 | Use `vcpkg_list()` instead of `list()` whenever it is a requirement to correctly handle lists of lists. 20 | 21 | `vcpkg_list()` supports all the subcommands of the built-in `list()` function, with the following restrictions: 22 | 23 | - `GET`, `REMOVE_ITEM`, and `REMOVE_AT` support only one index/value 24 | - `POP_BACK` and `POP_FRONT` do not support getting the value into 25 | another out variable. Use C++ style `GET` then `POP_(BACK|FRONT)`. 26 | - `FILTER` and `TRANSFORM` are unsupported. 27 | 28 | `vcpkg_list` also adds a `vcpkg_list(SET)` subcommand. This subcommand supports correctly creating a list of lists. 29 | 30 | See the [CMake documentation for `list()`](https://cmake.org/cmake/help/latest/command/list.html) for more information. 31 | 32 | ### Remarks on Zero-Element lists 33 | 34 | The most major weirdness is due to `""` pulling double-duty as "list of zero elements", 35 | and "list of one element, which is empty". `vcpkg_list` always uses the former understanding. 36 | This can cause weird behavior, for example: 37 | 38 | ```cmake 39 | set(lst "") 40 | vcpkg_list(APPEND lst "" "") 41 | # lst = ";" 42 | ``` 43 | 44 | This is because you're appending two elements to the empty list. 45 | One very weird behavior that comes out of this would be: 46 | 47 | ```cmake 48 | set(lst "") 49 | vcpkg_list(APPEND lst "") 50 | # lst = "" 51 | ``` 52 | 53 | since `""` is the empty list, we append the empty element and end up with a list 54 | of one element, which is empty. This does not happen for non-empty lists; 55 | for example: 56 | 57 | ```cmake 58 | set(lst "a") 59 | vcpkg_list(APPEND lst "") 60 | # lst = "a;" 61 | ``` 62 | 63 | only the empty list has this odd behavior. 64 | 65 | ## Examples 66 | 67 | ### Creating a list 68 | 69 | ```cmake 70 | vcpkg_list(SET foo_param) 71 | if(DEFINED arg_FOO) 72 | vcpkg_list(SET foo_param FOO "${arg_FOO}") 73 | endif() 74 | ``` 75 | 76 | ### Appending to a list 77 | 78 | ```cmake 79 | set(OPTIONS -DFOO=BAR) 80 | if(VCPKG_TARGET_IS_WINDOWS) 81 | vcpkg_list(APPEND OPTIONS "-DOS=WINDOWS;FOO") 82 | endif() 83 | ``` 84 | 85 | ### Popping the end off a list 86 | 87 | ```cmake 88 | if(NOT list STREQUAL "") 89 | vcpkg_list(GET list end -1) 90 | vcpkg_list(POP_BACK list) 91 | endif() 92 | ``` 93 | 94 | ## Source 95 | 96 | [scripts/cmake/vcpkg\_list.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_list.cmake) 97 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_install_nmake.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_install_nmake 3 | description: Learn how to use vcpkg_install_nmake. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_install_nmake 7 | 8 | Build and install a msvc makefile project. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_install_nmake( 14 | SOURCE_PATH <${SOURCE_PATH}> 15 | [PROJECT_SUBPATH <${SUBPATH}>] 16 | [PROJECT_NAME <${MAKEFILE_NAME}>] 17 | [CL_LANGUAGE ] 18 | [PREFER_JOM] 19 | [PRERUN_SHELL <${SHELL_PATH}>] 20 | [PRERUN_SHELL_DEBUG <${SHELL_PATH}>] 21 | [PRERUN_SHELL_RELEASE <${SHELL_PATH}>] 22 | [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] 23 | [OPTIONS_RELEASE <-DOPTIMIZE=1>...] 24 | [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] 25 | [TARGET ...] 26 | ) 27 | ``` 28 | 29 | ## Parameters 30 | 31 | ### SOURCE_PATH 32 | 33 | Specifies the directory containing the source files. 34 | By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. 35 | 36 | ### PROJECT_SUBPATH 37 | 38 | Specifies the sub directory containing the makefile. 39 | 40 | ### PROJECT_NAME 41 | 42 | Specifies the name of the makefile. 43 | Default is `makefile.vc` 44 | 45 | ### CL_LANGUAGE 46 | 47 | Specifies the language for setting up flags in the `_CL_` environment variable. 48 | The default language is `CXX`. 49 | To disable the modification of `_CL_`, use `NONE`. 50 | 51 | ### PREFER_JOM 52 | 53 | Specifies that a parallel build with `jom` should be attempted. 54 | This is useful for faster builds of makefiles which process many independent targets 55 | and which cannot benefit from the `/MP` cl option. 56 | To mitigate issues with concurrency-unaware makefiles, a normal `nmake` build is run after `jom` errors. 57 | 58 | ### PRERUN_SHELL 59 | 60 | Script that needs to be called before build. 61 | 62 | ### PRERUN_SHELL_DEBUG 63 | 64 | Script that needs to be called before debug build. 65 | 66 | ### PRERUN_SHELL_RELEASE 67 | 68 | Script that needs to be called before release build. 69 | 70 | ### OPTIONS 71 | 72 | Additional options passed to the build command. 73 | 74 | ### OPTIONS_RELEASE 75 | 76 | Additional options passed to the build command for the release build. These are in addition to `OPTIONS`. 77 | 78 | ### OPTIONS_DEBUG 79 | 80 | Additional options passed to the build command for the debug build. These are in addition to `OPTIONS`. 81 | 82 | ### TARGET 83 | 84 | The list of targets passed to the build command. 85 | If not specified, target `all` will be passed. 86 | 87 | ## Notes 88 | 89 | This command transparently forwards to [`vcpkg_build_nmake()`](vcpkg_build_nmake.md), adding `ENABLE_INSTALL`. 90 | 91 | ## Examples 92 | 93 | - [libspatialite](https://github.com/microsoft/vcpkg/blob/master/ports/libspatialite/portfile.cmake) 94 | - [tcl](https://github.com/microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake) 95 | 96 | ## Source 97 | 98 | [scripts/cmake/vcpkg\_install\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_nmake.cmake) 99 | -------------------------------------------------------------------------------- /vcpkg/users/examples/selecting-llvm-features.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Selecting LLVM Features 3 | description: Learn how to customize the llvm package with features in vcpkg. 4 | ms.date: 01/10/2024 5 | ms.topic: concept-article 6 | --- 7 | # Selecting LLVM features 8 | 9 | ## Installing a library 10 | 11 | We will look at [llvm](https://llvm.org/) as an example. You could install it using: 12 | 13 | ```powershell 14 | > vcpkg install llvm 15 | ``` 16 | 17 | or via a manifest with: 18 | 19 | ```json 20 | { 21 | "dependencies": ["llvm"] 22 | } 23 | ``` 24 | 25 | With llvm now installed, we can execute: 26 | 27 | ```powershell 28 | > installed\x86-windows\bin\llc.exe --version 29 | ``` 30 | 31 | We see: 32 | 33 | ```powershell 34 | Registered Targets: 35 | x86 - 32-bit X86: Pentium-Pro and above 36 | x86-64 - 64-bit X86: EM64T and AMD64 37 | ``` 38 | 39 | ## Installing additional features 40 | 41 | But [llvm supports many more targets](https://llvm.org/docs/GettingStarted.html#local-llvm-configuration), from ARM to SPARC to SystemZ. 42 | However, clearly our current installation doesn't include ARM as a target; 43 | thus, we need to learn how vcpkg allows us to install other LLVM targets. 44 | The llvm port allows this via the "target-*" features. 45 | 46 | If we do: 47 | 48 | ```powershell 49 | > vcpkg search llvm 50 | ``` 51 | 52 | We can see: 53 | 54 | ```powershell 55 | llvm 10.0.0#6 The LLVM Compiler Infrastructure 56 | llvm[clang] Build C Language Family Front-end. 57 | llvm[clang-tools-extra] Build Clang tools. 58 | ... 59 | llvm[target-all] Build with all backends. 60 | llvm[target-amdgpu] Build with AMDGPU backend. 61 | llvm[target-arm] Build with ARM backend. 62 | ... 63 | ``` 64 | 65 | We can install any of these targets by using the install-feature syntax: 66 | 67 | ```powershell 68 | > vcpkg install llvm[target-arm] # Installs LLVM with the ARM target 69 | ``` 70 | 71 | ```json 72 | { 73 | "dependencies": [{ "name": "llvm", "features": ["target-arm"] }] 74 | } 75 | ``` 76 | 77 | ## Opting out of default features 78 | 79 | The llvm port includes a few default features that you as a user may not want: for example, 80 | the `clang` feature is default, which means that `vcpkg install llvm` will also build and install clang. 81 | If you are writing a compiler that uses LLVM as a backend, 82 | you're likely not interested in installing clang as well, 83 | and we can do that by disabling default features with the special `core` "feature": 84 | 85 | ```powershell 86 | > vcpkg install llvm[core,target-arm] # removing the default-feature with "core" also removes all of the default targets you get 87 | ``` 88 | 89 | or in manifest files: 90 | 91 | ```json 92 | { 93 | "dependencies": [{ 94 | "name": "llvm", 95 | "default-features": false, 96 | "features": ["target-arm"] 97 | }] 98 | } 99 | ``` 100 | -------------------------------------------------------------------------------- /vcpkg/commands/integrate.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg integrate 3 | description: Command line reference for the vcpkg integrate command. Integrate vcpkg with shells and buildsystems. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg integrate 7 | 8 | ## Synopsis 9 | 10 | - **Build system integration** 11 | 12 | ```console 13 | vcpkg integrate [options] install 14 | vcpkg integrate [options] remove 15 | vcpkg integrate [options] project 16 | ``` 17 | 18 | - **Shell integration** 19 | 20 | ```console 21 | vcpkg integrate [options] powershell 22 | vcpkg integrate [options] bash 23 | vcpkg integrate [options] zsh 24 | vcpkg integrate [options] x-fish 25 | ``` 26 | 27 | ## Description 28 | 29 | Integrate vcpkg with shells and buildsystems. 30 | 31 | ### `vcpkg integrate install` 32 | 33 | 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. 34 | 35 | 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. 36 | 37 | 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: 38 | 39 | - `%LOCALAPPDATA%\vcpkg` or `%APPDATA%\Local\vcpkg` on Windows 40 | - `$HOME/.vcpkg` or `/var/.vcpkg` on non-Windows 41 | 42 | 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. 43 | 44 | ### `vcpkg integrate remove` 45 | 46 | Removes the user-wide vcpkg instance setting. 47 | 48 | This command deletes the linking files from the user-wide configuration location created by `vcpkg integrate install`. 49 | 50 | ### `vcpkg integrate project` 51 | 52 | Creates a linked NuGet package for MSBuild integration. 53 | 54 | See [MSBuild Per-Project Integration](../users/buildsystems/msbuild-integration.md#linked-nuget-package) for more information. 55 | 56 | ### `vcpkg integrate powershell` 57 | 58 | - **Windows only** 59 | 60 | Adds vcpkg tab-completion support to the current user's Powershell profile. 61 | 62 | ### `vcpkg integrate bash` 63 | 64 | - **Non-Windows only** 65 | 66 | Adds vcpkg tab-completion support to the current user's `.bashrc` (`.bash_profile` on MacOS). 67 | 68 | ### `vcpkg integrate zsh` 69 | 70 | - **Non-Windows only** 71 | 72 | Adds vcpkg tab-completion support to the current user's `.zshrc`. 73 | 74 | ### `vcpkg integrate x-fish` 75 | 76 | - **Non-Windows only** 77 | 78 | Adds vcpkg tab-completion support to the current user's fish shell completions directory. 79 | 80 | ## Example 81 | 82 | ```console 83 | $ vcpkg integrate install 84 | Applied user-wide integration for this vcpkg root. 85 | 86 | CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=/workspaces/vcpkg/scripts/buildsystems/vcpkg.cmake" 87 | ``` 88 | 89 | ## Options 90 | 91 | All vcpkg commands support a set of [common options](common-options.md). 92 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_cmake_config_fixup.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_cmake_config_fixup 3 | description: Use vcpkg_cmake_config_fixup to support multiconfig generators. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_cmake_config_fixup 7 | 8 | Merge and correct Release and Debug CMake targets and configs to support multiconfig generators. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_cmake_config_fixup( 14 | [PACKAGE_NAME ] 15 | [CONFIG_PATH ] 16 | [TOOLS_PATH ] 17 | [DO_NOT_DELETE_PARENT_CONFIG_PATH] 18 | [NO_PREFIX_CORRECTION] 19 | ) 20 | ``` 21 | 22 | To use this function, you must depend on the helper port `vcpkg-cmake-config`: 23 | 24 | ```json 25 | "dependencies": [ 26 | { 27 | "name": "vcpkg-cmake-config", 28 | "host": true 29 | } 30 | ] 31 | ``` 32 | 33 | Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries. 34 | 35 | For many ports, `vcpkg_cmake_config_fixup()` on its own should work, 36 | as `PACKAGE_NAME` defaults to `${PORT}` and `CONFIG_PATH` defaults to `share/${PACKAGE_NAME}`. 37 | For ports where the package name passed to `find_package` is distinct from the port name, 38 | `PACKAGE_NAME` should be changed to be that name instead. 39 | For ports where the directory of the `*config.cmake` files cannot be set, 40 | use the `CONFIG_PATH` to change the directory where the files come from. 41 | 42 | By default the parent directory of `CONFIG_PATH` is removed if it is named "cmake". 43 | Passing the `DO_NOT_DELETE_PARENT_CONFIG_PATH` option disables such behavior, 44 | as it is convenient for ports that install 45 | more than one CMake package configuration file. 46 | 47 | The `NO_PREFIX_CORRECTION` option disables the correction of `_IMPORT_PREFIX` 48 | done by vcpkg due to moving the config files. 49 | Currently the correction does not take into account how the files are moved, 50 | and applies a rather simply correction which in some cases will yield the wrong results. 51 | 52 | ## How it works 53 | 54 | 1. Moves `/debug//*targets-debug.cmake` to `/share/${PACKAGE_NAME}`. 55 | 1. Transforms all references matching `/bin/*.exe` to `/${TOOLS_PATH}/*.exe` on Windows. 56 | 1. Transforms all references matching `/bin/*` to `/${TOOLS_PATH}/*` on other platforms. 57 | 1. Fixes `${_IMPORT_PREFIX}` in auto generated targets. 58 | 1. Replaces `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs. 59 | 1. Merges `INTERFACE_LINK_LIBRARIES` of release and debug configurations. 60 | 1. Replaces `${CURRENT_INSTALLED_DIR}` with `${VCPKG_IMPORT_PREFIX}` in targets. 61 | 1. Removes `/debug//*config.cmake`. 62 | 63 | ## Examples 64 | 65 | - [concurrentqueue](https://github.com/Microsoft/vcpkg/blob/master/ports/concurrentqueue/portfile.cmake) 66 | - [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake) 67 | - [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake) 68 | 69 | ## Source 70 | 71 | [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) 72 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_from_sourceforge.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_from_sourceforge 3 | description: Learn how to use vcpkg_from_sourceforge. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_from_sourceforge 7 | 8 | Download and extract an archive from a project from SourceForge. 9 | 10 | This function automatically checks a set of SourceForge mirrors. 11 | Additional mirrors can be injected through the `VCPKG_SOURCEFORGE_EXTRA_MIRRORS` 12 | list variable in the triplet. 13 | 14 | ## Usage 15 | 16 | ```cmake 17 | vcpkg_from_sourceforge( 18 | OUT_SOURCE_PATH SOURCE_PATH 19 | REPO 20 | [REF <2.1-3>] 21 | SHA512 <547b417109332...> 22 | FILENAME 23 | [NO_REMOVE_ONE_LEVEL] 24 | [PATCHES ...] 25 | ) 26 | ``` 27 | 28 | ## Parameters 29 | 30 | ### OUT_SOURCE_PATH 31 | 32 | Specifies the out-variable that will contain the extracted location. 33 | 34 | This should be set to `SOURCE_PATH` by convention. 35 | 36 | ### REPO 37 | 38 | The organization or user and repository (optional) on SourceForge. 39 | 40 | ### REF 41 | 42 | A stable version number that will not change contents. 43 | 44 | ### FILENAME 45 | 46 | The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly 47 | attributed to this port and avoid conflicts. 48 | 49 | For example, we can get the download link: 50 | https://sourceforge.net/settings/mirror_choices?projectname=mad&filename=libmad/0.15.1b/libmad-0.15.1b.tar.gz&selected=nchc 51 | So the REPO is `mad/libmad`, the REF is `0.15.1b`, and the FILENAME is `libmad-0.15.1b.tar.gz` 52 | 53 | For some special links: 54 | https://sourceforge.net/settings/mirror_choices?projectname=soxr&filename=soxr-0.1.3-Source.tar.xz&selected=nchc 55 | The REPO is `soxr`, REF is not exist, and the FILENAME is `soxr-0.1.3-Source.tar.xz` 56 | 57 | ### SHA512 58 | 59 | The SHA512 hash that should match the archive. 60 | 61 | This is most easily determined by first setting it to `0`, then trying to build the port. The error message will 62 | contain the full hash, which can be copied back into the portfile. 63 | 64 | ### WORKING_DIRECTORY 65 | 66 | If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`. 67 | 68 | The archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`). 69 | 70 | ### PATCHES 71 | 72 | A list of patches to be applied to the extracted sources. 73 | 74 | Relative paths are based on the port directory. 75 | 76 | ### NO_REMOVE_ONE_LEVEL 77 | 78 | Specifies that the default removal of the top level folder should not occur. 79 | 80 | ## Examples 81 | 82 | - [cunit](https://github.com/Microsoft/vcpkg/blob/master/ports/cunit/portfile.cmake) 83 | - [polyclipping](https://github.com/Microsoft/vcpkg/blob/master/ports/polyclipping/portfile.cmake) 84 | - [tinyfiledialogs](https://github.com/Microsoft/vcpkg/blob/master/ports/tinyfiledialogs/portfile.cmake) 85 | 86 | ## Source 87 | 88 | [scripts/cmake/vcpkg\_from\_sourceforge.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_sourceforge.cmake) 89 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_configure_cmake.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_configure_cmake 3 | description: Use vcpkg_configure_cmake to configure a CMake project. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_configure_cmake 7 | 8 | > [!WARNING] 9 | > This function has been deprecated in favor of [`vcpkg_cmake_configure`](vcpkg_cmake_configure.md). 10 | 11 | Configure CMake for Debug and Release builds of a project. 12 | 13 | ## Usage 14 | 15 | ```cmake 16 | vcpkg_configure_cmake( 17 | SOURCE_PATH <${SOURCE_PATH}> 18 | [PREFER_NINJA] 19 | [DISABLE_PARALLEL_CONFIGURE] 20 | [NO_CHARSET_FLAG] 21 | [GENERATOR <"NMake Makefiles">] 22 | [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] 23 | [OPTIONS_RELEASE <-DOPTIMIZE=1>...] 24 | [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] 25 | [MAYBE_UNUSED_VARIABLES ...] 26 | ) 27 | ``` 28 | 29 | ## Parameters 30 | 31 | ### SOURCE_PATH 32 | 33 | Specifies the directory containing the `CMakeLists.txt`. 34 | By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. 35 | 36 | ### PREFER_NINJA 37 | 38 | Indicates that, when available, vcpkg should use Ninja to perform the build. 39 | This should be specified unless the port is known to not work under Ninja. 40 | 41 | ### DISABLE_PARALLEL_CONFIGURE 42 | 43 | Disables running the CMake configure step in parallel. 44 | This is needed for libraries which write back into their source directory during configure. 45 | 46 | This also disables CMAKE_DISABLE_SOURCE_CHANGES. 47 | 48 | ### NO_CHARSET_FLAG 49 | 50 | Disables passing `utf-8` as the default character set to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`. 51 | 52 | This is needed for libraries that set their own source code's character set. 53 | 54 | ### GENERATOR 55 | 56 | Specifies the precise generator to use. 57 | 58 | This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build. 59 | If used for this purpose, it should be set to `"NMake Makefiles"`. 60 | 61 | ### OPTIONS 62 | 63 | Additional options passed to CMake during the configuration. 64 | 65 | ### OPTIONS_RELEASE 66 | 67 | Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`. 68 | 69 | ### OPTIONS_DEBUG 70 | 71 | Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`. 72 | 73 | ### MAYBE_UNUSED_VARIABLES 74 | 75 | Any CMake variables which are explicitly passed in, but which may not be used on all platforms. 76 | For example: 77 | 78 | ```cmake 79 | vcpkg_cmake_configure( 80 | ... 81 | OPTIONS 82 | -DBUILD_EXAMPLE=OFF 83 | ... 84 | MAYBE_UNUSED_VARIABLES 85 | BUILD_EXAMPLE 86 | ) 87 | ``` 88 | 89 | ### LOGNAME 90 | 91 | Name of the log to write the output of the configure call to. 92 | 93 | ## Notes 94 | 95 | This command supplies many common arguments to CMake. To see the full list, examine the source. 96 | 97 | ## Source 98 | 99 | [scripts/cmake/vcpkg\_configure\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_cmake.cmake) 100 | -------------------------------------------------------------------------------- /vcpkg/consume/binary-caching-github-actions-cache.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Tutorial: Set up a vcpkg binary cache using GitHub Actions Cache" 3 | description: This tutorial shows how to set up a vcpkg binary cache using a NuGet feed hosted using GitHub Actions Cache 4 | author: vicroms 5 | ms.author: viromer 6 | ms.topic: tutorial 7 | ms.date: 05/01/2025 8 | #CustomerIntent: As a vcpkg user, I want to setup binary caching in my GitHub Actions workflow using GitHub Packages as the binary cache storage 9 | ROBOTS: NOINDEX 10 | --- 11 | # Tutorial: Set up a vcpkg binary cache using GitHub Actions Cache 12 | 13 | > [!CAUTION] 14 | > The GitHub Actions Cache backend for binary caching has been removed. This tutorial is no longer maintained. 15 | > For more information and migration guidance, please see [GitHub Pull Request #1662](). 16 | 17 | [!INCLUDE [experimental](../../includes/experimental.md)] 18 | 19 | vcpkg supports using the GitHub Actions cache as binary caching storage when running in the context of 20 | a GitHub Actions workflow. If you don't care about uploading binary packages to an external NuGet 21 | feed, this is the recommended method to use binary caching in a GitHub Actions workflow. Otherwise, 22 | read the [tutorial to use GitHub Packages in a GitHub Actions 23 | workflow](binary-caching-github-packages.md). 24 | 25 | In this tutorial, you'll learn how to: 26 | 27 | > [!div class="checklist"] 28 | > 29 | > * [Export required GitHub Actions environment variables](#1---export-required-github-actions-environment-variables) 30 | > * [Configure vcpkg to use the GitHub Actions 31 | > cache](#2---configure-vcpkg-to-use-the-github-actions-cache) 32 | 33 | ## Prerequisites 34 | 35 | * A code editor 36 | * A GitHub repository using GitHub Actions 37 | * A project using vcpkg 38 | 39 | ## 1 - Export required GitHub Actions environment variables 40 | 41 | vcpkg needs the Actions Cache URL and Runtime Token to be exported as environment variables 42 | available in your workflow. Copy the following step in your workflow file: 43 | 44 | ```YAML 45 | - name: Export GitHub Actions cache environment variables 46 | uses: actions/github-script@v7 47 | with: 48 | script: | 49 | core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || ''); 50 | core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || ''); 51 | ``` 52 | 53 | ## 2 - Configure vcpkg to use the GitHub Actions cache 54 | 55 | Next set the value of `VCPKG_BINARY_SOURCES` as follows: 56 | 57 | ```YAML 58 | env: 59 | VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite" 60 | ``` 61 | 62 | And that's it! vcpkg will now upload or restore packages from your GitHub Actions cache. 63 | 64 | ## Next steps 65 | 66 | > [!div class="nextstepaction"] 67 | > [Authenticate to private NuGet feeds](../reference/binarycaching.md#nuget-credentials) 68 | 69 | Here are other tasks to try next: 70 | 71 | * [Change the default binary cache location](binary-caching-default.md) 72 | * [Set up a local binary cache](binary-caching-local.md) 73 | * [Set up a binary cache using a NuGet feed](binary-caching-nuget.md) 74 | * [Set up a binary cache in your GitHub Actions workflow using GitHub Packages](binary-caching-github-packages.md) 75 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_download_distfile.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_download_distfile 3 | description: Learn how to use vcpkg_download_distfile. 4 | author: vicroms 5 | ms.author: viromer 6 | ms.topic: reference 7 | ms.date: 01/10/2024 8 | --- 9 | # vcpkg_download_distfile 10 | 11 | Download and cache a file needed for this port. 12 | 13 | This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command, as it 14 | enables features like [Asset Caching](../../users/assetcaching.md). 15 | 16 | If possible, one of the `vcpkg_from_` functions should be used rather than calling this function 17 | directly, such as one of the following: 18 | 19 | * [`vcpkg_from_bitbucket`](vcpkg_from_bitbucket.md) 20 | * [`vcpkg_from_git`](vcpkg_from_git.md) 21 | * [`vcpkg_from_github`](vcpkg_from_github.md) 22 | * [`vcpkg_from_gitlab`](vcpkg_from_gitlab.md) 23 | * [`vcpkg_from_sourceforge`](vcpkg_from_sourceforge.md) 24 | 25 | ## Usage 26 | 27 | ```cmake 28 | vcpkg_download_distfile( 29 | 30 | URLS ... 31 | FILENAME 32 | SHA512 <5981de...> 33 | [ALWAYS_REDOWNLOAD] 34 | ) 35 | ``` 36 | 37 | ## Parameters 38 | 39 | ### out-var 40 | 41 | The name of the out variable to be set with the full path to the downloaded file. 42 | 43 | This variable can then immediately be passed to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) 44 | for sources. 45 | 46 | Conventionally, `ARCHIVE` is used as the out variable name. 47 | 48 | ```cmake 49 | vcpkg_donwload_distfile( 50 | ARCHIVE #this is the out-var 51 | URLS "https://downloads.apache.org/apr/apr-${VERSION}.tar.bz2" 52 | FILENAME "apr-${VERSION}.tar.bz2" 53 | SHA512 629b60680d1244641828019db903a1b199e8a19c8f27a5132b93faacb381ce561f88463345ab019258f1f1e8cfdf8aa986ac815153a8e7e04a22b3932f9fedd2 54 | ) 55 | ``` 56 | 57 | ### URLS 58 | 59 | A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the 60 | SHA512 given. 61 | 62 | ### FILENAME 63 | 64 | The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly 65 | attributed to this port and avoid conflicts. 66 | 67 | ### SHA512 68 | 69 | The expected hash for the file. 70 | 71 | If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch. 72 | 73 | ### QUIET 74 | 75 | Suppress output on cache hit 76 | 77 | ### SKIP_SHA512 78 | 79 | Skip SHA512 hash check for file. 80 | 81 | This switch is only valid when building with the `--head` command line flag. 82 | 83 | ### ALWAYS_REDOWNLOAD 84 | 85 | Avoid caching; this is a REST call or otherwise unstable. 86 | 87 | Requires `SKIP_SHA512`. 88 | 89 | ### HEADERS 90 | 91 | A list of headers to append to the download request. This can be used for authentication during a download. 92 | 93 | Headers should be specified as `": "`. 94 | 95 | ## Examples 96 | 97 | - [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake) 98 | 99 | ## Source 100 | 101 | [scripts/cmake/vcpkg\_download\_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake) 102 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_build_nmake.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_build_nmake 3 | description: Use vcpkg_build_nmake to build an NMake Makefile project. 4 | ms.date: 01/10/2024 5 | --- 6 | # vcpkg_build_nmake 7 | 8 | Build an NMake Makefile project. 9 | 10 | ## Usage 11 | 12 | ```cmake 13 | vcpkg_build_nmake( 14 | SOURCE_PATH <${SOURCE_PATH}> 15 | [PROJECT_SUBPATH <${SUBPATH}>] 16 | [PROJECT_NAME <${MAKEFILE_NAME}>] 17 | [LOGFILE_ROOT ] 18 | [CL_LANGUAGE ] 19 | [PREFER_JOM] 20 | [PRERUN_SHELL <${SHELL_PATH}>] 21 | [PRERUN_SHELL_DEBUG <${SHELL_PATH}>] 22 | [PRERUN_SHELL_RELEASE <${SHELL_PATH}>] 23 | [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] 24 | [OPTIONS_RELEASE <-DOPTIMIZE=1>...] 25 | [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] 26 | [TARGET ...] 27 | [ENABLE_INSTALL] 28 | ) 29 | ``` 30 | 31 | ## Parameters 32 | 33 | ### SOURCE_PATH 34 | 35 | Specifies the directory containing the source files. 36 | By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. 37 | 38 | ### PROJECT_SUBPATH 39 | 40 | Specifies the sub directory containing the makefile. 41 | 42 | ### PROJECT_NAME 43 | 44 | Specifies the name of the makefile. 45 | Default is `makefile.vc`. 46 | 47 | ### LOGFILE_ROOT 48 | 49 | Specifies a log file prefix. 50 | 51 | ### CL_LANGUAGE 52 | 53 | Specifies the language for setting up flags in the `_CL_` environment variable. 54 | The default language is `CXX`. 55 | To disable the modification of `_CL_`, use `NONE`. 56 | 57 | ### PREFER_JOM 58 | 59 | Specifies that a parallel build with `jom` should be attempted. 60 | This is useful for faster builds of makefiles which process many independent targets 61 | and which cannot benefit from the `/MP` cl option. 62 | To mitigate issues with concurrency-unaware makefiles, a normal `nmake` build is run after `jom` errors. 63 | 64 | ### PRERUN_SHELL 65 | 66 | Script that needs to be called before build. 67 | 68 | ### PRERUN_SHELL_DEBUG 69 | 70 | Script that needs to be called before debug build. 71 | 72 | ### PRERUN_SHELL_RELEASE 73 | 74 | Script that needs to be called before release build. 75 | 76 | ### OPTIONS 77 | 78 | Additional options passed to the build command. 79 | 80 | ### OPTIONS_RELEASE 81 | 82 | Additional options passed to the build command for the release build. These are in addition to `OPTIONS`. 83 | 84 | ### OPTIONS_DEBUG 85 | 86 | Additional options passed to the build command for the debug build. These are in addition to `OPTIONS`. 87 | 88 | ### TARGET 89 | 90 | The list of targets passed to the build command. 91 | If not specified, target `all` will be passed. 92 | 93 | ### ENABLE_INSTALL 94 | 95 | Adds `install` to the list of targets passed to the build command, 96 | and passes the install prefix in the `INSTALLDIR` makefile variable. 97 | 98 | ## Notes 99 | 100 | You can use the alias [`vcpkg_install_nmake()`](vcpkg_install_nmake.md) function if your makefile supports the 101 | "install" target. 102 | 103 | ## Examples 104 | 105 | - [librttopo](https://github.com/microsoft/vcpkg/blob/master/ports/librttopo/portfile.cmake) 106 | 107 | ## Source 108 | 109 | [scripts/cmake/vcpkg\_build\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_nmake.cmake) 110 | -------------------------------------------------------------------------------- /vcpkg/maintainers/functions/vcpkg_check_linkage.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: vcpkg_check_linkage 3 | description: Assert the available library and CRT linkage options for the port. 4 | ms.date: 12/05/2024 5 | ms.topic: reference 6 | --- 7 | # vcpkg_check_linkage 8 | 9 | Asserts the available library and CRT linkage options for the port. 10 | 11 | ## Usage 12 | 13 | ```cmake 14 | vcpkg_check_linkage( 15 | [ONLY_STATIC_LIBRARY | ONLY_DYNAMIC_LIBRARY] 16 | [ONLY_STATIC_CRT | ONLY_DYNAMIC_CRT] 17 | ) 18 | ``` 19 | 20 | ## Parameters 21 | 22 | ### ONLY_STATIC_LIBRARY 23 | 24 | Indicates that this port can only be built with static library linkage. 25 | 26 | If the user requested a dynamic build, `ONLY_STATIC_LIBRARY` will result in a note being printed, 27 | not a fatal error. 28 | 29 | ### ONLY_DYNAMIC_LIBRARY 30 | 31 | Indicates that this port can only be built with dynamic/shared library linkage. When using this 32 | option, port authors should add `!(static & staticcrt)` to the [`"supports"`](../../reference/vcpkg-json.md#supports) expression in the 33 | port's `vcpkg.json` to warn consumers it will fail early. 34 | 35 | ### ONLY_STATIC_CRT 36 | 37 | Indicates that this port can only be built with static CRT linkage. 38 | 39 | ### ONLY_DYNAMIC_CRT 40 | 41 | Indicates that this port can only be built with dynamic/shared CRT linkage. 42 | 43 | ## Notes 44 | 45 | If the triplet requests a setting of `VCPKG_LIBRARY_LINKAGE` different than the port supports, 46 | and changing `VCPKG_LIBRARY_LINKAGE` to that the port supports is considered safe, 47 | `vcpkg_check_linkage` changes `VCPKG_LIBRARY_LINKAGE` to that the port supports and emits a warning. 48 | This means that the port may produce something that the user does not expect, but the alternative 49 | would be to just fail. 50 | 51 | If `vcpkg_check_linkage` would change `VCPKG_LIBRARY_LINKAGE` to `dynamic` while the triplet 52 | requests `VCPKG_CRT_LINKAGE` of `static`, the change is not considered safe and 53 | `vcpkg_check_linkage` fails. Building a dynamic library with a static CRT creates conditions many 54 | developers find surprising, and for which most ports are unprepared. 55 | 56 | For example, on Windows, each DLL will get its own copy of the CRT, meaning such DLLs cannot share 57 | standard library components over the DLL boundary. On non-Windows, different .sos or .dylibs may 58 | cause mutually incompatible symbols from different CRT versions to be concurrently loaded. 59 | 60 | If you are consuming a port and it fails in `vcpkg_check_linkage`, consider choosing a triplet that 61 | sets `VCPKG_CRT_LINKAGE` to `dynamic`. If you really know what you're doing, understand the 62 | potential problems a static CRT with a dynamic library can cause, and are confident that the port 63 | safely handles that configuration, author a custom triplet which explicitly sets 64 | `VCPKG_LIBRARY_LINKAGE` to `dynamic` and `VCPKG_CRT_LINKAGE` to static. For example: 65 | 66 | ```cmake 67 | if("${PORT}" STREQUAL "the-name-of-the-port-you-want-to-control") 68 | set(VCPKG_LIBRARY_LINKAGE dynamic) 69 | set(VCPKG_CRT_LINKAGE static) 70 | endif() 71 | ``` 72 | 73 | ## Examples 74 | 75 | - [abseil](https://github.com/Microsoft/vcpkg/blob/master/ports/abseil/portfile.cmake) 76 | 77 | ## Source 78 | 79 | [scripts/cmake/vcpkg\_check\_linkage.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_linkage.cmake) 80 | -------------------------------------------------------------------------------- /vcpkg/resources/vcpkg-mark-primary-36px.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | -------------------------------------------------------------------------------- /vcpkg/docfx.json: -------------------------------------------------------------------------------- 1 | { 2 | "build": { 3 | "content": [ 4 | { 5 | "files": [ 6 | "**/*.md", 7 | "**/*.yml" 8 | ], 9 | "src": ".", 10 | "exclude": [ 11 | "**/obj/**", 12 | "**/includes/**", 13 | "_themes/**", 14 | "_themes.pdf/**", 15 | "**/docfx.json", 16 | "_repo.en-us/**", 17 | "README.md", 18 | "LICENSE", 19 | "LICENSE-CODE", 20 | "ThirdPartyNotices.md", 21 | "SECURITY.md" 22 | ] 23 | } 24 | ], 25 | "resource": [ 26 | { 27 | "files": [ 28 | "**/*.png", 29 | "**/*.jpg", 30 | "**/*.gif", 31 | "**/*.svg", 32 | "**/zone-pivot-groups.json" 33 | ], 34 | "exclude": [ 35 | "**/obj/**", 36 | "**/includes/**", 37 | "_themes/**", 38 | "_themes.pdf/**", 39 | "**/docfx.json", 40 | "_repo.en-us/**" 41 | ] 42 | } 43 | ], 44 | "overwrite": [], 45 | "externalReference": [], 46 | "globalMetadata": { 47 | "breadcrumb_path": "/vcpkg/breadcrumb/toc.json", 48 | "feedback_system": "OpenSource", 49 | "feedback_github_repo": "MicrosoftDocs/vcpkg-docs", 50 | "feedback_product_url": "https://github.com/Microsoft/vcpkg/issues/", 51 | "open_source_feedback_contributorGuideUrl": "https://learn.microsoft.com/contribute/content/how-to-write-overview", 52 | "open_source_feedback_issueTitle": "", 53 | "open_source_feedback_issueUrl": "https://github.com/MicrosoftDocs/vcpkg-docs/issues/new?template=z-learn-feedback-tool.yml", 54 | "open_source_feedback_productLogoDarkUrl": "https://github.com/MicrosoftDocs/vcpkg-docs/vcpkg/resources/vcpkg-mark-primary-36px.svg", 55 | "open_source_feedback_productLogoLightUrl": "https://github.com/MicrosoftDocs/vcpkg-docs/vcpkg/resources/vcpkg-mark-primary-36px.svg", 56 | "open_source_feedback_productName": "vcpkg", 57 | "ROBOTS": "INDEX,FOLLOW", 58 | "manager": "aupopa", 59 | "ms.date": "02/01/2024", 60 | "ms.service": "vcpkg", 61 | "ms.topic": "reference", 62 | "audience": "developer", 63 | "uhfHeaderId": "MSDocsHeader-Vcpkg", 64 | "defaultDevLang": "cpp", 65 | "ms.workload": [ 66 | "cplusplus" 67 | ], 68 | "ms.reviewer": [ 69 | "aupopa", 70 | "viromer", 71 | "twhitney" 72 | 73 | ], 74 | "searchScope": [ 75 | "vcpkg" 76 | ], 77 | "zone_pivot_group_filename": "core/zone-pivot-groups.json" 78 | }, 79 | "fileMetadata": { 80 | "author": { 81 | "index.md": "vicroms", 82 | "about/**.md": "vicroms", 83 | "commands/**.md": "vicroms", 84 | "examples/**.md": "vicroms", 85 | "maintainers/**.md": "vicroms", 86 | "contributing/**.md": "vicroms", 87 | "users/**.md": "vicroms", 88 | "reference/**.md": "vicroms" 89 | }, 90 | "ms.author": { 91 | "index.md": "viromer", 92 | "about/**.md": "viromer", 93 | "commands/**.md": "viromer", 94 | "examples/**.md": "viromer", 95 | "maintainers/**.md": "viromer", 96 | "contributing/**.md": "viromer", 97 | "users/**.md": "viromer", 98 | "reference/**.md": "viromer" 99 | } 100 | }, 101 | "template": [], 102 | "dest": "vcpkg-docs", 103 | "markdownEngineName": "markdig" 104 | } 105 | } 106 | --------------------------------------------------------------------------------