early-access version 2853

externals/vcpkg/docs/maintainers/internal/vcpkg_catalog_release_process.md

@@ -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)".

externals/vcpkg/docs/maintainers/internal/vcpkg_tool_release_process.md

@@ -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)

externals/vcpkg/docs/maintainers/internal/z_vcpkg_apply_patches.md

@@ -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)

externals/vcpkg/docs/maintainers/internal/z_vcpkg_forward_output_variable.md

@@ -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)

externals/vcpkg/docs/maintainers/internal/z_vcpkg_function_arguments.md

@@ -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)

externals/vcpkg/docs/maintainers/internal/z_vcpkg_get_cmake_vars.md

@@ -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)

externals/vcpkg/docs/maintainers/internal/z_vcpkg_prettify_command_line.md

@@ -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)

externals/vcpkg/docs/maintainers/internal/z_vcpkg_setup_pkgconfig_path.cmake.md

@@ -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.

externals/vcpkg/docs/maintainers/internal/z_vcpkg_setup_pkgconfig_path.md

@@ -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)