[scripts-audit] vcpkg_add_to_path (#16189)

* [scripts-audit] vcpkg_add_to_path

* regenerate docs

2 files changed, 26 insertions, 29 deletions

diff --git a/docs/maintainers/vcpkg_add_to_path.md b/docs/maintainers/vcpkg_add_to_path.md
index af1727821..243757638 100644
--- a/docs/maintainers/vcpkg_add_to_path.md
+++ b/docs/maintainers/vcpkg_add_to_path.md
@@ -1,20 +1,20 @@
 # vcpkg_add_to_path
 
-Add a directory to the PATH environment variable
+Add a directory or directories to the PATH environment variable
 
-## Usage
 ```cmake
-vcpkg_add_to_path([PREPEND] <${PYTHON3_DIR}>)
+vcpkg_add_to_path([PREPEND] [<path>...])
 ```
 
-## Parameters
-### <positional>
-The directory to add
+`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.
 
-### PREPEND
-Prepends the directory.
+The paths are added in the order received, so that the first path is always searched
+before a later path.
 
-The default is to append.
+If no paths are passed, then nothing will be done.
 
 ## Examples:
 * [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75)
diff --git a/scripts/cmake/vcpkg_add_to_path.cmake b/scripts/cmake/vcpkg_add_to_path.cmake
index 6239db048..fe780c72a 100644
--- a/scripts/cmake/vcpkg_add_to_path.cmake
+++ b/scripts/cmake/vcpkg_add_to_path.cmake
@@ -1,21 +1,21 @@
 #[===[

 # vcpkg_add_to_path

 

-Add a directory to the PATH environment variable

+Add a directory or directories to the PATH environment variable

 

-## Usage

 ```cmake

-vcpkg_add_to_path([PREPEND] <${PYTHON3_DIR}>)

+vcpkg_add_to_path([PREPEND] [<path>...])

 ```

 

-## Parameters

-### <positional>

-The directory to add

+`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.

 

-### PREPEND

-Prepends the directory.

+The paths are added in the order received, so that the first path is always searched

+before a later path.

 

-The default is to append.

+If no paths are passed, then nothing will be done.

 

 ## Examples:

 * [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75)

@@ -23,18 +23,15 @@ The default is to append.
 * [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)

 #]===]

 function(vcpkg_add_to_path)

-    if(NOT "${ARGC}" STREQUAL "1" AND NOT "${ARGC}" STREQUAL "2")

-        message(FATAL_ERROR "vcpkg_add_to_path() only accepts 1 or 2 arguments.")

+    cmake_parse_arguments(PARSE_ARGV 0 "arg" "PREPEND" "" "")

+    if(NOT DEFINED arg_UNPARSED_ARGUMENTS)

+        return()

     endif()

-    if("${ARGV0}" STREQUAL "PREPEND")

-        if(NOT "${ARGC}" STREQUAL "2")

-            message(FATAL_ERROR "Expected second argument.")

-        endif()

-        set(ENV{PATH} "${ARGV1}${VCPKG_HOST_PATH_SEPARATOR}$ENV{PATH}")

+

+    list(JOIN arg_UNPARSED_ARGUMENTS "${VCPKG_HOST_PATH_SEPARATOR}" add_to_path)

+    if(arg_PREPEND)

+        set(ENV{PATH} "${add_to_path}${VCPKG_HOST_PATH_SEPARATOR}$ENV{PATH}")

     else()

-        if(NOT "${ARGC}" STREQUAL "1")

-            message(FATAL_ERROR "Unexpected second argument: ${ARGV1}")

-        endif()

-        set(ENV{PATH} "$ENV{PATH}${VCPKG_HOST_PATH_SEPARATOR}${ARGV0}")

+        set(ENV{PATH} "$ENV{PATH}${VCPKG_HOST_PATH_SEPARATOR}${add_to_path}")

     endif()

 endfunction()