etc/pineapple-src
2
1
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity

early-access version 2853

Browse source
This commit is contained in:
pineappleEA 2022-07-23 03:01:36 +02:00
parent 1f2b5081b5
commit 1f111bb69c
8955 changed files with 418777 additions and 999 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

172
CMakeLists.txt
View file

@ -35,6 +35,16 @@ option(YUZU_USE_BUNDLED_OPUS "Compile bundled opus" ON)
option(YUZU_TESTS "Compile tests" ON)
option(YUZU_USE_BUNDLED_VCPKG "Use vcpkg for yuzu dependencies" OFF)
if (YUZU_USE_BUNDLED_VCPKG)
include(${CMAKE_SOURCE_DIR}/externals/vcpkg/scripts/buildsystems/vcpkg.cmake)
elseif(NOT "$ENV{VCPKG_TOOLCHAIN_FILE}" STREQUAL "")
# Disable manifest mode (use vcpkg classic mode) when using a custom vcpkg installation
option(VCPKG_MANIFEST_MODE "")
include("$ENV{VCPKG_TOOLCHAIN_FILE}")
endif()
# Default to a Release build
get_property(IS_MULTI_CONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
if (NOT IS_MULTI_CONFIG AND NOT CMAKE_BUILD_TYPE)
@ -144,82 +154,34 @@ endif()
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/bin)
# System imported libraries
# If not found, download any missing through Conan
# =======================================================================
set(CONAN_CMAKE_SILENT_OUTPUT TRUE)
set(CMAKE_FIND_PACKAGE_PREFER_CONFIG TRUE)
if (YUZU_CONAN_INSTALLED)
if (IS_MULTI_CONFIG)
include(${CMAKE_BINARY_DIR}/conanbuildinfo_multi.cmake)
else()
include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
endif()
list(APPEND CMAKE_MODULE_PATH "${CMAKE_BINARY_DIR}")
list(APPEND CMAKE_PREFIX_PATH "${CMAKE_BINARY_DIR}")
conan_basic_setup()
message(STATUS "Adding conan installed libraries to the search path")
find_package(fmt 8.0.1 REQUIRED CONFIG)
find_package(lz4 1.8 REQUIRED)
find_package(nlohmann_json 3.8 REQUIRED CONFIG)
find_package(ZLIB 1.2 REQUIRED)
# Search for config-only package first (for vcpkg), then try non-config
find_package(zstd 1.5 CONFIG)
if (NOT zstd_FOUND)
find_package(zstd 1.5 REQUIRED)
endif()
macro(yuzu_find_packages)
set(options FORCE_REQUIRED)
cmake_parse_arguments(FN "${options}" "" "" ${ARGN})
# Cmake has a *serious* lack of 2D array or associative array...
# Capitalization matters here. We need the naming to match the generated paths from Conan
set(REQUIRED_LIBS
# Cmake Pkg Prefix Version Conan Pkg
"fmt 8.0.1 fmt/8.1.1"
"lz4 1.8 lz4/1.9.2"
"nlohmann_json 3.8 nlohmann_json/3.8.0"
"ZLIB 1.2 zlib/1.2.11"
"zstd 1.5 zstd/1.5.0"
# can't use opus until AVX check is fixed: https://github.com/yuzu-emu/yuzu/pull/4068
#"opus 1.3 opus/1.3.1"
)
if (YUZU_TESTS)
list(APPEND REQUIRED_LIBS
"Catch2 2.13.7 catch2/2.13.7"
)
find_package(Catch2 2.13.7 REQUIRED CONFIG)
endif()
foreach(PACKAGE ${REQUIRED_LIBS})
string(REGEX REPLACE "[ \t\r\n]+" ";" PACKAGE_SPLIT ${PACKAGE})
list(GET PACKAGE_SPLIT 0 PACKAGE_PREFIX)
list(GET PACKAGE_SPLIT 1 PACKAGE_VERSION)
list(GET PACKAGE_SPLIT 2 PACKAGE_CONAN)
# This function is called twice, once to check if the packages exist on the system already
# and a second time to check if conan installed them properly. The second check passes in FORCE_REQUIRED
if (NOT ${PACKAGE_PREFIX}_FOUND)
if (FN_FORCE_REQUIRED)
find_package(${PACKAGE_PREFIX} ${PACKAGE_VERSION} REQUIRED)
else()
find_package(${PACKAGE_PREFIX} ${PACKAGE_VERSION})
endif()
endif()
if (NOT ${PACKAGE_PREFIX}_FOUND)
list(APPEND CONAN_REQUIRED_LIBS ${PACKAGE_CONAN})
else()
# Set a legacy findPackage.cmake style PACKAGE_LIBRARIES variable for subprojects that rely on this
set(${PACKAGE_PREFIX}_LIBRARIES "${PACKAGE_PREFIX}::${PACKAGE_PREFIX}")
endif()
endforeach()
unset(FN_FORCE_REQUIRED)
endmacro()
find_package(Boost 1.73.0 COMPONENTS context headers)
find_package(Boost 1.73.0 COMPONENTS context)
if (Boost_FOUND)
set(Boost_LIBRARIES Boost::boost)
# Conditionally add Boost::context only if the active version of the Conan or system Boost package provides it
# Conditionally add Boost::context only if the found Boost package provides it
# The old version is missing Boost::context, so we want to avoid adding in that case
# The new version requires adding Boost::context to prevent linking issues
#
# This one is used by Conan on subsequent CMake configures, not the first configure.
if (TARGET Boost::context)
list(APPEND Boost_LIBRARIES Boost::context)
endif()
else()
message(STATUS "Boost 1.79.0 or newer not found, falling back to Conan")
list(APPEND CONAN_REQUIRED_LIBS "boost/1.79.0")
message(FATAL_ERROR "Boost 1.73.0 or newer not found")
endif()
# boost:asio has functions that require AcceptEx et al
@ -227,24 +189,14 @@ if (MINGW)
find_library(MSWSOCK_LIBRARY mswsock REQUIRED)
endif()
# Attempt to locate any packages that are required and report the missing ones in CONAN_REQUIRED_LIBS
yuzu_find_packages()
# Qt5 requires that we find components, so it doesn't fit our pretty little find package function
if(ENABLE_QT)
set(QT_VERSION 5.15)
# We want to load the generated conan qt config so that we get the QT_ROOT var so that we can use the official
# Qt5Config inside the root folder instead of the conan generated one.
if(EXISTS ${CMAKE_BINARY_DIR}/qtConfig.cmake)
include(${CMAKE_BINARY_DIR}/qtConfig.cmake)
list(APPEND CMAKE_MODULE_PATH "${CONAN_QT_ROOT_RELEASE}")
list(APPEND CMAKE_PREFIX_PATH "${CONAN_QT_ROOT_RELEASE}")
endif()
# Check for system Qt on Linux, fallback to bundled Qt
if (${CMAKE_SYSTEM_NAME} STREQUAL "Linux")
if (NOT YUZU_USE_BUNDLED_QT)
find_package(Qt5 ${QT_VERSION} COMPONENTS Widgets DBus Multimedia)
find_package(Qt5 ${QT_VERSION} COMPONENTS Widgets DBus)
endif()
if (NOT Qt5_FOUND OR YUZU_USE_BUNDLED_QT)
# Check for dependencies, then enable bundled Qt download
@ -330,9 +282,6 @@ if(ENABLE_QT)
set(YUZU_QT_NO_CMAKE_SYSTEM_PATH)
# Workaround for an issue where conan tries to build Qt from scratch instead of download prebuilt binaries
set(QT_PREFIX_HINT)
if(YUZU_USE_BUNDLED_QT)
if ((MSVC_VERSION GREATER_EQUAL 1920 AND MSVC_VERSION LESS 1940) AND ARCHITECTURE_x86_64)
set(QT_BUILD qt-5.15.2-msvc2019_64)
@ -351,9 +300,9 @@ if(ENABLE_QT)
set(YUZU_QT_NO_CMAKE_SYSTEM_PATH "NO_CMAKE_SYSTEM_PATH")
endif()
if ((${CMAKE_SYSTEM_NAME} STREQUAL "Linux") AND YUZU_USE_BUNDLED_QT)
find_package(Qt5 ${QT_VERSION} REQUIRED COMPONENTS Widgets DBus Multimedia ${QT_PREFIX_HINT} ${YUZU_QT_NO_CMAKE_SYSTEM_PATH})
find_package(Qt5 ${QT_VERSION} REQUIRED COMPONENTS Widgets DBus ${QT_PREFIX_HINT} ${YUZU_QT_NO_CMAKE_SYSTEM_PATH})
else()
find_package(Qt5 ${QT_VERSION} REQUIRED COMPONENTS Widgets Multimedia ${QT_PREFIX_HINT} ${YUZU_QT_NO_CMAKE_SYSTEM_PATH})
find_package(Qt5 ${QT_VERSION} REQUIRED COMPONENTS Widgets ${QT_PREFIX_HINT} ${YUZU_QT_NO_CMAKE_SYSTEM_PATH})
endif()
if (YUZU_USE_QT_WEB_ENGINE)
find_package(Qt5 COMPONENTS WebEngineCore WebEngineWidgets)
@ -403,71 +352,8 @@ if (ENABLE_SDL2)
endif()
endif()
# Install any missing dependencies with conan install
if (CONAN_REQUIRED_LIBS)
message(STATUS "Packages ${CONAN_REQUIRED_LIBS} not found!")
# Use Conan to fetch the libraries that aren't found
# Download conan.cmake automatically, you can also just copy the conan.cmake file
if(NOT EXISTS "${CMAKE_BINARY_DIR}/conan.cmake")
message(STATUS "Downloading conan.cmake from https://github.com/conan-io/cmake-conan")
file(DOWNLOAD "https://raw.githubusercontent.com/conan-io/cmake-conan/release/0.18/conan.cmake" "${CMAKE_BINARY_DIR}/conan.cmake")
endif()
include(${CMAKE_BINARY_DIR}/conan.cmake)
conan_check(VERSION 1.45.0 REQUIRED)
# Manually add iconv to fix a dep conflict between qt and sdl2
# We don't need to add it through find_package or anything since the other two can find it just fine
if ("${CONAN_REQUIRED_LIBS}" MATCHES "qt" AND "${CONAN_REQUIRED_LIBS}" MATCHES "sdl")
list(APPEND CONAN_REQUIRED_LIBS "libiconv/1.16")
endif()
if (IS_MULTI_CONFIG)
conan_cmake_run(REQUIRES ${CONAN_REQUIRED_LIBS}
OPTIONS ${CONAN_LIB_OPTIONS}
BUILD missing
CONFIGURATION_TYPES "Release;Debug"
GENERATORS cmake_multi cmake_find_package_multi)
include(${CMAKE_BINARY_DIR}/conanbuildinfo_multi.cmake)
else()
conan_cmake_run(REQUIRES ${CONAN_REQUIRED_LIBS}
OPTIONS ${CONAN_LIB_OPTIONS}
BUILD missing
GENERATORS cmake cmake_find_package_multi)
include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
endif()
list(APPEND CMAKE_MODULE_PATH "${CMAKE_BINARY_DIR}")
list(APPEND CMAKE_PREFIX_PATH "${CMAKE_BINARY_DIR}")
conan_basic_setup()
set(YUZU_CONAN_INSTALLED TRUE CACHE BOOL "If true, the following builds will add conan to the lib search path" FORCE)
# Now that we've installed what we are missing, try to locate them again,
# this time with required, so we bail if its not found.
yuzu_find_packages(FORCE_REQUIRED)
if (NOT Boost_FOUND)
find_package(Boost 1.73.0 REQUIRED COMPONENTS context headers)
set(Boost_LIBRARIES Boost::boost)
# Conditionally add Boost::context only if the active version of the Conan Boost package provides it
# The old version is missing Boost::context, so we want to avoid adding in that case
# The new version requires adding Boost::context to prevent linking issues
if (TARGET Boost::context)
list(APPEND Boost_LIBRARIES Boost::context)
endif()
endif()
# Due to issues with variable scopes in functions, we need to also find_package(qt5) outside of the function
if(ENABLE_QT)
list(APPEND CMAKE_MODULE_PATH "${CONAN_QT_ROOT_RELEASE}")
list(APPEND CMAKE_PREFIX_PATH "${CONAN_QT_ROOT_RELEASE}")
find_package(Qt5 5.15 REQUIRED COMPONENTS Widgets Multimedia)
if (YUZU_USE_QT_WEB_ENGINE)
find_package(Qt5 REQUIRED COMPONENTS WebEngineCore WebEngineWidgets)
endif()
endif()
endif()
# TODO(lat9nq): Determine what if any of this we still need
#
# Reexport some targets that are named differently when using the upstream CmakeConfig vs the generated Conan config
# In order to ALIAS targets to a new name, they first need to be IMPORTED_GLOBAL
# Dynarmic checks for target `boost` and so we want to make sure it can find it through our system instead of using their external

8
CMakeModules/CopyYuzuQt5Deps.cmake
View file

@ -10,13 +10,11 @@ function(copy_yuzu_Qt5_deps target_dir)
set(Qt5_PLATFORMS_DIR "${Qt5_DIR}/../../../plugins/platforms/")
set(Qt5_PLATFORMTHEMES_DIR "${Qt5_DIR}/../../../plugins/platformthemes/")
set(Qt5_PLATFORMINPUTCONTEXTS_DIR "${Qt5_DIR}/../../../plugins/platforminputcontexts/")
set(Qt5_MEDIASERVICE_DIR "${Qt5_DIR}/../../../plugins/mediaservice/")
set(Qt5_XCBGLINTEGRATIONS_DIR "${Qt5_DIR}/../../../plugins/xcbglintegrations/")
set(Qt5_STYLES_DIR "${Qt5_DIR}/../../../plugins/styles/")
set(Qt5_IMAGEFORMATS_DIR "${Qt5_DIR}/../../../plugins/imageformats/")
set(Qt5_RESOURCES_DIR "${Qt5_DIR}/../../../resources/")
set(PLATFORMS ${DLL_DEST}plugins/platforms/)
set(MEDIASERVICE ${DLL_DEST}mediaservice/)
set(STYLES ${DLL_DEST}plugins/styles/)
set(IMAGEFORMATS ${DLL_DEST}plugins/imageformats/)
if (MSVC)
@ -27,8 +25,6 @@ function(copy_yuzu_Qt5_deps target_dir)
Qt5Core$<$<CONFIG:Debug>:d>.*
Qt5Gui$<$<CONFIG:Debug>:d>.*
Qt5Widgets$<$<CONFIG:Debug>:d>.*
Qt5Multimedia$<$<CONFIG:Debug>:d>.*
Qt5Network$<$<CONFIG:Debug>:d>.*
)
if (YUZU_USE_QT_WEB_ENGINE)
@ -61,10 +57,6 @@ function(copy_yuzu_Qt5_deps target_dir)
qjpeg$<$<CONFIG:Debug>:d>.*
qgif$<$<CONFIG:Debug>:d>.*
)
windows_copy_files(yuzu ${Qt5_MEDIASERVICE_DIR} ${MEDIASERVICE}
dsengine$<$<CONFIG:Debug>:d>.*
wmfengine$<$<CONFIG:Debug>:d>.*
)
else()
set(Qt5_DLLS
"${Qt5_DLL_DIR}libQt5Core.so.5"

2
README.md
View file

@ -1,7 +1,7 @@
yuzu emulator early access
=============
This is the source code for early-access 2849.
This is the source code for early-access 2853.
## Legal Notice

5
externals/vcpkg/.gitattributes vendored Executable file
View file

@ -0,0 +1,5 @@
* -text
ports/** -linguist-detectable
# Declare files that will always have LF line endings on checkout.
scripts/ci.baseline.txt text eol=lf

10
externals/vcpkg/.github/ISSUE_TEMPLATE/i-have-a-question.md vendored Executable file
View file

@ -0,0 +1,10 @@
---
name: I have a question
about: I have a question and don't see a clear answer in documentation
title: How do I ...
labels: Question
assignees: ''
---
Please create a discussion in https://github.com/microsoft/vcpkg/discussions/new instead.

31
externals/vcpkg/.github/ISSUE_TEMPLATE/other-type-of-bug-report.md vendored Executable file
View file

@ -0,0 +1,31 @@
---
name: Other type of bug report
about: Let us know about an issues that does not fit into any of the other issues
types
title: ''
labels: ''
assignees: ''
---
**Describe the bug**
A clear and concise description of what the bug is.
**Environment**
- OS: [e.g. Windows/Linux etc...]
- Compiler: revision
**To Reproduce**
Steps to reproduce the behavior:
1. ./vcpkg install xxxx
2. See error
Repro code when
**Expected behavior**
A clear and concise description of what you expected to happen.
**Failure logs**
-(please attached failure logs)
**Additional context**
Add any other context about the problem here.

23
externals/vcpkg/.github/ISSUE_TEMPLATE/report-package-build-failure.md vendored Executable file
View file

@ -0,0 +1,23 @@
---
name: Report package build failure
about: Let us know about build failures in ports.
title: "[<port name>] build failure"
labels: port bug
assignees: ''
---
**Host Environment**
- OS: [e.g. Windows/Linux etc...]
- Compiler: revision
**To Reproduce**
Steps to reproduce the behavior:
`./vcpkg install xxxx`
**Failure logs**
-Cut and paste the appropriate build messages from the console output.
-Please attach any additional failure logs mentioned in the console output.
**Additional context**
Add any other context about the problem here, such as what you have already tried to resolve the issue.

22
externals/vcpkg/.github/ISSUE_TEMPLATE/request-a-feature-or-improvement-to-a-port.md vendored Executable file
View file

@ -0,0 +1,22 @@
---
name: Request a feature or improvement to a port
about: Suggest an improvement to one the the ports/libraries in vcpkg
title: "[<portname>] <short description of feature>"
labels: port feature
assignees: ''
---
****
**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
**Proposed solution**
A clear and concise description of what you want to happen.
**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered if applicable.
**Additional context**
Add any other context or screenshots about the feature request here.

22
externals/vcpkg/.github/ISSUE_TEMPLATE/request-a-feature-or-improvement.md vendored Executable file
View file

@ -0,0 +1,22 @@
---
name: Request a feature or improvement
about: Suggest an improvement to vcpkg
title: ''
labels: vcpkg feature
assignees: ''
---
****
**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
**Proposed solution**
A clear and concise description of what you want to happen.
**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.
**Additional context**
Add any other context or screenshots about the feature request here.

18
externals/vcpkg/.github/ISSUE_TEMPLATE/request-a-new-port.md vendored Executable file
View file

@ -0,0 +1,18 @@
---
name: Request a new port
about: Request a new port/library that vcpkg should support
title: "[New Port Request] <library name here>"
labels: new port request - consider making a PR!
assignees: ''
---
Library name:
Library description:
Source repository URL:
Project homepage (if different from the source repository):
Anything else that is useful to know when adding (such as optional features the library may have that should be included):

14
externals/vcpkg/.github/ISSUE_TEMPLATE/request-an-update-to-an-existing-port.md vendored Executable file
View file

@ -0,0 +1,14 @@
---
name: Request an update to an existing port
about: Let us know about a new version of a library we should pick up.
title: "[<port name>] update to <version>"
labels: port feature
assignees: ''
---
Library name:
New version number:
Other information that may be useful (release notes, etc...)

15
externals/vcpkg/.github/pull_request_template.md vendored Executable file
View file

@ -0,0 +1,15 @@
**Describe the pull request**
- #### What does your PR fix?
Fixes #...
- #### Which triplets are supported/not supported? Have you updated the [CI baseline](https://github.com/microsoft/vcpkg/blob/master/scripts/ci.baseline.txt)?
<all / linux, windows, ...>, <Yes/No>
- #### Does your PR follow the [maintainer guide](https://github.com/microsoft/vcpkg/blob/master/docs/maintainers/maintainer-guide.md)?
`Your answer`
- #### If you have added/updated a port: Have you run `./vcpkg x-add-version --all` and committed the result?
<Yes / I am still working on this PR>
**If you are still working on the PR, open it as a Draft: https://github.blog/2019-02-14-introducing-draft-pull-requests/**

58
externals/vcpkg/.github/workflows/trustedPR.yml vendored Executable file
View file

@ -0,0 +1,58 @@
# Modelled after https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
name: Post PR Suggestions
on:
workflow_run:
workflows: ["PR Suggestions"]
types:
- completed
jobs:
comment:
runs-on: ubuntu-latest
if: >
${{ github.event.workflow_run.event == 'pull_request' &&
github.event.workflow_run.conclusion == 'success' }}
steps:
- name: 'Download artifact'
uses: actions/github-script@v6
with:
script: |
var artifacts = await github.rest.actions.listWorkflowRunArtifacts({
owner: context.repo.owner,
repo: context.repo.repo,
run_id: ${{github.event.workflow_run.id }},
});
var matchArtifact = artifacts.data.artifacts.filter((artifact) => {
return artifact.name == "pr"
})[0];
var download = await github.rest.actions.downloadArtifact({
owner: context.repo.owner,
repo: context.repo.repo,
artifact_id: matchArtifact.id,
archive_format: 'zip',
});
var fs = require('fs');
fs.writeFileSync('${{github.workspace}}/pr.zip', Buffer.from(download.data));
- run: unzip pr.zip
- uses: actions/github-script@v6
with:
script: |
const { promises: fs } = require('fs')
const event = (await fs.readFile('event', 'utf8')).trim()
const body = (await fs.readFile('body', 'utf8')).trim()
const issue_number = Number(await fs.readFile('./NR'));
var req = {
owner: context.repo.owner,
pull_number: issue_number,
repo: context.repo.repo,
event: event
};
if (body !== "") {
req.body = body;
}
await github.rest.pulls.createReview(req);

147
externals/vcpkg/.github/workflows/untrustedPR.yml vendored Executable file
View file

@ -0,0 +1,147 @@
# Modelled after https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
# These "checks" are also performed as part of our critical-path azure-pipelines review,
# however here they are better able to post back to the original PR
name: PR Suggestions
on:
pull_request:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
# fetch-depth 50 tries to ensure we capture the whole history of the branch
fetch-depth: 50
- uses: actions/cache@v2
id: cache
with:
path: |
./vcpkg
key: ${{ runner.os }}-${{ hashFiles('scripts/bootstrap*') }}
- name: bootstrap
if: steps.cache.outputs.cache-hit != 'true'
run: ./bootstrap-vcpkg.sh
- name: Save PR number
run: |
mkdir -p ./pr
echo ${{ github.event.number }} > ./pr/NR
- name: Formatting
run: |
git config user.email github-actions
git config user.name github-actions@github.com
git diff --name-status --merge-base HEAD^ HEAD --diff-filter=MAR -- '*portfile.cmake' | sed 's/[MAR]\t*//' | while read filename; do grep -q -E '(vcpkg_install_cmake|vcpkg_build_cmake|vcpkg_configure_cmake|vcpkg_fixup_cmake_targets)' "$filename" && echo " - \`$filename\`" || true; done > .github-pr.deprecated-cmake
git diff --name-status --merge-base HEAD^ HEAD --diff-filter=MAR -- '*vcpkg.json' | sed 's/[MAR]\t*//' > .github-pr.changed-manifest-files
cat .github-pr.changed-manifest-files | while read filename; do grep -q -E '"license": ' "$filename" || echo " - \`$filename\`" || true; done > .github-pr.missing-license
cat .github-pr.changed-manifest-files | while read filename; do match=$(grep -oiP '"license": ".*\K(AGPL-1\.0|AGPL-3\.0|BSD-2-Clause-FreeBSD|BSD-2-Clause-NetBSD|bzip2-1\.0\.5|eCos-2\.0|GFDL-1\.1|GFDL-1\.2|GFDL-1\.3|GPL-1\.0|GPL-1\.0\+|GPL-2\.0|GPL-2\.0\+|GPL-2\.0-with-autoconf-exception|GPL-2\.0-with-bison-exception|GPL-2\.0-with-classpath-exception|GPL-2\.0-with-font-exception|GPL-2\.0-with-GCC-exception|GPL-3\.0|GPL-3\.0\+|GPL-3\.0-with-autoconf-exception|GPL-3\.0-with-GCC-exception|LGPL-2\.0|LGPL-2\.0\+|LGPL-2\.1|LGPL-2\.1\+|LGPL-3\.0|LGPL-3\.0\+|Nunit|StandardML-NJ|wxWindows)(?=[ "])' "$filename" || true); if [ ! -z "$match" ]; then echo " - \`$filename\` (has deprecated license \`$match\`)" ; fi ; done > .github-pr.deprecated-license
./vcpkg format-manifest --all --convert-control
git diff > .github-pr.format-manifest
git add -u
git commit -m "tmp" --allow-empty
# HEAD^^ refers to the "main" commit that was merged into
git checkout HEAD^^ -- versions
git restore --staged versions
./vcpkg x-add-version --all --skip-formatting-check | grep 'instead of "version-string"' | tee .github-pr.version-string.out || true
git checkout -- versions
./vcpkg x-add-version --all --skip-formatting-check --skip-version-format-check | tee .github-pr.x-add-version.out || true
git diff > .github-pr.x-add-version.diff
git reset HEAD~ --mixed
- uses: actions/github-script@v6
with:
script: |
const { promises: fs } = require('fs')
const add_version = (await fs.readFile('.github-pr.x-add-version.diff', 'utf8')).trim()
const add_version_out = (await fs.readFile('.github-pr.x-add-version.out', 'utf8')).trim()
const version_string_out = (await fs.readFile('.github-pr.version-string.out', 'utf8')).trim()
const format = (await fs.readFile('.github-pr.format-manifest', 'utf8')).trim()
const cmake = (await fs.readFile('.github-pr.deprecated-cmake', 'utf8')).trim()
const missing_license = (await fs.readFile('.github-pr.missing-license', 'utf8')).trim()
const deprecated_license = (await fs.readFile('.github-pr.deprecated-license', 'utf8')).trim()
let approve = true;
var output = ''
if (format !== "") {
output += "<details><summary><b>All manifest files must be formatted</b></summary>\n\n"
output += "`./vcpkg format-manifest ports/*/vcpkg.json`\n"
output += "<details><summary><b>Diff</b></summary>\n\n"
output += "```diff\n" + format + "\n```\n"
output += "</details></details>\n\n"
approve = false;
}
if (add_version_out !== "") {
output += "<details><summary><b>PRs must add only one version and must not modify any published versions</b></summary>\n\n"
output += "When making any changes to a library, the version or port-version in `vcpkg.json` or `CONTROL` must be modified.\n"
output += "```\n" + add_version_out + "\n```\n</details>\n\n"
approve = false;
}
if (version_string_out !== "") {
output += version_string_out + "\n\n"
}
if (add_version !== "") {
output += "<details><summary><b>After committing all other changes, the version database must be updated</b></summary>\n\n"
output += "```sh\n"
output += "git add -u && git commit\n"
output += "git checkout ${{ github.event.pull_request.base.sha }} -- versions\n"
output += "./vcpkg x-add-version --all\n"
output += "```\n"
output += "<details><summary><b>Diff</b></summary>\n\n"
output += "```diff\n" + add_version + "\n```\n"
output += "</details></details>\n\n"
approve = false;
}
if (cmake !== "") {
output += "You have modified or added at least one portfile where deprecated functions are used.\n"
output += "<details>\n\n"
output += "If you feel able to do so, please consider migrating them to the new functions:\n"
output += " `vcpkg_install_cmake` -> `vcpkg_cmake_install` (from port `vcpkg-cmake`)\n"
output += " `vcpkg_build_cmake` -> `vcpkg_cmake_build` (from port `vcpkg-cmake`)\n"
output += " `vcpkg_configure_cmake` -> `vcpkg_cmake_configure` (Please remove the option `PREFER_NINJA`) (from port `vcpkg-cmake`)\n"
output += " `vcpkg_fixup_cmake_targets` -> `vcpkg_cmake_config_fixup` (from port `vcpkg-cmake-config`)\n"
output += "\n"
output += "In the ports that use the new function, you have to add the corresponding dependencies:\n"
output += "```json\n"
output += '{\n "name": "vcpkg-cmake",\n "host": true\n},\n'
output += '{\n "name": "vcpkg-cmake-config",\n "host": true\n}\n'
output += "```\n"
output += `The following files are affected:\n${cmake}\n`
output += "</details>\n\n"
}
if (missing_license !== "" || deprecated_license !== "") {
output += 'You have modified or added at least one vcpkg.json where you should check the `license` field.\n'
output += "<details>\n\n"
if (missing_license !== "") {
output += 'If you feel able to do so, please consider adding a "license" field to the following files:\n'
output += missing_license
output += "\n\nValid values for the license field can be found in the [documentation](https://github.com/microsoft/vcpkg/blob/master/docs/maintainers/manifest-files.md#license)\n\n"
}
if (deprecated_license !== "") {
output += 'If you feel able to do so, please consider replacing the deprecated license identifiers in the following files:\n'
output += deprecated_license
output += "\n\nDeprecated and non deprecated license identifiers can be found [here](https://spdx.github.io/spdx-spec/SPDX-license-list/#a3-deprecated-licenses)\n"
}
output += "</details>\n\n"
}
if (approve) {
await fs.writeFile("pr/event", "APPROVE")
} else {
output = "_This is a new experimental fast check for PR issues. Please let us know if this bot is helpful!_\n\n" + output
await fs.writeFile("pr/event", "REQUEST_CHANGES")
}
await fs.writeFile("pr/body", output)
console.log(output);
- uses: actions/upload-artifact@v3
with:
name: pr
path: pr/

54
externals/vcpkg/.github/workflows/validateDocs.yml vendored Executable file
View file

@ -0,0 +1,54 @@
name: Doc Validation
on:
pull_request:
paths:
- 'docs/**'
jobs:
validate:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
with:
path: vcpkg
- name: Checkout Website
uses: actions/checkout@v3
with:
repository: vcpkg/vcpkg.github.io
ref: '8ee5cacc91b6e017b5e4236940d9f385c1563598'
path: vcpkg.github.io
- uses: actions/cache@v3
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- run: npm ci
working-directory: vcpkg.github.io
- name: Purge existing html files
run: rm -rf en
working-directory: vcpkg.github.io
# The current navbar embeds a link to integration.md which no longer exists
- name: Ignore navbar
run: echo "" > templates/navbar.html
working-directory: vcpkg.github.io
- name: Generate Core Pages
run: node scripts/generatePages.js
working-directory: vcpkg.github.io
- name: Generate Docs Pages
run: node scripts/generateDocs.js ../vcpkg/docs
working-directory: vcpkg.github.io
- name: Check Links
run: VCPKG_VALIDATE_LINKS_ONLY_DOCS=1 node scripts/validateLinks.js
working-directory: vcpkg.github.io

322
externals/vcpkg/.gitignore vendored Executable file
View file

@ -0,0 +1,322 @@
############################################################
# Visual Studio - Start
############################################################
## Ignore Visual Studio temporary files, build results, and
## files generated by popular Visual Studio add-ons.
# User-specific files
*.suo
*.user
*.userosscache
*.sln.docstates
/vcpkg-configuration.json
# fuzzing
sync_dir*
# User-specific files (MonoDevelop/Xamarin Studio)
*.userprefs
# Build results
[Dd]ebug/
[Dd]ebugPublic/
[Rr]elease/
[Rr]eleases/
x64/
x86/
bld/
[Bb]in/
[Oo]bj/
[Ll]og/
# Ignore the executable
/vcpkg
/vcpkg.exe
# Visual Studio 2015 cache/options directory
.vs/
# Uncomment if you have tasks that create the project's static files in wwwroot
#wwwroot/
# MSTest test Results
[Tt]est[Rr]esult*/
[Bb]uild[Ll]og.*
# NUNIT
*.VisualState.xml
TestResult.xml
# Build Results of an ATL Project
[Dd]ebugPS/
[Rr]eleasePS/
dlldata.c
# DNX
project.lock.json
project.fragment.lock.json
artifacts/
*_i.c
*_p.c
*_i.h
*.ilk
*.meta
*.obj
*.pch
*.pdb
*.pgc
*.pgd
*.rsp
*.sbr
*.tlb
*.tli
*.tlh
*.tmp
*.tmp_proj
*.log
*.vspscc
*.vssscc
.builds
*.pidb
*.svclog
*.scc
# Chutzpah Test files
_Chutzpah*
# Visual C++ cache files
ipch/
*.aps
*.ncb
*.opendb
*.opensdf
*.sdf
*.cachefile
*.VC.db
*.VC.VC.opendb
# Visual Studio profiler
*.psess
*.vsp
*.vspx
*.sap
# TFS 2012 Local Workspace
$tf/
# Guidance Automation Toolkit
*.gpState
# ReSharper is a .NET coding add-in
_ReSharper*/
*.[Rr]e[Ss]harper
*.DotSettings.user
# JustCode is a .NET coding add-in
.JustCode
# TeamCity is a build add-in
_TeamCity*
# DotCover is a Code Coverage Tool
*.dotCover
# NCrunch
_NCrunch_*
.*crunch*.local.xml
nCrunchTemp_*
# MightyMoose
*.mm.*
AutoTest.Net/
# Web workbench (sass)
.sass-cache/
# Installshield output folder
[Ee]xpress/
# DocProject is a documentation generator add-in
DocProject/buildhelp/
DocProject/Help/*.HxT
DocProject/Help/*.HxC
DocProject/Help/*.hhc
DocProject/Help/*.hhk
DocProject/Help/*.hhp
DocProject/Help/Html2
DocProject/Help/html
# Click-Once directory
publish/
# Publish Web Output
*.[Pp]ublish.xml
*.azurePubxml
# TODO: Comment the next line if you want to checkin your web deploy settings
# but database connection strings (with potential passwords) will be unencrypted
*.pubxml
*.publishproj
# Microsoft Azure Web App publish settings. Comment the next line if you want to
# checkin your Azure Web App publish settings, but sensitive information contained
# in these scripts will be unencrypted
PublishScripts/
# NuGet Packages
*.nupkg
# The packages folder can be ignored because of Package Restore
**/packages/*
# except build/, which is used as an MSBuild target.
!**/packages/build/
# Uncomment if necessary however generally it will be regenerated when needed
#!**/packages/repositories.config
# NuGet v3's project.json files produces more ignoreable files
*.nuget.props
*.nuget.targets
# Microsoft Azure Build Output
csx/
*.build.csdef
# Microsoft Azure Emulator
ecf/
rcf/
# Windows Store app package directories and files
AppPackages/
BundleArtifacts/
Package.StoreAssociation.xml
_pkginfo.txt
# Visual Studio cache files
# files ending in .cache can be ignored
*.[Cc]ache
# but keep track of directories ending in .cache
!*.[Cc]ache/
# Others
ClientBin/
~$*
*~
*.dbmdl
*.dbproj.schemaview
*.pfx
*.publishsettings
node_modules/
orleans.codegen.cs
# Since there are multiple workflows, uncomment next line to ignore bower_components
# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)
#bower_components/
# RIA/Silverlight projects
Generated_Code/
# Backup & report files from converting an old project file
# to a newer Visual Studio version. Backup files are not needed,
# because we have git ;-)
_UpgradeReport_Files/
Backup*/
UpgradeLog*.XML
UpgradeLog*.htm
# SQL Server files
*.mdf
*.ldf
# Business Intelligence projects
*.rdl.data
*.bim.layout
*.bim_*.settings
# Microsoft Fakes
FakesAssemblies/
# GhostDoc plugin setting file
*.GhostDoc.xml
# Node.js Tools for Visual Studio
.ntvs_analysis.dat
# Visual Studio 6 build log
*.plg
# Visual Studio 6 workspace options file
*.opt
# Visual Studio LightSwitch build output
**/*.HTMLClient/GeneratedArtifacts
**/*.DesktopClient/GeneratedArtifacts
**/*.DesktopClient/ModelManifest.xml
**/*.Server/GeneratedArtifacts
**/*.Server/ModelManifest.xml
_Pvt_Extensions
# Paket dependency manager
.paket/paket.exe
paket-files/
# FAKE - F# Make
.fake/
# JetBrains Rider
.idea/
*.sln.iml
# CodeRush
.cr/
# Python Tools for Visual Studio (PTVS)
__pycache__/
*.pyc
############################################################
# Visual Studio - End
############################################################
############################################################
# vcpkg - Start
############################################################
.vscode/
*.code-workspace
/buildtrees/
/build*/
/downloads/
/installed*/
/packages/
/scripts/buildsystems/tmp/
#ignore custom triplets
/triplets/*
#add vcpkg-designed triplets back in
!/triplets/arm-uwp.cmake
!/triplets/arm64-windows.cmake
!/triplets/x64-linux.cmake
!/triplets/x64-osx.cmake
!/triplets/x64-uwp.cmake
!/triplets/x64-windows-static.cmake
!/triplets/x64-windows.cmake
!/triplets/x86-windows.cmake
!/triplets/community
!/triplets/community/**
*.exe
*.zip
############################################################
# vcpkg - End
############################################################
vcpkg.disable-metrics
archives
.DS_Store
prefab/
*.swp
###################
# Codespaces
###################
pythonenv3.8/
.venv/

0
externals/vcpkg/.vcpkg-root vendored Executable file
View file

17525
externals/vcpkg/CHANGELOG.md vendored Executable file
View file

File diff suppressed because it is too large Load diff

33
externals/vcpkg/CONTRIBUTING.md vendored Executable file
View file

@ -0,0 +1,33 @@
# Contribution Guidelines
Vcpkg is a community driven effort to build a productive and robust ecosystem of native libraries - your contributions are invaluable!
## Issues
The easiest way to contribute is by reporting issues with either `vcpkg.exe` or an existing package on [GitHub](https://github.com/Microsoft/vcpkg). When reporting an issue with `vcpkg.exe`, make sure to clearly state:
- The machine setup: "I'm using Windows 10 Anniversary Update. My machine is using the fr-fr locale. I successfully ran 'install boost'."
- The steps to reproduce: "I run 'vcpkg list'"
- The outcome you expected: "I expected to see 'boost:x86-windows'"
- The actual outcome: "I get no output at all" or "I get a crash dialog"
When reporting an issue with a package, make sure to clearly state:
- The machine setup (as above)
- What package and version you're building: "opencv 3.1.0"
- Any relevant error logs from the build process.
## Pull Requests
We are happy to accept pull requests for fixes, features, new packages, and updates to existing packages. In order to avoid wasting your time, we highly encourage opening an issue to discuss whether the PR you're thinking about making will be acceptable. This is doubly true for features and new packages.
### New package Guidelines
We're glad you're interested in submitting a new package! Here are some guidelines to help you author an excellent portfile:
- Avoid functional patches. Patches should be considered a last resort to implement compatibility when there's no other way.
- When patches can't be avoided, do not modify the default behavior. The ideal lifecycle of a patch is to get merged upstream and no longer be needed. Try to keep this goal in mind when deciding how to patch something.
- Prefer to use the `vcpkg_xyz` functions over raw `execute_command` calls. This makes long term maintenance easier when new features (such as custom compiler flags or generators) are added.
## Legal
You will need to complete a Contributor License Agreement (CLA) before your pull request can be accepted. This agreement testifies that you are granting us permission to use the source code you are submitting, and that this work is being submitted under appropriate license that we can use it.
You can complete the CLA by going through the steps at https://cla.microsoft.com. Once we have received the signed CLA, we'll review the request. You will only need to do this once.

33
externals/vcpkg/CONTRIBUTING_zh.md vendored Executable file
View file

@ -0,0 +1,33 @@
# 贡献准则
Vcpkg 是一个尝试由社区驱动，旨在构建一个多产的、健壮的本地库生态系统 - 您的贡献价值不可估量！
## 报告问题
最简单的方法是通过 `vcpkg.exe` 或 [GitHub](https://github.com/Microsoft/vcpkg) 报告已有的包的问题。 当报告 `vcpkg.exe` 的问题时，确保清楚地说明:
- 机器设置: “我用的是Windows 10周年更新。 我的机器正位于fr-fr区域。 我成功地运行了'install boost'。”
- 复现步骤: “运行 'vcpkg list'”
- 预期结果: “我预期看到 'boost:x86-windows'”
- 实际结果: “没有输出” 或 “我得到一个崩溃对话框”
当报告包的问题时，一定要清楚地说明:
- 机器设置 (上述)
- 您正在构建什么包以及它的版本，例如: “opencv 3.1.0”
- 构建过程中的任何相关错误日志
## 贡献 (PR)
我们很乐意接受关于修复、特性、新包和更新现有包的拉取请求。 为了避免浪费您的时间，我们强烈建议您提交一个问题来讨论您想要制作的PR是否能被接受。 对于特性和新包来说也是如此。
### 新包贡献准则
我们很高兴您有兴趣来提交一个新的包! 这里有一些指导方针来帮助您编写一个优秀的端口文件:
- 避免功能补丁。 当没有其他方法时，补丁应该被视为实现兼容性的最后手段。
- 当无法避免补丁时，请不要修改默认行为。 一个补丁的理想生命周期是与上游合并，不再被需要。 在决定如何修补某些内容时，请记住这一目标。
- 相比原始的 `execute_command` 调用，尽量改为通过 `vcpkg_xyz` 函数实现。这使得在添加新特性(如自定义编译器标志或生成器)时更容易进行长期维护。
## 法律声明
在您的拉取请求被接受之前，您需要完成一个贡献者许可协议 (CLA)。 本协议证明您允许我们使用您提交的源代码，并且本作品是在合适的许可下提交的，我们可以使用它。
您可以通过 https://cla.microsoft.com 上的步骤来完成CLA。 一旦我们收到已签署的CLA，我们将审查请求。 您只需要这样做一次。

23
externals/vcpkg/LICENSE.txt vendored Executable file
View file

@ -0,0 +1,23 @@
Copyright (c) Microsoft Corporation
All rights reserved.
MIT License
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

46
externals/vcpkg/NOTICE.txt vendored Executable file
View file

@ -0,0 +1,46 @@
vcpkg uses third party material from the projects listed below.
The original copyright notice and the license under which Microsoft
received such third party material are set forth below. Microsoft
reserves all other rights not expressly granted, whether by
implication, estoppel or otherwise.
In the event that we accidentally failed to list a required notice, please
bring it to our attention by posting an issue.
THIRD-PARTY SOFTWARE NOTICES AND INFORMATION
Do Not Translate or Localize
vcpkg incorporates third party material from the projects listed below.
The original copyright notice and the license under which Microsoft received
such third party materials are set forth below. Microsoft reserved all other
rights not expressly granted, whether by implication, estoppel or otherwise.
1. Catch2
%% Catch2 NOTICES, INFORMATION, AND LICENSE BEGIN HERE
=========================================
Boost Software License - Version 1.0 - August 17th, 2003
Permission is hereby granted, free of charge, to any person or organization
obtaining a copy of the software and accompanying documentation covered by
this license (the "Software") to use, reproduce, display, distribute,
execute, and transmit the Software, and to prepare derivative works of the
Software, and to permit third-parties to whom the Software is furnished to
do so, all subject to the following:
The copyright notices in the Software and this entire statement, including
the above license grant, this restriction and the following disclaimer,
must be included in all copies of the Software, in whole or in part, and
all derivative works of the Software, unless such copies or derivative
works are solely in the form of machine-executable object code generated by
a source language processor.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
=========================================
END OF Catch2 NOTICES, INFORMATION, AND LICENSE

349
externals/vcpkg/README.md vendored Executable file
View file

@ -0,0 +1,349 @@
# Vcpkg: Overview
[中文总览](README_zh_CN.md)
[Español](README_es.md)
[한국어](README_ko_KR.md)
[Français](README_fr.md)
Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS.
This tool and ecosystem are constantly evolving, and we always appreciate contributions!
If you've never used vcpkg before, or if you're trying to figure out how to use vcpkg,
check out our [Getting Started](#getting-started) section for how to start using vcpkg.
For short description of available commands, once you've installed vcpkg,
you can run `vcpkg help`, or `vcpkg help [command]` for command-specific help.
* Github: ports at [https://github.com/microsoft/vcpkg](https://github.com/microsoft/vcpkg), program at [https://github.com/microsoft/vcpkg-tool](https://github.com/microsoft/vcpkg-tool)
* Slack: [https://cppalliance.org/slack/](https://cppalliance.org/slack/), the #vcpkg channel
* Discord: [\#include \<C++\>](https://www.includecpp.org), the #🌏vcpkg channel
* Docs: [Documentation](docs/README.md)
# Table of Contents
- [Vcpkg: Overview](#vcpkg-overview)
- [Table of Contents](#table-of-contents)
- [Getting Started](#getting-started)
- [Quick Start: Windows](#quick-start-windows)
- [Quick Start: Unix](#quick-start-unix)
- [Installing Linux Developer Tools](#installing-linux-developer-tools)
- [Installing macOS Developer Tools](#installing-macos-developer-tools)
- [Using vcpkg with CMake](#using-vcpkg-with-cmake)
- [Visual Studio Code with CMake Tools](#visual-studio-code-with-cmake-tools)
- [Vcpkg with Visual Studio CMake Projects](#vcpkg-with-visual-studio-cmake-projects)
- [Vcpkg with CLion](#vcpkg-with-clion)
- [Vcpkg as a Submodule](#vcpkg-as-a-submodule)
- [Tab-Completion/Auto-Completion](#tab-completionauto-completion)
- [Examples](#examples)
- [Contributing](#contributing)
- [License](#license)
- [Security](#security)
- [Telemetry](#telemetry)
# Getting Started
First, follow the quick start guide for either
[Windows](#quick-start-windows), or [macOS and Linux](#quick-start-unix),
depending on what you're using.
For more information, see [Installing and Using Packages][getting-started:using-a-package].
If a library you need is not present in the vcpkg catalog,
you can [open an issue on the GitHub repo][contributing:submit-issue]
where the vcpkg team and community can see it,
and potentially add the port to vcpkg.
After you've gotten vcpkg installed and working,
you may wish to add [tab completion](#tab-completionauto-completion) to your shell.
Finally, if you're interested in the future of vcpkg,
check out the [manifest][getting-started:manifest-spec] guide!
This is an experimental feature and will likely have bugs,
so try it out and [open all the issues][contributing:submit-issue]!
## Quick Start: Windows
Prerequisites:
- Windows 7 or newer
- [Git][getting-started:git]
- [Visual Studio][getting-started:visual-studio] 2015 Update 3 or greater with the English language pack
First, download and bootstrap vcpkg itself; it can be installed anywhere,
but generally we recommend using vcpkg as a submodule for CMake projects,
and installing it globally for Visual Studio projects.
We recommend somewhere like `C:\src\vcpkg` or `C:\dev\vcpkg`,
since otherwise you may run into path issues for some port build systems.
```cmd
> git clone https://github.com/microsoft/vcpkg
> .\vcpkg\bootstrap-vcpkg.bat
```
To install the libraries for your project, run:
```cmd
> .\vcpkg\vcpkg install [packages to install]
```
Note: This will install x86 libraries by default. To install x64, run:
```cmd
> .\vcpkg\vcpkg install [package name]:x64-windows
```
Or
```cmd
> .\vcpkg\vcpkg install [packages to install] --triplet=x64-windows
```
You can also search for the libraries you need with the `search` subcommand:
```cmd
> .\vcpkg\vcpkg search [search term]
```
In order to use vcpkg with Visual Studio,
run the following command (may require administrator elevation):
```cmd
> .\vcpkg\vcpkg integrate install
```
After this, you can now create a New non-CMake Project (or open an existing one).
All installed libraries are immediately ready to be `#include`'d and used
in your project without additional configuration.
If you're using CMake with Visual Studio,
continue [here](#vcpkg-with-visual-studio-cmake-projects).
In order to use vcpkg with CMake outside of an IDE,
you can use the toolchain file:
```cmd
> cmake -B [build directory] -S . "-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake"
> cmake --build [build directory]
```
With CMake, you will still need to `find_package` and the like to use the libraries.
Check out the [CMake section](#using-vcpkg-with-cmake) for more information,
including on using CMake with an IDE.
For any other tools, including Visual Studio Code,
check out the [integration guide][getting-started:integration].
## Quick Start: Unix
Prerequisites for Linux:
- [Git][getting-started:git]
- [g++][getting-started:linux-gcc] >= 6
Prerequisites for macOS:
- [Apple Developer Tools][getting-started:macos-dev-tools]
First, download and bootstrap vcpkg itself; it can be installed anywhere,
but generally we recommend using vcpkg as a submodule for CMake projects.
```sh
$ git clone https://github.com/microsoft/vcpkg
$ ./vcpkg/bootstrap-vcpkg.sh
```
To install the libraries for your project, run:
```sh
$ ./vcpkg/vcpkg install [packages to install]
```
You can also search for the libraries you need with the `search` subcommand:
```sh
$ ./vcpkg/vcpkg search [search term]
```
In order to use vcpkg with CMake, you can use the toolchain file:
```sh
$ cmake -B [build directory] -S . "-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake"
$ cmake --build [build directory]
```
With CMake, you will still need to `find_package` and the like to use the libraries.
Check out the [CMake section](#using-vcpkg-with-cmake)
for more information on how best to use vcpkg with CMake,
and CMake Tools for VSCode.
For any other tools, check out the [integration guide][getting-started:integration].
## Installing Linux Developer Tools
Across the different distros of Linux, there are different packages you'll
need to install:
- Debian, Ubuntu, popOS, and other Debian-based distributions:
```sh
$ sudo apt-get update
$ sudo apt-get install build-essential tar curl zip unzip
```
- CentOS
```sh
$ sudo yum install centos-release-scl
$ sudo yum install devtoolset-7
$ scl enable devtoolset-7 bash
```
For any other distributions, make sure you're installing g++ 6 or above.
If you want to add instructions for your specific distro,
[please open a PR][contributing:submit-pr]!
## Installing macOS Developer Tools
On macOS, the only thing you should need to do is run the following in your terminal:
```sh
$ xcode-select --install
```
Then follow along with the prompts in the windows that comes up.
You'll then be able to bootstrap vcpkg along with the [quick start guide](#quick-start-unix)
## Using vcpkg with CMake
### Visual Studio Code with CMake Tools
Adding the following to your workspace `settings.json` will make
CMake Tools automatically use vcpkg for libraries:
```json
{
"cmake.configureSettings": {
"CMAKE_TOOLCHAIN_FILE": "[vcpkg root]/scripts/buildsystems/vcpkg.cmake"
}
}
```
### Vcpkg with Visual Studio CMake Projects
Open the CMake Settings Editor, and under `CMake toolchain file`,
add the path to the vcpkg toolchain file:
```
[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
### Vcpkg with CLion
Open the Toolchains settings
(File > Settings on Windows and Linux, CLion > Preferences on macOS),
and go to the CMake settings (Build, Execution, Deployment > CMake).
Finally, in `CMake options`, add the following line:
```
-DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
You must add this line to each profile.
### Vcpkg as a Submodule
When using vcpkg as a submodule of your project,
you can add the following to your CMakeLists.txt before the first `project()` call,
instead of passing `CMAKE_TOOLCHAIN_FILE` to the cmake invocation.
```cmake
set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
CACHE STRING "Vcpkg toolchain file")
```
This will still allow people to not use vcpkg,
by passing the `CMAKE_TOOLCHAIN_FILE` directly,
but it will make the configure-build step slightly easier.
[getting-started:using-a-package]: docs/examples/installing-and-using-packages.md
[getting-started:integration]: docs/users/buildsystems/integration.md
[getting-started:git]: https://git-scm.com/downloads
[getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
[getting-started:linux-gcc]: #installing-linux-developer-tools
[getting-started:macos-dev-tools]: #installing-macos-developer-tools
[getting-started:macos-brew]: #installing-gcc-on-macos
[getting-started:macos-gcc]: #installing-gcc-on-macos
[getting-started:visual-studio]: https://visualstudio.microsoft.com/
[getting-started:manifest-spec]: docs/specifications/manifests.md
# Tab-Completion/Auto-Completion
`vcpkg` supports auto-completion of commands, package names,
and options in both powershell and bash.
To enable tab-completion in the shell of your choice, run:
```pwsh
> .\vcpkg integrate powershell
```
or
```sh
$ ./vcpkg integrate bash # or zsh
```
depending on the shell you use, then restart your console.
# Examples
See the [documentation](docs/README.md) for specific walkthroughs,
including [installing and using a package](docs/examples/installing-and-using-packages.md),
[adding a new package from a zipfile](docs/examples/packaging-zipfiles.md),
and [adding a new package from a GitHub repo](docs/examples/packaging-github-repos.md).
Our docs are now also available online at our website https://vcpkg.io/. We really appreciate any and all feedback! You can submit an issue in https://github.com/vcpkg/vcpkg.github.io/issues.
See a 4 minute [video demo](https://www.youtube.com/watch?v=y41WFKbQFTw).
# Contributing
Vcpkg is an open source project, and is thus built with your contributions.
Here are some ways you can contribute:
* [Submit Issues][contributing:submit-issue] in vcpkg or existing packages
* [Submit Fixes and New Packages][contributing:submit-pr]
Please refer to our [Contributing Guide](CONTRIBUTING.md) for more details.
This project has adopted the [Microsoft Open Source Code of Conduct][contributing:coc].
For more information see the [Code of Conduct FAQ][contributing:coc-faq]
or email [opencode@microsoft.com](mailto:opencode@microsoft.com)
with any additional questions or comments.
[contributing:submit-issue]: https://github.com/microsoft/vcpkg/issues/new/choose
[contributing:submit-pr]: https://github.com/microsoft/vcpkg/pulls
[contributing:coc]: https://opensource.microsoft.com/codeofconduct/
[contributing:coc-faq]: https://opensource.microsoft.com/codeofconduct/
# License
The code in this repository is licensed under the [MIT License](LICENSE.txt). The libraries
provided by ports are licensed under the terms of their original authors. Where available, vcpkg
places the associated license(s) in the location `installed/<triplet>/share/<port>/copyright`.
# Security
Most ports in vcpkg build the libraries in question using the original build system preferred
by the original developers of those libraries, and download source code and build tools from their
official distribution locations. For use behind a firewall, the specific access needed will depend
on which ports are being installed. If you must install in in an "air gapped" environment, consider
installing once in a non-"air gapped" environment, populating an
[asset cache](docs/users/assetcaching.md) shared with the otherwise "air gapped" environment.
# Telemetry
vcpkg collects usage data in order to help us improve your experience.
The data collected by Microsoft is anonymous.
You can opt-out of telemetry by
- running the bootstrap-vcpkg script with -disableMetrics
- passing --disable-metrics to vcpkg on the command line
- setting the VCPKG_DISABLE_METRICS environment variable
Read more about vcpkg telemetry at docs/about/privacy.md

405
externals/vcpkg/README_es.md vendored Executable file
View file

@ -0,0 +1,405 @@
# Vcpkg
[中文总览](README_zh_CN.md)
[English](README.md)
[한국어](README_ko_KR.md)
[Français](README_fr.md)
Vcpkg ayuda a manejar bibliotecas de C y C++ en Windows, Linux y MacOS.
Esta herramienta y ecosistema se encuentran en constante evolución ¡Siempre apreciamos contribuciones nuevas!
Si nunca ha usado Vcpkg antes,
o si está intentando aprender a usar vcpkg, consulte nuestra sección
[Primeros pasos](#primeros-pasos) para iniciar a usar Vcpkg.
Para una descripción corta de los comandos disponibles,
una vez instalado Vcpkg puede ejecutar `vcpkg help`, o
`vcpkg help [comando]` para obtener ayuda específica de un comando.
* ports en: [vcpkg GitHub](https://github.com/microsoft/vcpkg)
* este programa en: [vcpkg-tool GitHub](https://github.com/microsoft/vcpkg-tool)
* [Slack](https://cppalliance.org/slack/), en el canal #vcpkg
* Discord: [\#include \<C++\>](https://www.includecpp.org), en el canal #🌏vcpkg
* Docs: [Documentación](docs/README.md)
## Tabla de contenido
- [Vcpkg](#vcpkg)
- [Tabla de contenido](#tabla-de-contenido)
- [Primeros pasos](#primeros-pasos)
- [Inicio Rápido: Windows](#inicio-rápido-windows)
- [Inicio rápido: Unix](#inicio-rápido-unix)
- [Instalando Herramientas de desarrollo en Linux](#instalando-herramientas-de-desarrollo-en-linux)
- [Instalando Herramientas de desarrollo en macOS](#instalando-herramientas-de-desarrollo-en-macos)
- [Usando Vcpkg con CMake](#usando-vcpkg-con-cmake)
- [Visual Studio Code con CMake Tools](#visual-studio-code-con-cmake-tools)
- [Vcpkg con proyectos de Visual Studio(CMake)](#vcpkg-con-proyectos-de-visual-studiocmake)
- [Vcpkg con CLion](#vcpkg-con-clion)
- [Vcpkg como Submódulo](#vcpkg-como-submódulo)
- [Inicio rápido: Manifiestos](#inicio-rápido-manifiestos)
- [Completado-Tab/Autocompletado](#completado-tabautocompletado)
- [Ejemplos](#ejemplos)
- [Contribuyendo](#contribuyendo)
- [Licencia](#licencia)
- [Seguridad](#seguridad)
- [Telemetría](#telemetría)
## Primeros pasos
Antes de iniciar, siga la guía ya sea para [Windows](#inicio-rápido-windows),
o [macOS y Linux](#inicio-rápido-unix) dependiendo del SO que use.
Para más información, ver [Instalando y Usando Paquetes][getting-started:using-a-package].
Si una biblioteca que necesita no está presente en el catálogo de vcpkg,
puede [abrir una incidencia en el repositorio de GitHub][contributing:submit-issue]
donde el equipo de vcpkg y la comunidad pueden verlo, y potencialmente hacer un port a vcpkg.
Después de tener Vcpkg instalado y funcionando,
puede que desee añadir [completado con tab](#Completado-TabAuto-Completado) en su terminal.
Finalmente, si está interesado en el futuro de Vcpkg,
puede ver la guía de [archivos de manifiesto][getting-started:manifest-spec]!
esta es una característica experimental y es probable que tenga errores,
así que se recomienda revisar y [crear incidencias][contributing:submit-issue]!
### Inicio Rápido: Windows
Prerrequisitos:
- Windows 7 o superior
- [Git][getting-started:git]
- [Visual Studio][getting-started:visual-studio] 2015 Update 3 o superior con el paquete Inglés de Visual Studio.
Primero, descargue y compile vcpkg; puede ser instalado en cualquier lugar,
pero generalmente recomendamos usar vcpkg como submódulo para proyectos de CMake,
e instalándolo globalmente para Proyectos de Visual Studio.
recomendamos un lugar como `C:\src\vcpkg` o `C:\dev\vcpkg`,
ya que de otra forma puede encontrarse problemas de ruta para algunos sistemas de port.
```cmd
> git clone https://github.com/microsoft/vcpkg
> .\vcpkg\bootstrap-vcpkg.bat
```
Para instalar las bibliotecas para su proyecto, ejecute:
```cmd
> .\vcpkg\vcpkg install [paquetes a instalar]
```
también puede buscar bibliotecas que necesite usar el comando `search`:
```cmd
> .\vcpkg\vcpkg search [término de búsqueda]
```
Para poder utilizar vcpkg con Visual Studio,
ejecute el siguiente comando (puede requerir privilegios de administrador):
```cmd
> .\vcpkg\vcpkg integrate install
```
Después de esto, puede crear un nuevo proyecto que no sea de CMake(MSBuild) o abrir uno existente.
Todas las bibliotecas estarán listas para ser incluidas y
usadas en su proyecto sin configuración adicional.
Si está usando CMake con Visual Studio,
continúe [aquí](#vcpkg-con-proyectos-de-visual-studio\(CMake\)).
Para utilizar Vcpkg con CMake sin un IDE,
puede utilizar el archivo de herramientas incluido:
```cmd
> cmake -B [directorio de compilación] -S . "-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake"
> cmake --build [directorio de compilación]
```
Con CMake, todavía necesitara `find_package` y las configuraciones adicionales de la biblioteca.
Revise la [Sección de Cmake](#usando-vcpkg-con-cmake) para más información,
incluyendo el uso de CMake con un IDE.
Para cualquier otra herramienta, incluyendo Visual Studio Code,
reviste la [guía de integración][getting-started:integration].
### Inicio rápido: Unix
Prerrequisitos para Linux:
- [Git][getting-started:git]
- [G++/GCC][getting-started:linux-gcc] >= 6
Prerrequisitos para macOS:
- [Herramientas de desarrollo de Apple][getting-started:macos-dev-tools]
Primero, descargue y compile vcpkg, puede ser instalado donde sea,
pero recomendamos usar vcpkg como submodulo para proyectos de CMake.
```sh
$ git clone https://github.com/microsoft/vcpkg
$ ./vcpkg/bootstrap-vcpkg.sh
```
Para instalar las bibliotecas para su proyecto, ejecute:
```sh
$ ./vcpkg/vcpkg install [paquetes a instalar]
```
Nota: por defecto se instalarán las bibliotecas x86, para instalar x64, ejecute:
```cmd
> .\vcpkg\vcpkg install [paquete a instalar]:x64-windows
```
O si desea instalar varios paquetes:
```cmd
> .\vcpkg\vcpkg install [paquetes a instalar] --triplet=x64-windows
```
También puede buscar las bibliotecas que necesita con el subcomando `search`:
```sh
$ ./vcpkg/vcpkg search [término de búsqueda]
```
Para usar vcpkg con CMake, tiene que usar el siguiente archivo toolchain:
```sh
$ cmake -B [directorio de compilación] -S . "-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake"
$ cmake --build [directorio de compilación]
```
Con CMake, todavía necesitara `find_package` y las configuraciones adicionales de la biblioteca.
Revise la [Sección de CMake](#usando-vcpkg-con-cmake)
para más información en cómo aprovechar mejor Vcpkg con CMake,
y CMake tools para VSCode.
Para cualquier otra herramienta, visite la [guía de integración][getting-started:integration].
### Instalando Herramientas de desarrollo en Linux
Según las distribuciones de Linux, hay diferentes paquetes
que necesitará instalar:
- Debian, Ubuntu, popOS, y otra distribución basada en Debian:
```sh
$ sudo apt-get update
$ sudo apt-get install build-essential tar curl zip unzip
```
- CentOS
```sh
$ sudo yum install centos-release-scl
$ sudo yum install devtoolset-7
$ scl enable devtoolset-7 bash
```
Para cualquier otra distribución, asegúrese que dispone de g++ 6 o superior.
Si desea añadir instrucción para una distribución específica,
[cree un pull request][contributing:submit-pr]
### Instalando Herramientas de desarrollo en macOS
En macOS 10.15, solo tiene que ejecutar el siguiente comando en la terminal:
```sh
$ xcode-select --install
```
Luego seguir los pasos que aparecerán en las ventanas que se muestran.
Posteriormente podrá compilar vcpkg junto con la [guía de inicio rápido](#inicio-rápido-unix)
### Usando Vcpkg con CMake
¡Si está usando Vcpkg con CMake, lo siguiente puede ayudar!
#### Visual Studio Code con CMake Tools
Agregando lo siguiente al espacio de trabajo `settings.json` permitirá que
CMake Tools use automáticamente Vcpkg para las bibliotecas:
```json
{
"cmake.configureSettings": {
"CMAKE_TOOLCHAIN_FILE": "[raíz de vcpkg]/scripts/buildsystems/vcpkg.cmake"
}
}
```
#### Vcpkg con proyectos de Visual Studio(CMake)
Abra el editor de Ajustes de CMake, bajo la sección `CMake toolchain file`,
posteriormente agregue al path el archivo de cadena de herramientas de Vcpkg:
```sh
[raíz de vcpkg]/scripts/buildsystems/vcpkg.cmake
```
#### Vcpkg con CLion
Abra los ajustes de Cadena de Herramientas (Toolchains)
(File > Settings en Windows y Linux, Clion > Preferences en macOS),
y entre en la sección de ajustes de CMake (Build, Execution, Deployment > CMake).
Finalmente, en `CMake options`, agregue la línea siguiente:
```sh
-DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
Desafortunadamente, tendrá que hacerlo para cada perfil.
#### Vcpkg como Submódulo
Cuando este usando Vcpkg como un submódulo para su proyecto,
puede agregar lo siguiente as su CMakeLists,txt antes de la primera llamada a `project()`,
en vez de pasar `CMAKE_TOOLCHAIN_FILE` a la invocación de CMake.
```cmake
set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
CACHE STRING "Vcpkg toolchain file")
```
Esto permitirá a las personas no usar Vcpkg,
indicando el `CMAKE_TOOLCHAIN_FILE` directamente,
sin embargo, hará el proceso de configuración y compilación más sencillo.
### Inicio rápido: Manifiestos
Así que desea ver cómo será el futuro de Vcpkg!
realmente lo apreciamos. Sin embargo, primero una advertencia:
el soporte de archivos de manifiesto aún está en beta,
aun así la mayoría debería funcionar,
pero no hay garantía de esto y es muy probable que encuentre uno o más bugs
mientras use Vcpkg en este modo.
Adicionalmente, es probablemente que se rompan comportamientos antes de que se pueda considerar estable,
así que está advertido.
Por favor [Abra un Problema][contributing:submit-issue] si encuentra algún error
Primero, instale vcpkg normalmente para [Windows](#inicio-rápido-windows) o
[Unix](#inicio-rápido-unix).
Puede que desee instalar Vcpkg en un lugar centralizado,
ya que el directorio existe localmente,
y está bien ejecutar múltiples comandos desde el mismo directorio de vcpkg al mismo tiempo.
Luego, se requiere activar la bandera de característica `manifests` en vcpkg agregando
`manifests` a los valores separados por coma en la opción `--feature-flags`,
o agregándole en los valores separados por coma en la variable de entorno `VCPKG_FEATURE_FLAGS`
también puede que desee agregar Vcpkg al `PATH`.
Luego, todo lo que hay que hacer es crear un manifiesto;
cree un archivo llamado `vcpkg.json`, y escriba lo siguiente:
```json
{
"name": "<nombre de su proyecto>",
"version-string": "<versión de su proyecto>",
"dependencies": [
"abseil",
"boost"
]
}
```
Las bibliotecas serán instaladas en el directorio `vcpkg_installed`,
en el mismo directorio que su `vcpkg.json`.
Si puede usar el regular conjunto de herramientas de CMake,
o mediante la integración de Visual Studio/MSBuild,
este instalará las dependencias automáticamente,
pero necesitará ajustar `VcpkgManifestEnabled` en `On` para MSBuild.
Si desea instalar sus dependencias sin usar CMake o MSBuild,
puede usar un simple `vcpkg install --feature-flags=manifests`
Para más información, revise la especificación de [manifiesto][getting-started:manifest-spec]
[getting-started:using-a-package]: docs/examples/installing-and-using-packages.md
[getting-started:integration]: docs/users/buildsystems/integration.md
[getting-started:git]: https://git-scm.com/downloads
[getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
[getting-started:linux-gcc]: #Instalando-Herramientas-de-desarrollo-en-Linux
[getting-started:macos-dev-tools]: #Instalando-Herramientas-de-desarrollo-en-macOS
[getting-started:visual-studio]: https://visualstudio.microsoft.com/
[getting-started:manifest-spec]: docs/specifications/manifests.md
## Completado-Tab/Autocompletado
`vcpkg` soporta autocompletado para los comandos, nombres de paquetes,
y opciones, tanto en PowerShell como en bash.
para activar el autocompletado en la terminal de elección ejecute:
```pwsh
> .\vcpkg integrate powershell
```
o
```sh
$ ./vcpkg integrate bash # o zsh
```
según la terminal que use, luego reinicie la consola.
## Ejemplos
ver la [documentación](docs/README.md) para tutoriales específicos, incluyendo
[instalando y usando un paquete](docs/examples/installing-and-using-packages.md),
[agregando un nuevo paquete desde un archivo comprimido](docs/examples/packaging-zipfiles.md),
[agregando un nuevo paquete desde un repositorio en GitHub](docs/examples/packaging-github-repos.md).
Nuestra documentación también esta disponible en nuestro sitio web [vcpkg.io](https://vcpkg.io/).
Si necesita ayuda puede [crear un incidente](https://github.com/vcpkg/vcpkg.github.io/issues).
¡Apreciamos cualquier retroalimentación!
Ver un [video de demostración](https://www.youtube.com/watch?v=y41WFKbQFTw) de 4 minutos.
## Contribuyendo
Vcpkg es un proyecto de código abierto, y está construido con sus contribuciones.
Aquí hay unas de las maneras en las que puede contribuir:
* [Creando Incidencias][contributing:submit-issue] en vcpkg o paquetes existentes
* [Creando Correcciones y Nuevos Paquetes][contributing:submit-pr]
Por favor visite nuestra [Guía de Contribución](CONTRIBUTING.md) para más detalles.
Este proyecto ha adoptado el [Código de Conducta de Microsoft de Código Abierto][contributing:coc].
Para más información ver [Preguntas frecuentes del Código de Conducta][contributing:coc-faq]
o envíe un correo a [opencode@microsoft.com](mailto:opencode@microsoft.com)
con cualquier pregunta adicional o comentarios.
[contributing:submit-issue]: https://github.com/microsoft/vcpkg/issues/new/choose
[contributing:submit-pr]: https://github.com/microsoft/vcpkg/pulls
[contributing:coc]: https://opensource.microsoft.com/codeofconduct/
[contributing:coc-faq]: https://opensource.microsoft.com/codeofconduct/
## Licencia
El código en este repositorio se encuentra licenciado mediante la [Licencia MIT](LICENSE.txt).
Las bibliotecas proveídas por los `ports` están licenciadas mediante los terminos de los autores originales.
Donde estén disponibles, vcpkg almacena las licencias asociadas en la siguiente ubicación `installed/<triplet>/share/<port>/copyright`.
# Seguridad
La mayoría de los `ports` en vcpkg construyen las bibliotecas usando su sistema de compilación preferido
por los autores originales de las bibliotecas, y descargan el código fuente asi como las herramientas de compilación
de sus ubicaciones de distribucion oficiales. Para aquellos que usan un firewall, el acceso dependerá de cuales `ports`
están siendo instalados. Si tiene que instalarlos en un entorno aislado, puede instalarlos previamente en un entorno
no aislado, generando un [caché del paquete](docs/users/assetcaching.md) compartido con el entorno aislado.
## Telemetría
vcpkg recolecta datos de uso para mejorar su experiencia.
La información obtenida por Microsoft es anónima.
puede ser dado de baja de la telemetría realizando lo siguiente:
- ejecutar el script `bootstrap-vcpkg` con el parametro `-disableMetrics`
- agregar el parametro `--disable-metrics` a vcpkg en la línea de comandos
- agregar la variable de entorno `VCPKG_DISABLE_METRICS`
Se puede leer más sobre la telemetría de vcpkg en docs/about/privacy.md

311
externals/vcpkg/README_fr.md vendored Executable file
View file

@ -0,0 +1,311 @@
# Vcpkg: Vue d'ensemble
[中文总览](README_zh_CN.md)
[Español](README_es.md)
Vcpkg vous aide à gérer vos bibliothèques C et C++ sur Windows, Linux et MacOS.
L'outil et l'écosystème sont en évolution constante, et nous apprécions vos contributions!
Si vous n'avez jamais utilisé vcpkg, ou si vous essayez d'utiliser vcpkg, lisez notre [introduction](#introduction) pour comprendre comment l'utiliser.
Pour une description des commandes disponibles, quand vous avez installé vcpkg, vous pouvez lancer `vcpkg help` ou `vcpkg help [commande]` pour de l'aide spécifique à une commande.
* Github: [https://github.com/microsoft/vcpkg](https://github.com/microsoft/vcpkg)
* Slack: [https://cppalliance.org/slack/](https://cppalliance.org/slack/), the #vcpkg channel
* Discord: [\#include \<C++\>](https://www.includecpp.org), le canal #🌏vcpkg
* Docs: [Documentation](docs/README.md)
[![Build Status](https://dev.azure.com/vcpkg/public/_apis/build/status/microsoft.vcpkg.ci?branchName=master)](https://dev.azure.com/vcpkg/public/_build/latest?definitionId=29&branchName=master)
# Sommaire
- [Vcpkg: Vue d'ensemble](#vcpkg-vue-d'ensemble)
- [Sommaire](#Sommaire)
- [Introduction](#introduction)
- [Introduction Windows](#Introduction:-Windows)
- [Introduction Unix](#Introduction-aux-Systèmes-Unix)
- [Installer les prérequis pour linux](#installation-des-prérequis-linux)
- [Installer les prérequis pour macOS](#installation-des-prérequis-macos)
- [Installer GCC pour macOS avant 10.15](#installer-gcc-pour-macos-avant-10.15)
- [Utiliser vcpkg avec CMake](#utiliser-vcpkg-avec-cmake)
- [Visual Studio Code avec CMake Tools](#visual-studio-code-avec-cmake-tools)
- [Vcpkg avec Visual Studio pour un projet CMake](#vcpkg-avec-visual-studio-un-projet-cmake)
- [Vcpkg avec CLion](#vcpkg-avec-clion)
- [Vcpkg en tant que sous module](#vcpkg-en-tant-que-sous-module)
- [Tab-Completion/Auto-Completion](#tab-complétionauto-complétion)
- [Exemples](#exemples)
- [Contribuer](#contribuer)
- [Licence](#licence)
- [Télémétrie](#Télémétrie)
# Introduction
Premièrement, suivez le guide d'introduction [Windows](#Introduction:-Windows), ou [macOS et Linux](#Unix), en fonction de vos besoins.
Pour plus d'information, regardez [utiliser des paquets][getting-started:utiliser-un-paquet].
Si la bibliothèque dont vous avez besoin n'est pas présente dans la liste, vous pouvez [ouvrir une issue sur le repo github](contribuer:faire-une-issue) où l'équipe de vcpkg et la communauté peuvent le voir, et possiblement ajouter le port de vcpkg.
Après avoir installé et lancé vcpkg vous pourriez vouloir ajouter [l'auto-complétion](auto-completion) à votre shell.
Si vous êtes intéressé par le futur de vcpkg, regardez le guide du [manifeste][getting-started:manifest-spec] !
C'est une fonctionnalité expérimentale et possiblement boguée, donc essayez d'[ouvrir des issues](contribuer:envoyer-une-issue) !
# Introduction: Windows
Prérequis :
- Windows 7 ou plus
- [Git][getting-started:git]
+ [Visual Studio][getting-started:visualstudio] 2015 mise à jour 3 où plus récente avec le pack de langue Anglais
Premièrement, téléchargez et lancer le fichier bootstrap-vcpkg; il peut être installé n'importe où mais il est recommandé d'utiliser vcpkg pour des projets CMake. Nous recommandons ces chemins `C:\src\vcpkg` ou `C:\dev\vcpkg`, sinon vous pourriez avoir des problèmes de chemin pour certaines compilations.
```cmd
> git clone https://github.com/microsoft/vcpkg
> .\vcpkg\bootstrap-vcpkg.bat
```
Pour installer des bibliothèques pour votre projet, lancez:
```cmd
> .\vcpkg\vcpkg install [paquets à installer]
```
Vous pouvez aussi chercher la bibliothèque dont vous avez besoin avec l'argument `search`:
```cmd
> .\vcpkg\vcpkg search [terme de recherche]
```
Pour utiliser vcpkg avec Visual Studio, lancez cette commande (pourrait nécessiter d'être lancée avec les droits administrateur)
```cmd
> .\vcpkg\vcpkg integrate install
```
Ensuite, vous pouvez créer un nouveau projet n'utilisant pas CMake (ou en ouvrir un préexistant).
Toutes les bibliothèques installées sont directement prêtes à être `#include` et utilisées sans davantage de configuration.
Si vous utilisez CMake avec Visual Studio continuez [ici](#vcpkg-avec-cmake-et-visual-studio).
Afin d'utiliser vcpkg en dehors d'un IDE, vous pouvez utiliser le fichier de toolchain :
```cmd
> cmake -B [dossier de build] -S . "-DCMAKE_TOOLCHAIN_FILE=[chemin vers vcpkg]/scripts/buildsystems/vcpkg.cmake"
> cmake --build [dossier de build]
```
Avec CMake, vous devrez utiliser `find_package` notamment, et autres, pour compiler.
Regardez la [section CMake](#utiliser-vcpkg-avec-cmake) pour plus d'information, notamment utiliser CMake avec un IDE.
Pour les autres éditeurs, y compris Visual Studio Code regardez le [guide d'intégration](getting-started:integration).
## Introduction aux Systèmes Unix
Prérequis pour Linux :
- [Git][getting-started:git]
- [g++][getting-started:linux-gcc] >= 6
Prérequis pour macOS:
- [Outils de développement Apple][getting-started:macos-dev-tools]
- Pour macOS 10.14 et en dessous, vous aurez besoin de:
- [Homebrew][getting-started:macos-brew]
- [g++][getting-started:macos-gcc] >= 6
Premièrement, clonez et lancez le bootstrap vcpkg; il peut être installé n'importe où mais il est recommandé de l'utiliser comme un sous-module pour projets CMake.
```sh
$ git clone https://github.com/microsoft/vcpkg
$ ./vcpkg/bootstrap-vcpkg.sh
```
Pour installer des bibliothèques pour votre projet, lancez :
```sh
$ ./vcpkg/vcpkg install [paquets à installer]
```
Vous pouvez aussi chercher la bibliothèque dont vous avez besoin avec l'argument `search` :
```sh
$ ./vcpkg/vcpkg search [terme de recherche]
```
Pour utiliser vcpkg en dehors d'un IDE, vous pouvez utiliser le fichier de toolchain :
```cmd
> cmake -B [dossier de build] -S . "-DCMAKE_TOOLCHAIN_FILE=[chemin vers vcpkg]/scripts/buildsystems/vcpkg.cmake"
> cmake --build [dossier de build]
```
Avec CMake, vous devrez utiliser `find_package` notamment, et autres, pour compiler.
Lisez la [section CMake](#utiliser-vcpkg-avec-cmake) pour plus d'information, notamment utiliser CMake avec un IDE.
Pour les autres éditeurs, y compris Visual Studio Code lisez le [guide d'intégration][getting-started:integration].
## Installation des prérequis linux
Pour les différentes distros Linux, il y a différents paquets que vous aurez besoin d'installer :
- Debian, Ubuntu, popOS, et les autres distros basées sur Debian :
```sh
$ sudo apt-get update
$ sudo apt-get install build-essential tar curl zip unzip
```
- CentOS
```sh
$ sudo yum install centos-release-scl
$ sudo yum install devtoolset-7
$ scl enable devtoolset-7 bash
```
Pour les autres distributions, installez au minimum g++ 6.
Si vous voulez ajouter des instructions spécifiques pour votre distro, [ouvrez une PR svp][contribuer:faire-une-pr] !
## Installation des prérequis macOS
Pour macOS 10.15, la seule chose dont vous avez besoin est de lancer cette commande :
```sh
$ xcode-select --install
```
Ensuite suivez les instructions qui s'afficheront dans la fenêtre.
Pour macOS 10.14 et les versions précédentes, vous aurez besoin d'installer g++ avec homebrew; suivez les instructions dans la section suivante.
### Installer GCC pour macOS antérieur à 10.15
Cette partie est seulement nécessaire si vous avez une version de macOS antérieure à 10.15.
Installer homebrew devrait être très simple; pour plus d'informations allez sur <brew.sh>, mais le plus simple est de lancer la commande suivante :
```sh
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
```
Ensuite, afin d'obtenir une version à jour de gcc, lancez la commande suivante :
```sh
$ brew install gcc
```
Ensuite suivez l'[introduction Unix](#Introduction-aux-Systèmes-Unix)
## Utiliser vcpkg avec CMake
Si vous utilisez vcpkg avec CMake, la suite pourrait vous aider !
## Visual Studio Code avec CMake tools
```json
{
"cmake.configureSettings": {
"CMAKE_TOOLCHAIN_FILE": "[vcpkg root]/scripts/buildsystems/vcpkg.cmake"
}
}
```
### Vcpkg avec des projets CMake Visual Studio
Ouvrez les paramètres CMake, et ajoutez le chemin ci-dessous à `CMake toolchain file` :
```
[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
### Vcpkg avec CLion
Ouvrez les paramètres de Toolchains (File > Settings sur Windows et Linux, CLion > Preference pour macOS) et allez dans les paramètres CMake (Build, Execution, Deployment > CMake).
Finalement, dans `CMake options`, ajoutez la ligne suivante :
```
-DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
Malheureusement, vous devrez le refaire pour chaque projet.
### Vcpkg en tant que sous-module
Quand vous utilisez vcpkg comme un sous-module de votre projet, vous pouvez l'ajouter à votre CMakeLists.txt avant le premier appel de `project()`, au lieu d'utiliser `CMAKE_TOOLCHAIN_FILE` dans les paramètres d'appel de cmake.
```cmake
set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
CACHE STRING "Vcpkg toolchain file")
```
Cela permettra toujours aux gens de ne pas utiliser vcpkg, en passant directement le CMAKE_TOOLCHAIN_FILE, mais cela rendra l'étape de configuration-construction légèrement plus facile.
[getting-started:utiliser-un-paquet]: docs/examples/installing-and-using-packages.md
[getting-started:integration]: docs/users/buildsystems/integration.md
[getting-started:git]: https://git-scm.com/downloads
[getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
[getting-started:linux-gcc]: #installing-linux-developer-tools
[getting-started:macos-dev-tools]: #installing-macos-developer-tools
[getting-started:macos-brew]: #installing-gcc-on-macos
[getting-started:macos-gcc]: #installing-gcc-on-macos
[getting-started:visual-studio]: https://visualstudio.microsoft.com/
[getting-started:manifest-spec]: docs/specifications/manifests.md
# Tab-complétion/Auto-complétion
`vcpkg` supporte l'auto-complétion des commandes, nom de paquets, et options dans powershell et bash.
Pour activer la tab-complétion dans le shell de votre choix :
```pwsh
> .\vcpkg integrate powershell
```
ou
```sh
$ ./vcpkg integrate bash
```
selon le shell que vous utilisez, puis redémarrez la console.
# Exemples
Lisez la [documentation](doc/README.md) pour des instructions plus spécifiques ainsi que [l'installation et l'utilisation des paquets](docs/examples/installing-and-using-packages.md),
[ajouter un nouveau paquet depuis un fichier zip](docs/examples/packaging-zipfiles.md),
et [ajouter un nouveau paquet depuis un dépôt GitHub](docs/examples/packaging-github-repos.md).
La documentation est aussi disponible en ligne sur ReadTheDocs : <https://vcpkg.readthedocs.io/> !
Regardez une [démo vidéo]((https://www.youtube.com/watch?v=y41WFKbQFTw) de 4 minutes en anglais.
# Contribuer
Vcpkg est un projet open source, et évolue ainsi avec vos contributions.
Voici quelques moyens pour vous d'y contribuer :
* [Soumettre des Issues][contributing:submit-issue] sur vcpkg ou des paquets existants
* [Proposer des corrections et de nouveaux paquets][contributing:submit-pr]
Veuillez vous référer au [guide de contribution](CONTRIBUTING.md) pour plus de détails.
Ce projet a adopté le [Code de Conduite Open Source de Microsoft][contribuer:coc].
[contributing:submit-issue]: https://github.com/microsoft/vcpkg/issues/new/choose
[contributing:submit-pr]: https://github.com/microsoft/vcpkg/pulls
[contributing:coc]: https://opensource.microsoft.com/codeofconduct/
[contributing:coc-faq]: https://opensource.microsoft.com/codeofconduct/
# Licence
Le code sur ce dépôt est distribué sous [licence MIT](LICENSE.txt).
# Télémétrie
vcpkg collecte des données pour nous aider à améliorer votre expérience.
Les données collectées par Microsoft sont anonymes.
Vous pouvez désactiver la télémétrie en relançant le bootstrap-vcpkg avec l'argument `-disableMetrics`, passer l'argument `--disable-metrics` à chaque exécution de vcpkg, ou en créant une variable d'environnement nommée `VCPKG_DISABLE_METRICS`.
Vous trouverez plus d'informations à propos de la télémétrie dans vcpkg sur cette [page](docs/about/privacy.md).

346
externals/vcpkg/README_ko_KR.md vendored Executable file
View file

@ -0,0 +1,346 @@
# Vcpkg: 개요
[中文总览](README_zh_CN.md)
[Español](README_es.md)
[English](README.md)
[Français](README_fr.md)
Vcpkg는 Windows, Linux 및 MacOS에서 C 및 C++ 라이브러리를 관리하는 데 도움을 주는 라이브러리입니다.
이 도구와 생태계는 지속적으로 진화하고 있으며, 저희는 기여를 언제나 환영합니다!
이전에 vcpkg를 사용한 적이 없거나 vcpkg를 사용하는 방법을 알고 싶을 경우,
아래의 [시작하기](#시작하기) 단락을 확인하면 vcpkg 사용을 시작하는 방법이 설명되어 있습니다.
Vcpkg를 설치하였다면, `vcpkg help` 명령어로 사용 가능한 명령어에 대한 간단한 설명을 볼 수 있습니다.
`vcpkg help [command]` 명령어로는 각 명령어별 도움말을 볼 수 있습니다.
* Github: port는 [https://github.com/microsoft/vcpkg](https://github.com/microsoft/vcpkg)에, 관련 프로그램은 [https://github.com/microsoft/vcpkg-tool](https://github.com/microsoft/vcpkg-tool)에 있습니다.
* Slack: [https://cppalliance.org/slack/](https://cppalliance.org/slack/), #vcpkg 채널
* Discord: [\#include \<C++\>](https://www.includecpp.org), #🌏vcpkg 채널
* 도움말: [Documentation](docs/README.md)
# 목차
- [Vcpkg: 개요](#vcpkg-개요)
- [목차](#목차)
- [시작하기](#시작하기)
- [빠르게 시작하기: Windows](#빠르게-시작하기-windows)
- [빠르게 시작하기: Unix](#빠르게-시작하기-unix)
- [Linux 개발자 도구 설치하기](#linux-개발자-도구-설치하기)
- [macOS 개발자 도구 설치하기](#macos-개발자-도구-설치하기)
- [CMake와 함께 vcpkg 사용](#cmake와-함께-vcpkg-사용)
- [Visual Studio Code와 CMake Tools](#visual-studio-code와-cmake-tools)
- [Vcpkg와 Visual Studio CMake 프로젝트](#vcpkg와-visual-studio-cmake-프로젝트)
- [Vcpkg와 CLion](#vcpkg와-clion)
- [서브모듈로 vcpkg 사용하기](#서브모듈로-vcpkg-사용하기)
- [탭 완성/자동 완성](#탭-완성자동-완성)
- [예시](#예시)
- [기여하기](#기여하기)
- [라이선스](#라이선스)
- [보안](#보안)
- [데이터 수집](#데이터-수집)
# 시작하기
먼저, 사용하는 운영체제에 따라
[윈도우](#빠르게-시작하기-windows) 또는 [macOS와 Linux](#빠르게-시작하기-unix)
빠르게 시작하기 가이드를 따라가세요.
더 자세한 정보는 [패키지 설치 및 사용][getting-started:using-a-package]에 있습니다.
만약 필요한 라이브러리가 vcpkg 카탈로그에 없는 경우,
[GitHub 저장소에서 이슈를 열 ​​수 있습니다][contributing:submit-issue].
Vcpkg 팀과 커뮤니티가 이슈를 확인하면, 해당하는 port를 추가할 수 있습니다.
Vcpkg의 설치가 완료되었다면,
셸에 [탭 완성](#탭-완성자동-완성)을 추가할 수 있습니다.
마지막으로, vcpkg의 미래에 관심이 있다면,
[manifest][getting-started:manifest-spec] 가이드를 확인하세요!
이것은 실험적인 기능이며 버그가 있을 가능성이 높습니다.
시도해보고 문제가 있다면 [이슈를 열어주세요][contributing:submit-issue]!
## 빠르게 시작하기: Windows
필요조건:
- Windows 7 이상
- [Git][getting-started:git]
- [Visual Studio][getting-started:visual-studio] 영어 언어팩이 설치된 2015 Update 3 버전 이상
첫번째로, vcpkg 자체를 다운로드하고 부트스트랩합니다. Vcpkg는 어디에나 설치할 수 있지만,
일반적으로 CMake 프로젝트는 vcpkg를 submodule로 사용하는 것을,
Visual Studio 프로젝트는 시스템에 설치하는 것을 추천합니다.
시스템 설치는 `C:\src\vcpkg` 나 `C:\dev\vcpkg` 등의 위치에 하는 것을 권장하는데,
그렇지 않으면 일부 포트 빌드 시스템에서 경로 문제가 발생할 수도 있기 때문입니다.
```cmd
> git clone https://github.com/microsoft/vcpkg
> .\vcpkg\bootstrap-vcpkg.bat
```
당신의 프로젝트에 라이브러리를 설치하려면 다음 명령을 실행하세요.
```cmd
> .\vcpkg\vcpkg install [packages to install]
```
참고로, 위 명령은 x86 라이브러리를 설치하는 것이 기본 설정입니다. 만약 x64 버전을
설치하고 싶다면, 다음 명령을 실행하세요.
```cmd
> .\vcpkg\vcpkg install [package name]:x64-windows
```
또는 이렇게도 가능합니다.
```cmd
> .\vcpkg\vcpkg install [packages to install] --triplet=x64-windows
```
다음과 같이 `search` 하위 명령어를 사용하여 필요한 라이브러리를 검색할 수도 있습니다.
```cmd
> .\vcpkg\vcpkg search [search term]
```
Visual Studio에서 vcpkg를 사용하려면
다음 명령을 실행해야 합니다(관리자 권한이 필요할 수도 있습니다).
```cmd
> .\vcpkg\vcpkg integrate install
```
이제 CMake를 사용하지 않는 프로젝트도 만들 수 (또는 기존 프로젝트를 열 수) 있습니다.
설치한 모든 라이브러리는 추가 설정 없이도 프로젝트에서 즉시 `# include` 및 사용할 수 있습니다.
Visual Studio에서 CMake를 사용하는 경우,
[여기를 보세요](#vcpkg와-visual-studio-cmake-프로젝트).
IDE 외부에서 CMake와 함께 vcpkg를 사용하려면,
다음과 같이 툴체인 파일을 사용할 수 있습니다.
```cmd
> cmake -B [build directory] -S . "-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake"
> cmake --build [build directory]
```
CMake에서 라이브러리를 사용하려면 여전히 `find_package` 등이 필요합니다.
CMake를 IDE와 사용하는 방법을 포함한
자세한 정보는 [CMake 섹션](#cmake와-함께-vcpkg-사용)을 확인하세요.
Visual Studio Code를 포함한 다른 툴의 경우
[통합 가이드][getting-started:integration]를 확인하세요.
## 빠르게 시작하기: Unix
Linux에서의 필요조건:
- [Git][getting-started:git]
- [g++][getting-started:linux-gcc] >= 6
macOS에서의 필요조건:
- [Apple Developer Tools][getting-started:macos-dev-tools]
우선, vcpkg 자체를 다운로드하고 설치해야 합니다. 어디에나 설치할 수 있지만,
일반적으로 CMake 프로젝트의 하위 모듈로 vcpkg를 사용하는 것이 좋습니다.
```sh
$ git clone https://github.com/microsoft/vcpkg
$ ./vcpkg/bootstrap-vcpkg.sh
```
프로젝트에 라이브러리를 설치하려면 다음 명령을 실행하세요.
```sh
$ ./vcpkg/vcpkg install [packages to install]
```
다음과 같이 `search` 하위 명령어를 사용하여 필요한 라이브러리를 검색할 수도 있습니다.
```sh
$ ./vcpkg/vcpkg search [search term]
```
CMake와 함께 vcpkg를 사용하려면 툴체인 파일을 이용해 보세요.
```sh
$ cmake -B [build directory] -S . "-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake"
$ cmake --build [build directory]
```
CMake에서 라이브러리를 사용하려면 여전히 `find_package` 등이 필요합니다.
CMake와 VSCode를 위한 CMake Tools를 vcpkg와 함께 사용하는 최선의 방법을 포함한
자세한 정보는 [CMake 섹션](#cmake와-함께-vcpkg-사용)을 확인하세요.
다른 툴에 대해서는 [통합 가이드][getting-started:integration]를 확인하세요.
## Linux 개발자 도구 설치하기
Linux의 배포판별로 설치해야 하는 개발자 소프트웨어가 다릅니다.
- Debian, Ubuntu, popOS 및 기타 Debian 기반 배포판
```sh
$ sudo apt-get update
$ sudo apt-get install build-essential tar curl zip unzip
```
- CentOS
```sh
$ sudo yum install centos-release-scl
$ sudo yum install devtoolset-7
$ scl enable devtoolset-7 bash
```
다른 배포판의 경우, g++ 6 이상의 버전을 설치하여야 합니다.
특정 배포판에 대한 안내를 추가하고 싶은 경우,
[PR을 열어주세요][contributing:submit-pr]!
## macOS 개발자 도구 설치하기
macOS에서는 터미널에서 다음 명령어를 실행하기만 하면 됩니다.
```sh
$ xcode-select --install
```
그런 다음 나타나는 창의 안내에 따르세요.
설치가 끝나면 [빠른 시작 가이드](#빠르게-시작하기-unix)를 참고하여 vcpkg를 설치하세요.
## CMake와 함께 vcpkg 사용
CMake와 함께 vcpkg를 사용하는 경우, 다음 내용이 도움이 될 것입니다!
### Visual Studio Code와 CMake Tools
Workspace `settings.json` 파일에 다음을 추가하면
CMake Tools는 자동으로 vcpkg의 라이브러리를 사용할 것입니다.
```json
{
"cmake.configureSettings": {
"CMAKE_TOOLCHAIN_FILE": "[vcpkg root]/scripts/buildsystems/vcpkg.cmake"
}
}
```
### Vcpkg와 Visual Studio CMake 프로젝트
CMake 설정 편집기를 열고 `CMake toolchain file`에서
vcpkg 툴체인 파일에 경로를 추가합니다.
```
[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
### Vcpkg와 CLion
Toolchains settings을 엽니다.
(File > Settings on Windows and Linux, CLion > Preferences on macOS),
그리고 CMake 세팅을 엽니다 (Build, Execution, Deployment > CMake).
마지막으로 `CMake options`에서 다음 줄을 추가합니다.
```
-DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
각 프로필에 이것을 추가해야합니다.
### 서브모듈로 vcpkg 사용하기
프로젝트의 서브모듈로 vcpkg를 사용하는 경우,
cmake 실행 시 `CMAKE_TOOLCHAIN_FILE`을 전달하는 대신,
첫 번째 `project()` 호출 전에 CMakeLists.txt에 다음을 추가하는 방법도 있습니다.
```cmake
set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
CACHE STRING "Vcpkg toolchain file")
```
이렇게 하면 설정-빌드 단계가 약간 더 쉬워집니다.
또한, 여전히 `CMAKE_TOOLCHAIN_FILE`을 직접 전달하면
vcpkg를 사용하지 않을 수 있습니다.
[getting-started:using-a-package]: docs/examples/installing-and-using-packages.md
[getting-started:integration]: docs/users/buildsystems/integration.md
[getting-started:git]: https://git-scm.com/downloads
[getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
[getting-started:linux-gcc]: #installing-linux-developer-tools
[getting-started:macos-dev-tools]: #installing-macos-developer-tools
[getting-started:macos-brew]: #installing-gcc-on-macos
[getting-started:macos-gcc]: #installing-gcc-on-macos
[getting-started:visual-studio]: https://visualstudio.microsoft.com/
[getting-started:manifest-spec]: docs/specifications/manifests.md
# 탭 완성/자동 완성
`vcpkg`는 powershell과 bash 모두에서 명령, 패키지 이름 및 옵션의 자동 완성을 지원합니다.
선택한 셸에서 탭 완성을 활성화하려면 다음 두 명령어 중 하나를 실행합니다.
```pwsh
> .\vcpkg integrate powershell
```
```sh
$ ./vcpkg integrate bash # or zsh
```
그 다음 콘솔을 재시작하세요.
# 예시
[패키지 설치 및 사용](docs/examples/installing-and-using-packages.md),
[zip 파일에서 새 패키지 추가](docs/examples/packaging-zipfiles.md),
[GitHub 저장소에서 새 패키지 추가](docs/examples/packaging-github-repos.md)에
대한 구체적인 예시는 [문서](docs/README.md)를 참고하세요.
문서는 이제 웹사이트 https://vcpkg.io/ 에서도 온라인으로 확인 가능합니다. 모든 피드백에 진심으로 감사드립니다!
https://github.com/vcpkg/vcpkg.github.io/issues 에서 이슈를 제출할 수 있습니다.
[4분짜리 데모 영상도 준비되어 있습니다](https://www.youtube.com/watch?v=y41WFKbQFTw).
# 기여하기
Vcpkg는 오픈소스 프로젝트입니다, 따라서 여러분의 기여를 통해 만들어집니다.
기여할 수 있는 몇 가지 방법은 다음과 같습니다.
* Vcpkg 또는 vcpkg에 포함된 패키지의 [이슈 제출][contributing:submit-issue]
* [수정 사항 및 새 패키지 제출][contributing:submit-pr]
자세한 내용은 [기여 가이드](CONTRIBUTING.md)를 참고하세요.
이 프로젝트는 [Microsoft Open Source Code of Conduct][contributing:coc]을 채택했습니다.
더 많은 정보를 얻고 싶다면 [Code of Conduct FAQ][contributing:coc-faq] 문서를 참고하세요.
추가 질문이나 의견은 이메일 [opencode@microsoft.com](mailto:opencode@microsoft.com)로 보내주세요.
[contributing:submit-issue]: https://github.com/microsoft/vcpkg/issues/new/choose
[contributing:submit-pr]: https://github.com/microsoft/vcpkg/pulls
[contributing:coc]: https://opensource.microsoft.com/codeofconduct/
[contributing:coc-faq]: https://opensource.microsoft.com/codeofconduct/
# 라이선스
이 저장소의 코드는 [MIT 라이선스](LICENSE.txt)에 따라 사용이 허가됩니다. Port로 제공되는
라이브러리는 각 라이브러리의 원저자가 설정한 라이선스에 따라 제공됩니다. 가능한 경우, vcpkg는
`installed/<triplet>/share/<port>/copyright`에 관련된 라이선스를 저장합니다.
# 보안
Vcpk가 제공하는 대부분의 port는 각각의 라이브러리를 빌드할 때
원 개발자들이 권장하는 빌드 시스템을 이용하고,
소스 코드와 빌드 도구를 각각의 공식 배포처로부터 다운로드합니다.
방화벽 뒤에서 사용하는 경우, 어떤 port를 설치하느냐에 따라 필요한 접근 권한이 달라질 수 있습니다.
만약 "air gapped" 환경에서 설치해야만 한다면, "air gapped"가 아닌 환경에서
[asset 캐시](docs/users/assetcaching.md)를 다운로드하고,
이후에 "air gapped" 환경에서 공유하는 것을 고려해 보십시오.
# 데이터 수집
vcpkg는 사용자 경험을 개선하는 데 도움이 되도록 사용 데이터를 수집합니다.
Microsoft는 이 정보를 익명으로 수집합니다.
다음을 통해 원격 정보 제공을 비활성화할 수 있습니다.
- -disableMetrics 옵션을 포함하여 bootstrap-vcpkg 스크립트 실행
- 명령줄에서 vcpkg에 --disable-metrics 전달
- VCPKG_DISABLE_METRICS 환경 변수 설정
docs/about/privacy.md에서 vcpkg 데이터 수집에 대해 자세히 알아보세요.

318
externals/vcpkg/README_zh_CN.md vendored Executable file
View file

@ -0,0 +1,318 @@
# Vcpkg: 总览
[English Overview](README.md)
Vcpkg 可帮助您在 Windows、 Linux 和 MacOS 上管理 C 和 C++ 库。
这个工具和生态链正在不断发展，我们一直期待您的贡献！
若您从未使用过vcpkg，或者您正在尝试了解如何使用vcpkg，请查阅 [入门](#入门) 章节。
如需获取有关可用命令的简短描述，请在编译vcpkg后执行 `vcpkg help` 或执行 `vcpkg help [command]` 来获取具体的帮助信息。
* Github: [https://github.com/microsoft/vcpkg](https://github.com/microsoft/vcpkg)
* Slack: [https://cppalliance.org/slack/](https://cppalliance.org/slack/)， #vcpkg 频道
* Discord: [\#include \<C++\>](https://www.includecpp.org)， #🌏vcpkg 频道
* 文档: [Documentation](docs/README.md)
[![当前生成状态](https://dev.azure.com/vcpkg/public/_apis/build/status/microsoft.vcpkg.ci?branchName=master)](https://dev.azure.com/vcpkg/public/_build/latest?definitionId=29&branchName=master)
# 目录
- [Vcpkg: 总览](#vcpkg-总览)
- [目录](#目录)
- [入门](#入门)
- [快速开始: Windows](#快速开始-windows)
- [快速开始: Unix](#快速开始-unix)
- [安装 Linux Developer Tools](#安装-linux-developer-tools)
- [安装 macOS Developer Tools](#安装-macos-developer-tools)
- [在 CMake 中使用 vcpkg](#在-cmake-中使用-vcpkg)
- [Visual Studio Code 中的 CMake Tools](#visual-studio-code-中的-cmake-tools)
- [Visual Studio CMake 工程中使用 vcpkg](#visual-studio-cmake-工程中使用-vcpkg)
- [CLion 中使用 vcpkg](#clion-中使用-vcpkg)
- [将 vcpkg 作为一个子模块](#将-vcpkg-作为一个子模块)
- [Tab补全/自动补全](#tab补全自动补全)
- [示例](#示例)
- [贡献](#贡献)
- [开源协议](#开源协议)
- [数据收集](#数据收集)
# 入门
首先，请阅读以下任一快速入门指南：
[Windows](#快速开始-windows) 或 [macOS和Linux](#快速开始-unix)，
这取决于您使用的是什么平台。
有关更多信息，请参见 [安装和使用软件包][getting-started:using-a-package]。
如果vcpkg目录中没有您需要的库，
您可以 [在GitHub上打开问题][contributing:submit-issue]。
vcpkg团队和贡献者可以看到它的地方，
并可能将这个库添加到vcpkg。
安装并运行vcpkg后，
您可能希望将 [TAB补全](#tab补全自动补全) 添加到您的Shell中。
最后，如果您对vcpkg的未来感兴趣，请查看 [清单][getting-started:manifest-spec]！
这是一项实验性功能，可能会出现错误。
因此，请尝试一下并[打开所有问题][contributing:submit-issue]!
## 快速开始: Windows
前置条件:
- Windows 7 或更新的版本
- [Git][getting-started:git]
- [Visual Studio 2015 Update 3][getting-started:visual-studio] 或更新的版本（**包含英文语言包**）
首先，**请使用git clone vcpkg** 并执行 bootstrap.bat 脚本。
您可以将vcpkg安装在任何地方，但是通常我们建议您使用 vcpkg 作为 CMake 项目的子模块，并将其全局安装到 Visual Studio 项目中。
我们建议您使用例如 `C:\src\vcpkg` 或 `C:\dev\vcpkg` 的安装目录，否则您可能遇到某些库构建系统的路径问题。
```cmd
> git clone https://github.com/microsoft/vcpkg
> .\vcpkg\bootstrap-vcpkg.bat
```
使用以下命令安装您的项目所需要的库：
```cmd
> .\vcpkg\vcpkg install [packages to install]
```
请注意: vcpkg在Windows中默认编译并安装x86版本的库。 若要编译并安装x64版本，请执行:
```cmd
> .\vcpkg\vcpkg install [package name]:x64-windows
```
或
```cmd
> .\vcpkg\vcpkg install [packages to install] --triplet=x64-windows
```
您也可以使用 `search` 子命令来查找vcpkg中集成的库:
```cmd
> .\vcpkg\vcpkg search [search term]
```
若您希望在 Visual Studio 中使用vcpkg，请运行以下命令 (可能需要管理员权限)
```cmd
> .\vcpkg\vcpkg integrate install
```
在此之后，您可以创建一个非cmake项目 (或打开已有的项目)。
在您的项目中，所有已安装的库均可立即使用 `#include` 包含您需使用的库的头文件且无需额外配置。
若您在 Visual Studio 中使用cmake工程，请查阅[这里](#visual-studio-cmake-工程中使用-vcpkg)。
为了在IDE以外在cmake中使用vcpkg，您需要使用以下工具链文件:
```cmd
> cmake -B [build directory] -S . "-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake"
> cmake --build [build directory]
```
在cmake中，您仍需通过 `find_package` 来使用vcpkg中已安装的库。
请查阅 [CMake 章节](#在-cmake-中使用-vcpkg) 获取更多信息，其中包含了在IDE中使用cmake的内容。
对于其他工具 (包括Visual Studio Code)，请查阅 [集成指南][getting-started:integration]。
## 快速开始: Unix
Linux平台前置条件:
- [Git][getting-started:git]
- [g++][getting-started:linux-gcc] >= 6
macOS平台前置条件:
- [Apple Developer Tools][getting-started:macos-dev-tools]
首先，**请使用git clone vcpkg** 并执行 bootstrap.sh 脚本。
我们建议您将vcpkg作为cmake项目的子模块使用。
```sh
$ git clone https://github.com/microsoft/vcpkg
$ ./vcpkg/bootstrap-vcpkg.sh
```
使用以下命令安装任意包：
```sh
$ ./vcpkg/vcpkg install [packages to install]
```
您也可以使用 `search` 子命令来查找vcpkg中已集成的库:
```sh
$ ./vcpkg/vcpkg search [search term]
```
为了在cmake中使用vcpkg，您需要使用以下工具链文件:
```sh
$ cmake -B [build directory] -S . "-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake"
$ cmake --build [build directory]
```
在cmake中，您仍需通过 `find_package` 来使用vcpkg中已安装的库。
为了您更好的在cmake或 VSCode CMake Tools 中使用vcpkg，
请查阅 [CMake 章节](#在-cmake-中使用-vcpkg) 获取更多信息，
其中包含了在IDE中使用cmake的内容。
对于其他工具，请查阅 [集成指南][getting-started:integration]。
## 安装 Linux Developer Tools
在Linux的不同发行版中，您需要安装不同的工具包:
- Debian，Ubuntu，popOS或其他基于 Debian 的发行版:
```sh
$ sudo apt-get update
$ sudo apt-get install build-essential tar curl zip unzip
```
- CentOS
```sh
$ sudo yum install centos-release-scl
$ sudo yum install devtoolset-7
$ scl enable devtoolset-7 bash
```
对于其他的发行版，请确保已安装 g++ 6 或更新的版本。
若您希望添加特定发行版的说明，[请提交一个 PR][contributing:submit-pr]!
## 安装 macOS Developer Tools
在 macOS 中，您唯一需要做的是在终端中运行以下命令:
```sh
$ xcode-select --install
```
然后按照出现的窗口中的提示进行操作。
此时，您就可以使用 bootstrap.sh 编译vcpkg了。 请参阅 [快速开始](#快速开始-unix)
## 在 CMake 中使用 vcpkg
若您希望在CMake中使用vcpkg，以下内容可能帮助您：
### Visual Studio Code 中的 CMake Tools
将以下内容添加到您的工作区的 `settings.json` 中将使CMake Tools自动使用vcpkg中的第三方库:
```json
{
"cmake.configureSettings": {
"CMAKE_TOOLCHAIN_FILE": "[vcpkg root]/scripts/buildsystems/vcpkg.cmake"
}
}
```
### Visual Studio CMake 工程中使用 vcpkg
打开CMake设置选项，将 vcpkg toolchain 文件路径在 `CMake toolchain file` 中：
```
[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
### CLion 中使用 vcpkg
打开 Toolchains 设置
(File > Settings on Windows and Linux, CLion > Preferences on macOS)，
并打开 CMake 设置 (Build, Execution, Deployment > CMake)。
最后在 `CMake options` 中添加以下行:
```
-DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
遗憾的是，您必须手动将此选项加入每个项目配置文件中。
### 将 vcpkg 作为一个子模块
当您希望将vcpkg作为一个子模块加入到您的工程中时，
您可以在第一个 `project()` 调用之前将以下内容添加到 CMakeLists.txt 中，
而无需将 `CMAKE_TOOLCHAIN_FILE` 传递给cmake调用。
```cmake
set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
CACHE STRING "Vcpkg toolchain file")
```
使用此种方式可无需设置 `CMAKE_TOOLCHAIN_FILE` 即可使用vcpkg，且更容易完成配置工作。
[getting-started:using-a-package]: docs/examples/installing-and-using-packages.md
[getting-started:integration]: docs/users/buildsystems/integration.md
[getting-started:git]: https://git-scm.com/downloads
[getting-started:cmake-tools]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
[getting-started:linux-gcc]: #installing-linux-developer-tools
[getting-started:macos-dev-tools]: #installing-macos-developer-tools
[getting-started:macos-brew]: #installing-gcc-on-macos
[getting-started:macos-gcc]: #installing-gcc-on-macos
[getting-started:visual-studio]: https://visualstudio.microsoft.com/
[getting-started:manifest-spec]: docs/specifications/manifests.md
# Tab补全/自动补全
`vcpkg` 支持命令，包名称，以及 Powershell 和 Bash 中的选项。
若您需要在指定的 shell 中启用Tab补全功能，请依据您使用的shell运行：
```pwsh
> .\vcpkg integrate powershell
```
或
```sh
$ ./vcpkg integrate bash # 或 zsh
```
然后重新启动控制台。
## 示例
请查看 [文档](docs/README.md) 获取具体示例，
其包含 [安装并使用包](docs/examples/installing-and-using-packages.md)，
[使用压缩文件添加包](docs/examples/packaging-zipfiles.md)
和 [从GitHub源中添加一个包](docs/examples/packaging-github-repos.md)。
我们的文档现在也可以从 [vcpkg.io](https://vcpkg.io/) 在线获取。
我们真诚的希望您向我们提出关于此网站的任何建议! 请在[这里](https://github.com/vcpkg/vcpkg.github.io/issues) 打开issue.
观看4分钟 [demo视频](https://www.youtube.com/watch?v=y41WFKbQFTw)。
## 贡献
Vcpkg是一个开源项目，并通过您的贡献不断发展。
下面是一些您可以贡献的方式:
* [提交一个关于vcpkg或已支持包的新issue][contributing:submit-issue]
* [提交修复PR和创建新包][contributing:submit-pr]
请参阅我们的 [贡献准则](CONTRIBUTING_zh.md) 了解更多详细信息。
该项目采用了 [Microsoft开源行为准则][contributing:coc]。
获取更多信息请查看 [行为准则FAQ][contributing:coc-faq] 或联系 [opencode@microsoft.com](mailto:opencode@microsoft.com) 提出其他问题或意见。
[contributing:submit-issue]: https://github.com/microsoft/vcpkg/issues/new/choose
[contributing:submit-pr]: https://github.com/microsoft/vcpkg/pulls
[contributing:coc]: https://opensource.microsoft.com/codeofconduct/
[contributing:coc-faq]: https://opensource.microsoft.com/codeofconduct/
# 开源协议
在此存储库中使用的代码均遵循 [MIT License](LICENSE.txt)。
# 数据收集
vcpkg会收集使用情况数据，以帮助我们改善您的体验。
Microsoft收集的数据是匿名的。
您也可以通过以下步骤禁用数据收集：
- 将选项 `-disableMetrics` 传递给 bootstrap-vcpkg 脚本并重新运行此脚本
- 向 vcpkg 命令传递选项 `--disable-metrics`
- 设置环境变量 `VCPKG_DISABLE_METRICS`
请在 [privacy.md](docs/about/privacy.md) 中了解有关 vcpkg 数据收集的更多信息。

41
externals/vcpkg/SECURITY.md vendored Executable file
View file

@ -0,0 +1,41 @@
<!-- BEGIN MICROSOFT SECURITY.MD V0.0.7 BLOCK -->
## Security
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/).
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.
## Reporting Security Issues
**Please do not report security vulnerabilities through public GitHub issues.**
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).
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).
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).
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:
* Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
* Full paths of source file(s) related to the manifestation of the issue
* The location of the affected source code (tag/branch/commit or direct URL)
* Any special configuration required to reproduce the issue
* Step-by-step instructions to reproduce the issue
* Proof-of-concept or exploit code (if possible)
* Impact of the issue, including how an attacker might exploit the issue
This information will help us triage your report more quickly.
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.
## Preferred Languages
We prefer all communications to be in English.
## Policy
Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd).
<!-- END MICROSOFT SECURITY.MD BLOCK -->

2
externals/vcpkg/bootstrap-vcpkg.bat vendored Executable file
View file

@ -0,0 +1,2 @@
@echo off
powershell.exe -NoProfile -ExecutionPolicy Bypass "& {& '%~dp0scripts\bootstrap.ps1' %*}"

4
externals/vcpkg/bootstrap-vcpkg.sh vendored Executable file
View file

@ -0,0 +1,4 @@
#!/bin/sh -e
vcpkgRootDir=$(X= cd -- "$(dirname -- "$0")" && pwd -P)
. "$vcpkgRootDir/scripts/bootstrap.sh"

75
externals/vcpkg/docs/README.md vendored Executable file
View file

@ -0,0 +1,75 @@
### Quick Start
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/README.md).**
Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This tool and ecosystem are constantly evolving; your involvement is vital to its success!
### Examples
- [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md)
- [Packaging Zipfiles Example: zlib](examples/packaging-zipfiles.md)
- [Packaging GitHub Repositories Example: libogg](examples/packaging-github-repos.md)
- [Patching Example: Patching libpng to work for x64-uwp](examples/patching.md)
- [Getting Started with Versioning](examples/versioning.getting-started.md)
### Command Line Reference
- [Command Line Reference](commands/index.md)
### User Help
- [Buildsystem Integration](users/buildsystems/integration.md)
- [Triplet files](users/triplets.md)
- [Configuration and Environment](users/config-environment.md)
- [Authentication](users/authentication.md)
- [Manifest Mode](users/manifests.md)
- [Binary Caching](users/binarycaching.md)
- [Asset Caching](users/assetcaching.md)
- [Versioning](users/versioning.md)
- [Usage with Android](users/android.md)
- [Usage with Mingw-w64](users/mingw.md)
- [Host Dependencies](users/host-dependencies.md)
- [Using Registries](users/registries.md)
### Maintainer Help
- [Manifest Files - vcpkg.json](maintainers/manifest-files.md)
- [Control Files](maintainers/control-files.md)
- [Portfile Functions](maintainers/portfile-functions.md)
- [Authoring Script Ports](maintainers/authoring-script-ports.md)
- [Common CMake Definitions](maintainers/vcpkg_common_definitions.md)
- [Maintainer Guidelines](maintainers/maintainer-guide.md)
- [Creating Registries](maintainers/registries.md)
- [CMake Guidelines](maintainers/cmake-guidelines.md)
### [Vcpkg-Tool](https://github.com/microsoft/vcpkg-tool) Maintainer Help
- [Testing](https://github.com/microsoft/vcpkg-tool/tree/main/docs/testing.md)
- [Benchmarking](https://github.com/microsoft/vcpkg-tool/tree/main/docs/benchmarking.md)
- [Layout of the vcpkg source tree](https://github.com/microsoft/vcpkg-tool/tree/main/docs/layout.md)
### Community Resources (not directly affiliated with vcpkg)
- [vcpkg.info](https://vcpkg.info/) - Package index + search
- [vcpkgx](https://vcpkgx.com/) - Package index + search
- [vcpkg index](https://vcpkg.dev/) - Package index + search
### Blog posts
- [Vcpkg Host Dependencies for Cross-Compilation](https://devblogs.microsoft.com/cppblog/vcpkg-host-dependencies/)
- [Registries: Bring your own libraries to vcpkg](https://devblogs.microsoft.com/cppblog/registries-bring-your-own-libraries-to-vcpkg/)
- [Vcpkg: Accelerate your team development environment with binary caching and manifests](https://devblogs.microsoft.com/cppblog/vcpkg-accelerate-your-team-development-environment-with-binary-caching-and-manifests/)
- [Vcpkg: 2019.06 Update (overlay ports, overlay triplets, `vcpkg_check_features`)](https://devblogs.microsoft.com/cppblog/vcpkg-2019-06-update/)
- [Announcing a single C++ library manager for Linux, macOS and Windows: Vcpkg](https://blogs.msdn.microsoft.com/vcblog/2018/04/24/announcing-a-single-c-library-manager-for-linux-macos-and-windows-vcpkg/)
- [Vcpkg: Using multiple enlistments to handle multiple versions of a library](https://blogs.msdn.microsoft.com/vcblog/2017/10/23/vcpkg-using-multiple-enlistments/)
- [Vcpkg: introducing the export command](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/)
- [Binary Compatibility and Pain-free Upgrade Why Moving to Visual Studio 2017 is almost "too easy"](https://blogs.msdn.microsoft.com/vcblog/2017/03/07/binary-compatibility-and-pain-free-upgrade-why-moving-to-visual-studio-2017-is-almost-too-easy/)
- [Vcpkg recent enhancements](https://blogs.msdn.microsoft.com/vcblog/2017/02/14/vcpkg-recent-enhancements/)
- [Vcpkg 3 Months Anniversary, Survey](https://blogs.msdn.microsoft.com/vcblog/2017/01/11/vcpkg-3-months-anniversary-survey/)
- [Vcpkg updates: Static linking is now available](https://blogs.msdn.microsoft.com/vcblog/2016/11/01/vcpkg-updates-static-linking-is-now-available/)
- [Vcpkg: a tool to acquire and build C++ open source libraries on Windows](https://blogs.msdn.microsoft.com/vcblog/2016/09/19/vcpkg-a-tool-to-acquire-and-build-c-open-source-libraries-on-windows/)
### Other
- [FAQ](about/faq.md)
- [Privacy](about/privacy.md)

1
externals/vcpkg/docs/_config.yml vendored Executable file
View file

@ -0,0 +1 @@
theme: jekyll-theme-cayman

120
externals/vcpkg/docs/about/faq.md vendored Executable file
View file

@ -0,0 +1,120 @@
# Frequently Asked Questions
## Can I contribute a new library?
Yes! Start out by reading our [contribution guidelines](https://github.com/Microsoft/vcpkg/blob/master/CONTRIBUTING.md).
If you want to contribute but don't have a particular library in mind then take a look at the list
of [new port requests](https://github.com/Microsoft/vcpkg/issues?q=is%3Aissue+is%3Aopen+label%3Acategory%3Anew-port).
## Can Vcpkg create pre-built binary packages? What is the binary format used by Vcpkg?
Yes! See the [`export` command](../users/buildsystems/export-command.md).
## How do I update libraries?
The `vcpkg update` command lists all packages which are out-of-sync with your current portfiles. To update a package, follow the instructions in the command.
## How do I get more libraries?
The list of libraries is enumerated from the [`ports\`](https://github.com/Microsoft/vcpkg/blob/master/ports) directory. By design, you can add and remove libraries from this directory as you see fit for yourself or your company -- see our examples on packaging [zipfiles](../examples/packaging-zipfiles.md) and [GitHub repos](../examples/packaging-github-repos.md).
We recommend cloning directly from [GitHub](https://github.com/microsoft/vcpkg) and using `git pull` to update the list of portfiles. Once you've updated your portfiles, `vcpkg update` will indicate any installed libraries that are now out of date.
## Can I build a private library with this tool?
Yes. Follow [our packaging zlib Example](../examples/packaging-zipfiles.md) for creating a portfile using a fake URL. Then, either pre-seed the `downloads\` folder with a zip containing your private sources or replace the normal calls to `vcpkg_download_distfile` and `vcpkg_extract_source_archive` with functions that unpack your source code.
## Can I use a prebuilt private library with this tool?
Yes. The `portfile.cmake` for a library is fundamentally a script that places the headers and binaries into the correct arrangement in the `${CURRENT_PACKAGES_DIR}`, so to pull in prebuilt binaries you can write a portfile which directly downloads and arranges the files.
To see an example of this, look at [`ports\opengl\portfile.cmake`](https://github.com/microsoft/vcpkg/blob/master/ports/opengl/portfile.cmake) which simply copies files out of the Windows SDK.
## Which platforms I can target with Vcpkg?
We currently target Windows Desktop (x86 and x64) as well as the Universal Windows Platform (x86, x64, and ARM). See `vcpkg help triplet` for the current list.
## Does Vcpkg run on Linux/OSX?
Yes! We continuously test on OSX and Ubuntu 16.04, however we know users have been successful with Arch, Fedora, and FreeBSD. If you have trouble with your favorite Linux distribution, let us know in an issue and we'd be happy to help!
## How do I update vcpkg?
Execute `git pull` to get the latest sources, then run `bootstrap-vcpkg.bat` (Windows) or `./bootstrap-vcpkg.sh` (Unix) to update vcpkg.
## How do I use different versions of a library on one machine?
Within a single instance of Vcpkg (e.g. one set of `installed\`, `packages\`, `ports\` and so forth), you can only have one version of a library installed (otherwise, the headers would conflict with each other!). For those with experience with system-wide package managers, packages in Vcpkg correspond to the `X-dev` or `X-devel` packages.
To use different versions of a library for different projects, we recommend making separate instances of Vcpkg and using the [per-project integration mechanisms](../users/buildsystems/integration.md). The versions of each library are specified by the files in `ports\`, so they are easily manipulated using standard `git` commands. This makes it very easy to roll back the entire set of libraries to a consistent set of older versions which all work with each other. If you need to then pin a specific library forward, that is as easy as checking out the appropriate version of `ports\<package>\`.
If your application is very sensitive to the versions of libraries, we recommend checking in the specific set of portfiles you need into your source control along with your project sources and using the `--vcpkg-root` option to redirect the working directory of `vcpkg.exe`.
## How does Vcpkg protect my privacy?
See the [Privacy document](privacy.md) for all information regarding privacy.
## Can I use my own CMake toolchain file with Vcpkg's toolchain file?
Yes. If you already have a CMake toolchain file, you will need to include our toolchain file at the end of yours. This should be as simple as an `include(<vcpkg_root>\scripts\buildsystems\vcpkg.cmake)` directive. Alternatively, you could copy the contents of our `scripts\buildsystems\vcpkg.cmake` into the end of your existing toolchain file.
## Can I use my own/specific flags for rebuilding libs?
Yes. In the current version, there is not yet a standardized global way to change them, however you can edit individual portfiles and tweak the exact build process however you'd like.
By saving the changes to the portfile (and checking them in), you'll get the same results even if you're rebuilding from scratch in the future and forgot what exact settings you used.
## Can I get Vcpkg integration for custom configurations?
Yes. While Vcpkg will only produce the standard "Release" and "Debug" configurations when building a library, you can get integration support for your projects' custom configurations, in addition to your project's standard configurations.
First of all, Vcpkg will automatically assume any custom configuration starting with "Release" (resp. "Debug") as a configuration that is compatible with the standard "Release" (resp. "Debug") configuration and will act accordingly.
For other configurations, you only need to override the MSBuild `$(VcpkgConfiguration)` macro in your project file (.vcxproj) to declare the compatibility between your configuration, and the target standard configuration. Unfortunately, due to the sequential nature of MSBuild, you'll need to add those settings much higher in your vcxproj so that it is declared before the Vcpk integration is loaded. It is recommend that the `$(VcpkgConfiguration)` macro is added to the "Globals" PropertyGroup.
For example, you can add support for your "MyRelease" configuration by adding in your project file:
```
<PropertyGroup Label="Globals">
...
<VcpkgConfiguration Condition="'$(Configuration)' == 'MyRelease'">Release</VcpkgConfiguration>
</PropertyGroup>
```
Of course, this will only produce viable binaries if your custom configuration is compatible with the target configuration (e.g. they should both link with the same runtime library).
## I can't use user-wide integration. Can I use a per-project integration?
Yes. A NuGet package suitable for per-project use can be generated via either the `vcpkg integrate project` command (lightweight linking) or the `vcpkg export --nuget` command (shrinkwrapped).
A lower level mechanism to achieve the same as the `vcpkg integrate project` NuGet package is via the `<vcpkg_root>\scripts\buildsystems\msbuild\vcpkg.targets` file. All you need is to import it in your .vcxproj file, replacing `<vcpkg_root>` with the path where you installed vcpkg:
```
<Import Project="<vcpkg_root>\scripts\buildsystems\msbuild\vcpkg.targets" />
```
## How can I remove temporary files?
You can save some disk space by completely removing the `packages\`, `buildtrees\`, and `downloads\` folders.
## How is CMake used internally by Vcpkg?
Vcpkg uses CMake internally as a build scripting language. This is because CMake is already an extremely common build system for cross-platform open source libraries and is becoming very popular for C++ projects in general. It is easy to acquire on Windows, does not require system-wide installation, and legible for unfamiliar users.
## Will Vcpkg support downloading compiled binaries from a public or private server?
We would like to eventually support downloading precompiled binaries, similar to other system package managers.
In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host. See the [`export` command](../users/buildsystems/export-command.md).
## What Visual C++ toolsets are supported?
We support Visual Studio 2015 Update 3 and above.
## Why does Visual Studio not use my libraries with user-wide integration enabled?
Enabling user-wide integration (`vcpkg integrate install`) changes the default for some project properties. In particular, "C/C++/General/Additional Include Directories" and "Linker/General/Additional Library Directories" are normally blank *without* user-wide integration. *With* integration, a blank value means that the augmented default supplied by vcpkg is overridden, and headers/libraries will not be found. To reinstate the default, set the properties to inherit from parent.
## Why not NuGet?
NuGet is a package manager for .NET libraries with a strong dependency on MSBuild. It does not meet the specific needs of Native C++ customers in at least three ways.
- **Compilation Flavors**. With so many possible combinations of compilation options, the task of providing a truly complete set of options is intrinsically impossible. Furthermore, the download size for reasonably complete binary packages becomes enormous. This makes it a requirement to split the results into multiple packages, but then searching becomes very difficult.
- **Binary vs Source**. Very closely tied to the first point, NuGet is designed from the ground up to provide relatively small, prebuilt binaries. Due to the nature of native code, developers need to have access to the source code to ensure ABI compatibility, performance, integrity, and debuggability.
- **Per-dll vs Per-application**. NuGet is highly project centric. This works well in managed languages with naturally stable ABIs, because base libraries can continue to evolve without breaking those higher up. However, in native languages where the ABI is much more fragile, the only robust strategy is to explicitly build each library against the exact dependencies that will be included in the final application. This is difficult to ensure in NuGet and leads to a highly disconnected and independently versioned ecosystem.
## Why not Conan?
Conan.io is a publicly-federated, project-centric, cross-platform, C++ package manager written in python. Our primary differences are:
- **Public federation vs private federation**. Conan relies on individuals publishing independent copies of each package. We believe this approach encourages a large number of packages that are all broken in different ways. We believe it is a waste of user's time to pick through the list of 20+ public packages for Boost 1.56 to determine the handful that will work for their particular situation. In contrast, we believe there should be a single, collaboratively maintained version which works for the vast majority of cases and allow users to hack freely on their private versions. We believe this will result in a set of high quality packages that are heavily tested with each other and form a fantastic base for any private modifications you need.
- **Per-dll vs Per-application**. When dependencies are independently versioned on a library level, it encourages every build environment to be a completely unique, unable to take advantage of or contribute to a solid, well tested ecosystem. In contrast, by versioning all libraries together as a platform (similar to a system package manager), we hope to congregate testing and effort on very common sets of library versions to maximize the quality and stability of the ecosystem. This also completely designs out the ability for a library to ask for versions that conflict with the application's choices (I want openssl Z and boost X but X only claims to work with openssl Y).
- **Cross-platform vs single-platform**. While being hosted on many platforms is an excellent north star, we believe the level of system integration and stability provided by apt-get, yum, and homebrew is well worth needing to exchange `apt-get install libboost-all-dev` with `brew install boost` in automated scripts. We chose to make our system as easy as possible to integrate into a world with these very successful system managers -- one more line for `vcpkg install boost` -- instead of attempting to replace them where they are already so successful and well-loved.
- **C++/CMake vs python**. While Python is an excellent language loved by many, we believe that transparency and familiarity are the most important factors when choosing a tool as important to your workflow as a package manager. Consequently, we chose to make the implementation languages be as universally accepted as possible: C++ should be used in a C++ package manager for C++ programmers. You should not be required to learn another programming language just to understand your package manager.
## Why not Chocolatey?
Chocolatey is an excellent system for managing applications. However, it is not currently designed to acquire redistributable developer assets and help you with debugging. Vcpkg, in comparison, is designed to get you the libraries you need to build your application and help you deliver through any platform you'd like (including Chocolatey!).

50
externals/vcpkg/docs/about/privacy.md vendored Executable file
View file

@ -0,0 +1,50 @@
# Vcpkg Telemetry and Privacy
vcpkg collects telemetry data to understand usage issues, such as failing packages, and to guide tool improvements. The collected data is anonymous.
For more information about how Microsoft protects your privacy, see https://privacy.microsoft.com/en-US/privacystatement#mainenterprisedeveloperproductsmodule
## Scope
We explicitly ONLY collect information from invocations of the tool itself; we do NOT add any tracking information into the produced libraries. Telemetry is collected when using any of the `vcpkg` commands.
## How to opt out
The vcpkg telemetry feature is enabled by default. In order to opt-out of data collection, you can re-run the bootstrap script with the following flag, for Windows and Linux/OSX, respectively:
```PS> .\bootstrap-vcpkg.bat -disableMetrics```
```~/$ ./bootstrap-vcpkg.sh -disableMetrics```
## Disclosure
vcpkg displays text similar to the following when you build vcpkg. This is how Microsoft notifies you about data collection.
```
Telemetry
---------
vcpkg collects usage data in order to help us improve your experience.
The data collected by Microsoft is anonymous.
You can opt-out of telemetry by re-running the bootstrap-vcpkg script with -disableMetrics,
passing --disable-metrics to vcpkg on the command line,
or by setting the VCPKG_DISABLE_METRICS environment variable.
Read more about vcpkg telemetry at docs/about/privacy.md
```
## Data Collected
The telemetry feature doesn't collect personal data, such as usernames or email addresses. It doesn't scan your code and doesn't extract project-level data, such as name, repository, or author. The data is sent securely to Microsoft servers and held under restricted access.
Protecting your privacy is important to us. If you suspect the telemetry is collecting sensitive data or the data is being insecurely or inappropriately handled, file an issue in the Microsoft/vcpkg repository or send an email to vcpkg@microsoft.com for investigation.
We collect various telemetry events such as the command line used, the time of invocation, and how long execution took. Some commands also add additional calculated information (such as the full set of libraries to install). We generate a completely random UUID on first use and attach it to each event.
You can see the telemetry events any command by appending `--printmetrics` after the vcpkg command line.
In the source code (included at https://github.com/microsoft/vcpkg-tool/ ), you can search for calls to the functions `track_property()`, `track_feature()`, `track_metric()`, and `track_buildtime()`
to see every specific data point we collect.
## Avoid inadvertent disclosure information
vcpkg contributors and anyone else running a version of vcpkg that they built themselves should consider the path to their source code. If a crash occurs when using vcpkg, the file path from the build machine is collected as part of the stack trace and isn't hashed.
Because of this, builds of vcpkg shouldn't be located in directories whose path names expose personal or sensitive information.

121
externals/vcpkg/docs/commands/common-options.md vendored Executable file
View file

@ -0,0 +1,121 @@
# Common Command Options
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/common-options.md).**
Most vcpkg commands accept a group of common options that control cross-cutting aspects of the tool. Not all options affect every command. For example, a command that does not download any files will be unaffected by changing the downloads directory.
<a name="asset-sources"></a>
## `--x-asset-sources=<config>`
**Experimental: will change or be removed at any time**
Specify the cache configuration for [Asset Caching](../users/assetcaching.md).
<a name="binarysource"></a>
## `--binarysource=<config>`
Add a source for [Binary Caching](../users/binarycaching.md).
This option can be specified multiple times; see the Binary Caching documentation for how multiple binary sources interact.
<a name="buildtrees-root"></a>
## `--x-buildtrees-root=<path>`
**Experimental: will change or be removed at any time**
Specifies the temporary path to store intermediate build files, such as objects or unpacked source code.
Defaults to `buildtrees/` under the vcpkg root folder.
<a name="downloads-root"></a>
## `--downloads-root=<path>`
Specify where downloaded tools and source code archives should be kept.
Defaults to the `VCPKG_DOWNLOADS` environment variable. If that is unset, defaults to `downloads/` under the vcpkg root folder.
<a name="host-triplet"></a>
## `--host-triplet=<triplet>`
Specify the host [architecture triplet][triplets].
Defaults to the `VCPKG_DEFAULT_HOST_TRIPLET` environment variable. If that is unset, deduced based on the host architecture and operating system.
<a name="install-root"></a>
## `--x-install-root=<path>`
**Experimental: will change or be removed at any time**
Specifies the path to lay out installed packages.
In Classic Mode, defaults to `installed/` under the vcpkg root folder.
In [Manifest Mode][../users/manifests.md], defaults to `vcpkg_installed/` under the manifest folder.
<a name="manifest-root"></a>
### `--x-manifest-root=<path>`
**Experimental: will change or be removed at any time**
Specifies the directory containing [`vcpkg.json`](../users/manifests.md).
Defaults to searching upwards from the current working directory for the nearest `vcpkg.json`.
<a name="overlay-ports"></a>
## `--overlay-ports=<path>`
Specifies a directory containing [overlay ports](../specifications/ports-overlay.md).
This option can be specified multiple times; ports will resolve to the first match.
<a name="overlay-triplets"></a>
## `--overlay-triplets=<path>`
Specifies a directory containing [overlay triplets](../examples/overlay-triplets-linux-dynamic.md).
This option can be specified multiple times; [triplets][] will resolve to the first match.
<a name="packages-root"></a>
## `--x-packages-root=<path>`
**Experimental: will change or be removed at any time**
Specifies the temporary path to stage intermediate package files before final install.
Defaults to `packages/` under the vcpkg root folder.
<a name="triplet"></a>
## `--triplet=<triplet>`
Specify the target [architecture triplet][triplets].
Defaults to the `VCPKG_DEFAULT_TRIPLET` environment variable. If that is unset, deduced based on the host architecture and operating system.
Note that on Windows operating systems, the architecture is always deduced as x86 for legacy reasons.
<a name="vcpkg-root"></a>
## `--vcpkg-root=<path>`
Specifies the vcpkg root folder.
Defaults to the directory containing the vcpkg program. The directory must be a valid vcpkg instance, such as a `git clone` of `https://github.com/microsoft/vcpkg`. This option can be used to run a custom-built copy of the tool directly from the build folder.
## Response Files (`@<file>`)
The vcpkg command line accepts text files containing newline-separated command line parameters.
The tool will act as though the items in the file were spliced into the command line in place of the `@` reference. Response files cannot contain additional response files.
[triplets]: ../users/triplets.md

13
externals/vcpkg/docs/commands/index.md vendored Executable file
View file

@ -0,0 +1,13 @@
# vcpkg Command Line Reference
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/index.md).**
## Contents
- [Common Options](common-options.md)
- Commands
- [vcpkg install](install.md)
## Source
The vcpkg command line is developed in a separate repository on GitHub: [microsoft/vcpkg-tool](https://github.com/microsoft/vcpkg-tool). Issues should be posted to [microsoft/vcpkg](https://github.com/microsoft/vcpkg/issues).

183
externals/vcpkg/docs/commands/install.md vendored Executable file
View file

@ -0,0 +1,183 @@
# vcpkg install
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/install.md).**
## Synopsis
**Classic Mode**
```no-highlight
vcpkg install [options] <package>...
```
**Manifest Mode**
```no-highlight
vcpkg install [options]
```
## Description
Build and install port packages.
### Classic Mode
In Classic Mode, this verb adds port packages to the existing set in the [installed directory][] (defaults to `installed/` under the vcpkg root). This can require removing and rebuilding existing packages, which can fail.
**Package Syntax**
```
portname[feature1,feature2]:triplet
```
Package references without a triplet are automatically qualified by the [default target triplet](common-options.md#triplet). Package references that do not explicitly list `core` are considered to imply all default features.
### Manifest Mode
In [Manifest Mode][], this verb sets the [installed directory][] to the state specified by the `vcpkg.json` manifest file, adding, removing, or rebuilding packages as needed.
[installed directory]: common-options.md#install-root
## Options
All vcpkg commands support a set of [common options](common-options.md).
### `--allow-unsupported`
Instead of stopping on an unsupported port, continue with a warning.
By default, vcpkg refuses to execute an install plan containing a port installation for a triplet outside its [`"supports"`][] clause. The [`"supports"`][] clause of a package describes the full set of platforms a package is expected to be buildable on. This flag instructs vcpkg to warn that the build is expected to fail instead of stopping.
### `--clean-after-build`
Clean buildtrees, packages, and downloads after building each package.
This option has the same effect as passing [`--clean-buildtrees-after-build`](#clean-buildtrees-after-build), [`--clean-downloads-after-build`](#clean-downloads-after-build), and [`--clean-packages-after-build`](#clean-packages-after-build).
<a id="clean-buildtrees-after-build"></a>
### `--clean-buildtrees-after-build`
Clean all subdirectories from the buildtrees temporary subfolder after building each package.
All top-level files in the buildtrees subfolder (e.g. `buildtrees/zlib/config-x64-windows-out.log`) will be kept. All subdirectories will be deleted.
<a id="clean-downloads-after-build"></a>
### `--clean-downloads-after-build`
Clean all unextracted assets from the `downloads/` folder after building each package.
All top level files in the `downloads/` folder will be deleted. Extracted tools will be kept.
<a id="clean-packages-after-build"></a>
### `--clean-packages-after-build`
Clean the packages temporary subfolder after building each package.
The packages subfolder for the built package (for example, `packages/zlib_x64-windows`) will be deleted after installation.
### `--dry-run`
Print the install plan, but do not remove or install any packages.
The install plan lists all packages and features that will be installed, as well as any other packages that need to be removed and rebuilt.
### `--editable`
**Classic Mode Only**
Perform editable builds for all directly referenced packages on the command line.
When vcpkg builds ports, it purges and re-extracts the source code each time to ensure inputs are accurately. This is necessary for [Manifest Mode][] to accurately update what is installed and [Binary Caching][] to ensure cached content is correct.
Passing the `--editable` flag disables this behavior, preserving edits to the extracted sources in the `buildtrees/` folder. This helps develop patches quickly by avoiding the need to write a file on each change.
Sources extracted during an editable build do not have a `.clean/` suffix on the directory name and will not be cleared by subsequent non-editable builds.
### `--enforce-port-checks`
Fail install if a port has detected problems or attempts to use a deprecated feature.
By default, vcpkg will run several checks on built packages and emit warnings if any issues are detected. This flag upgrades those warnings to an error.
### `--x-feature=<feature>`
**Experimental and may change or be removed at any time**
**[Manifest Mode][] Only**
Specify an additional [feature](../users/manifests.md#features) from the `vcpkg.json` to install dependencies for.
By default, only [`"dependencies"`](../users/manifests.md#dependencies) and the dependencies of the [`"default-features"`](../users/manifests.md#default-features) will be installed.
### `--head`
**Classic Mode Only**
Request all packages explicitly referenced on the command line to fetch the latest sources available when building.
This flag is only intended for temporary testing and is not intended for production or long-term use. This disables [Binary Caching][] for all explicitly referenced packages and their dependents because vcpkg cannot accurately track all inputs.
### `--keep-going`
Continue the install plan after the first failure.
By default, vcpkg will stop at the first package build failure. This flag instructs vcpkg to continue building and installing other parts of the install plan that don't depend upon the failed package.
### `--x-no-default-features`
**Experimental and may change or be removed at any time**
**[Manifest Mode][] Only**
Don't install the default features from the top-level manifest.
When using `install` in Manifest Mode, by default all dependencies of the features listed in [`"default-features"`][] will be installed. This flag disables that behavior so (without any `TODO` flags) only the dependencies listed in [`"dependencies"`][] will be installed.
### `--no-downloads`
When building a package, prevent ports from downloading new assets during the build.
By default, ports will acquire source code and tools on demand from the internet (subject to [Asset Caching][]). This parameter blocks downloads and restricts ports to only the assets that were previously downloaded and cached on the machine.
### `--only-downloads`
Attempt to download all assets required for an install plan without performing any builds.
When passed this option, vcpkg will run each build in the plan until it makes its first non-downloading external process call. Most ports perform all downloads before the first external process call (usually to their buildsystem), so this procedure will download all required assets. Ports that do not follow this procedure will not have their assets predownloaded.
### `--only-binarycaching`
Refuse to perform any builds. Only restore packages from [Binary Caches][Binary Caching].
This flag blocks vcpkg from performing builds on demand and will fail if a package cannot be found in any binary caches.
### `--recurse`
**Classic Mode Only**
Approve an install plan that requires rebuilding packages.
In order to modify the set of features of an installed package, vcpkg must remove and rebuild that package. Because this has the potential of failing and leaving the install tree with fewer packages than the user started with, the user must approve plans that rebuild packages by passing this flag.
### `--x-use-aria2`
**Experimental and may change or be removed at any time**
Use aria2 to perform download tasks.
<a id="write-nuget-packages-config"></a>
### `--x-write-nuget-packages-config`
**Experimental and may change or be removed at any time**
Writes out a NuGet `packages.config`-formatted file for use with [Binary Caching][].
This option can be used in conjunction with `--dry-run` to obtain the list of NuGet packages required from [Binary Caching][] without building or installing any packages. This enables the NuGet command line to be invoked separately for advanced scenarios, such as using alternate protocols to acquire the `.nupkg` files.
[Asset Caching]: ../users/assetcaching.md
[Binary Caching]: ../users/binarycaching.md
[Manifest Mode]: ../users/manifests.md
[`"supports"`]: ../users/manifests.md#supports
[`"default-features"`]: ../users/manifests.md#default-features
[`"dependencies"`]: ../users/manifests.md#dependencies

84
externals/vcpkg/docs/commands/integrate.md vendored Executable file
View file

@ -0,0 +1,84 @@
# vcpkg integrate
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/integrate.md).**
## Synopsis
**Buildsystem Integration**
```no-highlight
vcpkg integrate [options] install
vcpkg integrate [options] remove
vcpkg integrate [options] project
```
**Shell Integration**
```no-highlight
vcpkg integrate [options] powershell
vcpkg integrate [options] bash
vcpkg integrate [options] zsh
vcpkg integrate [options] x-fish
```
## Description
Integrate vcpkg with shells and buildsystems.
### `vcpkg integrate install`
Integrates with [Visual Studio](../users/buildsystems/msbuild-integration.md#user-wide-integration) (Windows-only), sets the user-wide vcpkg instance, and displays CMake integration help.
On Windows with Visual Studio 2015, this subcommand will add redirecting logic into the MSBuild installation which will automatically pick up each user's user-wide vcpkg instance. Visual Studio 2017 and newer have this logic in the box.
To set the user-wide vcpkg instance, vcpkg creates a few short files containing the absolute path to the vcpkg instance inside the user's user-wide configuration location:
- `%LOCALAPPDATA%\vcpkg` or `%APPDATA%\Local\vcpkg` on Windows
- `$HOME/.vcpkg` or `/var/.vcpkg` on non-Windows
Displays the full path to the [CMake toolchain file](../users/buildsystems/cmake-integration.md). Running this command is not required to use the toolchain file.
### `vcpkg integrate remove`
Removes the user-wide vcpkg instance setting.
This command deletes the linking files from the user-wide configuration location created by `vcpkg integrate install`.
### `vcpkg integrate project`
Creates a linked NuGet package for MSBuild integration.
See [MSBuild Per-Project Integration](../users/buildsystems/msbuild-integration.md#linked-nuget-package) for more information.
### `vcpkg integrate powershell`
**Windows Only**
Adds vcpkg tab-completion support to the current user's Powershell profile.
### `vcpkg integrate bash`
**Non-Windows Only**
Adds vcpkg tab-completion support to the current user's `.bashrc` (`.bash_profile` on MacOS).
### `vcpkg integrate zsh`
**Non-Windows Only**
Adds vcpkg tab-completion support to the current user's `.zshrc`.
### `vcpkg integrate x-fish`
**Non-Windows Only**
Adds vcpkg tab-completion support to the current user's fish shell completions directory.
## Example
```no-highlight
$ vcpkg integrate install
Applied user-wide integration for this vcpkg root.
CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=/workspaces/vcpkg/scripts/buildsystems/vcpkg.cmake"
```
## Options
All vcpkg commands support a set of [common options](common-options.md).

37
externals/vcpkg/docs/commands/search.md vendored Executable file
View file

@ -0,0 +1,37 @@
# vcpkg search
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/search.md).**
## Synopsis
```no-highlight
vcpkg search [options] [query]
```
## Description
Searches for available packages by name and description.
Search performs a case-insensitive search through all available package names and descriptions. The results are displayed in a tabular format.
## Example
```no-highlight
$ vcpkg search zlib
miniz 2.2.0#1 Single C source file zlib-replacement library
zlib 1.2.12#1 A compression library
zlib-ng 2.0.6 zlib replacement with optimizations for 'next generation' systems
```
## Options
All vcpkg commands support a set of [common options](common-options.md).
### `--x-full-desc`
**Experimental and may change or be removed at any time**
Do not truncate long descriptions.
By default, long descriptions will be truncated to keep the tabular output browsable.
[Registries]: ../users/registries.md

182
externals/vcpkg/docs/examples/installing-and-using-packages.md vendored Executable file
View file

@ -0,0 +1,182 @@
## Installing and Using Packages Example: SQLite
_Note: this old example uses Classic Mode, but most developers will be happier with Manifest Mode. See [Manifest Mode: CMake Example](manifest-mode-cmake.md) for an example of converting to Manifest Mode._
- [Step 1: Install](#install)
- [Step 2: Use](#use)
- [VS/MSBuild Project (User-wide integration)](#msbuild)
- [CMake (Toolchain file)](#cmake)
- [Other integration options](../users/buildsystems/integration.md)
---
<a name="install"></a>
## Step 1: Install
First, we need to know what name [SQLite](https://sqlite.org) goes by in the ports tree. To do that, we'll run the `search` command and inspect the output:
```no-highlight
PS D:\src\vcpkg> .\vcpkg search sqlite
libodb-sqlite 2.4.0 Sqlite support for the ODB ORM library
sqlite3 3.32.1 SQLite is a software library that implements a se...
If your library is not listed, please open an issue at:
https://github.com/Microsoft/vcpkg/issues
```
Looking at the list, we can see that the port is named "sqlite3". You can also run the `search` command without arguments to see the full list of packages.
Installing is then as simple as using the `install` command.
```no-highlight
PS D:\src\vcpkg> .\vcpkg install sqlite3
Computing installation plan...
The following packages will be built and installed:
sqlite3[core]:x86-windows
Starting package 1/1: sqlite3:x86-windows
Building package sqlite3[core]:x86-windows...
-- Downloading https://sqlite.org/2020/sqlite-amalgamation-3320100.zip...
-- Extracting source C:/src/vcpkg/downloads/sqlite-amalgamation-3320100.zip
-- Applying patch fix-arm-uwp.patch
-- Using source at C:/src/vcpkg/buildtrees/sqlite3/src/3320100-15aeda126a.clean
-- Configuring x86-windows
-- Building x86-windows-dbg
-- Building x86-windows-rel
-- Performing post-build validation
-- Performing post-build validation done
Building package sqlite3[core]:x86-windows... done
Installing package sqlite3[core]:x86-windows...
Installing package sqlite3[core]:x86-windows... done
Elapsed time for package sqlite3:x86-windows: 12 s
Total elapsed time: 12.04 s
The package sqlite3:x86-windows provides CMake targets:
find_package(unofficial-sqlite3 CONFIG REQUIRED)
target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3))
```
We can check that sqlite3 was successfully installed for x86 Windows desktop by running the `list` command.
```no-highlight
PS D:\src\vcpkg> .\vcpkg list
sqlite3:x86-windows 3.32.1 SQLite is a software library that implements a se...
```
To install for other architectures and platforms such as Universal Windows Platform or x64 Desktop, you can suffix the package name with `:<target>`.
```no-highlight
PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows
```
See `.\vcpkg help triplet` for all supported targets.
---
<a name="use"></a>
## Step 2: Use
<a name="msbuild"></a>
#### VS/MSBuild Project (User-wide integration)
The recommended and most productive way to use vcpkg is via user-wide integration, making the system available for all projects you build. The user-wide integration will prompt for administrator access the first time it is used on a given machine, but afterwards is no longer required and the integration is configured on a per-user basis.
```no-highlight
PS D:\src\vcpkg> .\vcpkg integrate install
Applied user-wide integration for this vcpkg root.
All C++ projects can now #include any installed libraries.
Linking will be handled automatically.
Installing new libraries will make them instantly available.
```
*Note: You will need to restart Visual Studio or perform a Build to update intellisense with the changes.*
You can now simply use File -> New Project in Visual Studio and the library will be automatically available. For SQLite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html).
To remove the integration for your user, you can use `.\vcpkg integrate remove`.
<a name="cmake"></a>
#### CMake (Toolchain File)
The best way to use installed libraries with cmake is via the toolchain file `scripts\buildsystems\vcpkg.cmake`. To use this file, you simply need to add it onto your CMake command line as:
`-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake`.
If you are using CMake through Open Folder with Visual Studio you can define `CMAKE_TOOLCHAIN_FILE` by adding a "variables" section to each of your `CMakeSettings.json` configurations:
```json
{
"configurations": [{
"name": "x86-Debug",
"generator": "Visual Studio 15 2017",
"configurationType" : "Debug",
"buildRoot": "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}",
"cmakeCommandArgs": "",
"buildCommandArgs": "-m -v:minimal",
"variables": [{
"name": "CMAKE_TOOLCHAIN_FILE",
"value": "D:\\src\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake"
}]
}]
}
```
*Note: It might be necessary to delete the CMake cache folder of each modified configuration, to force a full regeneration. In the `CMake` menu, under `Cache (<configuration name>)` you'll find `Delete Cache Folders`.*
Now let's make a simple CMake project with a main file.
```cmake
# CMakeLists.txt
cmake_minimum_required(VERSION 3.0)
project(test)
find_package(unofficial-sqlite3 CONFIG REQUIRED)
add_executable(main main.cpp)
target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3)
```
```cpp
// main.cpp
#include <sqlite3.h>
#include <stdio.h>
int main()
{
printf("%s\n", sqlite3_libversion());
return 0;
}
```
Then, we build our project in the normal CMake way:
```no-highlight
PS D:\src\cmake-test> mkdir build
PS D:\src\cmake-test> cd build
PS D:\src\cmake-test\build> cmake .. "-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake"
// omitted CMake output here //
-- Build files have been written to: D:/src/cmake-test/build
PS D:\src\cmake-test\build> cmake --build .
// omitted MSBuild output here //
Build succeeded.
0 Warning(s)
0 Error(s)
Time Elapsed 00:00:02.38
PS D:\src\cmake-test\build> .\Debug\main.exe
3.15.0
```
*Note: The correct sqlite3.dll is automatically copied to the output folder when building for x86-windows. You will need to distribute this along with your application.*
##### Handling libraries without native cmake support
Unlike other platforms, we do not automatically add the `include\` directory to your compilation line by default. If you're using a library that does not provide CMake integration, you will need to explicitly search for the files and add them yourself using [`find_path()`][1] and [`find_library()`][2].
```cmake
# To find and use catch
find_path(CATCH_INCLUDE_DIR catch.hpp)
include_directories(${CATCH_INCLUDE_DIR})
# To find and use azure-storage-cpp
find_path(WASTORAGE_INCLUDE_DIR was/blob.h)
find_library(WASTORAGE_LIBRARY wastorage)
include_directories(${WASTORAGE_INCLUDE_DIR})
link_libraries(${WASTORAGE_LIBRARY})
# Note that we recommend using the target-specific directives for a cleaner cmake:
# target_include_directories(main ${LIBRARY})
# target_link_libraries(main PRIVATE ${LIBRARY})
```
[1]: https://cmake.org/cmake/help/latest/command/find_path.html
[2]: https://cmake.org/cmake/help/latest/command/find_library.html

200
externals/vcpkg/docs/examples/manifest-mode-cmake.md vendored Executable file
View file

@ -0,0 +1,200 @@
# Manifest Mode: CMake Example
We would like to add [vcpkg manifest support](../users/manifests.md) to an existing cmake project!
Let's create a simple project that prints the fibonacci sequence up to a certain number,
using some common dependencies.
## Initial Layout
Let's create the following file layout:
```no-highlight
fibo/
src/
main.cxx
CMakeLists.txt
```
And we wish to use [fmt](https://github.com/fmtlib/fmt), [range-v3](https://github.com/ericniebler/range-v3),
and [cxxopts](https://github.com/jarro2783/cxxopts).
Let's write our `CMakeLists.txt` first:
```cmake
cmake_minimum_required(VERSION 3.15)
project(fibo CXX)
find_package(fmt REQUIRED)
find_package(range-v3 REQUIRED)
find_package(cxxopts REQUIRED)
add_executable(fibo src/main.cxx)
target_compile_features(fibo PRIVATE cxx_std_17)
target_link_libraries(fibo
PRIVATE
fmt::fmt
range-v3::range-v3
cxxopts::cxxopts)
```
And then we should add `main.cxx`:
```cxx
#include <cxxopts.hpp>
#include <fmt/format.h>
#include <range/v3/view.hpp>
namespace view = ranges::views;
int fib(int x) {
int a = 0, b = 1;
for (int it : view::repeat(0) | view::take(x)) {
(void)it;
int tmp = a;
a += b;
b = tmp;
}
return a;
}
int main(int argc, char** argv) {
cxxopts::Options options("fibo", "Print the fibonacci sequence up to a value 'n'");
options.add_options()
("n,value", "The value to print to", cxxopts::value<int>()->default_value("10"));
auto result = options.parse(argc, argv);
auto n = result["value"].as<int>();
for (int x : view::iota(1) | view::take(n)) {
fmt::print("fib({}) = {}\n", x, fib(x));
}
}
```
This is a simple project of course, but it should give us a clean project to start with.
Let's try it out!
Let's assume you have `fmt`, `range-v3`, and `cxxopts` installed with vcpkg classic mode;
then, you can just do a simple:
```cmd
D:\src\fibo> cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake
-- Building for: Visual Studio 16 2019
-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.19041.
-- The CXX compiler identification is MSVC 19.27.29111.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx64/x64/cl.exe - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: D:/src/fibo/build
D:\src\fibo> cmake --build build
Microsoft (R) Build Engine version 16.7.0+b89cb5fde for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.
Checking Build System
Building Custom Rule D:/src/fibo/CMakeLists.txt
main.cxx
The contents of <span> are available only with C++20 or later.
fibo.vcxproj -> D:\src\fibo\build\Debug\fibo.exe
Building Custom Rule D:/src/fibo/CMakeLists.txt
```
And now we can try out the `fibo` binary!
```cmd
D:\src\fibo> .\build\Debug\fibo.exe -n 7
fib(1) = 1
fib(2) = 1
fib(3) = 2
fib(4) = 3
fib(5) = 5
fib(6) = 8
fib(7) = 13
```
it works!
## Converting to Manifest Mode
We now wish to use manifest mode, so all of our dependencies are managed for us! Let's write a `vcpkg.json`:
```json
{
"name": "fibo",
"version-string": "0.1.0",
"dependencies": [
"cxxopts",
"fmt",
"range-v3"
]
}
```
Let's delete the build directory and rerun the build:
```cmd
D:\src\fibo> rmdir /S /Q build
D:\src\fibo> cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake
-- Running vcpkg install
Detecting compiler hash for triplet x64-windows...
The following packages will be built and installed:
cxxopts[core]:x64-windows
fmt[core]:x64-windows
range-v3[core]:x64-windows
Starting package 1/3: cxxopts:x64-windows
Building package cxxopts[core]:x64-windows...
Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\d2\d2d1e5302cdfefef2fd090d8eda84cc0c1fbe6f1.zip
Building package cxxopts[core]:x64-windows... done
Installing package cxxopts[core]:x64-windows...
Installing package cxxopts[core]:x64-windows... done
Elapsed time for package cxxopts:x64-windows: 50.64 ms
Starting package 2/3: fmt:x64-windows
Building package fmt[core]:x64-windows...
Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\bf\bf00d5214e912d71414b545b241f54ef87fdf6e5.zip
Building package fmt[core]:x64-windows... done
Installing package fmt[core]:x64-windows...
Installing package fmt[core]:x64-windows... done
Elapsed time for package fmt:x64-windows: 225 ms
Starting package 3/3: range-v3:x64-windows
Building package range-v3[core]:x64-windows...
Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\fe\fe2cdedef6953bf954e8ddca471bf3cc8d9b06d7.zip
Building package range-v3[core]:x64-windows... done
Installing package range-v3[core]:x64-windows...
Installing package range-v3[core]:x64-windows... done
Elapsed time for package range-v3:x64-windows: 1.466 s
Total elapsed time: 1.742 s
-- Running vcpkg install - done
-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.19041.
-- The CXX compiler identification is MSVC 19.27.29111.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx64/x64/cl.exe - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: D:/src/fibo/build
D:\src\fibo> cmake --build build
Microsoft (R) Build Engine version 16.7.0+b89cb5fde for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.
Checking Build System
Building Custom Rule D:/src/fibo/CMakeLists.txt
main.cxx
The contents of <span> are available only with C++20 or later.
fibo.vcxproj -> D:\src\fibo\build\Debug\fibo.exe
Building Custom Rule D:/src/fibo/CMakeLists.txt
```
You can see that with just a _single file_, we've changed over to manifests without _any_ trouble.
The build system doesn't change _at all_! We just add a `vcpkg.json` file, delete the build directory,
and reconfigure. And we're done!

191
externals/vcpkg/docs/examples/modify-baseline-to-pin-old-boost.md vendored Executable file
View file

@ -0,0 +1,191 @@
# Pin old Boost versions
This document will teach you how to set versions of meta-packages like `boost` or `qt5`.
**What is a meta-package?**
In vcpkg we call meta-packages to ports that by themselves don't install anything but that instead forward installation to another port or ports. The reasons for these meta-packages to exist are plenty: to install different versions of a library depending on platform or to conveniently install/uninstall a catalog of related packages (Boost and Qt).
In the case of Boost, it is unlikely that a user requires all of the 140+ Boost libraries in their project. For the sake of convenience, vcpkg splits Boost into multiple sub-packages broken down to individual libraries. By doing so, users can limit the subset of Boost libraries that they depend on.
If a user wants to install all of the Boost libraries available in vcpkg, they can do so by installing the `boost` meta-package.
Due to the nature of meta-packages, some unexpected issues arise when trying to use them with versioning. If a user writes the following manifest file:
`vcpkg.json`
```json
{
"name": "demo",
"version": "1.0.0",
"builtin-baseline": "787fe1418ea968913cc6daf11855ffd8b0b5e9d4",
"dependencies": [ "boost-tuple" ],
"overrides": [
{ "name": "boost", "version": "1.72.0" }
]
}
```
The resulting installation plan is:
```
The following packages will be built and installed:
boost-assert[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-assert\3393715b4ebe30fe1c3b68acf7f84363e611f156
boost-compatibility[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-compatibility\cda5675366367789659c59aca65fc57d03c51deb
boost-config[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-config\ca82ca1b9c1739c91f3cf42c68cee56c896ae6bd
boost-container-hash[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-container-hash\bf472c23d29c3d80b562c43471eb92cea998f372
boost-core[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-core\20a19f6ece37686a02eed33e1f58add8b7a2582a
boost-detail[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-detail\96744251f025f9b3c856a275dfc338031876777b
boost-integer[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-integer\de70ce0d1500df1eda3496c4f98f42f5db256b4a
boost-io[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-io\7bf3407372f8fc2a99321d24a0e952d44fe25bf3
boost-preprocessor[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-preprocessor\8d78b8ba2e9f54cb00137115ddd2ffec1c63c149
boost-static-assert[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-static-assert\2a41c4703c7122de25b1c60510c43edc9371f63d
boost-throw-exception[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-throw-exception\b13bdf32a20786a0165cc20205ef63765cac0627
boost-tuple[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-tuple\22e3d000a178a88992c430d8ae8a0244c7dea674
boost-type-traits[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-type-traits\8829793f6c6c913257314caa317599f8d253a5ca
boost-uninstall[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-uninstall\08933bad27b6d41caef0940c31e2069ecb6a079c
boost-utility[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-utility\47572946bf6a63c731b9c4142eecb8bef3d3b270
boost-vcpkg-helpers[core]:x64-windows -> 7#2 -- D:\vcpkg\buildtrees\versioning\versions\boost-vcpkg-helpers\2a21e5ab45d1ce41c185faf85dff0670ea6def1d
```
It is reasonable to expect that overriding `boost` to version 1.72.0 results in all Boost packages being pinned to version 1.72.0. **However, vcpkg does not treat the `boost` meta-package any differently that any other port.** In other words, vcpkg has no notion that `boost` is related to all the other `boost-*` libraries, other than it depends on all of them. For this reason, all the other boost packages are installed at version 1.75.0, which is the baseline version.
Below, we describe two methods to pin down Boost versions effectively.
## Method 1: Pin specific packages
Use `"overrides"` to force specific versions in a package-by-package basis.
`vcpkg.json`
```json
{
"name": "demo",
"version": "1.0.0",
"builtin-baseline": "787fe1418ea968913cc6daf11855ffd8b0b5e9d4",
"dependencies": [ "boost-tuple" ],
"overrides": [
{ "name": "boost-core", "version": "1.72" },
{ "name": "boost-integer", "version": "1.72" },
{ "name": "boost-io", "version": "1.72" },
{ "name": "boost-tuple", "version": "1.72" }
]
}
```
This method allows you to quickly set the specific versions you want, but you will need to write an override for each package. Boost libraries are also heavily interdependent, which means that you may end up writing a lot of override lines.
The second method makes it easy to pin the entire Boost collection and end up with a very simple manifest file.
## Method 2: Modify baseline
An easy way to set the version for the entirety of boost is to use the `"builtin-baseline"` property.
As of right now, it is only possible to go back to Boost version `1.75.0` using a baseline, since that was the contemporary Boost version when the versioning feature was merged. **But, it is possible to modify the baseline to whatever you like and use that instead.**
### Step 1: Create a new branch
As described in the versioning documentation. The value that goes in `"builtin-baseline"` is a git commit in the microsoft/vcpkg repository's history. If you want to customize the baseline and have control over the vcpkg instance, you can create a new commit with said custom baseline.
Let's start by creating a new branch to hold our modified baseline.
In the directory containing your clone of the vcpkg Git repository run:
```
git checkout -b custom-boost-baseline
```
This will create a new branch named `custom-boost-baseline` and check it out immediately.
### Step 2: Modify the baseline
The next step is to modify the baseline file, open the file in your editor of choice and modify the entries for the Boost libraries.
Change the `"baseline"` version to your desired version.
_NOTE: Remember to also set the port versions to 0 (or your desired version)._
`${vcpkg-root}/versions/baseline.json`
```diff
...
"boost": {
- "baseline": "1.75.0",
+ "baseline": "1.72.0",
"port-version": 0
},
"boost-accumulators": {
- "baseline": "1.75.0",
- "port-version": 1
+ "baseline": "1.72.0",
+ "port-version": 0
},
"boost-algorithm": {
- "baseline": "1.75.0",
+ "baseline": "1.72.0",
"port-version": 0
},
"boost-align": {
- "baseline": "1.75.0",
+ "baseline": "1.72.0",
"port-version": 0
},
...
"boost-uninstall: {
"baseline": "1.75.0",
"port-version": 0
},
...
```
Some `boost-` packages are helpers used by vcpkg and are not part of Boost. For example, `"boost-uninstall"` is a vcpkg helper to conveniently uninstall all Boost libraries, but it didn't exist for Boost version `1.72.0`, in this case it is fine to leave it at `1.75.0` to avoid baseline errors (since all versions in `baseline.json` must have existed).
### Step 3: Commit your changes
After saving your modified file, run these commands to commit your changes:
```
git add versions/baseline.json
git commit -m "Baseline Boost 1.72.0"
```
You can set the commit message to whatever you want, just make it useful for you.
### Step 4: Get your baseline commit SHA
Once all your changes are ready, you can get the commit SHA by running:
```
git rev-parse HEAD
```
The output of that command will be the commit SHA you need to put as the `"builtin-baseline"` in your project's manifest file. Copy the 40-hex digits and save them to use later in your manifest file.
### Step 5: (Optional) Go back to the main repository branch
Once your changes have been committed locally, you can refer to the commit SHA regardless of the repository branch you're working on. So, let's go back to the main vcpkg repository branch.
```
git checkout master
```
### Step 6: Create your manifest file with your custom baseline
```json
{
"name": "demo",
"version": "1.0.0",
"builtin-baseline": "9b5cf7c3d9376ddf43429671282972ec4f99aa85",
"dependencies": [ "boost-tuple" ]
}
```
In this example, commit SHA `9b5cf7c3d9376ddf43429671282972ec4f99aa85` is the commit ID with the modified baseline. Even when a different branch (`master` in this case) is checked out, Git is able to find the commit as long as the branch with the modified baseline exists (the `custom-boost-baseline` branch we created in step 1).
We run `vcpkg install` in the directory containing our manifest file and the output looks like this:
```
The following packages will be built and installed:
boost-assert[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-assert\6754398591f48435b28014ca0d60e5375a4c04d1
boost-compatibility[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-compatibility\9893ff3c554575bc712df4108a949e07b269f401
boost-config[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-config\de2784767046b06ec31eb718f10df512e51f2aad
boost-container-hash[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-container-hash\cc19fb0154bbef188f309f49b2664ec7623b96b6
boost-core[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-core\0eb5e20df9e267e9eca325be946f52ceb8a60229
boost-detail[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-detail\759d7c6a3f9dbaed0b0c69fa0bb764f7606bb02d
boost-integer[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-integer\173956c61a26e83b0f8b58b0baf60f06aeee637c
boost-preprocessor[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-preprocessor\86eb3938b7875f124feb845331dbe84cbab5d1c6
boost-static-assert[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-static-assert\e82d8f7f3ee07e927dc374f5a08ed6d6f4ef81f4
boost-throw-exception[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-throw-exception\64df295f7df41de4fcb219834889b126b5020def
boost-tuple[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-tuple\b3e1b01ffce6e367e4fed0a5538a8546abacb6b2
boost-type-traits[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-type-traits\5e44ec657660eccf4d3b2710b092dd238e1e7a2d
boost-uninstall[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-uninstall\08933bad27b6d41caef0940c31e2069ecb6a079c
boost-utility[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-utility\7d721b2458d5d595ac341eb54883274f38a4b8c2
boost-vcpkg-helpers[core]:x64-windows -> 7#2 -- D:\vcpkg\buildtrees\versioning\versions\boost-vcpkg-helpers\2a21e5ab45d1ce41c185faf85dff0670ea6def1d
```
Notice how simple our manifest file has become, instead of having a multitude of `"overrides"` you can pin down all Boost packages just by setting the `"builtin-baseline"` to be your modified baseline commit SHA.

126
externals/vcpkg/docs/examples/overlay-triplets-linux-dynamic.md vendored Executable file
View file

@ -0,0 +1,126 @@
# Overlay triplets example
## Building dynamic libraries on Linux
Using **vcpkg** you can build libraries for many configurations out of the box. However, this doesn't currently include shared libraries on Linux and Mac OS.
This doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms! This document will guide you through creating your own custom triplets with `--overlay-triplets` to easily build dynamic libraries on Linux.
### Step 1: Create the custom triplet files
To save time, copy the existing `x64-linux.cmake` triplet file.
```sh
~/git$ mkdir custom-triplets
~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-dynamic.cmake
```
And modify `custom-triplets/x64-linux-dynamic.cmake` to match the contents below:
```cmake
# ~/git/custom-triplets/x64-linux-dynamic.cmake
set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic) # This changed from static to dynamic
set(VCPKG_CMAKE_SYSTEM_NAME Linux)
```
### Step 2: Use `--overlay-triplets` to build dynamic libraries
Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory.
```
~/git$ vcpkg/vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=custom-triplets
The following packages will be built and installed:
sqlite3[core]:x64-linux-dynamic
Starting package 1/1: sqlite3:x64-linux-dynamic
Building package sqlite3[core]:x64-linux-dynamic...
-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux-dynamic.cmake
-- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...
-- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip
-- Applying patch fix-arm-uwp.patch
-- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92
-- Configuring x64-linux-dynamic-dbg
-- Configuring x64-linux-dynamic-rel
-- Building x64-linux-dynamic-dbg
-- Building x64-linux-dynamic-rel
-- Performing post-build validation
-- Performing post-build validation done
Building package sqlite3[core]:x64-linux-dynamic... done
Installing package sqlite3[core]:x64-linux-dynamic...
Installing package sqlite3[core]:x64-linux-dynamic... done
Elapsed time for package sqlite3:x64-linux-dynamic: 44.82 s
Total elapsed time: 44.82 s
The package sqlite3:x64-linux-dynamic provides CMake targets:
find_package(unofficial-sqlite3 CONFIG REQUIRED)
target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3)
```
Overlay triplets enables your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`.
When using the `--overlay-triplets` option, a message like the following lets you know that a custom triplet is being used:
```
-- Loading triplet configuration from: /home/custom-triplets/x64-linux-dynamic.cmake
```
## Overriding default triplets
As you may have noticed, the default triplets for Windows (`x86-windows` and `x64-windows`) install dynamic libraries, while a suffix (`-static`) is needed for static libraries. This is different with Linux and Mac OS where static libraries are built by `x64-linux` and `x64-osx`.
Using `--overlay-triplets` it is possible to override the default triplets to accomplish the same behavior on Linux:
* `x64-linux`: Builds dynamic libraries,
* `x64-linux-static`: Builds static libraries.
### Step 1: Create the overlay triplets
Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`. Then, copy the default `x64-linux` triplet (which builds static libraries) in your `custom-triplets` folder and rename it to `x64-linux-static.cmake`.
```sh
~/git$ mv custom-triplets/x64-linux-dynamic.cmake custom-triplets/x64-linux.cmake
~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-static.cmake
```
### Step 2: Use `--overlay-triplets` to override default triplets
Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory.
```
~/git$ vcpkg/vcpkg install sqlite3:x64-linux --overlay-triplets=custom-triplets
The following packages will be built and installed:
sqlite3[core]:x64-linux
Starting package 1/1: sqlite3:x64-linux
Building package sqlite3[core]:x64-linux...
-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake
-- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...
-- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip
-- Applying patch fix-arm-uwp.patch
-- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92
-- Configuring x64-linux-dbg
-- Configuring x64-linux-rel
-- Building x64-linux-dbg
-- Building x64-linux-rel
-- Performing post-build validation
-- Performing post-build validation done
Building package sqlite3[core]:x64-linux... done
Installing package sqlite3[core]:x64-linux...
Installing package sqlite3[core]:x64-linux... done
Elapsed time for package sqlite3:x64-linux: 44.82 s
Total elapsed time: 44.82 s
The package sqlite3:x64-linux provides CMake targets:
find_package(unofficial-sqlite3 CONFIG REQUIRED)
target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3)
```
Note that the default triplet is masked by your custom triplet:
```
-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake
```

54
externals/vcpkg/docs/examples/packaging-github-repos.md vendored Executable file
View file

@ -0,0 +1,54 @@
## Packaging Github Repos Example: libogg
### Create the manifest file
The manifest file (called `vcpkg.json`) is a json file describing the package's metadata.
For libogg, we'll create the file `ports/libogg/vcpkg.json` with the following content:
```json
{
"name": "libogg",
"version-string": "1.3.3",
"description": "Ogg is a multimedia container format, and the native file and stream format for the Xiph.org multimedia codecs."
}
```
You can format the manifest file to our specifications with `vcpkg format-manifest ports/libogg/vcpkg.json`.
### Create the portfile
`portfile.cmake` describes how to build and install the package. First we download the project from Github with [`vcpkg_from_github`](../maintainers/vcpkg_from_github.md):
```cmake
vcpkg_from_github(
OUT_SOURCE_PATH SOURCE_PATH
REPO xiph/ogg
REF v1.3.3
SHA512 0bd6095d647530d4cb1f509eb5e99965a25cc3dd9b8125b93abd6b248255c890cf20710154bdec40568478eb5c4cde724abfb2eff1f3a04e63acef0fbbc9799b
HEAD_REF master
)
```
The important parts to update are `REPO` for the GitHub repository path, `REF` for a stable tag/commit to use, and `SHA512` with the checksum of the downloaded zipfile (you can get this easily by setting it to `0`, trying to install the package, and copying the checksum).
Finally, we configure the project with CMake, install the package, and copy over the license file:
```cmake
vcpkg_cmake_configure(SOURCE_PATH ${SOURCE_PATH})
vcpkg_cmake_install()
file(INSTALL "${SOURCE_PATH}/COPYING" DESTINATION "${CURRENT_PACKAGES_DIR}/share/libogg" RENAME copyright)
```
Check the documentation for [`vcpkg_cmake_configure`](../maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md) and [`vcpkg_cmake_install`](../maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md) if your package needs additional options.
Now you can run `vcpkg install libogg` to build and install the package.
### Suggested example portfiles
In the `ports/` directory are many libraries that can be used as examples, including many that are not based on CMake.
- Header only libraries
- rapidjson
- range-v3
- MSBuild-based
- mpg123
- Non-CMake, custom buildsystem
- openssl
- ffmpeg

76
externals/vcpkg/docs/examples/packaging-zipfiles.md vendored Executable file
View file

@ -0,0 +1,76 @@
## Packaging `.zip` Files Example: zlib
### Bootstrap with `create`
First, locate a globally accessible archive of the library's sources. Zip, gzip, and bzip are all supported. Strongly prefer official sources or mirrors over unofficial mirrors.
*Looking at zlib's website, the URL http://zlib.net/zlib-1.2.11.tar.gz looks appropriate.*
Second, determine a suitable package name. This should be ASCII, lowercase, and recognizable to someone who knows the library's "human name". If the library is already packaged in another package manager, prefer that name.
*Since zlib is already packaged as zlib, we will use the name zlib2 for this example.*
Finally, if the server's name for the archive is not very descriptive (such as downloading a zipped commit or branch from GitHub), choose a nice archive name of the form `<packagename>-<version>.zip`.
*`zlib1211.zip` is a fine name, so no change needed.*
All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports/<packagename>`.
```no-highlight
PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib-1.2.11.tar.gz zlib1211.tar.gz
-- Generated portfile: D:/src/vcpkg/ports/zlib2/portfile.cmake
```
### Create the manifest file
In addition to the generated `ports/<package>/portfile.cmake`, we also need a `ports/<package>/vcpkg.json` file. This file is a simple set of fields describing the package's metadata.
*For zlib2, we'll create the file `ports/zlib2/vcpkg.json` with the following contents:*
```json
{
"name": "zlib2",
"version-string": "1.2.11",
"description": "A Massively Spiffy Yet Delicately Unobtrusive Compression Library"
}
```
### Tweak the generated portfile
The generated `portfile.cmake` will need some editing to correctly package most libraries in the wild, however we can start by trying out the build.
```no-highlight
PS D:\src\vcpkg> .\vcpkg install zlib2
Computing installation plan...
The following packages will be built and installed:
zlib2[core]:x64-uwp
Starting package 1/1: zlib2:x64-uwp
Building package zlib2[core]:x64-uwp...
-- Using cached C:/src/vcpkg/downloads/zlib1211.tar.gz
-- Cleaning sources at C:/src/vcpkg/buildtrees/zlib2/src/1.2.11-deec42f53b.clean. Pass --editable to vcpkg to reuse sources.
-- Extracting source C:/src/vcpkg/downloads/zlib1211.tar.gz
-- Applying patch cmake_dont_build_more_than_needed.patch
-- Using source at C:/src/vcpkg/buildtrees/zlib2/src/1.2.11-deec42f53b.clean
-- Configuring x64-uwp
-- Building x64-uwp-dbg
-- Building x64-uwp-rel
-- Installing: C:/src/vcpkg/packages/zlib2_x64-uwp/share/zlib2/copyright
-- Performing post-build validation
Include files should not be duplicated into the /debug/include directory. If this cannot be disabled in the project cmake, use
file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include)
/debug/share should not exist. Please reorganize any important files, then use
file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/share)
The software license must be available at ${CURRENT_PACKAGES_DIR}/share/zlib2/copyright
Found 3 error(s). Please correct the portfile:
D:\src\vcpkg\ports\zlib2\portfile.cmake
```
At this point, it is a matter of reading the error messages and log files while steadily improving the quality of the portfile. Zlib required providing a discrete copy of the LICENSE to copy into the package, suppressing the build and installation of executables and headers, and removing the static libraries after they were installed.
### Suggested example portfiles
In the `ports/` directory are many libraries that can be used as examples, including many that are not based on CMake.
- Header only libraries
- rapidjson
- range-v3
- MSBuild-based
- mpg123
- Non-CMake, custom buildsystem
- openssl
- ffmpeg

220
externals/vcpkg/docs/examples/patching.md vendored Executable file
View file

@ -0,0 +1,220 @@
## Patching Example: Patching libpng to work for x64-uwp
### Initial error logs
First, try building:
```no-highlight
PS D:\src\vcpkg> vcpkg install libpng:x64-uwp --editable
Computing installation plan...
The following packages will be built and installed:
libpng[core]:x64-uwp
Starting package 1/1: libpng:x64-uwp
Building package libpng[core]:x64-uwp...
-- Using cached D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
-- Extracting source D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
-- Using source at D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-c993153cdf
-- Configuring x64-uwp
-- Building x64-uwp-rel
CMake Error at scripts/cmake/execute_required_process.cmake:14 (message):
Command failed: C:/Program Files/CMake/bin/cmake.exe;--build;.;--config;Release
Working Directory: D:/src/vcpkg/buildtrees/libpng/x64-uwp-rel
See logs for more information:
D:\src\vcpkg\buildtrees\libpng\build-x64-uwp-rel-out.log
D:\src\vcpkg\buildtrees\libpng\build-x64-uwp-rel-err.log
Call Stack (most recent call first):
scripts/cmake/vcpkg_build_cmake.cmake:3 (execute_required_process)
ports/libpng/portfile.cmake:22 (vcpkg_build_cmake)
scripts/ports.cmake:84 (include)
Error: build command failed
```
Next, looking at the above logs (build-xxx-out.log and build-xxx-err.log).
```no-highlight
// build-x64-uwp-rel-out.log
...
"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj" (default target) (3) ->
(ClCompile target) ->
D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf\pngerror.c(775): warning C4013: 'ExitProcess' undefined; assuming extern returning int [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj]
"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj" (default target) (3) ->
(Link target) ->
pngerror.obj : error LNK2019: unresolved external symbol _ExitProcess referenced in function _png_longjmp [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj]
D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\Release\libpng16.dll : fatal error LNK1120: 1 unresolved externals [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj]
1 Warning(s)
2 Error(s)
Time Elapsed 00:00:04.19
```
### Identify the problematic code
Taking a look at [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682658(v=vs.85).aspx) shows that `ExitProcess` is only available for desktop apps. Additionally, it's useful to see the surrounding context:
```c
/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngerror.c:769 */
/* If control reaches this point, png_longjmp() must not return. The only
* choice is to terminate the whole process (or maybe the thread); to do
* this the ANSI-C abort() function is used unless a different method is
* implemented by overriding the default configuration setting for
* PNG_ABORT().
*/
PNG_ABORT();
```
A recursive search for `PNG_ABORT` reveals the definition:
```no-highlight
PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> findstr /snipl "PNG_ABORT" *
CHANGES:701: Added PNG_SETJMP_SUPPORTED, PNG_SETJMP_NOT_SUPPORTED, and PNG_ABORT() macros
libpng-manual.txt:432:errors will result in a call to PNG_ABORT() which defaults to abort().
libpng-manual.txt:434:You can #define PNG_ABORT() to a function that does something
libpng-manual.txt:2753:errors will result in a call to PNG_ABORT() which defaults to abort().
libpng-manual.txt:2755:You can #define PNG_ABORT() to a function that does something
libpng-manual.txt:4226:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
libpng.3:942:errors will result in a call to PNG_ABORT() which defaults to abort().
libpng.3:944:You can #define PNG_ABORT() to a function that does something
libpng.3:3263:errors will result in a call to PNG_ABORT() which defaults to abort().
libpng.3:3265:You can #define PNG_ABORT() to a function that does something
libpng.3:4736:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
png.h:994: * will use it; otherwise it will call PNG_ABORT(). This function was
pngerror.c:773: * PNG_ABORT().
pngerror.c:775: PNG_ABORT();
pngpriv.h:459:#ifndef PNG_ABORT
pngpriv.h:461:# define PNG_ABORT() ExitProcess(0)
pngpriv.h:463:# define PNG_ABORT() abort()
```
This already gives us some great clues, but the full definition tells the complete story.
```c
/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngpriv.h:459 */
#ifndef PNG_ABORT
# ifdef _WINDOWS_
# define PNG_ABORT() ExitProcess(0)
# else
# define PNG_ABORT() abort()
# endif
#endif
```
`abort()` is a standard CRT call and certainly available in UWP, so we just need to convince libpng to be more platform agnostic. The easiest and most reliable way to achieve this is to patch the code; while in this particular case we could pass in a compiler flag to override `PNG_ABORT` because this is a private header, in general it is more reliable to avoid adding more required compiler switches when possible (especially when it isn't already exposed as a CMake option).
### Patching the code to improve compatibility
We recommend using git to create the patch file, since you'll already have it installed.
```no-highlight
PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git init .
Initialized empty Git repository in D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-c993153cdf/.git/
PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git add .
warning: LF will be replaced by CRLF in ANNOUNCE.
The file will have its original line endings in your working directory.
...
PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git commit -m "temp"
[master (root-commit) 68f253f] temp
422 files changed, 167717 insertions(+)
...
```
Now we can modify `pngpriv.h` to use `abort()` everywhere.
```c
/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngpriv.h:459 */
#ifndef PNG_ABORT
# define PNG_ABORT() abort()
#endif
```
The output of `git diff` is already in patch format, so we just need to save the patch into the `ports/libpng` directory.
```no-highlight
PS buildtrees\libpng\src\v1.6.37-c993153cdf> git diff --ignore-space-at-eol | out-file -enc ascii ..\..\..\..\ports\libpng\use-abort-on-all-platforms.patch
```
Finally, we need to apply the patch after extracting the source.
```cmake
# ports\libpng\portfile.cmake
...
vcpkg_extract_source_archive_ex(
OUT_SOURCE_PATH SOURCE_PATH
ARCHIVE ${ARCHIVE}
PATCHES
"use-abort-on-all-platforms.patch"
)
vcpkg_cmake_configure(
...
```
### Verification
To be completely sure this works from scratch, we need to remove the package and rebuild it:
```no-highlight
PS D:\src\vcpkg> vcpkg remove libpng:x64-uwp
Package libpng:x64-uwp was successfully removed
```
Now we try a fresh, from scratch install.
```no-highlight
PS D:\src\vcpkg> vcpkg install libpng:x64-uwp
Computing installation plan...
The following packages will be built and installed:
libpng[core]:x64-uwp
Starting package 1/1: libpng:x64-uwp
Building package libpng[core]:x64-uwp...
Could not locate cached archive: C:\Users\me\AppData\Local\vcpkg/archives\f4\f44b54f818f78b9a4ccd34b3666f566f94286850.zip
-- Using cached D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
-- Extracting source D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
-- Applying patch use_abort.patch
-- Applying patch cmake.patch
-- Applying patch pkgconfig.patch
-- Applying patch pkgconfig.2.patch
-- Using source at D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-10db9f58e4.clean
-- Configuring x64-uwp
-- Building x64-uwp-dbg
-- Building x64-uwp-rel
-- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/lib/pkgconfig/libpng.pc
-- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/lib/pkgconfig/libpng16.pc
-- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/debug/lib/pkgconfig/libpng.pc
-- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/debug/lib/pkgconfig/libpng16.pc
-- Installing: D:/src/vcpkg/packages/libpng_x64-uwp/share/libpng/copyright
-- Performing post-build validation
-- Performing post-build validation done
Stored binary cache: C:\Users\me\AppData\Local\vcpkg/archives\f4\f44b54f818f78b9a4ccd34b3666f566f94286850.zip
Building package libpng[core]:x64-uwp... done
Installing package libpng[core]:x64-uwp...
Installing package libpng[core]:x64-uwp... done
Elapsed time for package libpng:x64-uwp: 11.94 s
Total elapsed time: 11.95 s
The package libpng:x64-uwp provides CMake targets:
find_package(libpng CONFIG REQUIRED)
target_link_libraries(main PRIVATE png)
```
Finally, to fully commit and publish the changes, we need to bump the port version in `vcpkg.json`,
and add the patch file to source control, then make a Pull Request!
```json
{
"name": "libpng",
"version": "1.6.37",
"port-version": 1,
"dependencies": [
"zlib"
]
}
```

1
externals/vcpkg/docs/examples/vcpkg_android_example_cmake/.gitignore vendored Executable file
View file

@ -0,0 +1 @@
build

5
externals/vcpkg/docs/examples/vcpkg_android_example_cmake/CMakeLists.txt vendored Executable file
View file

@ -0,0 +1,5 @@
cmake_minimum_required(VERSION 3.0)
project(test)
find_package(jsoncpp CONFIG REQUIRED)
add_library(my_lib my_lib.cpp)
target_link_libraries(my_lib jsoncpp_lib)

54
externals/vcpkg/docs/examples/vcpkg_android_example_cmake/compile.sh vendored Executable file
View file

@ -0,0 +1,54 @@
#
# 1. Check the presence of required environment variables
#
if [ -z ${ANDROID_NDK_HOME+x} ]; then
echo "Please set ANDROID_NDK_HOME"
exit 1
fi
if [ -z ${VCPKG_ROOT+x} ]; then
echo "Please set VCPKG_ROOT"
exit 1
fi
#
# 2. Set the path to the toolchains
#
vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
#
# 3. Select a pair "Android abi" / "vcpkg triplet"
# Uncomment one of the four possibilities below
#
android_abi=armeabi-v7a
vcpkg_target_triplet=arm-android
# android_abi=x86
# vcpkg_target_triplet=x86-android
# android_abi=arm64-v8a
# vcpkg_target_triplet=arm64-android
# android_abi=x86_64
# vcpkg_target_triplet=x64-android
#
# 4. Install the library via vcpkg
#
$VCPKG_ROOT/vcpkg install jsoncpp:$vcpkg_target_triplet
#
# 5. Test the build
#
rm -rf build
mkdir build
cd build
cmake .. \
-DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \
-DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \
-DVCPKG_TARGET_TRIPLET=$vcpkg_target_triplet \
-DANDROID_ABI=$android_abi
make

8
externals/vcpkg/docs/examples/vcpkg_android_example_cmake/my_lib.cpp vendored Executable file
View file

@ -0,0 +1,8 @@
#include <json/json.h>
int answer()
{
Json::Value meaning_of;
meaning_of["everything"] = 42;
return meaning_of["everything"].asInt();
}

1
externals/vcpkg/docs/examples/vcpkg_android_example_cmake_script/.gitignore vendored Executable file
View file

@ -0,0 +1 @@
build

13
externals/vcpkg/docs/examples/vcpkg_android_example_cmake_script/CMakeLists.txt vendored Executable file
View file

@ -0,0 +1,13 @@
cmake_minimum_required(VERSION 3.0)
# if -DVCPKG_TARGET_ANDROID=ON is specified when invoking cmake, load cmake/vcpkg_android.cmake
# !!! Important: place this line before calling project() !!!
if (VCPKG_TARGET_ANDROID)
include("cmake/vcpkg_android.cmake")
endif()
project(test)
find_package(jsoncpp CONFIG REQUIRED)
add_library(my_lib my_lib.cpp)
target_link_libraries(my_lib JsonCpp::JsonCpp)

99
externals/vcpkg/docs/examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake vendored Executable file
View file

@ -0,0 +1,99 @@
#
# vcpkg_android.cmake
#
# Helper script when using vcpkg with cmake. It should be triggered via the variable VCPKG_TARGET_ANDROID
#
# For example:
# if (VCPKG_TARGET_ANDROID)
# include("cmake/vcpkg_android.cmake")
# endif()
#
# This script will:
# 1 & 2. check the presence of needed env variables: ANDROID_NDK_HOME and VCPKG_ROOT
# 3. set VCPKG_TARGET_TRIPLET according to ANDROID_ABI
# 4. Combine vcpkg and Android toolchains by setting CMAKE_TOOLCHAIN_FILE
# and VCPKG_CHAINLOAD_TOOLCHAIN_FILE
# Note: VCPKG_TARGET_ANDROID is not an official Vcpkg variable.
# it is introduced for the need of this script
if (VCPKG_TARGET_ANDROID)
#
# 1. Check the presence of environment variable ANDROID_NDK_HOME
#
if (NOT DEFINED ENV{ANDROID_NDK_HOME})
message(FATAL_ERROR "
Please set an environment variable ANDROID_NDK_HOME
For example:
export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle
Or:
export ANDROID_NDK_HOME=/home/your-account/Android/android-ndk-r21b
")
endif()
#
# 2. Check the presence of environment variable VCPKG_ROOT
#
if (NOT DEFINED ENV{VCPKG_ROOT})
message(FATAL_ERROR "
Please set an environment variable VCPKG_ROOT
For example:
export VCPKG_ROOT=/path/to/vcpkg
")
endif()
#
# 3. Set VCPKG_TARGET_TRIPLET according to ANDROID_ABI
#
# There are four different Android ABI, each of which maps to
# a vcpkg triplet. The following table outlines the mapping from vcpkg architectures to android architectures
#
# |VCPKG_TARGET_TRIPLET | ANDROID_ABI |
# |---------------------------|----------------------|
# |arm64-android | arm64-v8a |
# |arm-android | armeabi-v7a |
# |x64-android | x86_64 |
# |x86-android | x86 |
#
# The variable must be stored in the cache in order to successfully the two toolchains.
#
if (ANDROID_ABI MATCHES "arm64-v8a")
set(VCPKG_TARGET_TRIPLET "arm64-android" CACHE STRING "" FORCE)
elseif(ANDROID_ABI MATCHES "armeabi-v7a")
set(VCPKG_TARGET_TRIPLET "arm-android" CACHE STRING "" FORCE)
elseif(ANDROID_ABI MATCHES "x86_64")
set(VCPKG_TARGET_TRIPLET "x64-android" CACHE STRING "" FORCE)
elseif(ANDROID_ABI MATCHES "x86")
set(VCPKG_TARGET_TRIPLET "x86-android" CACHE STRING "" FORCE)
else()
message(FATAL_ERROR "
Please specify ANDROID_ABI
For example
cmake ... -DANDROID_ABI=armeabi-v7a
Possible ABIs are: arm64-v8a, armeabi-v7a, x64-android, x86-android
")
endif()
message("vcpkg_android.cmake: VCPKG_TARGET_TRIPLET was set to ${VCPKG_TARGET_TRIPLET}")
#
# 4. Combine vcpkg and Android toolchains
#
# vcpkg and android both provide dedicated toolchains:
#
# vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
# android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
#
# When using vcpkg, the vcpkg toolchain shall be specified first.
# However, vcpkg provides a way to preload and additional toolchain,
# with the VCPKG_CHAINLOAD_TOOLCHAIN_FILE option.
set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE $ENV{ANDROID_NDK_HOME}/build/cmake/android.toolchain.cmake)
set(CMAKE_TOOLCHAIN_FILE $ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake)
message("vcpkg_android.cmake: CMAKE_TOOLCHAIN_FILE was set to ${CMAKE_TOOLCHAIN_FILE}")
message("vcpkg_android.cmake: VCPKG_CHAINLOAD_TOOLCHAIN_FILE was set to ${VCPKG_CHAINLOAD_TOOLCHAIN_FILE}")
endif(VCPKG_TARGET_ANDROID)

37
externals/vcpkg/docs/examples/vcpkg_android_example_cmake_script/compile.sh vendored Executable file
View file

@ -0,0 +1,37 @@
# 1. Install the library via vcpkg
# This install jsoncpp for the 4 android target ABIs and for the host computer.
# see the correspondence between ABIs and vcpkg triplets in the table below:
#
# |VCPKG_TARGET_TRIPLET | ANDROID_ABI |
# |---------------------------|----------------------|
# |arm64-android | arm64-v8a |
# |arm-android | armeabi-v7a |
# |x64-android | x86_64 |
# |x86-android | x86 |
$VCPKG_ROOT/vcpkg install \
jsoncpp \
jsoncpp:arm-android \
jsoncpp:arm64-android \
jsoncpp:x86-android \
jsoncpp:x64-android
# 2. Test the build
#
# First, select an android ABI
# Uncomment one of the four possibilities below
#
android_abi=armeabi-v7a
# android_abi=x86
# android_abi=arm64-v8a
# android_abi=x86_64
rm -rf build
mkdir build && cd build
# DVCPKG_TARGET_ANDROID will load vcpkg_android.cmake,
# which will then load the android + vcpkg toolchains.
cmake .. \
-DVCPKG_TARGET_ANDROID=ON \
-DANDROID_ABI=$android_abi
make

8
externals/vcpkg/docs/examples/vcpkg_android_example_cmake_script/my_lib.cpp vendored Executable file
View file

@ -0,0 +1,8 @@
#include <json/json.h>
int answer()
{
Json::Value meaning_of;
meaning_of["everything"] = 42;
return meaning_of["everything"].asInt();
}

249
externals/vcpkg/docs/examples/versioning.getting-started.md vendored Executable file
View file

@ -0,0 +1,249 @@
# Getting started with versioning
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/examples/versioning.getting-started.md).**
Vcpkg lets you take control of which version of packages to install in your projects using manifests.
## Using versions with manifests
Let's start with creating a simple CMake project that depends on `fmt` and `zlib`.
Create a folder with the following files:
**vcpkg.json**
```json
{
"name": "versions-test",
"version": "1.0.0",
"dependencies": [
{
"name": "fmt",
"version>=": "7.1.3#1"
},
"zlib"
],
"builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc"
}
```
**main.cpp**
```c++
#include <fmt/core.h>
#include <zlib.h>
int main()
{
fmt::print("fmt version is {}\n"
"zlib version is {}\n",
FMT_VERSION, ZLIB_VERSION);
return 0;
}
```
**CMakeLists.txt**
```CMake
cmake_minimum_required(VERSION 3.18)
project(versionstest CXX)
add_executable(main main.cpp)
find_package(ZLIB REQUIRED)
find_package(fmt CONFIG REQUIRED)
target_link_libraries(main PRIVATE ZLIB::ZLIB fmt::fmt)
```
And now we build and run our project with CMake:
1. Create the build directory for the project.
```
PS D:\versions-test> mkdir build
PS D:\versions-test> cd build
```
2. Configure CMake.
```
PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
-- Running vcpkg install
Detecting compiler hash for triplet x86-windows...
The following packages will be built and installed:
fmt[core]:x64-windows -> 7.1.3#1 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72
vcpkg-cmake[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake\51896aa8073adb5c8450daa423d03eedf0dfc61f
vcpkg-cmake-config[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake-config\d255b3d566a8861dcc99a958240463e678528066
zlib[core]:x64-windows -> 1.2.11#9 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
...
```
3. Build the project.
```
PS D:\versions-test\build> cmake --build .
[2/2] Linking CXX executable main.exe
```
4. Run it!
```
PS D:\versions-test\build> ./main.exe
fmt version is 70103
zlib version is 1.2.11
```
Take a look at the output:
```
fmt[core]:x86-windows -> 7.1.3#1 -- D:\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72
...
zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
```
Instead of using the portfiles in `ports/`, vcpkg is checking out the files for each version in `buildtrees/versioning/versions/`. The files in `ports/` are still used when running vcpkg in classic mode.
_NOTE: Output from vcpkg while configuring CMake is only available when using CMake version `3.18` or newer. If you're using an older CMake you can check the `vcpkg-manifest-install.log` file in your build directory instead._
Read our [manifests announcement blog post](https://devblogs.microsoft.com/cppblog/vcpkg-accelerate-your-team-development-environment-with-binary-caching-and-manifests/#using-manifests-with-msbuild-projects) to learn how to use manifests with MSBuild.
### Manifest changes
If you have used manifests before you will notice that there are some new JSON properties. Let's review these changes:
#### **`version`**
```json
{
"name": "versions-test",
"version": "1.0.0"
}
```
This is your project's version declaration. Previously, you could only declare versions for your projects using the `version-string` property. Now that versioning has come around, vcpkg is aware of some new versioning schemes.
Version scheme | Description
---------------- | ---------------
`version` | Dot-separated numerics: `1.0.0.5`.
`version-semver` | Compliant [semantic versions](https://semver.org): `1.2.0` and `1.2.0-rc`.
`version-date` | Dates in `YYYY-MM-DD` format: `2021-01-01`
`version-string` | Arbitrary strings: `vista`, `candy`.
#### **`version>=`**
```json
{
"dependencies": [
{ "name": "fmt", "version>=": "7.1.3" },
"zlib"
]
}
```
This property is used to express minimum version constraints, it is allowed only as part of the `"dependencies"` declarations. In our example we set an explicit constraint on version `7.1.3#1` of `fmt`.
Vcpkg is allowed to upgrade this constraint if a transitive dependency requires a newer version. For example, if `zlib` were to declare a dependency on `fmt` version `7.1.4` then vcpkg would install `7.1.4` instead.
Vcpkg uses a minimum version approach, in our example, even if `fmt` version `8.0.0` were to be released, vcpkg would still install version `7.1.3#1` as that is the minimum version that satisfies the constraint. The advantages of this approach are that you don't get unexpected dependency upgrades when you update vcpkg and you get reproducible builds (in terms of version used) as long as you use the same manifest.
If you want to upgrade your dependencies, you can bump the minimum version constraint or use a newer baseline.
#### **`builtin-baseline`**
```json
{ "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc" }
```
This field declares the versioning baseline for all ports. Setting a baseline is required to enable versioning, otherwise you will get the current versions on the ports directory. You can run 'git rev-parse HEAD' to get the current commit of vcpkg and set it as the builtin-baseline. See the [`builtin-baseline` documentation](../users/versioning.md#builtin-baseline) for more information.
In our example, you can notice that we do not declare a version constraint for `zlib`; instead, the version is taken from the baseline. Internally, vcpkg will look in commit `3426db05b996481ca31e95fff3734cf23e0f51bc` to find out what version of `zlib` was the latest at that point in time (in our case it was `1.2.11#9`).
During version resolution, baseline versions are treated as minimum version constraints. If you declare an explicit constraint that is lower than a baseline version, the explicit constraint will be upgraded to the baseline version.
For example, if we modified our dependencies like this:
```json
{ "dependencies": [
{
"name": "fmt",
"version>=": "7.1.3#1"
},
{
"name": "zlib",
"version>=": "1.2.11#7"
}
] }
```
_NOTE: The value `1.2.11#7` represents version `1.2.11`, port version `7`._
Since the baseline introduces a minimum version constraint for `zlib` at `1.2.11#9` and a higher version does satisfy the minimum version constraint for `1.2.11#7`, vcpkg is allowed to upgrade it.
Baselines are also a convenient mechanism to upgrade multiple versions at a time, for example, if you wanted to depend on multiple `boost` libraries, it is more convenient to set the `baseline` once than declaring a version constraint on each package.
But what if you want to pin a version older than the baseline?
#### **`overrides`**
Since baselines establish a version floor for all packages and explicit constraints get upgraded when they are lower than the baseline, we need another mechanism to downgrade versions past the baseline.
The mechanism vcpkg provides for that scenario is `overrides`. When an override is declared on a package, vcpkg will ignore all other version constraints either directly declared in the manifest or from transitive dependencies. In short, `overrides` will force vcpkg to use the exact version declared, period.
Let's modify our example once more, this time to force vcpkg to use version `6.0.0` of `fmt`.
```json
{
"name": "versions-test",
"version": "1.0.0",
"dependencies": [
{
"name": "fmt",
"version>=": "7.1.3#1"
},
{
"name": "zlib",
"version>=": "1.2.11#7"
}
],
"builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc",
"overrides": [
{
"name": "fmt",
"version": "6.0.0"
}
]
}
```
Rebuild our project:
```
PS D:\versions-test\build> rm ./CMakeCache.txt
PS D:\versions-test\build> rm -r ./vcpkg_installed
PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
-- Running vcpkg install
Detecting compiler hash for triplet x86-windows...
The following packages will be built and installed:
fmt[core]:x86-windows -> 6.0.0 -- D:\vcpkg\buildtrees\versioning\versions\fmt\d99b6a35e1406ba6b6e09d719bebd086f83ed5f3
zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
...
PS D:\versions-test\build> cmake --build .
[2/2] Linking CXX executable main.exe
```
And run it!
```
PS D:\versions-test\build> .\main.exe
fmt version is 60000
zlib version is 1.2.11
```
Notice how the `fmt` is now at version `6.0.0` just like we wanted.
## Versions and custom ports
The last thing to discuss is how overlay ports interact with versioning resolution. The answer is: they don't.
Going into more detail, when you provide an overlay for a port, vcpkg will always use the overlay port without caring what version is contained in it. The reasons are two-fold: (1) it is consistent with the existing behavior of overlay ports of completely masking the existing port, and (2) overlay ports do not (and are not expected to) provide enough information to power vcpkg's versioning feature.
If you want to have flexible port customization along with versioning, you should consider making your own custom registry. See our [registries specification for more details](../specifications/registries.md).
## Further reading
If you're interested in delving deeper into the details of how versioning works we recommended that you read the [original versioning specification](../specifications/versioning.md) and the [implementation details](../users/versioning.implementation-details.md).
See also:
* [Versioning docs](../users/versioning.md)
* [Original specification](../specifications/versioning.md)
* [Versioning implementation details](../users/versioning.implementation-details.md)

45
externals/vcpkg/docs/maintainers/authoring-script-ports.md vendored Executable file
View file

@ -0,0 +1,45 @@
# Authoring Script Ports
Ports can expose functions for other ports to consume during their build. For
example, the `vcpkg-cmake` helper port exposes the `vcpkg_cmake_configure()`
helper function. Packaging common scripts into a shared helper port makes
maintenance easier because all consumers can be updated from a single place.
Because the scripts come from a port, they can be versioned and depended upon
via all the same mechanisms as any other port.
Script ports are implemented via the `vcpkg-port-config.cmake` extension
mechanism. Before invoking the `portfile.cmake` of a port, vcpkg will first
import `share/<port>/vcpkg-port-config.cmake` from each direct dependency. If
the direct dependency is a host dependency, the import will be performed in the
host installed tree (e.g.
`${HOST_INSTALLED_DIR}/share/<port>/vcpkg-port-config.cmake`).
Only direct dependencies are considered for `vcpkg-port-config.cmake` inclusion.
This means that if a script port relies on another script port, it must
explicitly import the `vcpkg-port-config.cmake` of its dependency.
Script-to-script dependencies should not be marked as host. The dependency from
a target port to a script should be marked host, which means that scripts should
always already be natively compiling. By making script-to-script dependencies
`"host": false`, it ensures that one script can depend upon the other being in
its same install directory.
Ports should never provide a `vcpkg-port-config.cmake` file under a different
`share/` subdirectory than the current port (`${PORT}`).
## Example
```cmake
# ${CURRENT_PACKAGES_DIR}/share/my-helper/vcpkg-port-config.cmake
# This include guard ensures the file will be loaded only once
include_guard(GLOBAL)
# This is how you could pull in a transitive dependency
include("${CMAKE_CURRENT_LIST_DIR}/../my-other-helper/vcpkg-port-config.cmake")
# Finally, it is convention to put each public function into a separate file with a matching name
include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_01.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_02.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_03.cmake")
```

166
externals/vcpkg/docs/maintainers/cmake-guidelines.md vendored Executable file
View file

@ -0,0 +1,166 @@
# CMake Guidelines
We expect that all CMake scripts that are either:
- In the `scripts/` directory, or
- In a `vcpkg-*` port
should follow the guidelines laid out in this document.
Existing scripts may not follow these guidelines yet;
it is expected that we will continue to update old scripts
to fall in line with these guidelines.
These guidelines are intended to create stability in our scripts.
We hope that they will make both forwards and backwards compatibility easier.
## The Guidelines
- Except for out-parameters, we always use `cmake_parse_arguments()`
rather than function parameters or referring to `${ARG<N>}`.
- This doesn't necessarily need to be followed for "script-local helper functions"
- In this case, positional parameters should be put in the function
declaration (rather than using `${ARG<N>}`),
and should be named according to local rules (i.e. `snake_case`).
- Exception: positional parameters that are optional should be
given a name via `set(argument_name "${ARG<N>}")`, after checking `ARGC`.
- Out-parameters should be the first parameter to a function. Example:
```cmake
function(format out_var)
cmake_parse_arguments(PARSE_ARGV 1 "arg" ...)
# ... set(buffer "output")
set("${out_var}" "${buffer}" PARENT_SCOPE)
endfunction()
```
- There are no unparsed or unused arguments.
Always check for `ARGN` or `arg_UNPARSED_ARGUMENTS`.
`FATAL_ERROR` when possible, `WARNING` if necessary for backwards compatibility.
- All `cmake_parse_arguments` must use `PARSE_ARGV`.
- All `foreach` loops must use `IN LISTS`, `IN ITEMS`, or `RANGE`.
- The variables `${ARGV}` and `${ARGN}` are unreferenced,
except in helpful messages to the user.
- (i.e., `message(FATAL_ERROR "blah was passed extra arguments: ${ARGN}")`)
- We always use functions, not macros or top level code.
- Exception: "script-local helper macros". It is sometimes helpful to define a small macro.
This should be done sparingly, and functions should be preferred.
- Exception: `vcpkg.cmake`'s `find_package`.
- Scripts in the scripts tree should not be expected to need observable changes
as part of normal operation.
- Example violation: `vcpkg_acquire_msys()` has hard-coded packages and versions
that need updating over time due to the MSYS project dropping old packages.
- Example exception: `vcpkg_from_sourceforge()` has a list of mirrors which
needs maintenance, but does not have an observable behavior impact on the callers.
- Rules for quoting: there are three kinds of arguments in CMake -
unquoted (`foo(BAR)`), quoted (`foo("BAR")`), and bracketed (`foo([[BAR]])`).
Follow these rules to quote correctly:
- If an argument contains a variable expansion `${...}`,
it must be quoted.
- Exception: a "splat" variable expansion, when one variable will be
passed to a function as multiple arguments. In this case, the argument
should simply be `${foo}`:
```cmake
vcpkg_list(SET working_directory)
if(DEFINED "arg_WORKING_DIRECTORY")
vcpkg_list(SET working_directory WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}")
endif()
# calls do_the_thing() if NOT DEFINED arg_WORKING_DIRECTORY,
# else calls do_the_thing(WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}")
do_the_thing(${working_directory})
```
- Otherwise, if the argument contains any escape sequences that are not
`\\`, `\"`, or `\$`, that argument must be a quoted argument.
- For example: `"foo\nbar"` must be quoted.
- Otherwise, if the argument contains a `\`, a `"`, or a `$`,
that argument should be bracketed.
- Example:
```cmake
set(x [[foo\bar]])
set(y [=[foo([[bar\baz]])]=])
```
- Otherwise, if the argument contains characters that are
not alphanumeric or `_`, that argument should be quoted.
- Otherwise, the argument should be unquoted.
- Exception: arguments to `if()` of type `<variable|string>` should always be quoted:
- Both arguments to the comparison operators -
`EQUAL`, `STREQUAL`, `VERSION_LESS`, etc.
- The first argument to `MATCHES` and `IN_LIST`
- Example:
```cmake
if("${FOO}" STREQUAL "BAR") # ...
if("${BAZ}" EQUAL "0") # ...
if("FOO" IN_LIST list_variable) # ...
if("${bar}" MATCHES [[a[bcd]+\.[bcd]+]]) # ...
```
- For single expressions and for other types of predicates that do not
take `<variable|string>`, use the normal rules.
- There are no "pointer" or "in-out" parameters
(where a user passes a variable name rather than the contents),
except for simple out-parameters.
- Variables are not assumed to be empty.
If the variable is intended to be used locally,
it must be explicitly initialized to empty with `set(foo "")` if it is a string variable,
and `vcpkg_list(SET foo)` if it is a list variable.
- `set(var)` should not be used. Use `unset(var)` to unset a variable,
`set(var "")` to set it to the empty string,
and `vcpkg_list(SET var)` to set it to the empty list.
_Note: the empty string and the empty list are the same value;_
_this is a notational difference rather than a difference in result_
- All variables expected to be inherited from the parent scope across an API boundary
(i.e. not a file-local function) should be documented.
Note that all variables mentioned in triplets.md are considered documented.
- Out parameters are only set in `PARENT_SCOPE` and are never read.
See also the helper `z_vcpkg_forward_output_variable()` to forward out parameters through a function scope.
- `CACHE` variables are used only for global variables which are shared internally among strongly coupled
functions and for internal state within a single function to avoid duplicating work.
These should be used extremely sparingly and should use the `Z_VCPKG_` prefix to avoid
colliding with any local variables that would be defined by any other code.
- Examples:
- `vcpkg_cmake_configure`'s `Z_VCPKG_CMAKE_GENERATOR`
- `z_vcpkg_get_cmake_vars`'s `Z_VCPKG_GET_CMAKE_VARS_FILE`
- `include()`s are only allowed in `ports.cmake` or `vcpkg-port-config.cmake`.
- `foreach(RANGE)`'s arguments _must always be_ natural numbers,
and `<start>` _must always be_ less than or equal to `<stop>`.
- This must be checked by something like:
```cmake
if("${start}" LESS_EQUAL "${end}")
foreach(RANGE "${start}" "${end}")
...
endforeach()
endif()
```
- All port-based scripts must use `include_guard(GLOBAL)`
to avoid being included multiple times.
### CMake Versions to Require
- All CMake scripts, except for `vcpkg.cmake`,
may assume the version of CMake that is present in the
`cmake_minimum_required` of `ports.cmake`.
- This `cmake_minimum_required` should be bumped every time a new version
of CMake is added to `vcpkgTools.xml`, as should the
`cmake_minimum_required` in all of the helper `CMakeLists.txt` files.
- `vcpkg.cmake` must assume a version of CMake back to 3.7.2 in general
- Specific functions and options may assume a greater CMake version;
if they do, make sure to comment that function or option
with the required CMake version.
### Changing Existing Functions
- Never remove arguments in non-internal functions;
if they should no longer do anything, just take them as normal and warn on use.
- Never add a new mandatory argument.
### Naming Variables
- `cmake_parse_arguments`: set prefix to `"arg"`
- Local variables are named with `snake_case`
- Internal global variable names are prefixed with `Z_VCPKG_`.
- External experimental global variable names are prefixed with `X_VCPKG_`.
- Internal functions are prefixed with `z_vcpkg_`
- Functions which are internal to a single function (i.e., helper functions)
are named `[z_]<func>_<name>`, where `<func>` is the name of the function they are
a helper to, and `<name>` is what the helper function does.
- `z_` should be added to the front if `<func>` doesn't have a `z_`,
but don't name a helper function `z_z_foo_bar`.
- Public global variables are named `VCPKG_`.

205
externals/vcpkg/docs/maintainers/control-files.md vendored Executable file
View file

@ -0,0 +1,205 @@
# CONTROL files
**CONTROL files are retained for backwards compatibility with earlier versions of vcpkg;
all new features are added only to [vcpkg.json manifest files](manifest-files.md), and we recommend using vcpkg.json for any newly authored port.
Use `./vcpkg format-manifest ports/<portname>/CONTROL` to convert an existing CONTROL file to a vcpkg.json file.**
The `CONTROL` file contains metadata about the port. The syntax is based on [the Debian `control` format][debian] although we only support the subset of fields documented here.
Field names are case-sensitive and start the line without leading whitespace. Paragraphs are separated by one or more empty lines.
[debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html
## Source Paragraph
The first paragraph in a `CONTROL` file is the Source paragraph. It must have a `Source`, `Version`, and `Description` field. The full set of fields is documented below.
### Examples:
```no-highlight
Source: ace
Version: 6.5.5
Description: The ADAPTIVE Communication Environment
```
```no-highlight
Source: vtk
Version: 8.2.0
Port-Version: 2
Description: Software system for 3D computer graphics, image processing, and visualization
Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype, expat, hdf5, libjpeg-turbo, proj4, lz4, libtheora, atlmfc (windows), eigen3, double-conversion, pugixml, libharu, sqlite3, netcdf-c
```
### Recognized fields
#### Source
The name of the port.
When adding new ports be aware that the name may conflict with other projects that are not a part of vcpkg. For example `json` conflicts with too many other projects so you should add a scope to the name such as `taocpp-json` to make it unique. Verify there are no conflicts on a search engine as well as on other package collections.
Package collections to check for conflicts:
+ [Repology](https://repology.org/projects/)
+ [Debian packages](https://www.debian.org/distrib/packages)
+ [Packages search](https://pkgs.org/)
#### Version
The library version.
This field is an alphanumeric string that may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bit strings and are only evaluated for equality.
For tagged-release ports, we follow the following convention:
1. If the port follows a scheme like `va.b.c`, we remove the leading `v`. In this case, it becomes `a.b.c`.
2. If the port includes its own name in the version like `curl-7_65_1`, we remove the leading name: `7_65_1`
For rolling-release ports, we use the date that the _commit was accessed by you_, formatted as `YYYY-MM-DD`. Stated another way: if someone had a time machine and went to that date, they would see this commit as the latest master.
For example, given:
1. The latest commit was made on 2019-04-19
2. The current version string is `2019-02-14-1`
3. Today's date is 2019-06-01.
Then if you update the source version today, you should give it version `2019-06-01`.
#### Port-Version
The version of the port.
This field is a non-negative integer. It allows one to version the port file separately from the version of the underlying library; if you make a change to a port, without changing the underlying version of the library, you should increment this field by one (starting at `0`, which is equivalent to no `Port-Version` field). When the version of the underlying library is upgraded, this field should be set back to `0` (i.e., delete the `Port-Version` field).
##### Examples:
```no-highlight
Version: 1.0.5
Port-Version: 2
```
```no-highlight
Version: 2019-03-21
```
#### Description
A description of the library.
By convention the first line of the description is a summary of the library. An optional detailed description follows. The detailed description can be multiple lines, all starting with whitespace.
##### Examples:
```no-highlight
Description: C++ header-only JSON library
```
```no-highlight
Description: Mosquitto is an open source message broker that implements the MQ Telemetry Transport protocol versions 3.1 and 3.1.1.
MQTT provides a lightweight method of carrying out messaging using a publish/subscribe model. This makes it suitable for "machine
to machine" messaging such as with low power sensors or mobile devices such as phones, embedded computers or microcontrollers like the Arduino.
```
#### Homepage
The URL of the homepage for the library where a user is able to find additional documentation or the original source code.
Example:
```no-highlight
Homepage: https://github.com/Microsoft/vcpkg
```
#### Build-Depends
Comma separated list of vcpkg ports the library has a dependency on.
Vcpkg does not distinguish between build-only dependencies and runtime dependencies. The complete list of dependencies needed to successfully use the library should be specified.
*For example: websocketpp is a header only library, and thus does not require any dependencies at install time. However, downstream users need boost and openssl to make use of the library. Therefore, websocketpp lists boost and openssl as dependencies*
If the port is dependent on optional features of another library those can be specified using the `portname[featurelist]` syntax. If the port does not require any features from the dependency, this should be specified as `portname[core]`.
Dependencies can be filtered based on the target triplet to support differing requirements. These filters use the same syntax as the Supports field below and are surrounded in parentheses following the portname and feature list.
##### Example:
```no-highlight
Build-Depends: rapidjson, curl[core,openssl] (!windows), curl[core,winssl] (windows)
```
#### Default-Features
Comma separated list of optional port features to install by default.
This field is optional.
##### Example:
```no-highlight
Default-Features: dynamodb, s3, kinesis
```
<a name="Supports"></a>
#### Supports
Expression that evaluates to true when the port is expected to build successfully for a triplet.
Currently, this field is only used in the CI testing to skip ports. In the future, this mechanism is intended to warn users in advance that a given install tree is not expected to succeed. Therefore, this field should be used optimistically; in cases where a port is expected to succeed 10% of the time, it should still be marked "supported".
The grammar for the supports expression uses standard operators:
- `!expr` - negation
- `expr|expr` - or (`||` is also supported)
- `expr&expr` - and (`&&` is also supported)
- `(expr)` - grouping/precedence
The predefined expressions are computed from standard triplet settings:
- `native` - `TARGET_TRIPLET` == `HOST_TRIPLET`
- `x64` - `VCPKG_TARGET_ARCHITECTURE` == `"x64"`
- `x86` - `VCPKG_TARGET_ARCHITECTURE` == `"x86"`
- `arm` - `VCPKG_TARGET_ARCHITECTURE` == `"arm"` or `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
- `arm64` - `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
- `windows` - `VCPKG_CMAKE_SYSTEM_NAME` == `""` or `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
- `uwp` - `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
- `linux` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Linux"`
- `osx` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Darwin"`
- `android` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Android"`
- `static` - `VCPKG_LIBRARY_LINKAGE` == `"static"`
- `wasm32` - `VCPKG_TARGET_ARCHITECTURE` == `"wasm32"`
- `emscripten` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Emscripten"`
These predefined expressions can be overridden in the triplet file via the [`VCPKG_DEP_INFO_OVERRIDE_VARS`](../users/triplets.md) option.
This field is optional and defaults to true.
> Implementers' Note: these terms are computed from the triplet via the `vcpkg_get_dep_info` mechanism.
##### Example:
```no-highlight
Supports: !(uwp|arm)
```
## Feature Paragraphs
Multiple optional features can be specified in the `CONTROL` files. It must have a `Feature` and `Description` field. It can optionally have a `Build-Depends` field. It must be separated from other paragraphs by one or more empty lines.
### Example:
```no-highlight
Source: vtk
Version: 8.2.0-2
Description: Software system for 3D computer graphics, image processing, and visualization
Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype, expat, hdf5, libjpeg-turbo, proj4, lz4, libtheora, atlmfc (windows), eigen3, double-conversion, pugixml, libharu, sqlite3, netcdf-c
Feature: openvr
Description: OpenVR functionality for VTK
Build-Depends: sdl2, openvr
Feature: qt
Description: Qt functionality for VTK
Build-Depends: qt5
Feature: mpi
Description: MPI functionality for VTK
Build-Depends: mpi, hdf5[parallel]
Feature: python
Description: Python functionality for VTK
Build-Depends: python3
```
### Recognized fields
#### Feature
The name of the feature.
#### Description
A description of the feature using the same syntax as the port `Description` field.
#### Build-Depends
The list of dependencies required to build and use this feature.
On installation the dependencies from all selected features are combined to produce the full dependency list for the build. This field follows the same syntax as `Build-Depends` in the Source Paragraph.

11
externals/vcpkg/docs/maintainers/execute_process.md vendored Executable file
View file

@ -0,0 +1,11 @@
# execute_process
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/execute_process.md).
Intercepts all calls to execute_process() inside portfiles and fails when Download Mode
is enabled.
In order to execute a process in Download Mode call `vcpkg_execute_in_download_mode()` instead.
## Source
[scripts/cmake/execute\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)

14
externals/vcpkg/docs/maintainers/internal/vcpkg_catalog_release_process.md vendored Executable file
View file

@ -0,0 +1,14 @@
# vcpkg_catalog_release_process
This document describes the acceptance criteria / process we use when doing a vcpkg release.
1. Generate a new GitHub Personal Access Token with repo permissions.
2. Using the PAT, invoke $/scripts/Get-Changelog.ps1 `-StartDate (previous release date) -EndDate (Get-Date) -OutFile path/to/results.md`
3. Create a new GitHub release in this repo.
4. Submit a vcpkg.ci (full tree rebuild) run with the same SHA as that release.
5. Use the "auto-generate release notes". Copy the "new contributors" and "full changelog" parts to the end of `path/to/results.md`.
6. Change `## New Contributors` to `#### New Contributors`
7. In `path/to/results.md`, update `LINK TO BUILD` with the most recent link to vcpkg.ci run.
8. In `path/to/results.md`, fill out the tables for number of existing ports and successful ports.
9. Replace the contents of the release notes with the contents of `path/to/results.md`
10. After the full rebuild submission completes, update the link to the one for the exact SHA, the counts, and remove "(tentative)".

42
externals/vcpkg/docs/maintainers/internal/vcpkg_tool_release_process.md vendored Executable file
View file

@ -0,0 +1,42 @@
# vcpkg_tool_release_process
This document describes the acceptance criteria / process we use when doing a vcpkg-tool update,
such as https://github.com/microsoft/vcpkg/pull/23757
1. Verify that all tests etc. are passing in the vcpkg-tool repo's `main` branch, and that the
contents therein are acceptable for release. (Steps after this will sign code there, so this
review is responsible gating what has access to code signing.)
2. Check that the changes there are in fact the changes that we want in that release. (Be aware,
you are responsible for what is about to be signed with a Microsoft code signing certificate by
proceeding)
3. Submit a new full tree rebuild by https://dev.azure.com/vcpkg/public/_build?definitionId=29
(microsoft.vcpkg.ci as of this writing) and queue a new build with the vcpkg-tool SHA overridden
to the one you wish to use. Example:
https://dev.azure.com/vcpkg/public/_build/results?buildId=73664&view=results
4. (Probably the next day) Check over the failures and ensure any differences with the most recent
full rebuild using the previous tool version are understood.
5. On your machine, in a prompt changed to the vcpkg-tool repo,
`git fetch https://github.com/microsoft/vcpkg-tool main && git switch -d FETCH_HEAD`
6. `git push https://devdiv.visualstudio.com/DevDiv/_git/vcpkg FETCH_HEAD:main`
7. Monitor the resulting signed build at:
https://devdiv.visualstudio.com/DefaultCollection/DevDiv/_build?definitionId=13610
and/or manually submit one. (The push is supposed to automatically submit a build but that
has been somewhat unstable at the time of this writing.)
8. The signed build will automatically create a draft GitHub release at
https://github.com/microsoft/vcpkg-tool/releases . Erase the contents filled in there and press
the "auto generate release notes" button. Manually remove any entries created by the automated
localization tools which will start with `* LEGO: Pull request from juno/`.
9. Publish that draft release as "pre-release".
10. Smoke test the 'one liner' installer: (Where 2022-06-15 is replaced with the right release name)
* Powershell:
`iex (iwr https://github.com/microsoft/vcpkg-tool/releases/download/2022-06-15/vcpkg-init.ps1)`
* Batch:
`curl -L -o vcpkg-init.cmd https://github.com/microsoft/vcpkg-tool/releases/download/2022-06-15/vcpkg-init.ps1 && .\vcpkg-init.cmd`
* Bash:
`. <(curl https://github.com/microsoft/vcpkg-tool/releases/download/2022-06-15/vcpkg-init -L)`
11. In the vcpkg repo, draft a PR which updates `bootstrap-vcpkg.sh` and `boostrap-vcpkg.ps1`
with the new release date, and update SHAs as appropriate in the .sh script. (For example, see
https://github.com/microsoft/vcpkg/pull/23757)
12. Merge the tool update PR.
13. Change the github release in vcpkg-tool from "prerelease" to "release". (This automatically
updates the aka.ms links)

32
externals/vcpkg/docs/maintainers/internal/z_vcpkg_apply_patches.md vendored Executable file
View file

@ -0,0 +1,32 @@
# z_vcpkg_apply_patches
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
Apply a set of patches to a source tree.
```cmake
z_vcpkg_apply_patches(
SOURCE_PATH <path-to-source>
[QUIET]
PATCHES <patch>...
)
```
The `<path-to-source>` should be set to `${SOURCE_PATH}` by convention,
and is the path to apply the patches in.
`z_vcpkg_apply_patches` will take the list of `<patch>`es,
which are by default relative to the port directory,
and apply them in order using `git apply`.
Generally, these `<patch>`es take the form of `some.patch`
to select patches in the port directory.
One may also download patches and use `${VCPKG_DOWNLOADS}/path/to/some.patch`.
If `QUIET` is not passed, it is a fatal error for a patch to fail to apply;
otherwise, if `QUIET` is passed, no message is printed.
This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
## Source
[scripts/cmake/z\_vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_apply_patches.cmake)

38
externals/vcpkg/docs/maintainers/internal/z_vcpkg_forward_output_variable.md vendored Executable file
View file

@ -0,0 +1,38 @@
# z_vcpkg_forward_output_variable
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
This macro helps with forwarding values from inner function calls,
through a local function scope, into pointer out parameters.
```cmake
z_vcpkg_forward_output_variable(ptr_to_parent_var var_to_forward)
```
is equivalent to
```cmake
if(DEFINED ptr_to_parent_var)
if(DEFINED value_var)
set("${ptr_to_parent_var}" "${value_var}" PARENT_SCOPE)
else()
unset("${ptr_to_parent_var}" PARENT_SCOPE)
endif()
endif()
```
Take note that the first argument should be a local variable that has a value of the parent variable name.
Most commonly, this local is the result of a pointer-out parameter to a function.
If the variable in the first parameter is not defined, this function does nothing,
simplifying functions with optional out parameters.
Most commonly, this should be used in cases like:
```cmake
function(my_function out_var)
file(SHA512 "somefile.txt" local_var)
z_vcpkg_forward_output_variable(out_var local_var)
endfunction()
```
## Source
[scripts/cmake/z\_vcpkg\_forward\_output\_variable.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_forward_output_variable.cmake)

29
externals/vcpkg/docs/maintainers/internal/z_vcpkg_function_arguments.md vendored Executable file
View file

@ -0,0 +1,29 @@
# z_vcpkg_function_arguments
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
Get a list of the arguments which were passed in.
Unlike `ARGV`, which is simply the arguments joined with `;`,
so that `(A B)` is not distinguishable from `("A;B")`,
this macro gives `"A;B"` for the first argument list,
and `"A\;B"` for the second.
```cmake
z_vcpkg_function_arguments(<out-var> [<N>])
```
`z_vcpkg_function_arguments` gets the arguments between `ARGV<N>` and the last argument.
`<N>` defaults to `0`, so that all arguments are taken.
## Example:
```cmake
function(foo_replacement)
z_vcpkg_function_arguments(ARGS)
foo(${ARGS})
...
endfunction()
```
## Source
[scripts/cmake/z\_vcpkg\_function\_arguments.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_function_arguments.cmake)

36
externals/vcpkg/docs/maintainers/internal/z_vcpkg_get_cmake_vars.md vendored Executable file
View file

@ -0,0 +1,36 @@
# z_vcpkg_get_cmake_vars
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
Runs a cmake configure with a dummy project to extract certain cmake variables
## Usage
```cmake
z_vcpkg_get_cmake_vars(<out-var>)
```
`z_vcpkg_get_cmake_vars(cmake_vars_file)` sets `<out-var>` to
a path to a generated CMake file, with the detected `CMAKE_*` variables
re-exported as `VCPKG_DETECTED_*`.
## Notes
Avoid usage in portfiles.
All calls to `z_vcpkg_get_cmake_vars` will result in the same output file;
the output file is not generated multiple times.
## Examples
* [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
### Basic Usage
```cmake
z_vcpkg_get_cmake_vars(cmake_vars_file)
include("${cmake_vars_file}")
message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CXX_FLAGS}")
```
## Source
[scripts/cmake/z\_vcpkg\_get\_cmake\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_get_cmake_vars.cmake)

21
externals/vcpkg/docs/maintainers/internal/z_vcpkg_prettify_command_line.md vendored Executable file
View file

@ -0,0 +1,21 @@
# z_vcpkg_prettify_command_line
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
Turn a command line into a formatted string.
```cmake
z_vcpkg_prettify_command_line(<out-var> <argument>...)
```
This command is for internal use, when printing out to a message.
## Examples
* `scripts/cmake/vcpkg_execute_build_process.cmake`
* `scripts/cmake/vcpkg_execute_required_process.cmake`
* `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
## Source
[scripts/cmake/z\_vcpkg\_prettify\_command\_line.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_prettify_command_line.cmake)

11
externals/vcpkg/docs/maintainers/internal/z_vcpkg_setup_pkgconfig_path.cmake.md vendored Executable file
View file

@ -0,0 +1,11 @@
# z_vcpkg_setup_pkgconfig_path
Setup the generated pkgconfig file path to PKG_CONFIG_PATH environment variable or restore PKG_CONFIG_PATH environment variable.
```cmake
z_vcpkg_setup_pkgconfig_path(BASE_DIRS <"${CURRENT_INSTALLED_DIR}" ...>)
z_vcpkg_restore_pkgconfig_path()
```
`z_vcpkg_setup_pkgconfig_path` prepends `lib/pkgconfig` and `share/pkgconfig` directories for the given `BASE_DIRS` to the `PKG_CONFIG_PATH` environment variable. It creates or updates a backup of the previous value.
`z_vcpkg_restore_pkgconfig_path` shall be called when leaving the scope which called `z_vcpkg_setup_pkgconfig_path` in order to restore the original value from the backup.

16
externals/vcpkg/docs/maintainers/internal/z_vcpkg_setup_pkgconfig_path.md vendored Executable file
View file

@ -0,0 +1,16 @@
# z_vcpkg_setup_pkgconfig_path
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
`z_vcpkg_setup_pkgconfig_path` sets up environment variables to use `pkgconfig`, such as `PKG_CONFIG` and `PKG_CONFIG_PATH`.
The original values are restored with `z_vcpkg_restore_pkgconfig_path`. `BASE_DIRS` indicates the base directories to find `.pc` files; typically `${CURRENT_INSTALLED_DIR}`, or `${CURRENT_INSTALLED_DIR}/debug`.
```cmake
z_vcpkg_setup_pkgconfig_path(BASE_DIRS <"${CURRENT_INSTALLED_DIR}" ...>)
# Build process that may transitively invoke pkgconfig
z_vcpkg_restore_pkgconfig_path()
```
## Source
[scripts/cmake/z\_vcpkg\_setup\_pkgconfig\_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_setup_pkgconfig_path.cmake)

418
externals/vcpkg/docs/maintainers/maintainer-guide.md vendored Executable file
View file

@ -0,0 +1,418 @@
# Maintainer Guidelines and Policies
This document lists a set of policies that you should apply when adding or updating a port recipe.
It is intended to serve the role of
[Debian's Policy Manual](https://www.debian.org/doc/debian-policy/),
[Homebrew's Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines), and
[Homebrew's Formula Cookbook](https://docs.brew.sh/Formula-Cookbook).
## PR Structure
### Make separate Pull Requests per port
Whenever possible, separate changes into multiple PRs.
This makes them significantly easier to review and prevents issues with one set of changes from holding up every other change.
### Avoid trivial changes in untouched files
For example, avoid reformatting or renaming variables in portfiles that otherwise have no reason to be modified for the issue at hand.
However, if you need to modify the file for the primary purpose of the PR (updating the library),
then obviously beneficial changes like fixing typos are appreciated!
### Check names against other repositories
A good service to check many at once is [Repology](https://repology.org/).
If the library you are adding could be confused with another one,
consider renaming to make it clear. We prefer when names are longer and/or
unlikely to conflict with any future use of the same name. If the port refers
to a library on GitHub, a good practice is to prefix the name with the organization
if there is any chance of confusion.
### Use GitHub Draft PRs
GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge.
Most new PRs should be opened as drafts and converted to normal PRs once the CI passes.
More information about GitHub Draft PRs:
https://github.blog/2019-02-14-introducing-draft-pull-requests/
## Portfiles
### Avoid deprecated helper functions
At this time, the following helpers are deprecated:
1. `vcpkg_extract_source_archive()` should be replaced by [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md)
2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md))
3. `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md)
4. `vcpkg_copy_tool_dependencies()` should be replaced by [`vcpkg_copy_tools()`](vcpkg_copy_tools.md)
5. `vcpkg_configure_cmake` should be replaced by [`vcpkg_cmake_configure()`](ports/vcpkg-cmake/vcpkg_cmake_configure.md#vcpkg_cmake_configure) after removing `PREFER_NINJA` (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md#vcpkg-cmake))
6. `vcpkg_build_cmake` should be replaced by [`vcpkg_cmake_build()`](ports/vcpkg-cmake/vcpkg_cmake_build.md#vcpkg_cmake_build) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md#vcpkg-cmake))
7. `vcpkg_install_cmake` should be replaced by [`vcpkg_cmake_install()`](ports/vcpkg-cmake/vcpkg_cmake_install.md#vcpkg_cmake_install) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md#vcpkg-cmake))
8. `vcpkg_fixup_cmake_targets` should be replaced by [`vcpkg_cmake_config_fixup`](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md#vcpkg_cmake_config_fixup) (from port [`vcpkg-cmake-config`](ports/vcpkg-cmake-config.md#vcpkg-cmake-config))
Some of the replacement helper functions are in "tools ports" to allow consumers to pin their
behavior at specific versions, to allow locking the behavior of the helpers at a particular
version. Tools ports need to be added to your port's `"dependencies"`, like so:
```json
{
"name": "vcpkg-cmake",
"host": true
},
{
"name": "vcpkg-cmake-config",
"host": true
}
```
### Avoid excessive comments in portfiles
Ideally, portfiles should be short, simple, and as declarative as possible.
Remove any boiler plate comments introduced by the `create` command before submitting a PR.
### Ports must not be path dependent
Ports must not change their behavior based on which ports are already installed in a form that would change which contents that port installs. For example, given:
```
> vcpkg install a
> vcpkg install b
> vcpkg remove a
```
and
```
> vcpkg install b
```
the files installed by `b` must be the same, regardless of influence by the previous installation of `a`. This means that ports must not try to detect whether something is provided in the installed tree by another port before taking some action. A specific and common cause of such "path dependent" behavior is described below in "When defining features, explicitly control dependencies."
### Unique port attribution rule
In the entire vcpkg system, no two ports a user is expected to use concurrently may provide the same file. If a port tries to install a file already provided by another file, installation will fail. If a port wants to use an extremely common name for a header, for example, it should place those headers in a subdirectory rather than in `include`.
### Add CMake exports in an unofficial- namespace
A core design ideal of vcpkg is to not create "lock-in" for customers. In the build system, there should be no difference between depending on a library from the system, and depending on a library from vcpkg. To that end, we avoid adding CMake exports or targets to existing libraries with "the obvious name", to allow upstreams to add their own official CMake exports without conflicting with vcpkg.
To that end, any CMake configs that the port exports, which are not in the upstream library, should have `unofficial-` as a prefix. Any additional targets should be in the `unofficial::<port>::` namespace.
This means that the user should see:
* `find_package(unofficial-<port> CONFIG)` as the way to get at the unique-to-vcpkg package
* `unofficial::<port>::<target>` as an exported target from that port.
Examples:
* [`brotli`](https://github.com/microsoft/vcpkg/blob/4f0a640e4c5b74166b759a862d7527c930eff32e/ports/brotli/install.patch) creates the `unofficial-brotli` package, producing target `unofficial::brotli::brotli`.
## Features
### Do not use features to implement alternatives
Features must be treated as additive functionality. If port[featureA] installs and port[featureB] installs, then port[featureA,featureB] must install. Moreover, if a second port depends on [featureA] and a third port depends on [featureB], installing both the second and third ports should have their dependencies satisfied.
Libraries in this situation must choose one of the available options as expressed in vcpkg, and users who want a different setting must use overlay ports at this time.
Existing examples we would not accept today retained for backwards compatibility:
* `libgit2`, `libzip`, `open62541` all have features for selecting a TLS or crypto backend. Note that `curl` has different crypto backend options but allows selecting between them at runtime, meaning the above tenet is maintained.
* `darknet` has `opencv2`, `opencv3`, features to control which version of opencv to use for its dependencies.
### A feature may engage preview or beta functionality
Notwithstanding the above, if there is a preview branch or similar where the preview functionality has a high probability of not disrupting the non-preview functionality (for example, no API removals), a feature is acceptable to model this setting.
Examples:
* The Azure SDKs (of the form `azure-Xxx`) have a `public-preview` feature.
* `imgui` has an `experimental-docking` feature which engages their preview docking branch which uses a merge commit attached to each of their public numbered releases.
### Default features should enable behaviors, not APIs
If a consumer is depending directly upon a library, they can list out any desired features easily (`library[feature1,feature2]`). However, if a consumer _does not know_ they are using a library, they cannot list out those features. If that hidden library is like `libarchive` where features are adding additional compression algorithms (and thus behaviors) to an existing generic interface, default features offer a way to ensure a reasonably functional transitive library is built even if the final consumer doesn't name it directly.
If the feature adds additional APIs (or executables, or library binaries) and doesn't modify the behavior of existing APIs, it should be left off by default. This is because any consumer which might want to use those APIs can easily require it via their direct reference.
If in doubt, do not mark a feature as default.
### Do not use features to control alternatives in published interfaces
If a consumer of a port depends on only the core functionality of that port, with high probability they must not be broken by turning on the feature. This is even more important when the alternative is not directly controlled by the consumer, but by compiler settings like `/std:c++17` / `-std=c++17`.
Existing examples we would not accept today retained for backwards compatibility:
* `redis-plus-plus[cxx17]` controls a polyfill but does not bake the setting into the installed tree.
* `ace[wchar]` changes all APIs to accept `const wchar_t*` rather than `const char*`.
### A feature may replace polyfills with aliases provided that replacement is baked into the installed tree
Notwithstanding the above, ports may remove polyfills with a feature, as long as:
1. Turning on the feature changes the polyfills to aliases of the polyfilled entity
2. The state of the polyfill is baked into the installed headers, such that ABI mismatch "impossible" runtime errors are unlikely
3. It is possible for a consumer of the port to write code which works in both modes, for example by using a typedef which is either polyfilled or not
Example:
* `abseil[cxx17]` changes `absl::string_view` to a replacement or `std::string_view`; the patch
https://github.com/microsoft/vcpkg/blob/981e65ce0ac1f6c86e5a5ded7824db8780173c76/ports/abseil/fix-cxx-standard.patch implements the baking requirement
### Recommended solutions
If it's critical to expose the underlying alternatives, we recommend providing messages at build time to instruct the user on how to copy the port into a private overlay:
```cmake
set(USING_DOG 0)
message(STATUS "This version of LibContosoFrobnicate uses the Kittens backend. To use the Dog backend instead, create an overlay port of this with USING_DOG set to 1 and the `kittens` dependency replaced with `dog`.")
message(STATUS "This recipe is at ${CMAKE_CURRENT_LIST_DIR}")
message(STATUS "See the overlay ports documentation at https://github.com/microsoft/vcpkg/blob/master/docs/specifications/ports-overlay.md")
```
## Build Techniques
### Do not use vendored dependencies
Do not use embedded copies of libraries.
All dependencies should be split out and packaged separately so they can be updated and maintained.
### Prefer using CMake
When multiple buildsystems are available, prefer using CMake.
Additionally, when appropriate, it can be easier and more maintainable to rewrite alternative buildsystems into CMake using `file(GLOB)` directives.
Examples: [abseil](../../ports/abseil/portfile.cmake)
### Choose either static or shared binaries
By default, `vcpkg_cmake_configure()` will pass in the appropriate setting for `BUILD_SHARED_LIBS`,
however for libraries that don't respect that variable, you can switch on `VCPKG_LIBRARY_LINKAGE`:
```cmake
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED)
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
OPTIONS
-DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC}
-DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED}
)
```
### When defining features, explicitly control dependencies
When defining a feature that captures an optional dependency,
ensure that the dependency will not be used accidentally when the feature is not explicitly enabled.
```cmake
set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB OFF)
if ("zlib" IN_LIST FEATURES)
set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB ON)
endif()
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
OPTIONS
-DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
-DCMAKE_REQUIRE_FIND_PACKAGE_ZLIB=${CMAKE_REQUIRE_FIND_PACKAGE_ZLIB}
)
```
The snippet below using `vcpkg_check_features()` is equivalent, [see the documentation](vcpkg_check_features.md).
```cmake
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
FEATURES
"zlib" CMAKE_REQUIRE_FIND_PACKAGE_ZLIB
INVERTED_FEATURES
"zlib" CMAKE_DISABLE_FIND_PACKAGE_ZLIB
)
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
OPTIONS
${FEATURE_OPTIONS}
)
```
Note that `ZLIB` in the above is case-sensitive. See the [CMAKE_DISABLE_FIND_PACKAGE_PackageName](https://cmake.org/cmake/help/v3.22/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html) and [CMAKE_REQUIRE_FIND_PACKAGE_PackageName](https://cmake.org/cmake/help/v3.22/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.html) documnetation for more details.
### Place conflicting libs in a `manual-link` directory
A lib is considered conflicting if it does any of the following:
+ Define `main`
+ Define malloc
+ Define symbols that are also declared in other libraries
Conflicting libs are typically by design and not considered a defect. Because some build systems link against everything in the lib directory, these should be moved into a subdirectory named `manual-link`.
## Manifests and CONTROL files
When adding a new port, use the new manifest syntax for defining a port;
you may also change over to manifests when modifying an existing port.
You may do so easily by running the `vcpkg format-manifest` command, which will convert existing CONTROL
files into manifest files. Do not convert CONTROL files that have not been modified.
## Versioning
### Follow common conventions for the `"version"` field
See our [versioning documentation](../users/versioning.md#version-schemes) for a full explanation of our conventions.
### Update the `"port-version"` field in the manifest file of any modified ports
Vcpkg uses this field to determine whether a given port is out-of-date and should be changed whenever the port's behavior changes.
Our convention is to use the `"port-version"` field for changes to the port that don't change the upstream version, and to reset the `"port-version"` back to zero when an update to the upstream version is made.
For Example:
- Zlib's package version is currently `1.2.1`, with no explicit `"port-version"` (equivalent to a `"port-version"` of `0`).
- You've discovered that the wrong copyright file has been deployed, and fixed that in the portfile.
- You should update the `"port-version"` field in the manifest file to `1`.
See our [manifest files document](manifest-files.md#port-version) for a full explanation of our conventions.
### Update the version files in `versions/` of any modified ports
Vcpkg uses a set of metadata files to power its versioning feature.
These files are located in the following locations:
* `${VCPKG_ROOT}/versions/baseline.json`, (this file is common to all ports) and
* `${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json` (one per port).
For example, for `zlib` the relevant files are:
* `${VCPKG_ROOT}/versions/baseline.json`
* `${VCPKG_ROOT}/versions/z-/zlib.json`
We expect that each time you update a port, you also update its version files.
**The recommended method to update these files is to run the `x-add-version` command, e.g.:**
```
vcpkg x-add-version zlib
```
If you're updating multiple ports at the same time, instead you can run:
```
vcpkg x-add-version --all
```
To update the files for all modified ports at once.
_NOTE: These commands require you to have committed your changes to the ports before running them. The reason is that the Git SHA of the port directory is required in these version files. But don't worry, the `x-add-version` command will warn you if you have local changes that haven't been committed._
See our [versioning specification](../specifications/versioning.md) and [registries specification](../specifications/registries-2.md) to learn how vcpkg interacts with these files.
## Patching
### Prefer options over patching
It is preferable to set options in a call to `vcpkg_configure_xyz()` over patching the settings directly.
Common options that allow avoiding patching:
1. [MSBUILD] `<PropertyGroup>` settings inside the project file can be overridden via `/p:` parameters
2. [CMAKE] Calls to `find_package(XYz)` in CMake scripts can be disabled via [`-DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON`](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html)
3. [CMAKE] Cache variables (declared as `set(VAR "value" CACHE STRING "Documentation")` or `option(VAR "Documentation" "Default Value")`) can be overridden by just passing them in on the command line as `-DVAR:STRING=Foo`. One notable exception is if the `FORCE` parameter is passed to `set()`. See also the [CMake `set` documentation](https://cmake.org/cmake/help/v3.15/command/set.html)
### Prefer patching over overriding `VCPKG_<VARIABLE>` values
Some variables prefixed with `VCPKG_<VARIABLE>` have an equivalent `CMAKE_<VARIABLE>`.
However, not all of them are passed to the internal package build [(see implementation: Windows toolchain)](../../scripts/toolchains/windows.cmake).
Consider the following example:
```cmake
set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}")
set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}")
```
Using `vcpkg`'s built-in toolchains this works, because the value of `VCPKG_<LANG>_FLAGS` is forwarded to the appropriate `CMAKE_LANG_FLAGS` variable. But, a custom toolchain that is not aware of `vcpkg`'s variables will not forward them.
Because of this, it is preferable to patch the buildsystem directly when setting `CMAKE_<LANG>_FLAGS`.
### Minimize patches
When making changes to a library, strive to minimize the final diff. This means you should _not_ reformat the upstream source code when making changes that affect a region. Also, when disabling a conditional, it is better to add a `AND FALSE` or `&& 0` to the condition than to delete every line of the conditional.
Don't add patches if the port is outdated and updating the port to a newer released version would solve the same issue. vcpkg prefers updating ports over patching outdated versions unless the version bump breaks a considerable amount of dependent ports.
This helps to keep the size of the vcpkg repository down as well as improves the likelihood that the patch will apply to future code versions.
### Do not implement features in patches
The purpose of patching in vcpkg is to enable compatibility with compilers, libraries, and platforms. It is not to implement new features in lieu of following proper Open Source procedure (submitting an Issue/PR/etc).
## Do not build tests/docs/examples by default
When submitting a new port, check for any options like `BUILD_TESTS` or `WITH_TESTS` or `POCO_ENABLE_SAMPLES` and ensure the additional binaries are disabled. This minimizes build times and dependencies for the average user.
Optionally, you can add a `test` feature which enables building the tests, however this should not be in the `Default-Features` list.
## Enable existing users of the library to switch to vcpkg
### Do not add `CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS`
Unless the author of the library is already using it, we should not use this CMake functionality because it interacts poorly with C++ templates and breaks certain compiler features. Libraries that don't provide a .def file and do not use __declspec() declarations simply do not support shared builds for Windows and should be marked as such with `vcpkg_check_linkage(ONLY_STATIC_LIBRARY)`.
### Do not rename binaries outside the names given by upstream
This means that if the upstream library has different names in release and debug (libx versus libxd), then the debug library should not be renamed to `libx`. Vice versa, if the upstream library has the same name in release and debug, we should not introduce a new name.
Important caveat:
- Static and shared variants often should be renamed to a common scheme. This enables consumers to use a common name and be ignorant of the downstream linkage. This is safe because we only make one at a time available.
Note that if a library generates CMake integration files (`foo-config.cmake`), renaming must be done through patching the CMake build itself instead of simply calling `file(RENAME)` on the output archives/LIBs.
Finally, DLL files on Windows should never be renamed post-build because it breaks the generated LIBs.
## Code format
### Vcpkg internal code
We require the C++ code inside vcpkg to follow the clang-format, if you change them. Please perform the following steps after modification:
- Use Visual Studio:
1. Configure your [clang-format tools](https://devblogs.microsoft.com/cppblog/clangformat-support-in-visual-studio-2017-15-7-preview-1/).
2. Open the modified file.
3. Use shortcut keys Ctrl+K, Ctrl+D to format the current file.
- Use tools:
1. Install [llvm clang-format](https://releases.llvm.org/download.html#10.0.0)
2. Run command:
```cmd
> LLVM_PATH/bin/clang-format.exe -style=file -i changed_file.cpp
```
### Manifests
We require that the manifest file be formatted. Use the following command to format all manifest files:
```cmd
> vcpkg format-manifest --all
```
## Useful implementation notes
### Portfiles are run in Script Mode
While `portfile.cmake`'s and `CMakeLists.txt`'s share a common syntax and core CMake language constructs, portfiles run in "Script Mode", whereas `CMakeLists.txt` files run in "Build Mode" (unofficial term). The most important difference between these two modes is that "Script Mode" does not have a concept of "Target" -- any behaviors that depend on the "target" machine (`CMAKE_CXX_COMPILER`, `CMAKE_EXECUTABLE_SUFFIX`, `CMAKE_SYSTEM_NAME`, etc) will not be correct.
Portfiles have direct access to variables set in the triplet file, but `CMakeLists.txt`s do not (though there is often a translation that happens -- `VCPKG_LIBRARY_LINKAGE` versus `BUILD_SHARED_LIBS`).
Portfiles and CMake builds invoked by portfiles are run in different processes. Conceptually:
```no-highlight
+----------------------------+ +------------------------------------+
| CMake.exe | | CMake.exe |
+----------------------------+ +------------------------------------+
| Triplet file | ====> | Toolchain file |
| (x64-windows.cmake) | | (scripts/buildsystems/vcpkg.cmake) |
+----------------------------+ +------------------------------------+
| Portfile | ====> | CMakeLists.txt |
| (ports/foo/portfile.cmake) | | (buildtrees/../CMakeLists.txt) |
+----------------------------+ +------------------------------------+
```
To determine the host in a portfile, the standard CMake variables are fine (`CMAKE_HOST_WIN32`).
To determine the target in a portfile, the vcpkg triplet variables should be used (`VCPKG_CMAKE_SYSTEM_NAME`).
See also our [triplet documentation](../users/triplets.md) for a full enumeration of possible settings.

551
externals/vcpkg/docs/maintainers/manifest-files.md vendored Executable file
View file

@ -0,0 +1,551 @@
# Manifest files - `vcpkg.json`
The `vcpkg.json` file contains metadata about the port.
It's a JSON file, and replaces the existing CONTROL file metadata structure.
It must have a top level object, and all fields are case sensitive.
## Examples:
The most important fields in a manifest, the ones which are required for all ports,
are the `"name"` field, and a version field (for now, just `"version-string"`).
There's more information about these fields below.
```json
{
"name": "ace",
"version-string": "6.5.5"
}
```
```json
{
"name": "vtk",
"version-string": "8.2.0",
"port-version": 2,
"description": "Software system for 3D computer graphics, image processing, and visualization",
"dependencies": [
{
"name": "atlmfc",
"platform": "windows"
},
"double-conversion",
"eigen3",
"expat",
"freetype",
"glew",
"hdf5",
"jsoncpp",
"libharu",
"libjpeg-turbo",
"libpng",
"libtheora",
"libxml2",
"lz4",
"netcdf-c",
"proj4",
"pugixml",
"sqlite3",
"tiff",
"zlib"
]
}
```
## Fields
### `"name"`
The name of the port.
When adding new ports be aware that the name may conflict with other projects that are not a part of vcpkg. For example `json` conflicts with too many other projects so you should add a scope to the name such as `taocpp-json` to make it unique. Verify there are no conflicts on a search engine as well as on other package collections.
Package collections to check for conflicts:
+ [Repology](https://repology.org/projects/)
+ [Debian packages](https://www.debian.org/distrib/packages)
+ [Packages search](https://pkgs.org/)
A name must be an identifier: i.e., it must only consist of lowercase ascii alphabetic characters,
numbers, and hyphens, and it must not begin nor end with a hyphen.
### Version fields
Currently there are different fields for special versioning. Namely:
Manifest property | Versioning scheme
------------------|------------------------------------
`version` | For dot-separated numeric versions
`version-semver` | For SemVer compliant versions
`version-date` | For dates in the format YYYY-MM-DD
`version-string` | For arbitrary strings
See https://github.com/microsoft/vcpkg/blob/master/docs/specifications/versioning.md#22-package-versions for more details.
Additionally, `"port-version"` is used to differentiate between port changes that don't change the underlying library version.
#### `"version-string"`
This field is an ascii string, and may contain alphanumeric characters, `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as byte strings and are only evaluated for equality.
For tagged-release ports, we follow the following convention:
1. If the library follows a scheme like `va.b.c`, we remove the leading `v`. In this case, it becomes `a.b.c`.
2. If the library includes its own name in the version like `curl-7_65_1`, we remove the leading name: `7_65_1`
3. If the library is versioned by dates, format the resulting version string just like the upstream library;
for example, Abseil formats their dates `lts_2020_02_25`, so the `"version-string"` should be `"lts_2020_02_25"`.
For rolling-release ports, we use the date that the _commit was accessed by you_, formatted as `YYYY-MM-DD`. Stated another way: if someone had a time machine and went to that date, they would see this commit as the latest master.
For example, given:
1. The latest commit was made on 2019-04-19
2. The current version string is `2019-02-14`
3. Today's date is 2019-06-01.
Then if you update the source version today, you should give it version `2019-06-01`.
#### `"port-version"`
The version of the port, aside from the library version.
This field is a non-negative integer.
It allows one to version the port file separately from the version of the underlying library;
if you make a change to a port, without changing the underlying version of the library,
you should increment this field by one (starting at `0`, which is equivalent to no `"port-version"` field).
When the version of the underlying library is upgraded,
this field should be set back to `0` (i.e., delete the `"port-version"` field).
#### Examples:
```json
{
"version": "1.0.5",
"port-version": 2
}
```
```json
{
"version": "2019-03-21"
}
```
### `"description"`
A description of the library.
This field can either be a single string, which should be a summary of the library,
or can be an array, with the first line being a summary and the remaining lines being the detailed description -
one string per line.
#### Examples:
```json
{
"description": "C++ header-only JSON library"
}
```
```json
{
"description": [
"Mosquitto is an open source message broker that implements the MQ Telemetry Transport protocol versions 3.1 and 3.1.1.",
"MQTT provides a lightweight method of carrying out messaging using a publish/subscribe model."
"This makes it suitable for 'machine to machine' messaging such as with low power sensors or mobile devices such as phones, embedded computers or microcontrollers like the Arduino."
]
}
```
### `"homepage"`
The URL of the homepage for the library where a user is able to find additional documentation or the original source code.
### `"documentation"`
The URL where a user would be able to find official documentation for the library. Optional.
### `"maintainers"`
A list of strings that define the set of maintainers of a package.
It's recommended that these take the form of `Givenname Surname <email>`,
but this field is not checked for consistency.
Optional.
#### Example:
```json
{
"homepage": "https://github.com/microsoft/vcpkg"
}
```
### `"dependencies"`
An array of ports the library has a dependency on.
vcpkg does not distinguish between build-only dependencies and runtime dependencies.
The complete list of dependencies needed to successfully use the library should be specified.
For example: websocketpp is a header only library, and thus does not require any dependencies at install time.
However, downstream users need boost and openssl to make use of the library.
Therefore, websocketpp lists boost and openssl as dependencies.
Each dependency may be either an identifier, or an object.
For many dependencies, just listing the name of the library should be fine;
however, if one needs to add extra information to that dependency, one may use the dependency object.
For a dependency object, the `"name"` field is used to designate the library;
for example the dependency object `{ "name": "zlib" }` is equivalent to just writing `"zlib"`.
If the port is dependent on optional features of another library,
those can be specified using the `"features"` field of the dependency object.
If the port does not require any features from the dependency,
this should be specified with the `"default-features"` fields set to `false`.
Dependencies can also be filtered based on the target triplet to support differing requirements.
These filters use the same syntax as the `"supports"` field below,
and are specified in the `"platform"` field.
#### Example:
```json
{
"dependencies": [
{
"name": "curl",
"default-features": false,
"features": [
"winssl"
],
"platform": "windows"
},
{
"name": "curl",
"default-features": false,
"features": [
"openssl"
],
"platform": "!windows"
},
"rapidjson"
]
}
```
### `"features"`
Multiple optional features can be specified in manifest files, in the `"features"` object field.
This field is a map from the feature name, to the feature's information.
Each one must have a `"description"` field, and may also optionally have a `"dependencies"` field.
A feature's name must be an identifier -
in other words, lowercase alphabetic characters, digits, and hyphens,
neither starting nor ending with a hyphen.
A feature's `"description"` is a description of the feature,
and is the same kind of thing as the port `"description"` field.
A feature's `"dependencies"` field contains the list of extra dependencies required to build and use this feature;
this field isn't required if the feature doesn't require any extra dependencies.
On installation the dependencies from all selected features are combined to produce the full dependency list for the build.
#### Example:
```json
{
"name": "vtk",
"version-string": "8.2.0",
"port-version": 2,
"description": "Software system for 3D computer graphics, image processing, and visualization",
"dependencies": [
{
"name": "atlmfc",
"platform": "windows"
},
"double-conversion",
"eigen3",
"expat",
"freetype",
"glew",
"hdf5",
"jsoncpp",
"libharu",
"libjpeg-turbo",
"libpng",
"libtheora",
"libxml2",
"lz4",
"netcdf-c",
"proj4",
"pugixml",
"sqlite3",
"tiff",
"zlib"
],
"features": {
"mpi": {
"description": "MPI functionality for VTK",
"dependencies": [
{
"name": "hdf5",
"features": [
"parallel"
]
},
"mpi"
]
},
"openvr": {
"description": "OpenVR functionality for VTK",
"dependencies": [
"openvr",
"sdl2"
]
},
"python": {
"description": "Python functionality for VTK",
"dependencies": [
"python3"
]
},
"qt": {
"description": "Qt functionality for VTK",
"dependencies": [
"qt5"
]
}
}
}
```
### `"default-features"`
An array of feature names that the library uses by default, if nothing else is specified.
#### Example:
```json
{
"default-features": [
"kinesis"
],
"features": {
"dynamodb": {
"description": "Build dynamodb support",
"dependencies": [
"dynamodb"
]
},
"kinesis": {
"description": "build kinesis support"
}
}
}
```
### `"supports"`
A string, formatted as a platform expression,
that evaluates to true when the port should build successfully for a triplet.
This field is used in the CI testing to skip ports,
and warns users in advance that a given install tree is not expected to succeed.
Therefore, this field should be used optimistically;
in cases where a port is expected to succeed 10% of the time, it should still be marked "supported".
The grammar for this top-level platform expression, in [EBNF], is as follows:
```ebnf
whitespace-character =
| ? U+0009 "CHARACTER TABULATION" ?
| ? U+000A "LINE FEED" ?
| ? U+000D "CARRIAGE RETURN" ?
| ? U+0020 "SPACE" ? ;
optional-whitespace = { whitespace-character } ;
required-whitespace = whitespace-character, { optional-whitespace } ;
lowercase-alpha =
| "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m"
| "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" ;
digit =
| "0" | "1" | "2" | "3" | "4"
| "5" | "6" | "7" | "8" | "9" ;
identifier-character =
| lowercase-alpha
| digit ;
platform-expression-list =
| platform-expression { ",", optional-whitespace, platform-expression } ;
platform-expression =
| platform-expression-not
| platform-expression-and
| platform-expression-or ;
platform-expression-identifier =
| identifier-character, { identifier-character }, optional-whitespace ;
platform-expression-grouped =
| "(", optional-whitespace, platform-expression, ")", optional-whitespace ;
platform-expression-simple =
| platform-expression-identifier
| platform-expression-grouped ;
platform-expression-unary-keyword-operand =
| required-whitespace, platform-expression-simple
| optional-whitespace, platform-expression-grouped ;
platform-expression-not =
| platform-expression-simple
| "!", optional-whitespace, platform-expression-simple
| "not", platform-expression-unary-keyword-operand ;
platform-expression-binary-keyword-first-operand =
| platform-expression-not, required-whitespace
| platform-expression-grouped ;
platform-expression-binary-keyword-second-operand =
| required-whitespace, platform-expression-not
| platform-expression-grouped ;
platform-expression-and =
| platform-expression-not, { "&", optional-whitespace, platform-expression-not }
| platform-expression-binary-keyword-first-operand, { "and", platform-expression-binary-keyword-second-operand } ;
platform-expression-or =
| platform-expression-not, { "|", optional-whitespace, platform-expression-not }
| platform-expression-binary-keyword-first-operand, { "or", platform-expression-binary-keyword-second-operand } (* to allow for future extension *) ;
top-level-platform-expression = optional-whitespace, platform-expression-list ;
```
Basically, there are four kinds of expressions -- identifiers, negations, ands, and ors.
Negations may only negate an identifier or a grouped expression.
Ands and ors are a list of `&` or `|` separated identifiers, negated expressions, and grouped expressions.
One may not mix `&` and `|` without parentheses for grouping.
These predefined identifier expressions are computed from standard triplet settings:
- `native` - `TARGET_TRIPLET` == `HOST_TRIPLET`;
useful for ports which depend on their own built binaries in their build.
- `x64` - `VCPKG_TARGET_ARCHITECTURE` == `"x64"`
- `x86` - `VCPKG_TARGET_ARCHITECTURE` == `"x86"`
- `arm` - `VCPKG_TARGET_ARCHITECTURE` == `"arm"` or `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
- `arm64` - `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
- `windows` - `VCPKG_CMAKE_SYSTEM_NAME` == `""` or `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
- `mingw` - `VCPKG_CMAKE_SYSTEM_NAME` == `"MinGW"`
- `uwp` - `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
- `linux` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Linux"`
- `osx` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Darwin"`
- `android` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Android"`
- `static` - `VCPKG_LIBRARY_LINKAGE` == `"static"`
- `wasm32` - `VCPKG_TARGET_ARCHITECTURE` == `"wasm32"`
- `emscripten` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Emscripten"`
- `staticcrt` - `VCPKG_CRT_LINKAGE` == `"static"`
These predefined identifier expressions can be overridden in the triplet file,
via the [`VCPKG_DEP_INFO_OVERRIDE_VARS`](../users/triplets.md) option,
and new identifier expressions can be added via the same mechanism.
This field is optional and defaults to true.
> Implementers' Note: these terms are computed from the triplet via the `vcpkg_get_dep_info` mechanism.
[EBNF]: https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form
#### Example:
```json
{
"supports": "!uwp & !(arm & !arm64)"
}
```
This means "doesn't support uwp, nor arm32 (but does support arm64)".
### `"license"`
The license of the port. This is an [SPDX license expression],
or `null` for proprietary licenses and other licenses for which
one should "just read the `copyright` file" (e.g., Qt).
[SPDX license expression]: https://spdx.dev/ids/#how
Additionally, you can find the list of [recognized license IDs]
and [recognized license exception IDs] in Annex A of the SPDX specification.
[recognized license IDs]: https://spdx.github.io/spdx-spec/SPDX-license-list/#a1-licenses-with-short-identifiers
[recognized license exception IDs]: https://spdx.github.io/spdx-spec/SPDX-license-list/#a2-exceptions-list
The following is an EBNF conversion of the ABNF located at
<https://spdx.github.io/spdx-spec/SPDX-license-expressions/>,
and this is what we actually parse in vcpkg.
Note that vcpkg does not support DocumentRefs.
```ebnf
idchar = ? regex /[-.a-zA-Z0-9]/ ?
idstring = ( idchar ), { idchar } ;
(* note that unrecognized license and license exception IDs will be warned against *)
license-id = idstring ;
license-exception-id = idstring ;
(* note that DocumentRefs are unsupported by this implementation *)
license-ref = "LicenseRef-", idstring ;
with = [ whitespace ], "WITH", [ whitespace ] ;
and = [ whitespace ], "AND", [ whitespace ] ;
or = [ whitespace ], "OR", [ whitespace ] ;
simple-expression = [ whitespace ], (
| license-id
| license-id, "+"
| license-ref
), [ whitespace ] ;
(* the following are split up from compound-expression to make precedence obvious *)
parenthesized-expression =
| simple-expression
| [ whitespace ], "(", or-expression, ")", [ whitespace ] ;
with-expression =
| parenthesized-expression
| simple-expression, with, license-exception-id, [ whitespace ] ;
(* note: "a AND b OR c" gets parsed as "(a AND b) OR c" *)
and-expression = with-expression, { and, with-expression } ;
or-expression = and-expression, { or, and-exression } ;
license-expression = or-expression ;
```
#### Examples
For libraries with simple licensing,
only one license identifier may be needed;
vcpkg, for example, would use this since it uses the MIT license:
```json
{
"license": "MIT"
}
```
Many GPL'd projects allow either the GPL 2 or any later versions:
```json
{
"license": "GPL-2.0-or-later"
}
```
Many Rust projects, in order to make certain they're useable with GPL,
but also desiring the MIT license, will allow licensing under either
the MIT license or Apache 2.0:
```json
{
"license": "Apache-2.0 OR MIT"
}
```
Some major projects include exceptions;
the Microsoft C++ standard library, and the LLVM project,
are licensed under Apache 2.0 with the LLVM exception:
```json
{
"license": "Apache-2.0 WITH LLVM-exception"
}
```

100
externals/vcpkg/docs/maintainers/portfile-functions.md vendored Executable file
View file

@ -0,0 +1,100 @@
<!-- Run regenerate.ps1 to extract scripts documentation -->
# Portfile helper functions
- [execute\_process](execute_process.md)
- [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
- [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
- [vcpkg\_apply\_patches](vcpkg_apply_patches.md) (deprecated)
- [vcpkg\_backup\_restore\_env\_vars](vcpkg_backup_restore_env_vars.md)
- [vcpkg\_build\_cmake](vcpkg_build_cmake.md) (deprecated, use [vcpkg\_cmake\_build](ports/vcpkg-cmake/vcpkg_cmake_build.md))
- [vcpkg\_build\_make](vcpkg_build_make.md)
- [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
- [vcpkg\_build\_ninja](vcpkg_build_ninja.md)
- [vcpkg\_build\_nmake](vcpkg_build_nmake.md)
- [vcpkg\_build\_qmake](vcpkg_build_qmake.md)
- [vcpkg\_buildpath\_length\_warning](vcpkg_buildpath_length_warning.md)
- [vcpkg\_check\_features](vcpkg_check_features.md)
- [vcpkg\_check\_linkage](vcpkg_check_linkage.md)
- [vcpkg\_clean\_executables\_in\_bin](vcpkg_clean_executables_in_bin.md)
- [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)
- [vcpkg\_common\_definitions](vcpkg_common_definitions.md)
- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md) (deprecated, use [vcpkg\_cmake\_configure](ports/vcpkg-cmake/vcpkg_cmake_configure.md))
- [vcpkg\_configure\_gn](vcpkg_configure_gn.md) (deprecated, use [vcpkg\_gn\_configure](ports/vcpkg-gn/vcpkg_gn_configure.md))
- [vcpkg\_configure\_make](vcpkg_configure_make.md)
- [vcpkg\_configure\_meson](vcpkg_configure_meson.md)
- [vcpkg\_configure\_qmake](vcpkg_configure_qmake.md)
- [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)
- [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)
- [vcpkg\_copy\_tools](vcpkg_copy_tools.md)
- [vcpkg\_download\_distfile](vcpkg_download_distfile.md)
- [vcpkg\_execute\_build\_process](vcpkg_execute_build_process.md)
- [vcpkg\_execute\_in\_download\_mode](vcpkg_execute_in_download_mode.md)
- [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)
- [vcpkg\_execute\_required\_process\_repeat](vcpkg_execute_required_process_repeat.md)
- [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)
- [vcpkg\_extract\_source\_archive\_ex](vcpkg_extract_source_archive_ex.md)
- [vcpkg\_fail\_port\_install](vcpkg_fail_port_install.md) (deprecated)
- [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
- [vcpkg\_find\_fortran](vcpkg_find_fortran.md)
- [vcpkg\_fixup\_cmake\_targets](vcpkg_fixup_cmake_targets.md) (deprecated, use [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md))
- [vcpkg\_fixup\_pkgconfig](vcpkg_fixup_pkgconfig.md)
- [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)
- [vcpkg\_from\_git](vcpkg_from_git.md)
- [vcpkg\_from\_github](vcpkg_from_github.md)
- [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md)
- [vcpkg\_from\_sourceforge](vcpkg_from_sourceforge.md)
- [vcpkg\_get\_program\_files\_platform\_bitness](vcpkg_get_program_files_platform_bitness.md)
- [vcpkg\_get\_windows\_sdk](vcpkg_get_windows_sdk.md)
- [vcpkg\_host\_path\_list](vcpkg_host_path_list.md)
- [vcpkg\_install\_cmake](vcpkg_install_cmake.md) (deprecated, use [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md))
- [vcpkg\_install\_gn](vcpkg_install_gn.md) (deprecated, use [vcpkg\_gn\_install](ports/vcpkg-gn/vcpkg_gn_install.md))
- [vcpkg\_install\_make](vcpkg_install_make.md)
- [vcpkg\_install\_meson](vcpkg_install_meson.md)
- [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md)
- [vcpkg\_install\_nmake](vcpkg_install_nmake.md)
- [vcpkg\_install\_qmake](vcpkg_install_qmake.md)
- [vcpkg\_list](vcpkg_list.md)
- [vcpkg\_minimum\_required](vcpkg_minimum_required.md)
- [vcpkg\_replace\_string](vcpkg_replace_string.md)
## Internal Functions
- [z\_vcpkg\_apply\_patches](internal/z_vcpkg_apply_patches.md)
- [z\_vcpkg\_forward\_output\_variable](internal/z_vcpkg_forward_output_variable.md)
- [z\_vcpkg\_function\_arguments](internal/z_vcpkg_function_arguments.md)
- [z\_vcpkg\_get\_cmake\_vars](internal/z_vcpkg_get_cmake_vars.md)
- [z\_vcpkg\_prettify\_command\_line](internal/z_vcpkg_prettify_command_line.md)
- [z\_vcpkg\_setup\_pkgconfig\_path](internal/z_vcpkg_setup_pkgconfig_path.md)
## Scripts from Ports
### [vcpkg-cmake](ports/vcpkg-cmake.md)
- [vcpkg\_cmake\_build](ports/vcpkg-cmake/vcpkg_cmake_build.md)
- [vcpkg\_cmake\_configure](ports/vcpkg-cmake/vcpkg_cmake_configure.md)
- [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md)
### [vcpkg-gn](ports/vcpkg-gn.md)
- [vcpkg\_gn\_configure](ports/vcpkg-gn/vcpkg_gn_configure.md)
- [vcpkg\_gn\_install](ports/vcpkg-gn/vcpkg_gn_install.md)
### [vcpkg-cmake-config](ports/vcpkg-cmake-config.md)
- [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md)
### [vcpkg-cmake-get-vars](ports/vcpkg-cmake-get-vars.md)
- [vcpkg\_cmake\_get\_vars](ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md)
### [vcpkg-pkgconfig-get-modules](ports/vcpkg-pkgconfig-get-modules.md)
- [x\_vcpkg\_pkgconfig\_get\_modules](ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md)
### [vcpkg-get-python-packages](ports/vcpkg-get-python-packages.md)
- [x\_vcpkg\_get\_python\_packages](ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md)
### [vcpkg-qmake](ports/vcpkg-qmake.md)
- [vcpkg\_qmake\_configure](ports/vcpkg-qmake/vcpkg_qmake_configure.md)

10
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake-config.md vendored Executable file
View file

@ -0,0 +1,10 @@
# vcpkg-cmake-config
`vcpkg-cmake-config` provides `vcpkg_cmake_config_fixup()`,
a function which both:
- Fixes common mistakes in port build systems, like using absolute paths
- Merges the debug and release config files.
This function should almost always be used when a port has `*config.cmake` files,
even when the buildsystem of the project is not CMake.

54
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md vendored Executable file
View file

@ -0,0 +1,54 @@
# vcpkg_cmake_config_fixup
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md).
Merge release and debug CMake targets and configs to support multiconfig generators.
Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries.
```cmake
vcpkg_cmake_config_fixup(
[PACKAGE_NAME <name>]
[CONFIG_PATH <config-directory>]
[TOOLS_PATH <tools/${PORT}>]
[DO_NOT_DELETE_PARENT_CONFIG_PATH]
[NO_PREFIX_CORRECTION]
)
```
For many ports, `vcpkg_cmake_config_fixup()` on its own should work,
as `PACKAGE_NAME` defaults to `${PORT}` and `CONFIG_PATH` defaults to `share/${PACKAGE_NAME}`.
For ports where the package name passed to `find_package` is distinct from the port name,
`PACKAGE_NAME` should be changed to be that name instead.
For ports where the directory of the `*config.cmake` files cannot be set,
use the `CONFIG_PATH` to change the directory where the files come from.
By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
Passing the `DO_NOT_DELETE_PARENT_CONFIG_PATH` option disable such behavior,
as it is convenient for ports that install
more than one CMake package configuration file.
The `NO_PREFIX_CORRECTION` option disables the correction of `_IMPORT_PREFIX`
done by vcpkg due to moving the config files.
Currently the correction does not take into account how the files are moved,
and applies a rather simply correction which in some cases will yield the wrong results.
## How it Works
1. Moves `/debug/<CONFIG_PATH>/*targets-debug.cmake` to `/share/${PACKAGE_NAME}`.
2. Transforms all references matching `/bin/*.exe` to `/${TOOLS_PATH}/*.exe` on Windows.
3. Transforms all references matching `/bin/*` to `/${TOOLS_PATH}/*` on other platforms.
4. Fixes `${_IMPORT_PREFIX}` in auto generated targets.
5. Replaces `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs.
6. Merges INTERFACE_LINK_LIBRARIES of release and debug configurations.
7. Replaces `${CURRENT_INSTALLED_DIR}` with `${VCPKG_IMPORT_PREFIX}` in targets.
8. Removes `/debug/<CONFIG_PATH>/*config.cmake`.
## Examples
* [concurrentqueue](https://github.com/Microsoft/vcpkg/blob/master/ports/concurrentqueue/portfile.cmake)
* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake)
* [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake)
## Source
[ports/vcpkg-cmake-config/vcpkg\_cmake\_config\_fixup.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.cmake)

3
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake-get-vars.md vendored Executable file
View file

@ -0,0 +1,3 @@
# vcpkg-cmake-get-vars
This port contains a helper function to extract CMake variables into the scope of the portfile or other scripts

41
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md vendored Executable file
View file

@ -0,0 +1,41 @@
# vcpkg_cmake_get_vars
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md).
Runs a cmake configure with a dummy project to extract certain cmake variables
## Usage
```cmake
vcpkg_cmake_get_vars(<out-var>)
```
`vcpkg_cmake_get_vars(<out-var>)` sets `<out-var>` to
a path to a generated CMake file, with the detected `CMAKE_*` variables
re-exported as `VCPKG_DETECTED_CMAKE_*`.
Additionally sets, for `RELEASE` and `DEBUG`:
- VCPKG_COMBINED_CXX_FLAGS_<config>
- VCPKG_COMBINED_C_FLAGS_<config>
- VCPKG_COMBINED_SHARED_LINKER_FLAGS_<config>
- VCPKG_COMBINED_STATIC_LINKER_FLAGS_<config>
- VCPKG_COMBINED_EXE_LINKER_FLAGS_<config>
Most users should use these pre-combined flags instead of attempting
to read the `VCPKG_DETECTED_*` flags directly.
## Notes
Avoid usage in portfiles.
All calls to `vcpkg_cmake_get_vars` will result in the same output file;
the output file is not generated multiple times.
### Basic Usage
```cmake
vcpkg_cmake_get_vars(cmake_vars_file)
include("${cmake_vars_file}")
message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CMAKE_CXX_FLAGS}")
```
## Source
[ports/vcpkg-cmake-get-vars/vcpkg\_cmake\_get\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.cmake)

7
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake.md vendored Executable file
View file

@ -0,0 +1,7 @@
# vcpkg-cmake
This port contains cmake functions for dealing with a CMake buildsystem.
In the common case, `vcpkg_cmake_configure()` (with appropriate arguments)
followed by `vcpkg_cmake_install()` will be enough to build and install a port.
`vcpkg_cmake_build()` is provided for more complex cases.

38
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md vendored Executable file
View file

@ -0,0 +1,38 @@
# vcpkg_cmake_build
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md).
Build a cmake project.
```cmake
vcpkg_cmake_build(
[TARGET <target>]
[LOGFILE_BASE <base>]
[DISABLE_PARALLEL]
[ADD_BIN_TO_PATH]
)
```
`vcpkg_cmake_build` builds an already-configured cmake project.
You can use the alias [`vcpkg_cmake_install()`] function
if your CMake build system supports the `install` TARGET,
and this is something we recommend doing whenever possible.
Otherwise, you can use `TARGET` to set the target to build.
This function defaults to not passing a target to cmake.
[`vcpkg_cmake_install()`]: vcpkg_cmake_install.md
`LOGFILE_BASE` is used to set the base of the logfile names;
by default, this is `build`, and thus the logfiles end up being something like
`build-x86-windows-dbg.log`; if you use `vcpkg_cmake_install`,
this is set to `install`, so you'll get log names like `install-x86-windows-dbg.log`.
For build systems that are buggy when run in parallel,
using `DISABLE_PARALLEL` will run the build with only one job.
Finally, `ADD_BIN_TO_PATH` adds the appropriate (either release or debug)
`bin/` directories to the path during the build,
such that executables run during the build will be able to access those DLLs.
## Source
[ports/vcpkg-cmake/vcpkg\_cmake\_build.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_build.cmake)

93
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md vendored Executable file
View file

@ -0,0 +1,93 @@
# vcpkg_cmake_configure
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md).
Configure a CMake buildsystem.
```cmake
vcpkg_cmake_configure(
SOURCE_PATH <source-path>
[LOGFILE_BASE <logname-base>]
[DISABLE_PARALLEL_CONFIGURE]
[NO_CHARSET_FLAG]
[WINDOWS_USE_MSBUILD]
[GENERATOR <generator>]
[OPTIONS
<configure-setting>...]
[OPTIONS_RELEASE
<configure-setting>...]
[OPTIONS_DEBUG
<configure-setting>...]
[MAYBE_UNUSED_VARIABLES
<option-name>...]
)
```
`vcpkg_cmake_configure` configures a CMake build system for use with
`vcpkg_cmake_buildsystem_build` and `vcpkg_cmake_buildsystem_install`.
`source-path` is where the source is located; by convention,
this is usually `${SOURCE_PATH}`, which is set by one of the `vcpkg_from_*` functions.
This function configures the build system for both Debug and Release builds by default,
assuming that `VCPKG_BUILD_TYPE` is not set; if it is, then it will only configure for
that build type.
Use the `OPTIONS` argument to set the configure settings for both release and debug,
and use `OPTIONS_RELEASE` and `OPTIONS_DEBUG` to set the configure settings for
release only and debug only respectively.
By default, when possible, `vcpkg_cmake_configure` uses [ninja-build]
as its build system. If the `WINDOWS_USE_MSBUILD` argument is passed, then
`vcpkg_cmake_configure` will use a Visual Studio generator on Windows;
on every other platform, `vcpkg_cmake_configure` just uses Ninja.
[ninja-build]: https://ninja-build.org/
Additionally, one may pass the specific generator a port should use with `GENERATOR`.
This is useful if some project-specific buildsystem
has been wrapped in a CMake build system that doesn't perform an actual build.
If used for this purpose, it should be set to `"NMake Makefiles"`.
`vcpkg_cmake_buildsystem_build` and `install` do not support this being set to anything
except for NMake.
For libraries which cannot be configured in parallel,
pass the `DISABLE_PARALLEL_CONFIGURE` flag. This is needed, for example,
if the library's build system writes back into the source directory during configure.
This also disables the `CMAKE_DISABLE_SOURCE_CHANGES` option.
By default, this function adds flags to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`
which set the default character set to utf-8 for MSVC.
If the library sets its own code page, pass the `NO_CHARSET_FLAG` option.
This function makes certain that all options passed in are used by the
underlying CMake build system. If there are options that might be unused,
perhaps on certain platforms, pass those variable names to
`MAYBE_UNUSED_VARIABLES`. For example:
```cmake
vcpkg_cmake_configure(
...
OPTIONS
-DBUILD_EXAMPLE=OFF
...
MAYBE_UNUSED_VARIABLES
BUILD_EXAMPLE
)
```
`LOGFILE_BASE` is used to set the base of the logfile names;
by default, this is `config`, and thus the logfiles end up being something like
`config-x86-windows-dbg.log`. You can set it to anything you like;
if you set it to `config-the-first`,
you'll get something like `config-the-first-x86-windows.dbg.log`.
## Notes
This command supplies many common arguments to CMake. To see the full list, examine the source.
## Examples
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
* [opencv4](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv4/portfile.cmake)
## Source
[ports/vcpkg-cmake/vcpkg\_cmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_configure.cmake)

25
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md vendored Executable file
View file

@ -0,0 +1,25 @@
# vcpkg_cmake_install
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md).
Build and install a cmake project.
```cmake
vcpkg_cmake_install(
[DISABLE_PARALLEL]
[ADD_BIN_TO_PATH]
)
```
`vcpkg_cmake_install` transparently forwards to [`vcpkg_cmake_build()`],
with additional parameters to set the `TARGET` to `install`,
and to set the `LOGFILE_ROOT` to `install` as well.
[`vcpkg_cmake_build()`]: vcpkg_cmake_build.md
## Examples:
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
## Source
[ports/vcpkg-cmake/vcpkg\_cmake\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_install.cmake)

6
externals/vcpkg/docs/maintainers/ports/vcpkg-get-python-packages.md vendored Executable file
View file

@ -0,0 +1,6 @@
# vcpkg-get-python-packages
**Experimental: will change or be removed at any time**
`vcpkg-get-python-packages` provides `x_vcpkg_get_python_packages()`, a function which simplifies getting
python packages.

38
externals/vcpkg/docs/maintainers/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md vendored Executable file
View file

@ -0,0 +1,38 @@
# x_vcpkg_get_python_packages
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md).
Experimental
Retrieve needed python packages
## Usage
```cmake
x_vcpkg_get_python_packages(
[PYTHON_VERSION (2|3)]
PYTHON_EXECUTABLE <path to python binary>
REQUIREMENTS_FILE <file-path>
PACKAGES <packages to aqcuire>...
[OUT_PYTHON_VAR somevar]
)
```
## Parameters
### PYTHON_VERSION
Python version to be used. Either 2 or 3
### PYTHON_EXECUTABLE
Full path to the python executable
### REQUIREMENTS_FILE
Requirement file with the list of python packages
### PACKAGES
List of python packages to acquire
### OUT_PYTHON_VAR
Variable to store the path to the python binary inside the virtual environment
## Source
[ports/vcpkg-get-python-packages/x\_vcpkg\_get\_python\_packages.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.cmake)

12
externals/vcpkg/docs/maintainers/ports/vcpkg-gn.md vendored Executable file
View file

@ -0,0 +1,12 @@
# vcpkg-gn
This port contains cmake functions for dealing with a GN buildsystem.
## Example
```cmake
vcpkg_gn_configure(
SOURCE_PATH "${SOURCE_PATH}"
)
vcpkg_gn_install()
```

32
externals/vcpkg/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md vendored Executable file
View file

@ -0,0 +1,32 @@
# vcpkg_gn_configure
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md).
Generate Ninja (GN) targets
## Usage:
```cmake
vcpkg_gn_configure(
SOURCE_PATH <SOURCE_PATH>
[OPTIONS <OPTIONS>]
[OPTIONS_DEBUG <OPTIONS_DEBUG>]
[OPTIONS_RELEASE <OPTIONS_RELEASE>]
)
```
## Parameters:
### SOURCE_PATH (required)
The path to the GN project.
### OPTIONS
Options to be passed to both the debug and release targets.
Note: Must be provided as a space-separated string.
### OPTIONS_DEBUG (space-separated string)
Options to be passed to the debug target.
### OPTIONS_RELEASE (space-separated string)
Options to be passed to the release target.
## Source
[ports/vcpkg-gn/vcpkg\_gn\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_configure.cmake)

29
externals/vcpkg/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md vendored Executable file
View file

@ -0,0 +1,29 @@
# vcpkg_gn_install
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md).
Installs a GN project.
In order to build a GN project without installing, use [`vcpkg_build_ninja()`].
## Usage:
```cmake
vcpkg_gn_install(
SOURCE_PATH <SOURCE_PATH>
[TARGETS <target>...]
)
```
## Parameters:
### SOURCE_PATH
The path to the source directory
### TARGETS
Only install the specified targets.
Note: includes must be handled separately
[`vcpkg_build_ninja()`]: vcpkg_build_ninja.md
## Source
[ports/vcpkg-gn/vcpkg\_gn\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_install.cmake)

6
externals/vcpkg/docs/maintainers/ports/vcpkg-pkgconfig-get-modules.md vendored Executable file
View file

@ -0,0 +1,6 @@
# vcpkg-pkgconfig-get-modules
**Experimental: will change or be removed at any time**
`vcpkg-pkgconfig-get-modules` provides `x_vcpkg_pkgconfig_get_modules()`, a function which simplifies calling
`pkg-config` in portfiles in order to gather dependencies for exotic buildsystems.

45
externals/vcpkg/docs/maintainers/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md vendored Executable file
View file

@ -0,0 +1,45 @@
# x_vcpkg_pkgconfig_get_modules
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md).
Experimental
Retrieve required module information from pkgconfig modules
## Usage
```cmake
x_vcpkg_pkgconfig_get_modules(
PREFIX <prefix>
MODULES <pkgconfig_modules>...
[CFLAGS]
[LIBS]
[LIBRARIES]
[LIBRARIES_DIRS]
[INCLUDE_DIRS]
)
```
## Parameters
### PREFIX
Used variable prefix to use
### MODULES
List of pkgconfig modules to retrieve information for.
### LIBS
Returns `"${PKGCONFIG}" --libs` in <prefix>_LIBS_(DEBUG|RELEASE)
### LIBRARIES
Returns `"${PKGCONFIG}" --libs-only-l` in <prefix>_LIBRARIES_(DEBUG|RELEASE)
### LIBRARIES_DIRS
Returns `"${PKGCONFIG}" --libs-only-L` in <prefix>_LIBRARIES_DIRS_(DEBUG|RELEASE)
### INCLUDE_DIRS
Returns `"${PKGCONFIG}" --cflags-only-I` in <prefix>_INCLUDE_DIRS_(DEBUG|RELEASE)
## Examples
* [qt5-base](https://github.com/microsoft/vcpkg/blob/master/ports/qt5-base/portfile.cmake)
## Source
[ports/vcpkg-pkgconfig-get-modules/x\_vcpkg\_pkgconfig\_get\_modules.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.cmake)

7
externals/vcpkg/docs/maintainers/ports/vcpkg-qmake.md vendored Executable file
View file

@ -0,0 +1,7 @@
# vcpkg-qmake
This port contains qmake functions for dealing with a QMake buildsystem.
In the common case, `vcpkg_qmake_configure()` (with appropriate arguments)
followed by `vcpkg_install_qmake()` will be enough to build and install a port.

36
externals/vcpkg/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_configure.md vendored Executable file
View file

@ -0,0 +1,36 @@
# vcpkg_qmake_configure
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_configure.md).
Configure a qmake-based project.
###User setable triplet variables:
VCPKG_OSX_DEPLOYMENT_TARGET: Determines QMAKE_MACOSX_DEPLOYMENT_TARGET
VCPKG_QMAKE_COMMAND: Path to qmake. (default: "${CURRENT_HOST_INSTALLED_DIR}/tools/Qt6/bin/qmake${VCPKG_HOST_EXECUTABLE_SUFFIX}")
VCPKG_QT_CONF_(RELEASE|DEBUG): Path to qt.config being used for RELEASE/DEBUG. (default: "${CURRENT_INSTALLED_DIR}/tools/Qt6/qt_(release|debug).conf")
VCPKG_QMAKE_OPTIONS(_RELEASE|_DEBUG)?: Extra options to pass to QMake
```cmake
vcpkg_qmake_configure(
SOURCE_PATH <pro_file_path>
[QMAKE_OPTIONS arg1 [arg2 ...]]
[QMAKE_OPTIONS_RELEASE arg1 [arg2 ...]]
[QMAKE_OPTIONS_DEBUG arg1 [arg2 ...]]
[OPTIONS arg1 [arg2 ...]]
[OPTIONS_RELEASE arg1 [arg2 ...]]
[OPTIONS_DEBUG arg1 [arg2 ...]]
)
```
### SOURCE_PATH
The path to the *.pro qmake project file.
### QMAKE_OPTIONS, QMAKE_OPTIONS\_RELEASE, QMAKE_OPTIONS\_DEBUG
options directly passed to qmake with the form QMAKE_X=something or CONFIG=something
### OPTIONS, OPTIONS\_RELEASE, OPTIONS\_DEBUG
The options passed after -- to qmake.
## Source
[ports/vcpkg-qmake/vcpkg\_qmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-qmake/vcpkg_qmake_configure.cmake)

115
externals/vcpkg/docs/maintainers/pr-review-checklist.md vendored Executable file
View file

@ -0,0 +1,115 @@
Vcpkg PR Checklist
=====================
Revision: 1
## Overview
This document provides an annotated checklist which vcpkg team members use to apply the "reviewed" label on incoming pull requests. If a pull request violates any of these points, we may ask contributors to make necessary changes before we can merge the changeset.
Feel free to create an issue or pull request if you feel that this checklist can be improved. Please increment the revision number when modifying the checklist content.
## Checklist
You can link any of these checklist items in a GitHub comment by copying the link address attached to each item code.
<details id="c000001">
<summary><a href="#c000001">c000001</a>: No deprecated helper functions are used</summary>
See our [Maintainer Guidelines and Policies](maintainer-guide.md#avoid-deprecated-helper-functions) for more information.
</details>
<details id="c000002">
<summary><a href="#c000002">c000002</a>: `"port-version"` field is updated</summary>
See our [Maintainer Guidelines and Policies](maintainer-guide.md#versioning) for more information.
</details>
<details id="c000003">
<summary><a href="#c000003">c000003</a>: New ports contain a `"description"` field written in English</summary>
A description only one or a few sentences long is helpful. Consider using the library's official description from their `README.md` or similar if possible. Automatic translations are acceptable and we are happy to clean up translations to English for our contributors.
See our [manifest file documentation](manifest-files.md#description) for more information.
</details>
<details id="c000004">
<summary><a href="#c000004">c000004</a>: No unnecessary comments are present in the changeset</summary>
See our [Maintainer Guidelines and Policies](maintainer-guide.md#avoid-excessive-comments-in-portfiles) for more information.
</details>
<details id="c000005">
<summary><a href="#c000005">c000005</a>: Downloaded archives are versioned if available</summary
To ensure archive content does not change, archives downloaded preferably have an associated version tag that can be incremented alongside the port's `"version"`.
</details>
<details id="c000006">
<summary><a href="#c000006">c000006</a>: New ports pass CI checks for triplets that the library officially supports</summary>
To ensure vcpkg ports are of a high quality, we ask that incoming ports support the official platforms for the library in question.
</details>
<details id="c000007">
<summary><a href="#c000007">c000007</a>: Patches fix issues that are vcpkg-specific only</summary>
If possible, patches to the library source code should be upstreamed to the library's official repository. Opening up a pull request on the library's repository will help to improve the library for everyone, not just vcpkg users.
</details>
<details id="c000008">
<summary><a href="#c000008">c000008</a>: New ports download source code from the official source if available</summary>
To respect library authors and keep code secure, please have ports download source code from the official source. We may make exceptions if the original source code is not available and there is substantial community interest in maintaining the library in question.
</details>
<details id="c000009">
<summary><a href="#c000009">c000009</a>: Ports and port features are named correctly</summary>
For user accessibility, we prefer names of ports and port features to be intuitive and close to their counterparts in official sources and other package managers. If you are unsure about the naming of a port or port feature, we recommend checking repology.org, packages.ubuntu.com, or searching for additional information using a search engine. We can also help our contributors with this, so feel free to ask for naming suggestions if you are unsure.
</details>
<details id="c000010">
<summary><a href="#c000010">c000010</a>: Library targets are exported when appropriate</summary>
To provide users with a seamless build system integration, please be sure to export and provide a means of finding the library targets intended to be used downstream. Targets not meant to be exported should be be marked private and not exported.
</details>
<details id="c000011">
<summary><a href="#c000011">c000011</a>: Ports do not use applications which modify the user's system</summary>
Ports should uphold vcpkg's contract of not modifying the user's system by avoiding applications which do so. Examples of these applications are `sudo`, `apt`, `brew`, or `pip`. Please use an alternative to these types of programs wherever possible.
</details>
<details id="c000012">
<summary><a href="#c000012">c000012</a>: Ports with system dependencies include an information message during installation</summary>
Some ports have library and tool dependencies that do not exist within vcpkg. For these missing dependencies, we ask that contributors add a message to the top of the port's `portfile.cmake` stating the missing dependencies and how to acquire them. We ask that the message is displayed before any major work is done to ensure that users can "early out" of the installation process as soon as possible in case they are missing the dependency.
Example:
```cmake
message(
"${PORT} currently requires the following libraries from the system package manager:
autoconf libtool
These can be installed on Ubuntu systems via sudo apt install autoconf libtool"
)
```
</details>
<details id="c000013">
<summary><a href="#c000013">c000013</a>: Manifest files are used instead of CONTROL files for new ports</summary>
Many existing ports use the CONTROL file syntax; while this syntax will be supported for some time to come,
new ports should not use these. Any newly added port _must_ use the manifest files.
We also recommend, when significant modifications are made to ports, that one switches to manifest files;
however, this is not required. You may find `vcpkg format-manifest` useful.

365
externals/vcpkg/docs/maintainers/registries.md vendored Executable file
View file

@ -0,0 +1,365 @@
# Creating Registries
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/maintainers/registries.md).**
There are two parts to using registries; this documents the creation side of
the relationship. In order to learn more about using registries that others
have created, please read [this documentation](../users/registries.md).
## Table of Contents
- [Creating Registries](#creating-registries)
- [Table of Contents](#table-of-contents)
- [Overview](#overview)
- [Git Registries](#git-registries)
- [Adding a New Version](#adding-a-new-version)
- [Filesystem Registries](#filesystem-registries)
- [Adding a New Version](#adding-a-new-version-1)
- [Builtin Registries](#builtin-registries)
## Overview
Registries are collections of ports and their versions. There are two major
choices of implementation for registries, if you want to create your own -
git registries, and filesystem registries.
Git registries are simple git repositories, and can be shared publicly or
privately via normal mechanisms for git repositories. The vcpkg repository at
<https://github.com/microsoft/vcpkg>, for example, is a git registry.
Filesystem registries are designed as more of a testing ground. Given that they
literally live on your filesystem, the only way to share them is via shared
directories. However, filesystem registries can be useful as a way to represent
registries held in non-git version control systems, assuming one has some way
to get the registry onto the disk.
Note that we expect the set of registry types to grow over time; if you would
like support for registries built in your favorite public version control
system, don't hesitate to open a PR.
The basic structure of a registry is:
- The set of versions that are considered "latest" at certain times in history,
known as the "baseline".
- The set of all the versions of all the ports, and where to find each of
these in the registry.
### Git Registries
As you're following along with this documentation, it may be helpful to have
a working example to refer to. We've written one and put it here:
<https://github.com/northwindtraders/vcpkg-registry>.
All git registries must have a `versions/baseline.json` file. This file
contains the set of "latest versions" at a certain commit. It is laid out as
a top-level object containing only the `"default"` field. This field should
contain an object mapping port names to the version which is currently the
latest.
Here's an example of a valid baseline.json:
```json
{
"default": {
"kitten": {
"baseline": "2.6.2",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 2
}
}
}
```
The `versions` directory contains all the information about which versions of
which packages are contained in the registry, along with where those versions
are stored. The rest of the registry just acts as a backing store, as far as
vcpkg is concerned: only things inside the `versions` directory will be used
to direct how your registry is seen by vcpkg.
Each port in a registry should exist in the versions directory as
`<first letter of port>-/<name of port>.json`; in other words, the
information about the `kitten` port would be located in
`versions/k-/kitten.json`. This should be a top-level object with only a
single field: `"versions"`. This field should contain an array of version
objects:
- The version of the port in question; should be exactly the same as the
`vcpkg.json` file, including the version fields and `"port-version"`.
- The `"git-tree"` field, which is a git tree; in other words, what you get
when you write `git rev-parse COMMIT-ID:path/to/port`.
Note that the version fields for ports with `CONTROL` files, is
`"version-string"`; we do not recommend using `CONTROL` files in new
registries, however.
_WARNING_: One very important part of registries is that versions should
_never_ be changed. Updating to a later ref should never remove or change an
existing version. It must always be safe to update a registry.
Here's an example of a valid version database for a `kitten` port with one
version:
```json
{
"versions": [
{
"version": "2.6.2",
"port-version": 0,
"git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
}
]
}
```
In general, it's not important where you place port directories. However, the
idiom in vcpkg is to follow what the built in vcpkg registry does: your
`kitten` port should be placed in `ports/kitten`.
_WARNING_: One other thing to keep in mind is that when you update a registry,
all previous versions should also be accessible. Since your user will set their
baseline to a commit ID, that commit ID must always exist, and be accessible
from your HEAD commit, which is what is actually fetched. This means that your
HEAD commit should be a child of all previous HEAD commits.
### Builtin Registries
Builtin registries are treated as special Git registries. Instead of fetching
from a remote url, builtin registries consult the `$VCPKG_ROOT/.git` directory
of the vcpkg clone. They use the currently checked out `$VCPKG_ROOT/versions`
directory as the source for versioning information.
#### Adding a New Version
There is some git trickery involved in creating a new version of a port. The
first thing to do is make some changes, update the `"port-version"` and regular
version field as you need to, and then test with `overlay-ports`:
`vcpkg install kitten --overlay-ports=ports/kitten`.
Once you've finished your testing, you'll need to make sure that the directory
as it is is under git's purview. You'll do this by creating a temporary commit:
```pwsh
> git add ports/kitten
> git commit -m 'temporary commit'
```
Then, get the git tree ID of the directory:
```pwsh
> git rev-parse HEAD:ports/kitten
73ad3c823ef701c37421b450a34271d6beaf7b07
```
Then, you can add this version to the versions database. At the top of your
`versions/k-/kitten.json`, you can add (assuming you're adding version
`2.6.3#0`):
```json
{
"versions": [
{
"version": "2.6.3",
"port-version": 0,
"git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07"
},
{
"version": "2.6.2",
"port-version": 0,
"git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
}
]
}
```
then, you'll want to modify your `versions/baseline.json` with your new version
as well:
```json
{
"default": {
"kitten": {
"baseline": "2.6.3",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 2
}
}
}
```
and amend your current commit:
```pwsh
> git commit --amend
```
then share away!
### Filesystem Registries
As you're following along with this documentation, it may be helpful to have
a working example to refer to. We've written one and put it here:
<https://github.com/vcpkg/example-filesystem-registry>.
All filesystem registries must have a `versions/baseline.json` file. This file
contains the set of "latest versions" for a certain version of the registry.
It is laid out as a top-level object containing a map from version name to
"baseline objects", which map port names to the version which is considered
"latest" for that version of the registry.
Filesystem registries need to decide on a versioning scheme. Unlike git
registries, which have the implicit versioning scheme of refs, filesystem
registries can't rely on the version control system here. One possible option
is to do a daily release, and have your "versions" be dates.
_WARNING_: A baseline must always refer to the same set of versions. If you
want to add new versions, you need to create a new version of the registry in
the `baseline.json` file.
Here's an example of a valid `baseline.json`, for a registry that has decided
upon dates for their versions:
```json
{
"2021-04-16": {
"kitten": {
"baseline": "2.6.2",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 2
}
},
"2021-04-15": {
"kitten": {
"baseline": "2.6.2",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 1
}
}
}
```
The `versions` directory contains all the information about which versions of
which packages are contained in the registry, along with where those versions
are stored. The rest of the registry just acts as a backing store, as far as
vcpkg is concerned: only things inside the `versions` directory will be used
to direct how your registry is seen by vcpkg.
Each port in a registry should exist in the versions directory as
`<first letter of port>-/<name of port>.json`; in other words, the
information about the `kitten` port would be located in
`versions/k-/kitten.json`. This should be a top-level object with only a
single field: `"versions"`. This field should contain an array of version
objects:
- The version of the port in question; should be exactly the same as the
`vcpkg.json` file, including the version fields and `"port-version"`.
- The `"path"` field: a relative directory, rooted at the base of the registry
(in other words, the directory where `versions` is located), to the port
directory. It should look something like `"$/path/to/port/dir`"
Note that the version fields for ports with `CONTROL` files, is
`"version-string"`; we do not recommend using `CONTROL` files in new
registries, however.
In general, it's not important where you place port directories. However, the
idiom in vcpkg is to follow somewhat closely to what the built in vcpkg
registry does: your `kitten` port at version `x.y.z` should be placed in
`ports/kitten/x.y.z`, with port versions appended as you see fit (although
since `#` is not a good character to use for file names, perhaps use `_`).
_WARNING_: One very important part of registries is that versions should
_never_ be changed. One should never remove or change an existing version.
Your changes to your registry shouldn't change behavior to downstream users.
Here's an example of a valid version database for a `kitten` port with one
version:
```json
{
"versions": [
{
"version": "2.6.2",
"port-version": 0,
"path": "$/ports/kitten/2.6.2_0"
}
]
}
```
#### Adding a New Version
Unlike git registries, adding a new version to a filesystem registry mostly
involves a lot of copying. The first thing to do is to copy the latest
version of your port into a new version directory, update the version and
`"port-version"` fields as you need to, and then test with `overlay-ports`:
`vcpkg install kitten --overlay-ports=ports/kitten/new-version`.
Once you've finished your testing, you can add this new version to the top of
your `versions/k-/kitten.json`:
```json
{
"versions": [
{
"version": "2.6.3",
"port-version": 0,
"path": "$/ports/kitten/2.6.3_0"
},
{
"version": "2.6.2",
"port-version": 0,
"path": "$/ports/kitten/2.6.2_0"
}
]
}
```
then, you'll want to modify your `versions/baseline.json` with your new version
as well (remember not to modify existing baselines):
```json
{
"2021-04-17": {
"kitten": {
"baseline": "2.6.3",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 2
}
},
"2021-04-16": {
"kitten": {
"baseline": "2.6.2",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 2
}
},
"2021-04-15": {
"kitten": {
"baseline": "2.6.2",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 1
}
}
}
```
and you're done!

60
externals/vcpkg/docs/maintainers/vcpkg_acquire_msys.md vendored Executable file
View file

@ -0,0 +1,60 @@
# vcpkg_acquire_msys
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_acquire_msys.md).
Download and prepare an MSYS2 instance.
## Usage
```cmake
vcpkg_acquire_msys(<MSYS_ROOT_VAR>
PACKAGES <package>...
[NO_DEFAULT_PACKAGES]
[DIRECT_PACKAGES <URL> <SHA512> <URL> <SHA512> ...]
)
```
## Parameters
### MSYS_ROOT_VAR
An out-variable that will be set to the path to MSYS2.
### PACKAGES
A list of packages to acquire in msys.
To ensure a package is available: `vcpkg_acquire_msys(MSYS_ROOT PACKAGES make automake1.16)`
### NO_DEFAULT_PACKAGES
Exclude the normal base packages.
The list of base packages includes: bash, coreutils, sed, grep, gawk, gzip, diffutils, make, and pkg-config
### DIRECT_PACKAGES
A list of URL/SHA512 pairs to acquire in msys.
This parameter can be used by a port to privately extend the list of msys packages to be acquired.
The URLs can be found on the msys2 website[1] and should be a direct archive link:
https://repo.msys2.org/mingw/i686/mingw-w64-i686-gettext-0.19.8.1-9-any.pkg.tar.zst
[1] https://packages.msys2.org/search
## Notes
A call to `vcpkg_acquire_msys` will usually be followed by a call to `bash.exe`:
```cmake
vcpkg_acquire_msys(MSYS_ROOT)
set(BASH ${MSYS_ROOT}/usr/bin/bash.exe)
vcpkg_execute_required_process(
COMMAND ${BASH} --noprofile --norc "${CMAKE_CURRENT_LIST_DIR}\\build.sh"
WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel
LOGNAME build-${TARGET_TRIPLET}-rel
)
```
## Examples
* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
* [libvpx](https://github.com/Microsoft/vcpkg/blob/master/ports/libvpx/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_acquire\_msys.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_acquire_msys.cmake)

27
externals/vcpkg/docs/maintainers/vcpkg_add_to_path.md vendored Executable file
View file

@ -0,0 +1,27 @@
# vcpkg_add_to_path
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_add_to_path.md).
Add a directory or directories to the PATH environment variable
```cmake
vcpkg_add_to_path([PREPEND] [<path>...])
```
`vcpkg_add_to_path` adds all of the paths passed to it to the PATH environment variable.
If PREPEND is passed, then those paths are prepended to the PATH environment variable,
so that they are searched first; otherwise, those paths are appended, so they are
searched after the paths which are already in the environment variable.
The paths are added in the order received, so that the first path is always searched
before a later path.
If no paths are passed, then nothing will be done.
## Examples:
* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75)
* [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
* [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
## Source
[scripts/cmake/vcpkg\_add\_to\_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake)

18
externals/vcpkg/docs/maintainers/vcpkg_apply_patches.md vendored Executable file
View file

@ -0,0 +1,18 @@
# vcpkg_apply_patches
**This function has been deprecated in favor of the `PATCHES` argument to [`vcpkg_from_github()`](vcpkg_from_github.md) et al.**
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_apply_patches.md).
Apply a set of patches to a source tree.
```cmake
vcpkg_apply_patches(
SOURCE_PATH <${SOURCE_PATH}>
[QUIET]
PATCHES <patch1.patch>...
)
```
## Source
[scripts/cmake/vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake)

26
externals/vcpkg/docs/maintainers/vcpkg_backup_restore_env_vars.md vendored Executable file
View file

@ -0,0 +1,26 @@
# vcpkg_backup_restore_env_vars
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_backup_restore_env_vars.md).
Backup or restore the environment variables
## Usage:
```cmake
vcpkg_backup_env_variables(VARS [<environment-variable>...])
vcpkg_restore_env_variables(VARS [<environment-variable>...])
```
### VARS
The variables to back up or restore.
These are placed in the parent scope, so you must backup and restore
from the same scope.
## Notes
One must always call `vcpkg_backup_env_variables` before
`vcpkg_restore_env_variables`; however, `vcpkg_restore_env_variables`
does not change the back up variables, and so you may call `restore`
multiple times for one `backup`.
## Source
[scripts/cmake/vcpkg\_backup\_restore\_env\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_backup_restore_env_vars.cmake)

38
externals/vcpkg/docs/maintainers/vcpkg_build_cmake.md vendored Executable file
View file

@ -0,0 +1,38 @@
# vcpkg_build_cmake
**This function has been deprecated in favor of [`vcpkg_cmake_build`](ports/vcpkg-cmake/vcpkg_cmake_build.md) from the vcpkg-cmake port.**
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_cmake.md).
Build a cmake project.
## Usage:
```cmake
vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET <target>])
```
## Parameters:
### DISABLE_PARALLEL
The underlying buildsystem will be instructed to not parallelize
### TARGET
The target passed to the cmake build command (`cmake --build . --target <target>`). If not specified, no target will
be passed.
### ADD_BIN_TO_PATH
Adds the appropriate Release and Debug `bin` directories to the path during the build such that executables can run against the in-tree DLLs.
## Notes:
This command should be preceded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the
"install" target
## Examples:
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_build\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_cmake.cmake)

57
externals/vcpkg/docs/maintainers/vcpkg_build_make.md vendored Executable file
View file

@ -0,0 +1,57 @@
# vcpkg_build_make
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_make.md).
Build a linux makefile project.
## Usage:
```cmake
vcpkg_build_make([BUILD_TARGET <target>]
[INSTALL_TARGET <target>]
[ADD_BIN_TO_PATH]
[ENABLE_INSTALL]
[MAKEFILE <makefileName>]
[LOGFILE_ROOT <logfileroot>]
[DISABLE_PARALLEL]
[SUBPATH <path>])
```
### BUILD_TARGET
The target passed to the make build command (`./make <target>`). If not specified, the 'all' target will
be passed.
### INSTALL_TARGET
The target passed to the make build command (`./make <target>`) if `ENABLE_INSTALL` is used. Defaults to 'install'.
### ADD_BIN_TO_PATH
Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs.
### ENABLE_INSTALL
IF the port supports the install target use vcpkg_install_make() instead of vcpkg_build_make()
### MAKEFILE
Specifies the Makefile as a relative path from the root of the sources passed to `vcpkg_configure_make()`
### LOGFILE_ROOT
Specifies a log file prefix.
### DISABLE_PARALLEL
The underlying buildsystem will be instructed to not parallelize
### SUBPATH
Additional subdir to invoke make in. Useful if only parts of a port should be built.
## Notes:
This command should be preceded by a call to [`vcpkg_configure_make()`](vcpkg_configure_make.md).
You can use the alias [`vcpkg_install_make()`](vcpkg_install_make.md) function if your makefile supports the
"install" target
## Examples
* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake)
* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_build\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_make.cmake)

66
externals/vcpkg/docs/maintainers/vcpkg_build_msbuild.md vendored Executable file
View file

@ -0,0 +1,66 @@
# vcpkg_build_msbuild
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_msbuild.md).
Build a msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
## Usage
```cmake
vcpkg_build_msbuild(
PROJECT_PATH <${SOURCE_PATH}/port.sln>
[RELEASE_CONFIGURATION <Release>]
[DEBUG_CONFIGURATION <Debug>]
[TARGET <Build>]
[TARGET_PLATFORM_VERSION <10.0.15063.0>]
[PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
[PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
[OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
[OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
[OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
[USE_VCPKG_INTEGRATION]
)
```
## Parameters
### USE_VCPKG_INTEGRATION
Apply the normal `integrate install` integration for building the project.
By default, projects built with this command will not automatically link libraries or have header paths set.
### PROJECT_PATH
The path to the solution (`.sln`) or project (`.vcxproj`) file.
### RELEASE_CONFIGURATION
The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
### DEBUG_CONFIGURATION
The configuration (``/p:Configuration`` msbuild parameter)
used for Debug builds.
### TARGET_PLATFORM_VERSION
The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
### TARGET
The MSBuild target to build. (``/t:<TARGET>``)
### PLATFORM
The platform (``/p:Platform`` msbuild parameter) used for the build.
### PLATFORM_TOOLSET
The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build.
### OPTIONS
Additional options passed to msbuild for all builds.
### OPTIONS_RELEASE
Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`.
## Examples
* [chakracore](https://github.com/Microsoft/vcpkg/blob/master/ports/chakracore/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_build\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake)

19
externals/vcpkg/docs/maintainers/vcpkg_build_ninja.md vendored Executable file
View file

@ -0,0 +1,19 @@
# vcpkg_build_ninja
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_ninja.md).
Build a ninja project
## Usage:
```cmake
vcpkg_build_ninja(
[TARGETS <target>...]
)
```
## Parameters:
### TARGETS
Only build the specified targets.
## Source
[scripts/cmake/vcpkg\_build\_ninja.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_ninja.cmake)

72
externals/vcpkg/docs/maintainers/vcpkg_build_nmake.md vendored Executable file
View file

@ -0,0 +1,72 @@
# vcpkg_build_nmake
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_nmake.md).
Build a msvc makefile project.
## Usage:
```cmake
vcpkg_build_nmake(
SOURCE_PATH <${SOURCE_PATH}>
[NO_DEBUG]
[ENABLE_INSTALL]
[TARGET <all>]
[PROJECT_SUBPATH <${SUBPATH}>]
[PROJECT_NAME <${MAKEFILE_NAME}>]
[PRERUN_SHELL <${SHELL_PATH}>]
[PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
[PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
[OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
[OPTIONS_RELEASE <-DOPTIMIZE=1>...]
[OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
[TARGET <target>])
```
## Parameters
### SOURCE_PATH
Specifies the directory containing the source files.
By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### PROJECT_SUBPATH
Specifies the sub directory containing the `makefile.vc`/`makefile.mak`/`makefile.msvc` or other msvc makefile.
### PROJECT_NAME
Specifies the name of msvc makefile name.
Default is `makefile.vc`
### ENABLE_INSTALL
Install binaries after build.
### PRERUN_SHELL
Script that needs to be called before build
### PRERUN_SHELL_DEBUG
Script that needs to be called before debug build
### PRERUN_SHELL_RELEASE
Script that needs to be called before release build
### OPTIONS
Additional options passed to generate during the generation.
### OPTIONS_RELEASE
Additional options passed to generate during the Release generation. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to generate during the Debug generation. These are in addition to `OPTIONS`.
### TARGET
The target passed to the nmake build command (`nmake/nmake install`). If not specified, no target will
be passed.
## Notes:
You can use the alias [`vcpkg_install_nmake()`](vcpkg_install_nmake.md) function if your makefile supports the
"install" target
## Examples
* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_build\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_nmake.cmake)

Some files were not shown because too many files have changed in this diff Show more