From d369df7ecf194005eaca46f07368779cd486badd Mon Sep 17 00:00:00 2001 From: nicole mazzuca <83086508+strega-nil-ms@users.noreply.github.com> Date: Wed, 14 Jul 2021 14:45:18 -0500 Subject: [rollup:2021-07-06] Rollup PR (#18838) * [rollup:2021-07-06 1/8] PR #18272 (@strega-nil) [scripts-audit] vcpkg_from_* * [rollup:2021-07-06 2/8] PR #18319 (@strega-nil) [scripts-audit] add guidelines for cmake * [rollup 2021-07-06 3/8] PR #18410 (@mheyman) [vcpkg-cmake-config] documentation fix * [rollup:2021-07-06 4/8] PR #18488 (@strega-nil) [scripts-audit] vcpkg_execute_* * [rollup:2021-07-06 5/8] PR #18517 (@strega-nil) [scripts-audit] vcpkg_extract_source_archive * [rollup:2021-07-06 6/8] PR #18674 (@NancyLi1013) [vcpkg doc] Update examples * [rollup:2021-07-06 7/8] PR #18695 (@JackBoosY) [vcpkg] Update the minimum version of vcpkg * [rollup:2021-07-06 8/8] PR #18758 (@ras0219-msft) [vcpkg_from_git] Fix error if downloads folder does not exist * build docs! * fix bond:*-windows * fix nmap Co-authored-by: nicole mazzuca Co-authored-by: Michael Heyman Co-authored-by: NancyLi1013 Co-authored-by: JackBoosY Co-authored-by: Robert Schumacher --- .../internal/z_vcpkg_forward_output_variable.md | 38 ++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/maintainers/internal/z_vcpkg_forward_output_variable.md (limited to 'docs/maintainers/internal') diff --git a/docs/maintainers/internal/z_vcpkg_forward_output_variable.md b/docs/maintainers/internal/z_vcpkg_forward_output_variable.md new file mode 100644 index 000000000..10c5855df --- /dev/null +++ b/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) -- cgit v1.2.3