[scripts-audit] gn buildsystem (#17776)

* [scripts-audit] Remove vcpkg_build_gn

This command has never been used (git log -S"vcpkg_build_gn\("
gives no results outside of the file itself and docs)
and so shrink the public interface surface

* [scripts-audit] gn buildsystem

* format

* oops

* aaaugh

* cr

7 files changed, 139 insertions, 121 deletions

diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index ccc06db88..0b8e7f3b5 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -6,7 +6,6 @@
 - [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
 - [vcpkg\_apply\_patches](vcpkg_apply_patches.md) (deprecated)
 - [vcpkg\_build\_cmake](vcpkg_build_cmake.md) (deprecated, use [vcpkg\_cmake\_build](ports/vcpkg-cmake/vcpkg_cmake_build.md))
-- [vcpkg\_build\_gn](vcpkg_build_gn.md)
 - [vcpkg\_build\_make](vcpkg_build_make.md)
 - [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
 - [vcpkg\_build\_ninja](vcpkg_build_ninja.md)
diff --git a/docs/maintainers/vcpkg_build_gn.md b/docs/maintainers/vcpkg_build_gn.md
deleted file mode 100644
index b664b9c54..000000000
--- a/docs/maintainers/vcpkg_build_gn.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# vcpkg_build_gn
-
-The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_gn.md).
-
-Build a GN project
-
-## Usage:
-```cmake
-vcpkg_build_gn(
-    [TARGETS <target>...]
-)
-```
-
-## Parameters:
-### TARGETS
-Only build the specified targets.
-
-## Source
-[scripts/cmake/vcpkg\_build\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_gn.cmake)
diff --git a/docs/maintainers/vcpkg_install_gn.md b/docs/maintainers/vcpkg_install_gn.md
index 46018ffef..a0134b4a1 100644
--- a/docs/maintainers/vcpkg_install_gn.md
+++ b/docs/maintainers/vcpkg_install_gn.md
@@ -2,7 +2,9 @@
 
 The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_gn.md).
 
-Installs a GN project
+Installs a GN project.
+
+In order to build a GN project without installing, use [`vcpkg_build_ninja()`].
 
 ## Usage:
 ```cmake
@@ -21,5 +23,7 @@ Only install the specified targets.
 
 Note: includes must be handled separately
 
+[`vcpkg_build_ninja()`]: vcpkg_build_ninja.md
+
 ## Source
 [scripts/cmake/vcpkg\_install\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_gn.cmake)
diff --git a/scripts/cmake/vcpkg_build_gn.cmake b/scripts/cmake/vcpkg_build_gn.cmake
deleted file mode 100644
index 3952e7eed..000000000
--- a/scripts/cmake/vcpkg_build_gn.cmake
+++ /dev/null
@@ -1,20 +0,0 @@
-#[===[.md:
-# vcpkg_build_gn
-
-Build a GN project
-
-## Usage:
-```cmake
-vcpkg_build_gn(
-    [TARGETS <target>...]
-)
-```
-
-## Parameters:
-### TARGETS
-Only build the specified targets.
-#]===]
-
-function(vcpkg_build_gn)
-    vcpkg_build_ninja(${ARGN})
-endfunction()
diff --git a/scripts/cmake/vcpkg_configure_gn.cmake b/scripts/cmake/vcpkg_configure_gn.cmake
index 883463402..e844d8d70 100644
--- a/scripts/cmake/vcpkg_configure_gn.cmake
+++ b/scripts/cmake/vcpkg_configure_gn.cmake
@@ -28,11 +28,27 @@ Options to be passed to the debug target.
 Options to be passed to the release target.
 #]===]
 
+function(z_vcpkg_configure_gn_generate)
+    cmake_parse_arguments(PARSE_ARGV 0 "arg" "" "SOURCE_PATH;CONFIG;ARGS" "")
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(FATAL_ERROR "Internal error: generate was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+
+    message(STATUS "Generating build (${arg_CONFIG})...")
+    vcpkg_execute_required_process(
+        COMMAND "${GN}" gen "${CURRENT_BUILDTREES_DIR}/${arg_CONFIG}" "${arg_ARGS}"
+        WORKING_DIRECTORY "${arg_SOURCE_PATH}"
+        LOGNAME "generate-${arg_CONFIG}"
+    )
+endfunction()
+
 function(vcpkg_configure_gn)
-    # parse parameters such that semicolons in options arguments to COMMAND don't get erased
-    cmake_parse_arguments(PARSE_ARGV 0 _vcg "" "SOURCE_PATH;OPTIONS;OPTIONS_DEBUG;OPTIONS_RELEASE" "")
+    cmake_parse_arguments(PARSE_ARGV 0 "arg" "" "SOURCE_PATH;OPTIONS;OPTIONS_DEBUG;OPTIONS_RELEASE" "")
 
-    if(NOT DEFINED _vcg_SOURCE_PATH)
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(WARNING "vcpkg_configure_gn was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+    if(NOT DEFINED arg_SOURCE_PATH)
         message(FATAL_ERROR "SOURCE_PATH must be specified.")
     endif()
 
@@ -42,20 +58,19 @@ function(vcpkg_configure_gn)
 
     vcpkg_find_acquire_program(GN)
 
-    function(generate CONFIG ARGS)
-        message(STATUS "Generating build (${CONFIG})...")
-        vcpkg_execute_required_process(
-            COMMAND "${GN}" gen "${CURRENT_BUILDTREES_DIR}/${CONFIG}" ${ARGS}
-            WORKING_DIRECTORY "${SOURCE_PATH}"
-            LOGNAME generate-${CONFIG}
-        )
-    endfunction()
-
     if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "debug")
-        generate(${TARGET_TRIPLET}-dbg "--args=${_vcg_OPTIONS} ${_vcg_OPTIONS_DEBUG}")
+        z_vcpkg_configure_gn_generate(
+            SOURCE_PATH "${arg_SOURCE_PATH}"
+            CONFIG "${TARGET_TRIPLET}-dbg"
+            ARGS "--args=${arg_OPTIONS} ${arg_OPTIONS_DEBUG}"
+        )
     endif()
 
     if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "release")
-        generate(${TARGET_TRIPLET}-rel "--args=${_vcg_OPTIONS} ${_vcg_OPTIONS_RELEASE}")
+        z_vcpkg_configure_gn_generate(
+            SOURCE_PATH "${arg_SOURCE_PATH}"
+            CONFIG "${TARGET_TRIPLET}-rel"
+            ARGS "--args=${arg_OPTIONS} ${arg_OPTIONS_RELEASE}"
+        )
     endif()
 endfunction()
diff --git a/scripts/cmake/vcpkg_install_gn.cmake b/scripts/cmake/vcpkg_install_gn.cmake
index 8dd83510e..69165d392 100644
--- a/scripts/cmake/vcpkg_install_gn.cmake
+++ b/scripts/cmake/vcpkg_install_gn.cmake
@@ -1,7 +1,9 @@
 #[===[.md:
 # vcpkg_install_gn
 
-Installs a GN project
+Installs a GN project.
+
+In order to build a GN project without installing, use [`vcpkg_build_ninja()`].
 
 ## Usage:
 ```cmake
@@ -19,82 +21,120 @@ The path to the source directory
 Only install the specified targets.
 
 Note: includes must be handled separately
+
+[`vcpkg_build_ninja()`]: vcpkg_build_ninja.md
 #]===]
 
-function(vcpkg_install_gn)
-    # parse parameters such that semicolons in options arguments to COMMAND don't get erased
-    cmake_parse_arguments(PARSE_ARGV 0 _vig "" "SOURCE_PATH" "TARGETS")
-    
-    if(NOT DEFINED _vig_SOURCE_PATH)
-        message(FATAL_ERROR "SOURCE_PATH must be specified.")
+function(z_vcpkg_install_gn_get_target_type out_var)
+    cmake_parse_arguments(PARSE_ARGV 1 "arg" "" "SOURCE_PATH;BUILD_DIR;TARGET" "")
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(FATAL_ERROR "Internal error: get_target_type was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
     endif()
 
-    vcpkg_build_ninja(TARGETS ${_vig_TARGETS})
+    execute_process(
+        COMMAND "${GN}" desc "${arg_BUILD_DIR}" "${arg_TARGET}"
+        WORKING_DIRECTORY "${arg_SOURCE_PATH}"
+        OUTPUT_VARIABLE output
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
+    if(output MATCHES [[type: ([A-Za-z0-9_]+)]])
+        set("${out_var}" "${CMAKE_MATCH_1}" PARENT_SCOPE)
+    else()
+        message(FATAL_ERROR "invalid result from `gn desc`: ${output}")
+    endif()
+endfunction()
 
-    vcpkg_find_acquire_program(GN)
+function(z_vcpkg_install_gn_get_desc out_var)
+    cmake_parse_arguments(PARSE_ARGV 1 "arg" "" "SOURCE_PATH;BUILD_DIR;TARGET;WHAT_TO_DISPLAY" "")
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(FATAL_ERROR "Internal error: get_desc was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+
+    execute_process(
+        COMMAND "${GN}" desc "${arg_BUILD_DIR}" "${arg_TARGET}" "${arg_WHAT_TO_DISPLAY}"
+        WORKING_DIRECTORY "${arg_SOURCE_PATH}"
+        OUTPUT_VARIABLE output
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
+    string(REPLACE ";" "\\;" output "${output}")
+    string(REGEX REPLACE "\n|(\r\n)" ";" output "${output}")
+    set("${out_var}" "${output}" PARENT_SCOPE)
+endfunction()
 
-    function(gn_get_target_type OUT_VAR BUILD_DIR TARGET)
-        execute_process(
-            COMMAND ${GN} desc "${BUILD_DIR}" "${TARGET}"
-            WORKING_DIRECTORY "${_vig_SOURCE_PATH}"
-            OUTPUT_VARIABLE OUTPUT_
-            OUTPUT_STRIP_TRAILING_WHITESPACE
+function(z_vcpkg_install_gn_install)
+    cmake_parse_arguments(PARSE_ARGV 0 "arg" "" "SOURCE_PATH;BUILD_DIR;INSTALL_DIR" "TARGETS")
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(FATAL_ERROR "Internal error: install was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+
+    foreach(target IN LISTS arg_TARGETS)
+        # GN targets must start with a //
+        z_vcpkg_install_gn_get_desc(outputs
+            SOURCE_PATH "${arg_SOURCE_PATH}"
+            BUILD_DIR "${arg_BUILD_DIR}"
+            TARGET "//${target}"
+            WHAT_TO_DISPLAY outputs
         )
-        string(REGEX MATCH "type: ([A-Za-z0-9_]+)" OUTPUT_ "${OUTPUT_}")
-        set(${OUT_VAR} ${CMAKE_MATCH_1} PARENT_SCOPE)
-    endfunction()
-
-    function(gn_desc OUT_VAR BUILD_DIR TARGET WHAT_TO_DISPLAY)
-        execute_process(
-            COMMAND ${GN} desc "${BUILD_DIR}" "${TARGET}" "${WHAT_TO_DISPLAY}"
-            WORKING_DIRECTORY "${_vig_SOURCE_PATH}"
-            OUTPUT_VARIABLE OUTPUT_
-            OUTPUT_STRIP_TRAILING_WHITESPACE
+        z_vcpkg_install_gn_get_target_type(target_type
+            SOURCE_PATH "${arg_SOURCE_PATH}"
+            BUILD_DIR "${arg_BUILD_DIR}"
+            TARGET "//${target}"
         )
-        string(REGEX REPLACE "\n|(\r\n)" ";" OUTPUT_ "${OUTPUT_}")
-        set(${OUT_VAR} ${OUTPUT_} PARENT_SCOPE)
-    endfunction()
-
-    function(install_ BUILD_DIR INSTALL_DIR)
-        if(_vig_TARGETS)
-            foreach(TARGET ${_vig_TARGETS})
-                # GN targets must start with a //
-                gn_desc(OUTPUTS "${BUILD_DIR}" "//${TARGET}" outputs)
-                gn_get_target_type(TARGET_TYPE "${BUILD_DIR}" "//${TARGET}")
-                foreach(OUTPUT ${OUTPUTS})
-                    if(NOT EXISTS "${OUTPUT}")
-                        if(OUTPUT MATCHES "^//")
-                            # relative path (e.g. //out/Release/target.lib)
-                            string(REGEX REPLACE "^//" "${_vig_SOURCE_PATH}/" OUTPUT "${OUTPUT}")
-                        elseif(OUTPUT MATCHES "^/" AND CMAKE_HOST_WIN32)
-                            # absolute path (e.g. /C:/path/to/target.lib)
-                            string(REGEX REPLACE "^/" "" OUTPUT "${OUTPUT}")
-                        endif()
-                    endif()
-
-                    if(NOT EXISTS "${OUTPUT}")
-                        message(STATUS "Output for target, ${TARGET} doesn't exist: ${OUTPUT}.")
-                        continue()
-                    endif()
-                    
-                    if(TARGET_TYPE STREQUAL "executable")
-                        file(INSTALL "${OUTPUT}" DESTINATION "${INSTALL_DIR}/tools")
-                    elseif("${OUTPUT}" MATCHES "(\\.dll|\\.pdb)$")
-                        file(INSTALL "${OUTPUT}" DESTINATION "${INSTALL_DIR}/bin")
-                    else()
-                        file(INSTALL "${OUTPUT}" DESTINATION "${INSTALL_DIR}/lib")
-                    endif()
-                endforeach()
-            endforeach()
-        endif()
-    endfunction()
+
+        foreach(output IN LISTS OUTPUTS)
+            if(output MATCHES "^//")
+                # relative path (e.g. //out/Release/target.lib)
+                string(REGEX REPLACE "^//" "${arg_SOURCE_PATH}/" output "${output}")
+            elseif(output MATCHES "^/" AND CMAKE_HOST_WIN32)
+                # absolute path (e.g. /C:/path/to/target.lib)
+                string(REGEX REPLACE "^/" "" output "${output}")
+            endif()
+
+            if(NOT EXISTS "${output}")
+                message(WARNING "Output for target `${target}` doesn't exist: ${output}.")
+                continue()
+            endif()
+
+            if(target_type STREQUAL "executable")
+                file(INSTALL "${output}" DESTINATION "${arg_INSTALL_DIR}/tools")
+            elseif(output MATCHES "(\\.dll|\\.pdb)$")
+                file(INSTALL "${output}" DESTINATION "${arg_INSTALL_DIR}/bin")
+            else()
+                file(INSTALL "${output}" DESTINATION "${arg_INSTALL_DIR}/lib")
+            endif()
+        endforeach()
+    endforeach()
+endfunction()
+
+function(vcpkg_install_gn)
+    cmake_parse_arguments(PARSE_ARGV 0 arg "" "SOURCE_PATH" "TARGETS")
+
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(WARNING "vcpkg_install_gn was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+    if(NOT DEFINED arg_SOURCE_PATH)
+        message(FATAL_ERROR "SOURCE_PATH must be specified.")
+    endif()
+
+    vcpkg_build_ninja(TARGETS ${arg_TARGETS})
+
+    vcpkg_find_acquire_program(GN)
 
     if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "debug")
-        install_("${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg" "${CURRENT_PACKAGES_DIR}/debug")
+        z_vcpkg_install_gn_install(
+            SOURCE_PATH "${arg_SOURCE_PATH}"
+            BUILD_DIR "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg"
+            INSTALL_DIR "${CURRENT_PACKAGES_DIR}/debug"
+            TARGETS ${arg_TARGETS}
+        )
     endif()
 
     if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "release")
-        install_("${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel" "${CURRENT_PACKAGES_DIR}")
+        z_vcpkg_install_gn_install(
+            SOURCE_PATH "${arg_SOURCE_PATH}"
+            BUILD_DIR "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel"
+            INSTALL_DIR "${CURRENT_PACKAGES_DIR}"
+            TARGETS ${arg_TARGETS}
+        )
     endif()
-
 endfunction()
diff --git a/scripts/ports.cmake b/scripts/ports.cmake
index 4adb48149..0e994cd4f 100644
--- a/scripts/ports.cmake
+++ b/scripts/ports.cmake
@@ -89,7 +89,6 @@ if(CMD MATCHES "^BUILD$")
     include("${SCRIPTS}/cmake/vcpkg_add_to_path.cmake")
     include("${SCRIPTS}/cmake/vcpkg_apply_patches.cmake")
     include("${SCRIPTS}/cmake/vcpkg_build_cmake.cmake")
-    include("${SCRIPTS}/cmake/vcpkg_build_gn.cmake")
     include("${SCRIPTS}/cmake/vcpkg_build_make.cmake")
     include("${SCRIPTS}/cmake/vcpkg_build_msbuild.cmake")
     include("${SCRIPTS}/cmake/vcpkg_build_ninja.cmake")