[vcpkg docs] Check for documentation generation in CI (#14614)

* [vcpkg docs] Change how documenting port functions works

Instead of using `##`, use comment blocks for documentation.

Also, add some minor docs and change RST -> MD
so we actually get docs generated.

* add CI stuff

* regenerate docs

* fix vcpkg_find_acquire_program to not use _execute_process

docs/maintainers/execute_process.md

@@ -5,6 +5,5 @@ 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)

docs/maintainers/portfile-functions.md

@@ -1,4 +1,4 @@
-<!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->
+<!-- Run regenerate.ps1 to extract documentation from scripts/cmake/*.cmake -->
 
 # Portfile helper functions
 - [execute\_process](execute_process.md)
@@ -11,6 +11,8 @@
 - [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)
@@ -20,6 +22,7 @@
 - [vcpkg\_configure\_gn](vcpkg_configure_gn.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)
@@ -27,6 +30,7 @@
 - [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)
@@ -39,6 +43,8 @@
 - [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\_install\_cmake](vcpkg_install_cmake.md)
 - [vcpkg\_install\_gn](vcpkg_install_gn.md)
 - [vcpkg\_install\_make](vcpkg_install_make.md)
@@ -48,3 +54,4 @@
 - [vcpkg\_install\_qmake](vcpkg_install_qmake.md)
 - [vcpkg\_internal\_get\_cmake\_vars](vcpkg_internal_get_cmake_vars.md)
 - [vcpkg\_prettify\_command](vcpkg_prettify_command.md)
+- [vcpkg\_replace\_string](vcpkg_replace_string.md)

docs/maintainers/vcpkg_add_to_path.md

@@ -21,6 +21,5 @@ The default is to append.
 * [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)

docs/maintainers/vcpkg_build_make.md

@@ -6,7 +6,7 @@ Build a linux makefile project.
 ```cmake
 vcpkg_build_make([BUILD_TARGET <target>]
                  [ADD_BIN_TO_PATH]
-                 [ENABLE_INSTALL])
+                 [ENABLE_INSTALL]
                  [MAKEFILE <makefileName>]
                  [LOGFILE_ROOT <logfileroot>])
 ```
@@ -36,7 +36,7 @@ Additional subdir to invoke make in. Useful if only parts of a port should be bu
 
 ## Notes:
 This command should be preceeded by a call to [`vcpkg_configure_make()`](vcpkg_configure_make.md).
-You can use the alias [`vcpkg_install_make()`](vcpkg_configure_make.md) function if your CMake script supports the
+You can use the alias [`vcpkg_install_make()`](vcpkg_install_make.md) function if your CMake script supports the
 "install" target
 
 ## Examples

docs/maintainers/vcpkg_build_nmake.md

@@ -64,7 +64,7 @@ Adds the appropriate Release and Debug `bin\` directories to the path during the
 
 ## Notes:
 This command should be preceeded by a call to [`vcpkg_configure_nmake()`](vcpkg_configure_nmake.md).
-You can use the alias [`vcpkg_install_nmake()`](vcpkg_configure_nmake.md) function if your CMake script supports the
+You can use the alias [`vcpkg_install_nmake()`](vcpkg_install_nmake.md) function if your CMake script supports the
 "install" target
 
 ## Examples

docs/maintainers/vcpkg_build_qmake.md

@@ -0,0 +1,10 @@
+# vcpkg_build_qmake
+
+Build a qmake-based project, previously configured using vcpkg_configure_qmake.
+
+```cmake
+vcpkg_build_qmake()
+```
+
+## Source
+[scripts/cmake/vcpkg_build_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_qmake.cmake)

docs/maintainers/vcpkg_buildpath_length_warning.md

@@ -0,0 +1,11 @@
+# vcpkg_buildpath_length_warning
+
+Warns the user if their vcpkg installation path might be too long for the package they're installing.
+
+## Usage
+```cmake
+vcpkg_buildpath_length_warning(13)
+```
+
+## Source
+[scripts/cmake/vcpkg_buildpath_length_warning.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_buildpath_length_warning.cmake)

docs/maintainers/vcpkg_check_features.md

@@ -143,6 +143,5 @@ vcpkg_configure_cmake(
 * [pcl](https://github.com/microsoft/vcpkg/blob/master/ports/pcl/portfile.cmake)
 * [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
 
-
 ## Source
 [scripts/cmake/vcpkg_check_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)

docs/maintainers/vcpkg_check_linkage.md

@@ -28,7 +28,7 @@ This command will either alter the settings for `VCPKG_LIBRARY_LINKAGE` or fail,
 
 ## Examples
 
-* [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
+* [abseil](https://github.com/Microsoft/vcpkg/blob/master/ports/abseil/portfile.cmake)
 
 ## Source
 [scripts/cmake/vcpkg_check_linkage.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_linkage.cmake)

docs/maintainers/vcpkg_common_definitions.md

@@ -24,6 +24,5 @@ CMAKE_STATIC_LIBRARY_(PREFIX|SUFFIX), CMAKE_SHARED_LIBRARY_(PREFIX|SUFFIX) and C
 Furthermore the variables CMAKE_FIND_LIBRARY_(PREFIXES|SUFFIXES) are also defined for the target so that
 portfiles are able to use find_library calls to discover dependent libraries within the current triplet for ports.
 
-
 ## Source
 [scripts/cmake/vcpkg_common_definitions.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_common_definitions.cmake)

docs/maintainers/vcpkg_configure_qmake.md

@@ -0,0 +1,21 @@
+# vcpkg_configure_qmake
+
+Configure a qmake-based project.
+
+```cmake
+vcpkg_configure_qmake(
+    SOURCE_PATH <pro_file_path>
+    [OPTIONS arg1 [arg2 ...]]
+    [OPTIONS_RELEASE arg1 [arg2 ...]]
+    [OPTIONS_DEBUG arg1 [arg2 ...]]
+)
+```
+
+### SOURCE_PATH
+The path to the *.pro qmake project file.
+
+### OPTIONS, OPTIONS\_RELEASE, OPTIONS\_DEBUG
+The options passed to qmake.
+
+## Source
+[scripts/cmake/vcpkg_configure_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_qmake.cmake)

docs/maintainers/vcpkg_execute_in_download_mode.md

@@ -5,25 +5,30 @@ Execute a process even in download mode.
 ## Usage
 ```cmake
 vcpkg_execute_in_download_mode(
-    COMMAND <cmd> [<arguments>...]
+    COMMAND <cmd> [<arguments>]
-    OUTPUT_QUIET ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_STRIP_TRAILING_WHITESPACE
+    [WORKING_DIRECTORY <dir>]
-    WORKING_DIRECTORY <dir>
+    [TIMEOUT <seconds>]
-    TIMEOUT <seconds>
+    [RESULT_VARIABLE <variable>]
-    RESULT_VARIABLE <seconds>
+    [OUTPUT_VARIABLE <variable>]
-    OUTPUT_VARIABLE <var_out>
+    [ERROR_VARIABLE <variable>]
-    ERROR_VARIABLE <var_err>
+    [INPUT_FILE <file>]
-    INPUT_FILE <f_in>
+    [OUTPUT_FILE <file>]
-    OUTPUT_FILE <f_out>
+    [ERROR_FILE <file>]
-    ERROR_FILE <f_err>
+    [OUTPUT_QUIET]
-    ENCODING <enc>
+    [ERROR_QUIET]
+    [OUTPUT_STRIP_TRAILING_WHITESPACE]
+    [ERROR_STRIP_TRAILING_WHITESPACE]
+    [ENCODING <name>]
 )
 ```
 
-The signature of this function is identical with `execute_process()` except that
+The signature of this function is identical to `execute_process()` except that
 it only accepts one COMMAND argument, i.e., does not support chaining multiple
 commands with pipes.
 
-See `execute_process()` for a detailed description of the parameters.
+See [`execute_process()`] for a detailed description of the parameters.
+
+[`execute_process()`]: https://cmake.org/cmake/help/latest/command/execute_process.html
 
 ## Source
 [scripts/cmake/vcpkg_execute_in_download_mode.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_in_download_mode.cmake)

docs/maintainers/vcpkg_execute_required_process_repeat.md

@@ -0,0 +1,16 @@
+# vcpkg_execute_required_process_repeat
+
+Execute a process until the command succeeds, or until the COUNT is reached.
+
+## Usage
+```cmake
+vcpkg_execute_required_process_repeat(
+    COUNT <num>
+    COMMAND <cmd> [<arguments>]
+    WORKING_DIRECTORY <directory>
+    LOGNAME <name>
+)
+```
+
+## Source
+[scripts/cmake/vcpkg_execute_required_process_repeat.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process_repeat.cmake)

docs/maintainers/vcpkg_extract_source_archive.md

@@ -15,7 +15,7 @@ The full path to the archive to be extracted.
 This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md).
 
 ### TARGET_DIRECTORY
-If specified, the archive will be extracted into the target directory instead of `${CURRENT_BUILDTREES_DIR}\src\`.
+If specified, the archive will be extracted into the target directory instead of `${CURRENT_BUILDTREES_DIR}/src/`.
 
 This can be used to mimic git submodules, by extracting into a subdirectory of another archive.
 

docs/maintainers/vcpkg_find_acquire_program.md

@@ -13,29 +13,29 @@ This variable specifies both the program to be acquired as well as the out param
 ## Notes
 The current list of programs includes:
 
-- 7Z
+* 7Z
-- ARIA2 (Downloader)
+* ARIA2 (Downloader)
-- BISON
+* BISON
-- CLANG
+* CLANG
-- DARK
+* DARK
-- DOXYGEN
+* DOXYGEN
-- FLEX
+* FLEX
-- GASPREPROCESSOR
+* GASPREPROCESSOR
-- GPERF
+* GPERF
-- PERL
+* PERL
-- PYTHON2
+* PYTHON2
-- PYTHON3
+* PYTHON3
-- GIT
+* GIT
-- GN
+* GN
-- GO
+* GO
-- JOM
+* JOM
-- MESON
+* MESON
-- NASM
+* NASM
-- NINJA
+* NINJA
-- NUGET
+* NUGET
-- SCONS
+* SCONS
-- SWIG
+* SWIG
-- YASM
+* YASM
 
 Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
 

docs/maintainers/vcpkg_find_fortran.md

@@ -6,8 +6,7 @@ Windows(x86/x64) Only: If not it will switch/enable MinGW gfortran
 
 ## Usage
 ```cmake
-vcpkg_find_fortran(<additional_cmake_args_out>
+vcpkg_find_fortran(<additional_cmake_args_out>)
-)
 ```
 
 ## Source

docs/maintainers/vcpkg_fixup_cmake_targets.md

@@ -27,6 +27,11 @@ By default the parent directory of CONFIG_PATH is removed if it is named "cmake"
 Passing this option disable such behavior, as it is convenient for ports that install
 more than one CMake package configuration file.
 
+### NO_PREFIX_CORRECTION
+Disables the correction of_IMPORT_PREFIX done by vcpkg due to moving the targets.
+Currently the correction does not take into account how the files are moved and applies
+I rather simply correction which in some cases will yield the wrong results.
+
 ## Notes
 Transform all `/debug/<CONFIG_PATH>/*targets-debug.cmake` files and move them to `/<TARGET_PATH>`.
 Removes all `/debug/<CONFIG_PATH>/*targets.cmake` and `/debug/<CONFIG_PATH>/*config.cmake`.

docs/maintainers/vcpkg_fixup_pkgconfig.md

@@ -36,7 +36,7 @@ Skips the library checks in vcpkg_fixup_pkgconfig. Only use if the script itself
 Still work in progress. If there are more cases which can be handled here feel free to add them
 
 ## Examples
-Just call vcpkg_fixup_pkgconfig() after any install step which installs *.pc files.
+Just call `vcpkg_fixup_pkgconfig()` after any install step which installs *.pc files.
 
 ## Source
 [scripts/cmake/vcpkg_fixup_pkgconfig.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_pkgconfig.cmake)

docs/maintainers/vcpkg_from_gitlab.md

@@ -61,6 +61,5 @@ This exports the `VCPKG_HEAD_VERSION` variable during head builds.
 * [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_from_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)

docs/maintainers/vcpkg_get_program_files_platform_bitness.md

@@ -0,0 +1,13 @@
+# vcpkg_get_program_files_platform_bitness
+
+Get the Program Files directory of the current platform's bitness:
+either `$ENV{ProgramW6432}` on 64-bit windows,
+or `$ENV{PROGRAMFILES}` on 32-bit windows.
+
+## Usage:
+```cmake
+vcpkg_get_program_files_platform_bitness(<variable>)
+```
+
+## Source
+[scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake)

docs/maintainers/vcpkg_get_windows_sdk.md

@@ -0,0 +1,11 @@
+# vcpkg_get_windows_sdk
+
+Get the Windows SDK number.
+
+## Usage:
+```cmake
+vcpkg_get_windows_sdk(<variable>)
+```
+
+## Source
+[scripts/cmake/vcpkg_get_windows_sdk.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_windows_sdk.cmake)

docs/maintainers/vcpkg_replace_string.md

@@ -0,0 +1,11 @@
+# vcpkg_replace_string
+
+Replace a string in a file.
+
+```cmake
+vcpkg_replace_string(filename match_string replace_string)
+```
+
+
+## Source
+[scripts/cmake/vcpkg_replace_string.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_replace_string.cmake)

docs/regenerate.ps1

@@ -1,27 +1,81 @@
-Param([string]$VcpkgRoot = "")
+[CmdletBinding()]
+Param(
+    [String]$VcpkgRoot = ''
+)
 
-$ErrorActionPreference = "Stop"
+if ([String]::IsNullOrEmpty($VcpkgRoot)) {
-
+    $VcpkgRoot = "${PSScriptRoot}/.."
-if (!$VcpkgRoot) {
-    $VcpkgRoot = ".."
 }
 
 $VcpkgRoot = Resolve-Path $VcpkgRoot
 
-if (!(Test-Path "$VcpkgRoot\.vcpkg-root")) {
+if (-not (Test-Path "$VcpkgRoot/.vcpkg-root")) {
     throw "Invalid vcpkg instance, did you forget -VcpkgRoot?"
 }
 
-Set-Content -Path "$PSScriptRoot\maintainers\portfile-functions.md" -Value "<!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->`n`n# Portfile helper functions"
+Set-Content `
+    -Path "$PSScriptRoot/maintainers/portfile-functions.md" `
+    -Value "<!-- Run regenerate.ps1 to extract documentation from scripts/cmake/*.cmake -->`n`n# Portfile helper functions"
+
+Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
+    $filename = $_
+    [String[]]$contents = Get-Content $filename
+
+    if ($contents[0] -eq '# DEPRECATED') {
+        return
+    }
+
+    [String]$startCommentRegex = '#\[(=*)\['
+    [String]$endCommentRegex = ''
+    [Bool]$inComment = $False
+    [Bool]$failThisFile = $False
+
+    $contents = $contents | ForEach-Object {
+        if (-not $inComment) {
+            if ($_ -match "^\s*${startCommentRegex}(\.[a-z]*)?:?\s*$") {
+                if (-not [String]::IsNullOrEmpty($matches[2]) -and $matches[2] -ne '.md') {
+                    Write-Warning "The documentation in ${filename} doesn't seem to be markdown (extension: $($matches[2])). Only markdown is supported; please rewrite the documentation in markdown."
+                }
+                $inComment = $True
+                $endCommentRegex = "\]$($matches[1])\]"
+            } elseif ($_ -match $startCommentRegex) {
+                $failThisFile = $True
+                Write-Warning "Invalid start of comment -- the comment start must be at the beginning of the line.
+    (on line: `"$_`")"
+            } else {
+                # do nothing -- we're outside a comment, so cmake code
+            }
+        } else {
+            if ($_ -match "^\s*#?${endCommentRegex}\s*$") {
+                $inComment = $False
+                $endCommentRegex = ''
+            } elseif ($_ -match $endCommentRegex) {
+                $failThisFile = $True
+                Write-Warning "Invalid end of comment -- the comment end must be on it's own on a line.
+    (on line: `"$_`")"
+            } else {
+                # regular documentation line
+                $_
+            }
+        }
+    }
+
+    if ($inComment) {
+        Write-Warning "File ${filename} has an unclosed comment."
+        return
+    }
+
+    if ($failThisFile) {
+        return
+    }
 
-ls "$VcpkgRoot\scripts\cmake\*.cmake" | % {
-    $contents = Get-Content $_ `
-    | ? { $_ -match "^## |^##`$" } `
-    | % { $_ -replace "^## ?","" }
 
     if ($contents) {
-        Set-Content -Path "$PSScriptRoot\maintainers\$($_.BaseName).md" -Value "$($contents -join "`n")`n`n## Source`n[scripts/cmake/$($_.Name)](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/$($_.Name))"
+        Set-Content -Path "$PSScriptRoot/maintainers/$($filename.BaseName).md" -Value "$($contents -join "`n")`n`n## Source`n[scripts/cmake/$($filename.Name)](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/$($filename.Name))"
-        "- [$($_.BaseName -replace "_","\_")]($($_.BaseName).md)" `
+        "- [$($filename.BaseName -replace "_","\_")]($($filename.BaseName).md)" `
-        | Out-File -Enc Ascii -Append -FilePath "$PSScriptRoot\maintainers\portfile-functions.md"
+        | Out-File -Enc Ascii -Append -FilePath "$PSScriptRoot/maintainers/portfile-functions.md"
+    } elseif (-not $filename.Name.StartsWith("vcpkg_internal")) {
+        # don't worry about undocumented internal functions
+        Write-Warning "The cmake function in file $filename doesn't seem to have any documentation. Make sure the documentation comments are correctly written."
     }
 }

scripts/azure-pipelines/azure-pipelines.yml

@@ -39,11 +39,27 @@ stages:
         filePath: 'scripts/azure-pipelines/windows/Check-ManifestFormatting.ps1'
         arguments: '-Root .'
         pwsh: true
+- stage: check_documentation_generation
+  displayName: Check if the documentation has been regenerated correctly
+  pool: $(windows-pool)
+  dependsOn: []
+  jobs:
+  - job:
+    workspace:
+      clean: resources
+    steps:
+    - task: Powershell@2
+      displayName: 'Check documentation generation'
+      inputs:
+        filePath: 'scripts/azure-pipelines/windows/Check-CMakeFunctionDocumentation.ps1'
+        arguments: '-Root .'
+        pwsh: true
 - stage: run_port_ci
   displayName: 'Run the Port CI'
   dependsOn:
   - check_cxx_formatting
   - check_manifest_formatting
+  - check_documentation_generation
   jobs:
   - template: windows/azure-pipelines.yml
     parameters:

scripts/azure-pipelines/windows/Check-CMakeFunctionDocumentation.ps1

@@ -0,0 +1,30 @@
+[CmdletBinding()]
+Param(
+    [Parameter(Mandatory=$True)]
+    [string]$Root
+)
+
+if (-not (Test-Path "$Root/.vcpkg-root"))
+{
+    Write-Error "The vcpkg root was not at $Root"
+    throw
+}
+
+& "$Root/docs/regenerate.ps1" -VcpkgRoot $Root -WarningAction 'Stop'
+
+$changedFiles = & "$PSScriptRoot/Get-ChangedFiles.ps1" -Directory "$Root/docs"
+if ($null -ne $changedFiles)
+{
+    $msg = @(
+        "",
+        "The documentation files do not seem to have been regenerated.",
+        "Please re-run `docs/regenerate.ps1`."
+    )
+    $msg += ""
+
+    $msg += "This should produce the following diff:"
+    $msg += git diff "$Root/docs"
+
+    Write-Error ($msg -join "`n")
+    throw
+}

scripts/cmake/execute_process.cmake

@@ -1,10 +1,12 @@
-## # execute_process
+#[===[.md:
-##
+# execute_process
-## Intercepts all calls to execute_process() inside portfiles and fails when Download Mode
+
-## is enabled.
+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.
+
-##
+In order to execute a process in Download Mode call `vcpkg_execute_in_download_mode()` instead.
+#]===]
+
 if (NOT DEFINED OVERRIDEN_EXECUTE_PROCESS)
   set(OVERRIDEN_EXECUTE_PROCESS ON)
 
@@ -12,9 +14,5 @@ if (NOT DEFINED OVERRIDEN_EXECUTE_PROCESS)
     macro(execute_process)
       message(FATAL_ERROR "This command cannot be executed in Download Mode.\nHalting portfile execution.\n")
     endmacro()
-  else()
-    macro(_execute_process)
-      execute_process(${ARGV})
-    endmacro()
   endif()
 endif()

scripts/cmake/vcpkg_add_to_path.cmake

@@ -1,26 +1,27 @@
-## # vcpkg_add_to_path
+#[===[
-##
+# vcpkg_add_to_path
-## Add a directory to the PATH environment variable
+
-##
+Add a directory to the PATH environment variable
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_add_to_path([PREPEND] <${PYTHON3_DIR}>)
+```cmake
-## ```
+vcpkg_add_to_path([PREPEND] <${PYTHON3_DIR}>)
-##
+```
-## ## Parameters
+
-## ### <positional>
+## Parameters
-## The directory to add
+### <positional>
-##
+The directory to add
-## ### PREPEND
+
-## Prepends the directory.
+### PREPEND
-##
+Prepends the directory.
-## The default is to append.
+
-##
+The default is to append.
-## ## Examples:
+
-## * [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75)
+## Examples:
-## * [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
+* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75)
-## * [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
+* [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)
+#]===]
 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.")
@@ -36,4 +37,4 @@ function(vcpkg_add_to_path)
         endif()
         set(ENV{PATH} "$ENV{PATH}${VCPKG_HOST_PATH_SEPARATOR}${ARGV0}")
     endif()
-endfunction()
+endfunction()

scripts/cmake/vcpkg_apply_patches.cmake

@@ -1,34 +1,36 @@
-## # vcpkg_apply_patches
+#[===[.md
-##
+# vcpkg_apply_patches
-## Apply a set of patches to a source tree. This function is deprecated in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.
+
-##
+Apply a set of patches to a source tree. This function is deprecated in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_apply_patches(
+```cmake
-##     SOURCE_PATH <${SOURCE_PATH}>
+vcpkg_apply_patches(
-##     [QUIET]
+    SOURCE_PATH <${SOURCE_PATH}>
-##     PATCHES <patch1.patch>...
+    [QUIET]
-## )
+    PATCHES <patch1.patch>...
-## ```
+)
-##
+```
-## ## Parameters
+
-## ### SOURCE_PATH
+## Parameters
-## The source path in which apply the patches. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+### SOURCE_PATH
-##
+The source path in which apply the patches. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
-## ### PATCHES
+
-## A list of patches that are applied to the source tree.
+### PATCHES
-##
+A list of patches that are applied to the source tree.
-## Generally, these take the form of `${CMAKE_CURRENT_LIST_DIR}/some.patch` to select patches in the `port\<port>\` directory.
+
-##
+Generally, these take the form of `${CMAKE_CURRENT_LIST_DIR}/some.patch` to select patches in the `port\<port>\` directory.
-## ### QUIET
+
-## Disables the warning message upon failure.
+### QUIET
-##
+Disables the warning message upon failure.
-## This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
+
-##
+This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
-## ## Examples
+
-##
+## Examples
-## * [libbson](https://github.com/Microsoft/vcpkg/blob/master/ports/libbson/portfile.cmake)
+
-## * [gdal](https://github.com/Microsoft/vcpkg/blob/master/ports/gdal/portfile.cmake)
+* [libbson](https://github.com/Microsoft/vcpkg/blob/master/ports/libbson/portfile.cmake)
+* [gdal](https://github.com/Microsoft/vcpkg/blob/master/ports/gdal/portfile.cmake)
+#]===]
 
 include(vcpkg_execute_in_download_mode)
 

scripts/cmake/vcpkg_build_cmake.cmake

@@ -1,34 +1,37 @@
-## # vcpkg_build_cmake
+#[===[.md:
-##
+# vcpkg_build_cmake
-## Build a cmake project.
+
-##
+Build a cmake project.
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET <target>])
+```cmake
-## ```
+vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET <target>])
-##
+```
-## ## Parameters:
+
-## ### DISABLE_PARALLEL
+## Parameters:
-## The underlying buildsystem will be instructed to not parallelize
+### 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
+### TARGET
-## be passed.
+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.
+### 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 preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
+## Notes:
-## You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the
+This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
-## "install" target
+You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the
-##
+"install" target
-## ## Examples:
+
-##
+## 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)
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
-## * [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
-## * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/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)
+#]===]
+
 function(vcpkg_build_cmake)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
     cmake_parse_arguments(PARSE_ARGV 0 _bc "DISABLE_PARALLEL;ADD_BIN_TO_PATH" "TARGET;LOGFILE_ROOT" "")

scripts/cmake/vcpkg_build_gn.cmake

@@ -1,18 +1,20 @@
-## # vcpkg_build_gn
+#[===[.md:
-##
+# vcpkg_build_gn
-## Build a GN project
+
-##
+Build a GN project
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_build_gn(
+```cmake
-##     [TARGETS <target>...]
+vcpkg_build_gn(
-## )
+    [TARGETS <target>...]
-## ```
+)
-##
+```
-## ## Parameters:
+
-## ### TARGETS
+## Parameters:
-## Only build the specified targets.
+### TARGETS
+Only build the specified targets.
+#]===]
 
 function(vcpkg_build_gn)
     vcpkg_build_ninja(${ARGN})
-endfunction()
+endfunction()

scripts/cmake/vcpkg_build_make.cmake

@@ -1,50 +1,53 @@
-## # vcpkg_build_make
+#[===[.md:
-##
+# vcpkg_build_make
-## Build a linux makefile project.
+
-##
+Build a linux makefile project.
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_build_make([BUILD_TARGET <target>]
+```cmake
-##                  [ADD_BIN_TO_PATH]
+vcpkg_build_make([BUILD_TARGET <target>]
-##                  [ENABLE_INSTALL])
+                 [ADD_BIN_TO_PATH]
-##                  [MAKEFILE <makefileName>]
+                 [ENABLE_INSTALL]
-##                  [LOGFILE_ROOT <logfileroot>])
+                 [MAKEFILE <makefileName>]
-## ```
+                 [LOGFILE_ROOT <logfileroot>])
-##
+```
-## ### BUILD_TARGET
+
-## The target passed to the make build command (`./make <target>`). If not specified, the 'all' target will
+### BUILD_TARGET
-## be passed.
+The target passed to the make build command (`./make <target>`). If not specified, the 'all' 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.
+### 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()
+### 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()`
+### MAKEFILE
-##
+Specifies the Makefile as a relative path from the root of the sources passed to `vcpkg_configure_make()`
-## ### BUILD_TARGET
+
-## The target passed to the make build command (`./make <target>`). If not specified, the 'all' target will
+### BUILD_TARGET
-## be passed.
+The target passed to the make build command (`./make <target>`). If not specified, the 'all' target will
-##
+be passed.
-## ### DISABLE_PARALLEL
+
-## The underlying buildsystem will be instructed to not parallelize
+### 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. 
+### SUBPATH
-##
+Additional subdir to invoke make in. Useful if only parts of a port should be built. 
-## ## Notes:
+
-## This command should be preceeded by a call to [`vcpkg_configure_make()`](vcpkg_configure_make.md).
+## Notes:
-## You can use the alias [`vcpkg_install_make()`](vcpkg_configure_make.md) function if your CMake script supports the
+This command should be preceeded by a call to [`vcpkg_configure_make()`](vcpkg_configure_make.md).
-## "install" target
+You can use the alias [`vcpkg_install_make()`](vcpkg_install_make.md) function if your CMake script supports the
-##
+"install" target
-## ## Examples
+
-##
+## 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)
+* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake)
-## * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
+* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
-## * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/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)
+#]===]
+
 function(vcpkg_build_make)
     if(NOT _VCPKG_CMAKE_VARS_FILE)
         # vcpkg_build_make called without using vcpkg_configure_make before

scripts/cmake/vcpkg_build_msbuild.cmake

@@ -1,65 +1,67 @@
-## # vcpkg_build_msbuild
+#[===[.md:
-##
+# vcpkg_build_msbuild
-## Build a msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
+
-##
+Build a msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_build_msbuild(
+```cmake
-##     PROJECT_PATH <${SOURCE_PATH}/port.sln>
+vcpkg_build_msbuild(
-##     [RELEASE_CONFIGURATION <Release>]
+    PROJECT_PATH <${SOURCE_PATH}/port.sln>
-##     [DEBUG_CONFIGURATION <Debug>]
+    [RELEASE_CONFIGURATION <Release>]
-##     [TARGET <Build>]
+    [DEBUG_CONFIGURATION <Debug>]
-##     [TARGET_PLATFORM_VERSION <10.0.15063.0>]
+    [TARGET <Build>]
-##     [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
+    [TARGET_PLATFORM_VERSION <10.0.15063.0>]
-##     [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
+    [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
-##     [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
+    [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
-##     [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
+    [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
-##     [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
+    [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
-##     [USE_VCPKG_INTEGRATION]
+    [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
-## )
+    [USE_VCPKG_INTEGRATION]
-## ```
+)
-##
+```
-## ## Parameters
+
-## ### USE_VCPKG_INTEGRATION
+## Parameters
-## Apply the normal `integrate install` integration for building the project.
+### 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.
+
-##
+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.
+### PROJECT_PATH
-##
+The path to the solution (`.sln`) or project (`.vcxproj`) file.
-## ### RELEASE_CONFIGURATION
+
-## The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
+### RELEASE_CONFIGURATION
-##
+The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
-## ### DEBUG_CONFIGURATION
+
-## The configuration (``/p:Configuration`` msbuild parameter)
+### DEBUG_CONFIGURATION
-## used for Debug builds.
+The configuration (``/p:Configuration`` msbuild parameter)
-##
+used for Debug builds.
-## ### TARGET_PLATFORM_VERSION
+
-## The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
+### TARGET_PLATFORM_VERSION
-##
+The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
-## ### TARGET
+
-## The MSBuild target to build. (``/t:<TARGET>``)
+### TARGET
-##
+The MSBuild target to build. (``/t:<TARGET>``)
-## ### PLATFORM
+
-## The platform (``/p:Platform`` msbuild parameter) used for the build.
+### PLATFORM
-##
+The platform (``/p:Platform`` msbuild parameter) used for the build.
-## ### PLATFORM_TOOLSET
+
-## The platform toolset (``/p:PlatformToolset`` 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
-##
+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_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`.
+### OPTIONS_DEBUG
-##
+Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`.
-## ## Examples
+
-##
+## Examples
-## * [chakracore](https://github.com/Microsoft/vcpkg/blob/master/ports/chakracore/portfile.cmake)
+
-## * [cppunit](https://github.com/Microsoft/vcpkg/blob/master/ports/cppunit/portfile.cmake)
+* [chakracore](https://github.com/Microsoft/vcpkg/blob/master/ports/chakracore/portfile.cmake)
+* [cppunit](https://github.com/Microsoft/vcpkg/blob/master/ports/cppunit/portfile.cmake)
+#]===]
 
 function(vcpkg_build_msbuild)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased

scripts/cmake/vcpkg_build_ninja.cmake

@@ -1,17 +1,19 @@
-## # vcpkg_build_ninja
+#[===[.md:
-##
+# vcpkg_build_ninja
-## Build a ninja project
+
-##
+Build a ninja project
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_build_ninja(
+```cmake
-##     [TARGETS <target>...]
+vcpkg_build_ninja(
-## )
+    [TARGETS <target>...]
-## ```
+)
-##
+```
-## ## Parameters:
+
-## ### TARGETS
+## Parameters:
-## Only build the specified targets.
+### TARGETS
+Only build the specified targets.
+#]===]
 
 function(vcpkg_build_ninja)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
@@ -35,4 +37,4 @@ function(vcpkg_build_ninja)
     if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "release")
         build(${TARGET_TRIPLET}-rel)
     endif()
-endfunction()
+endfunction()

scripts/cmake/vcpkg_build_nmake.cmake

@@ -1,76 +1,79 @@
-## # vcpkg_build_nmake
+#[===[.md:
-##
+# vcpkg_build_nmake
-## Build a msvc makefile project.
+
-##
+Build a msvc makefile project.
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_build_nmake(
+```cmake
-##     SOURCE_PATH <${SOURCE_PATH}>
+vcpkg_build_nmake(
-##     [NO_DEBUG]
+    SOURCE_PATH <${SOURCE_PATH}>
-##     [TARGET <all>]
+    [NO_DEBUG]
-##     [PROJECT_SUBPATH <${SUBPATH}>]
+    [TARGET <all>]
-##     [PROJECT_NAME <${MAKEFILE_NAME}>]
+    [PROJECT_SUBPATH <${SUBPATH}>]
-##     [PRERUN_SHELL <${SHELL_PATH}>]
+    [PROJECT_NAME <${MAKEFILE_NAME}>]
-##     [PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
+    [PRERUN_SHELL <${SHELL_PATH}>]
-##     [PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
+    [PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    [PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
-##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-##     [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+    [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
-##     [TARGET <target>])
+    [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
-## ```
+    [TARGET <target>])
-##
+```
-## ## Parameters
+
-## ### SOURCE_PATH
+## Parameters
-## Specifies the directory containing the source files.
+### SOURCE_PATH
-## By convention, this is usually set in the portfile as the variable `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_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.
+### PROJECT_NAME
-## Default is `makefile.vc`
+Specifies the name of msvc makefile name.
-##
+Default is `makefile.vc`
-## ### NO_DEBUG
+
-## This port doesn't support debug mode.
+### NO_DEBUG
-##
+This port doesn't support debug mode.
-## ### ENABLE_INSTALL
+
-## Install binaries after build.
+### ENABLE_INSTALL
-##
+Install binaries after build.
-## ### PRERUN_SHELL
+
-## Script that needs to be called before 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_DEBUG
-##
+Script that needs to be called before debug build
-## ### PRERUN_SHELL_RELEASE
+
-## Script that needs to be called before release build
+### PRERUN_SHELL_RELEASE
-##
+Script that needs to be called before release build
-## ### OPTIONS
+
-## Additional options passed to generate during the generation.
+### 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_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`.
+### 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
+### TARGET
-## be passed.
+The target passed to the nmake build command (`nmake/nmake install`). 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.
+### 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 preceeded by a call to [`vcpkg_configure_nmake()`](vcpkg_configure_nmake.md).
+## Notes:
-## You can use the alias [`vcpkg_install_nmake()`](vcpkg_configure_nmake.md) function if your CMake script supports the
+This command should be preceeded by a call to [`vcpkg_configure_nmake()`](vcpkg_configure_nmake.md).
-## "install" target
+You can use the alias [`vcpkg_install_nmake()`](vcpkg_install_nmake.md) function if your CMake script supports the
-##
+"install" target
-## ## Examples
+
-##
+## 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)
+* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
+* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
+#]===]
+
 function(vcpkg_build_nmake)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
     cmake_parse_arguments(PARSE_ARGV 0 _bn

scripts/cmake/vcpkg_build_qmake.cmake

@@ -1,11 +1,13 @@
-#.rst:
+#[===[.md:
-# .. command:: vcpkg_build_qmake
+# vcpkg_build_qmake
-#
+
-#  Build a qmake-based project, previously configured using vcpkg_configure_qmake.
+Build a qmake-based project, previously configured using vcpkg_configure_qmake.
-#
+
-#  ::
+```cmake
-#  vcpkg_build_qmake()
+vcpkg_build_qmake()
-#
+```
+#]===]
+
 function(vcpkg_build_qmake)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
     cmake_parse_arguments(PARSE_ARGV 0 _csc "SKIP_MAKEFILES" "BUILD_LOGNAME" "TARGETS;RELEASE_TARGETS;DEBUG_TARGETS")

scripts/cmake/vcpkg_buildpath_length_warning.cmake

@@ -1,3 +1,14 @@
+#[===[.md:
+# vcpkg_buildpath_length_warning
+
+Warns the user if their vcpkg installation path might be too long for the package they're installing.
+
+## Usage
+```cmake
+vcpkg_buildpath_length_warning(13)
+```
+#]===]
+
 function(vcpkg_buildpath_length_warning WARNING_LENGTH)
     string(LENGTH "${CURRENT_BUILDTREES_DIR}" BUILDTREES_PATH_LENGTH)
     if(BUILDTREES_PATH_LENGTH GREATER ${WARNING_LENGTH} AND CMAKE_HOST_WIN32)
@@ -5,4 +16,4 @@ function(vcpkg_buildpath_length_warning WARNING_LENGTH)
                 "We recommend moving vcpkg to a short path such as 'C:\\src\\vcpkg' or using the subst command."
             )
     endif()
-endfunction()
+endfunction()

scripts/cmake/vcpkg_check_features.cmake

@@ -1,148 +1,150 @@
-## # vcpkg_check_features
+#[===[.md:
-## Check if one or more features are a part of a package installation.
+# vcpkg_check_features
-## 
+Check if one or more features are a part of a package installation.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_check_features(
+```cmake
-##   OUT_FEATURE_OPTIONS <FEATURE_OPTIONS>  
+vcpkg_check_features(
-##   [FEATURES
+  OUT_FEATURE_OPTIONS <FEATURE_OPTIONS>  
-##     <cuda> <WITH_CUDA>
+  [FEATURES
-##     [<opencv> <WITH_OPENCV>]
+    <cuda> <WITH_CUDA>
-##     ...]
+    [<opencv> <WITH_OPENCV>]
-##   [INVERTED_FEATURES
+    ...]
-##     <cuda> <IGNORE_PACKAGE_CUDA>
+  [INVERTED_FEATURES
-##     [<opencv> <IGNORE_PACKAGE_OPENCV>]
+    <cuda> <IGNORE_PACKAGE_CUDA>
-##     ...]
+    [<opencv> <IGNORE_PACKAGE_OPENCV>]
-## )
+    ...]
-## ```
+)
-## `vcpkg_check_features()` accepts these parameters: 
+```
-## 
+`vcpkg_check_features()` accepts these parameters: 
-## * `OUT_FEATURE_OPTIONS`:  
+
-##   An output variable, the function will clear the variable passed to `OUT_FEATURE_OPTIONS` 
+* `OUT_FEATURE_OPTIONS`:  
-##   and then set it to contain a list of option definitions (`-D<OPTION_NAME>=ON|OFF`).
+  An output variable, the function will clear the variable passed to `OUT_FEATURE_OPTIONS` 
-##   
+  and then set it to contain a list of option definitions (`-D<OPTION_NAME>=ON|OFF`).
-##   This should be set to `FEATURE_OPTIONS` by convention.
+  
-##   
+  This should be set to `FEATURE_OPTIONS` by convention.
-## * `FEATURES`:  
+  
-##   A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs.  
+* `FEATURES`:  
-##   For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:   
+  A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs.  
-##     
+  For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:   
-##     * `-D<OPTION_NAME>=ON`, if a feature is specified for installation,
+    
-##     * `-D<OPTION_NAME>=OFF`, otherwise. 
+    * `-D<OPTION_NAME>=ON`, if a feature is specified for installation,
-## 
+    * `-D<OPTION_NAME>=OFF`, otherwise. 
-## * `INVERTED_FEATURES`:  
+
-##   A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs, uses reversed logic from `FEATURES`.  
+* `INVERTED_FEATURES`:  
-##   For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:   
+  A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs, uses reversed logic from `FEATURES`.  
-##     
+  For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:   
-##     * `-D<OPTION_NAME>=OFF`, if a feature is specified for installation,
+    
-##     * `-D<OPTION_NAME>=ON`, otherwise. 
+    * `-D<OPTION_NAME>=OFF`, if a feature is specified for installation,
-## 
+    * `-D<OPTION_NAME>=ON`, otherwise. 
-## 
+
-## ## Notes
+
-## 
+## Notes
-## The `FEATURES` name parameter can be omitted if no `INVERTED_FEATURES` are used.
+
-## 
+The `FEATURES` name parameter can be omitted if no `INVERTED_FEATURES` are used.
-## At least one (`FEATURE_NAME`, `OPTION_NAME`) pair must be passed to the function call.
+
-## 
+At least one (`FEATURE_NAME`, `OPTION_NAME`) pair must be passed to the function call.
-## Arguments passed to `FEATURES` and `INVERTED_FEATURES` are not validated to prevent duplication.  
+
-## If the same (`FEATURE_NAME`, `OPTION_NAME`) pair is passed to both lists, 
+Arguments passed to `FEATURES` and `INVERTED_FEATURES` are not validated to prevent duplication.  
-## two conflicting definitions are added to `OUT_FEATURE_OPTIONS`.
+If the same (`FEATURE_NAME`, `OPTION_NAME`) pair is passed to both lists, 
-## 
+two conflicting definitions are added to `OUT_FEATURE_OPTIONS`.
-## 
+
-## ## Examples
+
-## 
+## Examples
-## ### Example 1: Regular features
+
-## 
+### Example 1: Regular features
-## ```cmake
+
-## $ ./vcpkg install mimalloc[asm,secure]
+```cmake
-## 
+$ ./vcpkg install mimalloc[asm,secure]
-## # ports/mimalloc/portfile.cmake
+
-## vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+# ports/mimalloc/portfile.cmake
-##   # Keyword FEATURES is optional if INVERTED_FEATURES are not used
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-##     asm       MI_SEE_ASM
+  # Keyword FEATURES is optional if INVERTED_FEATURES are not used
-##     override  MI_OVERRIDE
+    asm       MI_SEE_ASM
-##     secure    MI_SECURE
+    override  MI_OVERRIDE
-## )
+    secure    MI_SECURE
-## 
+)
-## vcpkg_configure_cmake(
+
-##   SOURCE_PATH ${SOURCE_PATH}
+vcpkg_configure_cmake(
-##   PREFER_NINJA
+  SOURCE_PATH ${SOURCE_PATH}
-##   OPTIONS
+  PREFER_NINJA
-##     # Expands to "-DMI_SEE_ASM=ON; -DMI_OVERRIDE=OFF; -DMI_SECURE=ON"
+  OPTIONS
-##     ${FEATURE_OPTIONS}
+    # Expands to "-DMI_SEE_ASM=ON; -DMI_OVERRIDE=OFF; -DMI_SECURE=ON"
-## )
+    ${FEATURE_OPTIONS}
-## ```
+)
-## 
+```
-## ### Example 2: Inverted features
+
-## 
+### Example 2: Inverted features
-## ```cmake
+
-## $ ./vcpkg install cpprestsdk[websockets]
+```cmake
-## 
+$ ./vcpkg install cpprestsdk[websockets]
-## # ports/cpprestsdk/portfile.cmake
+
-## vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+# ports/cpprestsdk/portfile.cmake
-##   INVERTED_FEATURES # <- Keyword INVERTED_FEATURES required
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-##     brotli      CPPREST_EXCLUDE_BROTLI
+  INVERTED_FEATURES # <- Keyword INVERTED_FEATURES required
-##     websockets  CPPREST_EXCLUDE_WEBSOCKETS
+    brotli      CPPREST_EXCLUDE_BROTLI
-## )
+    websockets  CPPREST_EXCLUDE_WEBSOCKETS
-## 
+)
-## vcpkg_configure_cmake(
+
-##   SOURCE_PATH ${SOURCE_PATH}
+vcpkg_configure_cmake(
-##   PREFER_NINJA
+  SOURCE_PATH ${SOURCE_PATH}
-##   OPTIONS
+  PREFER_NINJA
-##     # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON; -DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
+  OPTIONS
-##     ${FEATURE_OPTIONS}
+    # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON; -DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
-## )
+    ${FEATURE_OPTIONS}
-## ```
+)
-## 
+```
-## ### Example 3: Set multiple options for same feature
+
-## 
+### Example 3: Set multiple options for same feature
-## ```cmake
+
-## $ ./vcpkg install pcl[cuda]
+```cmake
-## 
+$ ./vcpkg install pcl[cuda]
-## # ports/pcl/portfile.cmake
+
-## vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+# ports/pcl/portfile.cmake
-##     cuda  WITH_CUDA
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-##     cuda  BUILD_CUDA
+    cuda  WITH_CUDA
-##     cuda  BUILD_GPU
+    cuda  BUILD_CUDA
-## )
+    cuda  BUILD_GPU
-## 
+)
-## vcpkg_configure_cmake(
+
-##   SOURCE_PATH ${SOURCE_PATH}
+vcpkg_configure_cmake(
-##   PREFER_NINJA
+  SOURCE_PATH ${SOURCE_PATH}
-##   OPTIONS
+  PREFER_NINJA
-##     # Expands to "-DWITH_CUDA=ON; -DBUILD_CUDA=ON; -DBUILD_GPU=ON"
+  OPTIONS
-##     ${FEATURE_OPTIONS}
+    # Expands to "-DWITH_CUDA=ON; -DBUILD_CUDA=ON; -DBUILD_GPU=ON"
-## )
+    ${FEATURE_OPTIONS}
-## ``` 
+)
-## 
+``` 
-## ### Example 4: Use regular and inverted features
+
-## 
+### Example 4: Use regular and inverted features
-## ```cmake
+
-## $ ./vcpkg install rocksdb[tbb]
+```cmake
-## 
+$ ./vcpkg install rocksdb[tbb]
-## # ports/rocksdb/portfile.cmake
+
-## vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+# ports/rocksdb/portfile.cmake
-##   FEATURES # <- Keyword FEATURES is required because INVERTED_FEATURES are being used
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-##     tbb   WITH_TBB
+  FEATURES # <- Keyword FEATURES is required because INVERTED_FEATURES are being used
-##   INVERTED_FEATURES
+    tbb   WITH_TBB
-##     tbb   ROCKSDB_IGNORE_PACKAGE_TBB
+  INVERTED_FEATURES
-## )
+    tbb   ROCKSDB_IGNORE_PACKAGE_TBB
-## 
+)
-## vcpkg_configure_cmake(
+
-##   SOURCE_PATH ${SOURCE_PATH}
+vcpkg_configure_cmake(
-##   PREFER_NINJA
+  SOURCE_PATH ${SOURCE_PATH}
-##   OPTIONS
+  PREFER_NINJA
-##     # Expands to "-DWITH_TBB=ON; -DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
+  OPTIONS
-##     ${FEATURE_OPTIONS}
+    # Expands to "-DWITH_TBB=ON; -DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
-## )
+    ${FEATURE_OPTIONS}
-## ``` 
+)
-## 
+``` 
-## ## Examples in portfiles
+
-## 
+## Examples in portfiles
-## * [cpprestsdk](https://github.com/microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+
-## * [pcl](https://github.com/microsoft/vcpkg/blob/master/ports/pcl/portfile.cmake)
+* [cpprestsdk](https://github.com/microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
-## * [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
+* [pcl](https://github.com/microsoft/vcpkg/blob/master/ports/pcl/portfile.cmake)
-## 
+* [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
+#]===]
+
 function(vcpkg_check_features)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
     cmake_parse_arguments(PARSE_ARGV 0 _vcf "" "OUT_FEATURE_OPTIONS" "FEATURES;INVERTED_FEATURES")

scripts/cmake/vcpkg_check_linkage.cmake

@@ -1,34 +1,37 @@
-## # vcpkg_check_linkage
+#[===[.md:
-##
+# vcpkg_check_linkage
-## Asserts the available library and CRT linkage options for the port.
+
-##
+Asserts the available library and CRT linkage options for the port.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_check_linkage(
+```cmake
-##     [ONLY_STATIC_LIBRARY | ONLY_DYNAMIC_LIBRARY]
+vcpkg_check_linkage(
-##     [ONLY_STATIC_CRT | ONLY_DYNAMIC_CRT]
+    [ONLY_STATIC_LIBRARY | ONLY_DYNAMIC_LIBRARY]
-## )
+    [ONLY_STATIC_CRT | ONLY_DYNAMIC_CRT]
-## ```
+)
-##
+```
-## ## Parameters
+
-## ### ONLY_STATIC_LIBRARY
+## Parameters
-## Indicates that this port can only be built with static library linkage.
+### ONLY_STATIC_LIBRARY
-##
+Indicates that this port can only be built with static library linkage.
-## ### ONLY_DYNAMIC_LIBRARY
+
-## Indicates that this port can only be built with dynamic/shared library linkage.
+### ONLY_DYNAMIC_LIBRARY
-##
+Indicates that this port can only be built with dynamic/shared library linkage.
-## ### ONLY_STATIC_CRT
+
-## Indicates that this port can only be built with static CRT linkage.
+### ONLY_STATIC_CRT
-##
+Indicates that this port can only be built with static CRT linkage.
-## ### ONLY_DYNAMIC_CRT
+
-## Indicates that this port can only be built with dynamic/shared CRT linkage.
+### ONLY_DYNAMIC_CRT
-##
+Indicates that this port can only be built with dynamic/shared CRT linkage.
-## ## Notes
+
-## This command will either alter the settings for `VCPKG_LIBRARY_LINKAGE` or fail, depending on what was requested by the user versus what the library supports.
+## Notes
-##
+This command will either alter the settings for `VCPKG_LIBRARY_LINKAGE` or fail, depending on what was requested by the user versus what the library supports.
-## ## Examples
+
-##
+## Examples
-## * [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
+
+* [abseil](https://github.com/Microsoft/vcpkg/blob/master/ports/abseil/portfile.cmake)
+#]===]
+
 function(vcpkg_check_linkage)
     cmake_parse_arguments(_csc "ONLY_STATIC_LIBRARY;ONLY_DYNAMIC_LIBRARY;ONLY_DYNAMIC_CRT;ONLY_STATIC_CRT" "" "" ${ARGN})
 

scripts/cmake/vcpkg_clean_executables_in_bin.cmake

@@ -1,23 +1,26 @@
-## # vcpkg_clean_executables_in_bin
+#[===[.md:
-##
+# vcpkg_clean_executables_in_bin
-## Remove specified executables found in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`. If, after all specified executables have been removed, and the `bin` and `debug/bin` directories are empty, then also delete `bin` and `debug/bin` directories.
+
-##
+Remove specified executables found in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`. If, after all specified executables have been removed, and the `bin` and `debug/bin` directories are empty, then also delete `bin` and `debug/bin` directories.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_clean_executables_in_bin(
+```cmake
-##     FILE_NAMES <file1>...
+vcpkg_clean_executables_in_bin(
-## )
+    FILE_NAMES <file1>...
-## ```
+)
-##
+```
-## ## Parameters
+
-## ### FILE_NAMES
+## Parameters
-## A list of executable filenames without extension.
+### FILE_NAMES
-##
+A list of executable filenames without extension.
-## ## Notes
+
-## Generally, there is no need to call this function manually. Instead, pass an extra `AUTO_CLEAN` argument when calling `vcpkg_copy_tools`.
+## Notes
-##
+Generally, there is no need to call this function manually. Instead, pass an extra `AUTO_CLEAN` argument when calling `vcpkg_copy_tools`.
-## ## Examples
+
-## * [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
+## Examples
+* [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
+#]===]
+
 function(vcpkg_clean_executables_in_bin)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
     cmake_parse_arguments(PARSE_ARGV 0 _vct "" "" "FILE_NAMES")

scripts/cmake/vcpkg_clean_msbuild.cmake

@@ -1,15 +1,17 @@
-## # vcpkg_clean_msbuild
+#[===[.md:
-##
+# vcpkg_clean_msbuild
-## Clean intermediate files generated by `vcpkg_install_msbuild()`.
+
-##
+Clean intermediate files generated by `vcpkg_install_msbuild()`.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_clean_msbuild()
+```cmake
-## ```
+vcpkg_clean_msbuild()
-##
+```
-## ## Examples
+
-##
+## Examples
-## * [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
+
+* [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
+#]===]
 
 function(vcpkg_clean_msbuild)
     file(REMOVE_RECURSE

scripts/cmake/vcpkg_common_definitions.cmake

@@ -1,29 +1,30 @@
-## # vcpkg_common_definitions
+#[===[.md:
-##
+# vcpkg_common_definitions
-## File contains helpful variabls for portfiles which are commonly needed or used.
+
-##
+File contains helpful variabls for portfiles which are commonly needed or used.
-## ## The following variables are available:
+
-## ```cmake
+## The following variables are available:
-## VCPKG_TARGET_IS_<target>                 with <target> being one of the following: WINDOWS, UWP, LINUX, OSX, ANDROID, FREEBSD, OPENBSD. only defined if <target>
+```cmake
-## VCPKG_HOST_IS_<target>                   with <host> being one of the following: WINDOWS, LINUX, OSX, FREEBSD, OPENBSD. only defined if <host>
+VCPKG_TARGET_IS_<target>                 with <target> being one of the following: WINDOWS, UWP, LINUX, OSX, ANDROID, FREEBSD, OPENBSD. only defined if <target>
-## VCPKG_HOST_PATH_SEPARATOR                Host specific path separator (USAGE: "<something>${VCPKG_HOST_PATH_SEPARATOR}<something>"; only use and pass variables with VCPKG_HOST_PATH_SEPARATOR within "")
+VCPKG_HOST_IS_<target>                   with <host> being one of the following: WINDOWS, LINUX, OSX, FREEBSD, OPENBSD. only defined if <host>
-## VCPKG_HOST_EXECUTABLE_SUFFIX             executable suffix of the host
+VCPKG_HOST_PATH_SEPARATOR                Host specific path separator (USAGE: "<something>${VCPKG_HOST_PATH_SEPARATOR}<something>"; only use and pass variables with VCPKG_HOST_PATH_SEPARATOR within "")
-## VCPKG_TARGET_EXECUTABLE_SUFFIX           executable suffix of the target
+VCPKG_HOST_EXECUTABLE_SUFFIX             executable suffix of the host
-## VCPKG_TARGET_STATIC_LIBRARY_PREFIX       static library prefix for target (same as CMAKE_STATIC_LIBRARY_PREFIX)
+VCPKG_TARGET_EXECUTABLE_SUFFIX           executable suffix of the target
-## VCPKG_TARGET_STATIC_LIBRARY_SUFFIX       static library suffix for target (same as CMAKE_STATIC_LIBRARY_SUFFIX)
+VCPKG_TARGET_STATIC_LIBRARY_PREFIX       static library prefix for target (same as CMAKE_STATIC_LIBRARY_PREFIX)
-## VCPKG_TARGET_SHARED_LIBRARY_PREFIX       shared library prefix for target (same as CMAKE_SHARED_LIBRARY_PREFIX)
+VCPKG_TARGET_STATIC_LIBRARY_SUFFIX       static library suffix for target (same as CMAKE_STATIC_LIBRARY_SUFFIX)
-## VCPKG_TARGET_SHARED_LIBRARY_SUFFIX       shared library suffix for target (same as CMAKE_SHARED_LIBRARY_SUFFIX)
+VCPKG_TARGET_SHARED_LIBRARY_PREFIX       shared library prefix for target (same as CMAKE_SHARED_LIBRARY_PREFIX)
-## VCPKG_TARGET_IMPORT_LIBRARY_PREFIX       import library prefix for target (same as CMAKE_IMPORT_LIBRARY_PREFIX)
+VCPKG_TARGET_SHARED_LIBRARY_SUFFIX       shared library suffix for target (same as CMAKE_SHARED_LIBRARY_SUFFIX)
-## VCPKG_TARGET_IMPORT_LIBRARY_SUFFIX       import library suffix for target (same as CMAKE_IMPORT_LIBRARY_SUFFIX)
+VCPKG_TARGET_IMPORT_LIBRARY_PREFIX       import library prefix for target (same as CMAKE_IMPORT_LIBRARY_PREFIX)
-## VCPKG_FIND_LIBRARY_PREFIXES              target dependent prefixes used for find_library calls in portfiles
+VCPKG_TARGET_IMPORT_LIBRARY_SUFFIX       import library suffix for target (same as CMAKE_IMPORT_LIBRARY_SUFFIX)
-## VCPKG_FIND_LIBRARY_SUFFIXES              target dependent suffixes used for find_library calls in portfiles
+VCPKG_FIND_LIBRARY_PREFIXES              target dependent prefixes used for find_library calls in portfiles
-## VCPKG_SYSTEM_LIBRARIES                   list of libraries are provide by the toolchain and are not managed by vcpkg
+VCPKG_FIND_LIBRARY_SUFFIXES              target dependent suffixes used for find_library calls in portfiles
-## ```
+VCPKG_SYSTEM_LIBRARIES                   list of libraries are provide by the toolchain and are not managed by vcpkg
-##
+```
-## CMAKE_STATIC_LIBRARY_(PREFIX|SUFFIX), CMAKE_SHARED_LIBRARY_(PREFIX|SUFFIX) and CMAKE_IMPORT_LIBRARY_(PREFIX|SUFFIX) are defined for the target
+
-## Furthermore the variables CMAKE_FIND_LIBRARY_(PREFIXES|SUFFIXES) are also defined for the target so that
+CMAKE_STATIC_LIBRARY_(PREFIX|SUFFIX), CMAKE_SHARED_LIBRARY_(PREFIX|SUFFIX) and CMAKE_IMPORT_LIBRARY_(PREFIX|SUFFIX) are defined for the target
-## portfiles are able to use find_library calls to discover dependent libraries within the current triplet for ports.
+Furthermore the variables CMAKE_FIND_LIBRARY_(PREFIXES|SUFFIXES) are also defined for the target so that
-##
+portfiles are able to use find_library calls to discover dependent libraries within the current triplet for ports.
+#]===]
 
 #Helper variable to identify the Target system. VCPKG_TARGET_IS_<targetname>
 if (NOT VCPKG_CMAKE_SYSTEM_NAME OR VCPKG_CMAKE_SYSTEM_NAME STREQUAL "WindowsStore")

scripts/cmake/vcpkg_common_functions.cmake

@@ -1 +1,3 @@
+# DEPRECATED
+
 message("${_VCPKG_BACKCOMPAT_MESSAGE_LEVEL}" "vcpkg_common_functions has been removed and all values are automatically provided in all portfile.cmake invocations. Please remove `include(vcpkg_common_functions)`.")

scripts/cmake/vcpkg_configure_cmake.cmake

@@ -1,68 +1,71 @@
-## # vcpkg_configure_cmake
+#[===[.md:
-##
+# vcpkg_configure_cmake
-## Configure CMake for Debug and Release builds of a project.
+
-##
+Configure CMake for Debug and Release builds of a project.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_configure_cmake(
+```cmake
-##     SOURCE_PATH <${SOURCE_PATH}>
+vcpkg_configure_cmake(
-##     [PREFER_NINJA]
+    SOURCE_PATH <${SOURCE_PATH}>
-##     [DISABLE_PARALLEL_CONFIGURE]
+    [PREFER_NINJA]
-##     [NO_CHARSET_FLAG]
+    [DISABLE_PARALLEL_CONFIGURE]
-##     [GENERATOR <"NMake Makefiles">]
+    [NO_CHARSET_FLAG]
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    [GENERATOR <"NMake Makefiles">]
-##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-##     [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+    [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
-## )
+    [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
-## ```
+)
-##
+```
-## ## Parameters
+
-## ### SOURCE_PATH
+## Parameters
-## Specifies the directory containing the `CMakeLists.txt`.
+### SOURCE_PATH
-## By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+Specifies the directory containing the `CMakeLists.txt`.
-##
+By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
-## ### PREFER_NINJA
+
-## Indicates that, when available, Vcpkg should use Ninja to perform the build.
+### PREFER_NINJA
-## This should be specified unless the port is known to not work under Ninja.
+Indicates that, when available, Vcpkg should use Ninja to perform the build.
-##
+This should be specified unless the port is known to not work under Ninja.
-## ### DISABLE_PARALLEL_CONFIGURE
+
-## Disables running the CMake configure step in parallel.
+### DISABLE_PARALLEL_CONFIGURE
-## This is needed for libraries which write back into their source directory during configure.
+Disables running the CMake configure step in parallel.
-##
+This is needed for libraries which write back into their source directory during configure.
-## This also disables CMAKE_DISABLE_SOURCE_CHANGES.
+
-##
+This also disables CMAKE_DISABLE_SOURCE_CHANGES.
-## ### NO_CHARSET_FLAG
+
-## Disables passing `utf-8` as the default character set to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`.
+### NO_CHARSET_FLAG
-##
+Disables passing `utf-8` as the default character set to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`.
-## This is needed for libraries that set their own source code's character set.
+
-##
+This is needed for libraries that set their own source code's character set.
-## ### GENERATOR
+
-## Specifies the precise generator to use.
+### GENERATOR
-##
+Specifies the precise generator to use.
-## This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build.
+
-## If used for this purpose, it should be set to `"NMake Makefiles"`.
+This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build.
-##
+If used for this purpose, it should be set to `"NMake Makefiles"`.
-## ### OPTIONS
+
-## Additional options passed to CMake during the configuration.
+### OPTIONS
-##
+Additional options passed to CMake during the configuration.
-## ### OPTIONS_RELEASE
+
-## Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`.
+### OPTIONS_RELEASE
-##
+Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`.
-## ### OPTIONS_DEBUG
+
-## Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`.
+### OPTIONS_DEBUG
-##
+Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`.
-## ### LOGNAME
+
-## Name of the log to write the output of the configure call to.
+### LOGNAME
-##
+Name of the log to write the output of the configure call to.
-## ## Notes
+
-## This command supplies many common arguments to CMake. To see the full list, examine the source.
+## Notes
-##
+This command supplies many common arguments to CMake. To see the full list, examine the source.
-## ## Examples
+
-##
+## 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)
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
-## * [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
-## * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/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)
+#]===]
+
 function(vcpkg_configure_cmake)
     # parse parameters such that semicolons in arguments to OPTIONS don't get erased
     cmake_parse_arguments(PARSE_ARGV 0 _csc

scripts/cmake/vcpkg_configure_gn.cmake

@@ -1,30 +1,32 @@
-## # vcpkg_configure_gn
+#[===[.md:
-##
+# vcpkg_configure_gn
-## Generate Ninja (GN) targets
+
-##
+Generate Ninja (GN) targets
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_configure_gn(
+```cmake
-##     SOURCE_PATH <SOURCE_PATH>
+vcpkg_configure_gn(
-##     [OPTIONS <OPTIONS>]
+    SOURCE_PATH <SOURCE_PATH>
-##     [OPTIONS_DEBUG <OPTIONS_DEBUG>]
+    [OPTIONS <OPTIONS>]
-##     [OPTIONS_RELEASE <OPTIONS_RELEASE>]
+    [OPTIONS_DEBUG <OPTIONS_DEBUG>]
-## )
+    [OPTIONS_RELEASE <OPTIONS_RELEASE>]
-## ```
+)
-##
+```
-## ## Parameters:
+
-## ### SOURCE_PATH (required)
+## Parameters:
-## The path to the GN project.
+### SOURCE_PATH (required)
-##
+The path to the GN project.
-## ### OPTIONS
+
-## Options to be passed to both the debug and release targets.
+### OPTIONS
-## Note: Must be provided as a space-separated string.
+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_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.
+### OPTIONS_RELEASE (space-separated string)
+Options to be passed to the release target.
+#]===]
 
 function(vcpkg_configure_gn)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
@@ -56,4 +58,4 @@ function(vcpkg_configure_gn)
     if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "release")
         generate(${TARGET_TRIPLET}-rel "--args=${_vcg_OPTIONS} ${_vcg_OPTIONS_RELEASE}")
     endif()
-endfunction()
+endfunction()

scripts/cmake/vcpkg_configure_make.cmake

@@ -1,91 +1,94 @@
-## # vcpkg_configure_make
+#[===[.md:
-##
+# vcpkg_configure_make
-## Configure configure for Debug and Release builds of a project.
+
-##
+Configure configure for Debug and Release builds of a project.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_configure_make(
+```cmake
-##     SOURCE_PATH <${SOURCE_PATH}>
+vcpkg_configure_make(
-##     [AUTOCONFIG]
+    SOURCE_PATH <${SOURCE_PATH}>
-##     [USE_WRAPPERS]
+    [AUTOCONFIG]
-##     [DETERMINE_BUILD_TRIPLET]
+    [USE_WRAPPERS]
-##     [BUILD_TRIPLET "--host=x64 --build=i686-unknown-pc"]
+    [DETERMINE_BUILD_TRIPLET]
-##     [NO_ADDITIONAL_PATHS]
+    [BUILD_TRIPLET "--host=x64 --build=i686-unknown-pc"]
-##     [CONFIG_DEPENDENT_ENVIRONMENT <SOME_VAR>...]
+    [NO_ADDITIONAL_PATHS]
-##     [CONFIGURE_ENVIRONMENT_VARIABLES <SOME_ENVVAR>...]
+    [CONFIG_DEPENDENT_ENVIRONMENT <SOME_VAR>...]
-##     [ADD_BIN_TO_PATH]
+    [CONFIGURE_ENVIRONMENT_VARIABLES <SOME_ENVVAR>...]
-##     [NO_DEBUG]
+    [ADD_BIN_TO_PATH]
-##     [SKIP_CONFIGURE]
+    [NO_DEBUG]
-##     [PROJECT_SUBPATH <${PROJ_SUBPATH}>]
+    [SKIP_CONFIGURE]
-##     [PRERUN_SHELL <${SHELL_PATH}>]
+    [PROJECT_SUBPATH <${PROJ_SUBPATH}>]
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    [PRERUN_SHELL <${SHELL_PATH}>]
-##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-##     [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+    [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
-## )
+    [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
-## ```
+)
-##
+```
-## ## Parameters
+
-## ### SOURCE_PATH
+## Parameters
-## Specifies the directory containing the `configure`/`configure.ac`.
+### SOURCE_PATH
-## By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+Specifies the directory containing the `configure`/`configure.ac`.
-##
+By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
-## ### PROJECT_SUBPATH
+
-## Specifies the directory containing the ``configure`/`configure.ac`.
+### PROJECT_SUBPATH
-## By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+Specifies the directory containing the ``configure`/`configure.ac`.
-##
+By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
-## ### SKIP_CONFIGURE
+
-## Skip configure process
+### SKIP_CONFIGURE
-##
+Skip configure process
-## ### USE_WRAPPERS
+
-## Use autotools ar-lib and compile wrappers (only applies to windows cl and lib)
+### USE_WRAPPERS
-##
+Use autotools ar-lib and compile wrappers (only applies to windows cl and lib)
-## ### BUILD_TRIPLET
+
-## Used to pass custom --build/--target/--host to configure. Can be globally overwritten by VCPKG_MAKE_BUILD_TRIPLET
+### BUILD_TRIPLET
-##
+Used to pass custom --build/--target/--host to configure. Can be globally overwritten by VCPKG_MAKE_BUILD_TRIPLET
-## ### DETERMINE_BUILD_TRIPLET
+
-## For ports having a configure script following the autotools rules for selecting the triplet
+### DETERMINE_BUILD_TRIPLET
-##
+For ports having a configure script following the autotools rules for selecting the triplet
-## ### NO_ADDITIONAL_PATHS
+
-## Don't pass any additional paths except for --prefix to the configure call
+### NO_ADDITIONAL_PATHS
-##
+Don't pass any additional paths except for --prefix to the configure call
-## ### AUTOCONFIG
+
-## Need to use autoconfig to generate configure file.
+### AUTOCONFIG
-##
+Need to use autoconfig to generate configure file.
-## ### PRERUN_SHELL
+
-## Script that needs to be called before configuration (do not use for batch files which simply call autoconf or configure)
+### PRERUN_SHELL
-##
+Script that needs to be called before configuration (do not use for batch files which simply call autoconf or configure)
-## ### ADD_BIN_TO_PATH
+
-## Adds the appropriate Release and Debug `bin\` directories to the path during configure such that executables can run against the in-tree DLLs.
+### ADD_BIN_TO_PATH
-##
+Adds the appropriate Release and Debug `bin\` directories to the path during configure such that executables can run against the in-tree DLLs.
-## ## DISABLE_VERBOSE_FLAGS
+
-## do not pass '--disable-silent-rules --verbose' to configure
+## DISABLE_VERBOSE_FLAGS
-##
+do not pass '--disable-silent-rules --verbose' to configure
-## ### OPTIONS
+
-## Additional options passed to configure during the configuration.
+### OPTIONS
-##
+Additional options passed to configure during the configuration.
-## ### OPTIONS_RELEASE
+
-## Additional options passed to configure during the Release configuration. These are in addition to `OPTIONS`.
+### OPTIONS_RELEASE
-##
+Additional options passed to configure during the Release configuration. These are in addition to `OPTIONS`.
-## ### OPTIONS_DEBUG
+
-## Additional options passed to configure during the Debug configuration. These are in addition to `OPTIONS`.
+### OPTIONS_DEBUG
-##
+Additional options passed to configure during the Debug configuration. These are in addition to `OPTIONS`.
-## ### CONFIG_DEPENDENT_ENVIRONMENT
+
-## List of additional configuration dependent environment variables to set. 
+### CONFIG_DEPENDENT_ENVIRONMENT
-## Pass SOMEVAR to set the environment and have SOMEVAR_(DEBUG|RELEASE) set in the portfile to the appropriate values
+List of additional configuration dependent environment variables to set. 
-## General environment variables can be set from within the portfile itself. 
+Pass SOMEVAR to set the environment and have SOMEVAR_(DEBUG|RELEASE) set in the portfile to the appropriate values
-##
+General environment variables can be set from within the portfile itself. 
-## ### CONFIGURE_ENVIRONMENT_VARIABLES
+
-## List of additional environment variables to pass via the configure call. 
+### CONFIGURE_ENVIRONMENT_VARIABLES
-##
+List of additional environment variables to pass via the configure call. 
-## ## Notes
+
-## This command supplies many common arguments to configure. To see the full list, examine the source.
+## Notes
-##
+This command supplies many common arguments to configure. To see the full list, examine the source.
-## ## Examples
+
-##
+## 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)
+* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake)
-## * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
+* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
-## * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/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)
+#]===]
+
 macro(_vcpkg_determine_host_mingw out_var)
     if(DEFINED ENV{PROCESSOR_ARCHITEW6432})
         set(HOST_ARCH $ENV{PROCESSOR_ARCHITEW6432})
@@ -202,7 +205,7 @@ macro(_vcpkg_extract_cpp_flags_and_set_cflags_and_cxxflags _SUFFIX)
 endmacro()
 
 function(vcpkg_configure_make)
-    # parse parameters such that semicolons in options arguments to COMMAND don't get erased
+    # parse parameters such that semicolons in options arguments to COMMAND don't get erased
     cmake_parse_arguments(PARSE_ARGV 0 _csc
         "AUTOCONFIG;SKIP_CONFIGURE;COPY_SOURCE;DISABLE_VERBOSE_FLAGS;NO_ADDITIONAL_PATHS;ADD_BIN_TO_PATH;USE_WRAPPERS;DETERMINE_BUILD_TRIPLET"
         "SOURCE_PATH;PROJECT_SUBPATH;PRERUN_SHELL;BUILD_TRIPLET"

scripts/cmake/vcpkg_configure_meson.cmake

@@ -1,38 +1,41 @@
-## # vcpkg_configure_meson
+#[===[.md:
-##
+# vcpkg_configure_meson
-## Configure Meson for Debug and Release builds of a project.
+
-##
+Configure Meson for Debug and Release builds of a project.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_configure_meson(
+```cmake
-##     SOURCE_PATH <${SOURCE_PATH}>
+vcpkg_configure_meson(
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    SOURCE_PATH <${SOURCE_PATH}>
-##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-##     [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+    [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
-## )
+    [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
-## ```
+)
-##
+```
-## ## Parameters
+
-## ### SOURCE_PATH
+## Parameters
-## Specifies the directory containing the `meson.build`.
+### SOURCE_PATH
-## By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+Specifies the directory containing the `meson.build`.
-##
+By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
-## ### OPTIONS
+
-## Additional options passed to Meson during the configuration.
+### OPTIONS
-##
+Additional options passed to Meson during the configuration.
-## ### OPTIONS_RELEASE
+
-## Additional options passed to Meson during the Release configuration. These are in addition to `OPTIONS`.
+### OPTIONS_RELEASE
-##
+Additional options passed to Meson during the Release configuration. These are in addition to `OPTIONS`.
-## ### OPTIONS_DEBUG
+
-## Additional options passed to Meson during the Debug configuration. These are in addition to `OPTIONS`.
+### OPTIONS_DEBUG
-##
+Additional options passed to Meson during the Debug configuration. These are in addition to `OPTIONS`.
-## ## Notes
+
-## This command supplies many common arguments to Meson. To see the full list, examine the source.
+## Notes
-##
+This command supplies many common arguments to Meson. To see the full list, examine the source.
-## ## Examples
+
-##
+## Examples
-## * [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake)
+
-## * [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
+* [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake)
+* [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
+#]===]
+
 function(vcpkg_internal_meson_generate_native_file) #https://mesonbuild.com/Native-environments.html
     set(NATIVE "[binaries]\n")
     #set(proglist AR RANLIB STRIP NM OBJDUMP DLLTOOL MT)
@@ -60,7 +63,6 @@ function(vcpkg_internal_meson_generate_native_file) #https://mesonbuild.com/Nati
         string(APPEND NATIVE "cpp_ld = '${VCPKG_DETECTED_CMAKE_LINKER}'\n")
     endif()
     string(APPEND NATIVE "cmake = '${CMAKE_COMMAND}'\n")
-    
     string(APPEND NATIVE "[built-in options]\n") #https://mesonbuild.com/Builtin-options.html
     if(VCPKG_DETECTED_CMAKE_C_COMPILER MATCHES "cl.exe")
         string(APPEND NATIVE "cpp_eh='none'\n") # To make sure meson is not adding eh flags by itself using msvc

scripts/cmake/vcpkg_configure_qmake.cmake

@@ -1,19 +1,23 @@
-#.rst:
+#[===[.md:
-# .. command:: vcpkg_configure_qmake
+# vcpkg_configure_qmake
-#
+
-#  Configure a qmake-based project.
+Configure a qmake-based project.
-#
+
-#  ::
+```cmake
-#  vcpkg_configure_qmake(SOURCE_PATH <pro_file_path>
+vcpkg_configure_qmake(
-#                        [OPTIONS arg1 [arg2 ...]]
+    SOURCE_PATH <pro_file_path>
-#                        [OPTIONS_RELEASE arg1 [arg2 ...]]
+    [OPTIONS arg1 [arg2 ...]]
-#                        [OPTIONS_DEBUG arg1 [arg2 ...]]
+    [OPTIONS_RELEASE arg1 [arg2 ...]]
-#                        )
+    [OPTIONS_DEBUG arg1 [arg2 ...]]
-#
+)
-#  ``SOURCE_PATH``
+```
-#    The path to the *.pro qmake project file.
+
-#  ``OPTIONS[_RELEASE|_DEBUG]``
+### SOURCE_PATH
-#    The options passed to qmake.
+The path to the *.pro qmake project file.
+
+### OPTIONS, OPTIONS\_RELEASE, OPTIONS\_DEBUG
+The options passed to qmake.
+#]===]
 
 function(vcpkg_configure_qmake)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
@@ -127,4 +131,4 @@ function(vcpkg_configure_qmake)
         endif()
     endif()
 
-endfunction()
+endfunction()

scripts/cmake/vcpkg_copy_pdbs.cmake

@@ -1,25 +1,28 @@
-## # vcpkg_copy_pdbs
+#[===[.md:
-##
+# vcpkg_copy_pdbs
-## Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
+
-##
+Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_copy_pdbs([BUILD_PATHS <${CURRENT_PACKAGES_DIR}/bin/*.dll> ...])
+```cmake
-## ```
+vcpkg_copy_pdbs([BUILD_PATHS <${CURRENT_PACKAGES_DIR}/bin/*.dll> ...])
-##
+```
-## ## Notes
+
-## This command should always be called by portfiles after they have finished rearranging the binary output.
+## Notes
-##
+This command should always be called by portfiles after they have finished rearranging the binary output.
-## ## Parameters
+
-## ### BUILD_PATHS
+## Parameters
-## Path patterns passed to `file(GLOB_RECURSE)` for locating dlls.
+### BUILD_PATHS
-##
+Path patterns passed to `file(GLOB_RECURSE)` for locating dlls.
-## Defaults to `${CURRENT_PACKAGES_DIR}/bin/*.dll` and `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`.
+
-##
+Defaults to `${CURRENT_PACKAGES_DIR}/bin/*.dll` and `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`.
-## ## Examples
+
-##
+## 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)
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+#]===]
+
 function(vcpkg_copy_pdbs)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
     cmake_parse_arguments(PARSE_ARGV 0 _vcp "" "" "BUILD_PATHS")
@@ -75,4 +78,4 @@ function(vcpkg_copy_pdbs)
         endif()
     endif()
 
-endfunction()
+endfunction()

scripts/cmake/vcpkg_copy_tool_dependencies.cmake

@@ -1,21 +1,24 @@
-## # vcpkg_copy_tool_dependencies
+#[===[.md:
-##
+# vcpkg_copy_tool_dependencies
-## Copy all DLL dependencies of built tools into the tool folder.
+
-##
+Copy all DLL dependencies of built tools into the tool folder.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>)
+```cmake
-## ```
+vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>)
-## ## Parameters
+```
-## The path to the directory containing the tools.
+## Parameters
-##
+The path to the directory containing the tools.
-## ## Notes
+
-## This command should always be called by portfiles after they have finished rearranging the binary output, if they have any tools.
+## Notes
-##
+This command should always be called by portfiles after they have finished rearranging the binary output, if they have any tools.
-## ## Examples
+
-##
+## Examples
-## * [glib](https://github.com/Microsoft/vcpkg/blob/master/ports/glib/portfile.cmake)
+
-## * [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake)
+* [glib](https://github.com/Microsoft/vcpkg/blob/master/ports/glib/portfile.cmake)
+* [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake)
+#]===]
+
 function(vcpkg_copy_tool_dependencies TOOL_DIR)
     if (VCPKG_TARGET_IS_WINDOWS)
         find_program(PWSH_EXE pwsh)

scripts/cmake/vcpkg_copy_tools.cmake

@@ -1,30 +1,33 @@
-## # vcpkg_copy_tools
+#[===[.md:
-##
+# vcpkg_copy_tools
-## Copy tools and all their DLL dependencies into the `tools` folder.
+
-##
+Copy tools and all their DLL dependencies into the `tools` folder.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_copy_tools(
+```cmake
-##     TOOL_NAMES <tool1>...
+vcpkg_copy_tools(
-##     [SEARCH_DIR <${CURRENT_PACKAGES_DIR}/bin>]
+    TOOL_NAMES <tool1>...
-##     [AUTO_CLEAN]
+    [SEARCH_DIR <${CURRENT_PACKAGES_DIR}/bin>]
-## )
+    [AUTO_CLEAN]
-## ```
+)
-## ## Parameters
+```
-## ### TOOL_NAMES
+## Parameters
-## A list of tool filenames without extension.
+### TOOL_NAMES
-##
+A list of tool filenames without extension.
-## ### SEARCH_DIR
+
-## The path to the directory containing the tools. This will be set to `${CURRENT_PACKAGES_DIR}/bin` if ommited.
+### SEARCH_DIR
-##
+The path to the directory containing the tools. This will be set to `${CURRENT_PACKAGES_DIR}/bin` if ommited.
-## ### AUTO_CLEAN
+
-## Auto clean executables in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`.
+### AUTO_CLEAN
-##
+Auto clean executables in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`.
-## ## Examples
+
-##
+## Examples
-## * [cpuinfo](https://github.com/microsoft/vcpkg/blob/master/ports/cpuinfo/portfile.cmake)
+
-## * [nanomsg](https://github.com/microsoft/vcpkg/blob/master/ports/nanomsg/portfile.cmake)
+* [cpuinfo](https://github.com/microsoft/vcpkg/blob/master/ports/cpuinfo/portfile.cmake)
-## * [uriparser](https://github.com/microsoft/vcpkg/blob/master/ports/uriparser/portfile.cmake)
+* [nanomsg](https://github.com/microsoft/vcpkg/blob/master/ports/nanomsg/portfile.cmake)
+* [uriparser](https://github.com/microsoft/vcpkg/blob/master/ports/uriparser/portfile.cmake)
+#]===]
+
 function(vcpkg_copy_tools)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
     cmake_parse_arguments(PARSE_ARGV 0 _vct "AUTO_CLEAN" "SEARCH_DIR" "TOOL_NAMES")

scripts/cmake/vcpkg_download_distfile.cmake

@@ -1,54 +1,56 @@
-## # vcpkg_download_distfile
+#[===[.md:
-##
+# vcpkg_download_distfile
-## Download and cache a file needed for this port.
+
-##
+Download and cache a file needed for this port.
-## This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.
+
-##
+This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_download_distfile(
+```cmake
-##     <OUT_VARIABLE>
+vcpkg_download_distfile(
-##     URLS <http://mainUrl> <http://mirror1>...
+    <OUT_VARIABLE>
-##     FILENAME <output.zip>
+    URLS <http://mainUrl> <http://mirror1>...
-##     SHA512 <5981de...>
+    FILENAME <output.zip>
-## )
+    SHA512 <5981de...>
-## ```
+)
-## ## Parameters
+```
-## ### OUT_VARIABLE
+## Parameters
-## This variable will be set to the full path to the downloaded file. This can then immediately be passed in to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) for sources.
+### OUT_VARIABLE
-##
+This variable will be set to the full path to the downloaded file. This can then immediately be passed in to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) for sources.
-## ### URLS
+
-## A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given.
+### URLS
-##
+A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given.
-## ### FILENAME
+
-## The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.
+### FILENAME
-##
+The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.
-## ### SHA512
+
-## The expected hash for the file.
+### SHA512
-##
+The expected hash for the file.
-## If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch.
+
-##
+If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch.
-## ### QUIET
+
-## Suppress output on cache hit
+### QUIET
-##
+Suppress output on cache hit
-## ### SKIP_SHA512
+
-## Skip SHA512 hash check for file.
+### SKIP_SHA512
-##
+Skip SHA512 hash check for file.
-## This switch is only valid when building with the `--head` command line flag.
+
-##
+This switch is only valid when building with the `--head` command line flag.
-## ### HEADERS
+
-## A list of headers to append to the download request. This can be used for authentication during a download.
+### HEADERS
-##
+A list of headers to append to the download request. This can be used for authentication during a download.
-## Headers should be specified as "<header-name>: <header-value>".
+
-##
+Headers should be specified as "<header-name>: <header-value>".
-## ## Notes
+
-## The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects.
+## Notes
-##
+The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects.
-## ## Examples
+
-##
+## Examples
-## * [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake)
+
-## * [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)
+* [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake)
-## * [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)
+* [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)
+* [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)
+#]===]
 
 include(vcpkg_execute_in_download_mode)
 

scripts/cmake/vcpkg_execute_build_process.cmake

@@ -1,36 +1,39 @@
-## # vcpkg_execute_build_process
+#[===[.md:
-##
+# vcpkg_execute_build_process
-## Execute a required build process
+
-##
+Execute a required build process
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_execute_build_process(
+```cmake
-##     COMMAND <cmd> [<args>...]
+vcpkg_execute_build_process(
-##     [NO_PARALLEL_COMMAND <cmd> [<args>...]]
+    COMMAND <cmd> [<args>...]
-##     WORKING_DIRECTORY </path/to/dir>
+    [NO_PARALLEL_COMMAND <cmd> [<args>...]]
-##     LOGNAME <log_name>)
+    WORKING_DIRECTORY </path/to/dir>
-## )
+    LOGNAME <log_name>)
-## ```
+)
-## ## Parameters
+```
-## ### COMMAND
+## Parameters
-## The command to be executed, along with its arguments.
+### COMMAND
-##
+The command to be executed, along with its arguments.
-## ### NO_PARALLEL_COMMAND
+
-## Optional parameter which specifies a non-parallel command to attempt if a
+### NO_PARALLEL_COMMAND
-## failure potentially due to parallelism is detected.
+Optional parameter which specifies a non-parallel command to attempt if a
-##
+failure potentially due to parallelism is detected.
-## ### WORKING_DIRECTORY
+
-## The directory to execute the command in.
+### WORKING_DIRECTORY
-##
+The directory to execute the command in.
-## ### LOGNAME
+
-## The prefix to use for the log files.
+### LOGNAME
-##
+The prefix to use for the log files.
-## This should be a unique name for different triplets so that the logs don't
+
-## conflict when building multiple at once.
+This should be a unique name for different triplets so that the logs don't
-##
+conflict when building multiple at once.
-## ## Examples
+
-##
+## Examples
-## * [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
+
+* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
+#]===]
+
 include(vcpkg_prettify_command)
 function(vcpkg_execute_build_process)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased

scripts/cmake/vcpkg_execute_in_download_mode.cmake

@@ -1,59 +1,67 @@
-## # vcpkg_execute_in_download_mode
+#[===[.md:
-##
+# vcpkg_execute_in_download_mode
-## Execute a process even in download mode.
+
-##
+Execute a process even in download mode.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_execute_in_download_mode(
+```cmake
-##     COMMAND <cmd> [<arguments>...]
+vcpkg_execute_in_download_mode(
-##     OUTPUT_QUIET ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_STRIP_TRAILING_WHITESPACE
+    COMMAND <cmd> [<arguments>]
-##     WORKING_DIRECTORY <dir>
+    [WORKING_DIRECTORY <dir>]
-##     TIMEOUT <seconds>
+    [TIMEOUT <seconds>]
-##     RESULT_VARIABLE <seconds>
+    [RESULT_VARIABLE <variable>]
-##     OUTPUT_VARIABLE <var_out>
+    [OUTPUT_VARIABLE <variable>]
-##     ERROR_VARIABLE <var_err>
+    [ERROR_VARIABLE <variable>]
-##     INPUT_FILE <f_in>
+    [INPUT_FILE <file>]
-##     OUTPUT_FILE <f_out>
+    [OUTPUT_FILE <file>]
-##     ERROR_FILE <f_err>
+    [ERROR_FILE <file>]
-##     ENCODING <enc>
+    [OUTPUT_QUIET]
-## )
+    [ERROR_QUIET]
-## ```
+    [OUTPUT_STRIP_TRAILING_WHITESPACE]
-##
+    [ERROR_STRIP_TRAILING_WHITESPACE]
-## The signature of this function is identical with `execute_process()` except that
+    [ENCODING <name>]
-## it only accepts one COMMAND argument, i.e., does not support chaining multiple
+)
-## commands with pipes.
+```
-## 
+
-## See `execute_process()` for a detailed description of the parameters.
+The signature of this function is identical to `execute_process()` except that
+it only accepts one COMMAND argument, i.e., does not support chaining multiple
+commands with pipes.
+
+See [`execute_process()`] for a detailed description of the parameters.
+
+[`execute_process()`]: https://cmake.org/cmake/help/latest/command/execute_process.html
+#]===]
+
 function(vcpkg_execute_in_download_mode)
-  # parse parameters such that semicolons in options arguments to COMMAND don't get erased
+    # parse parameters such that semicolons in options arguments to COMMAND don't get erased
-  cmake_parse_arguments(PARSE_ARGV 0 vcpkg_execute_in_download_mode
+    cmake_parse_arguments(PARSE_ARGV 0 vcpkg_execute_in_download_mode
-                        "OUTPUT_QUIET;ERROR_QUIET;OUTPUT_STRIP_TRAILING_WHITESPACE;ERROR_STRIP_TRAILING_WHITESPACE"
+        "OUTPUT_QUIET;ERROR_QUIET;OUTPUT_STRIP_TRAILING_WHITESPACE;ERROR_STRIP_TRAILING_WHITESPACE"
-                        "WORKING_DIRECTORY;TIMEOUT;RESULT_VARIABLE;RESULTS_VARIABLE;OUTPUT_VARIABLE;ERROR_VARIABLE;INPUT_FILE;OUTPUT_FILE;ERROR_FILE;ENCODING"
+        "WORKING_DIRECTORY;TIMEOUT;RESULT_VARIABLE;RESULTS_VARIABLE;OUTPUT_VARIABLE;ERROR_VARIABLE;INPUT_FILE;OUTPUT_FILE;ERROR_FILE;ENCODING"
-                        "COMMAND")
+        "COMMAND")
 
-  # collect all other present parameters
+    # collect all other present parameters
-  set(other_args "")
+    set(other_args "")
-  foreach(arg OUTPUT_QUIET ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_STRIP_TRAILING_WHITESPACE)
+    foreach(arg OUTPUT_QUIET ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_STRIP_TRAILING_WHITESPACE)
-    if(vcpkg_execute_in_download_mode_${arg})
+        if(vcpkg_execute_in_download_mode_${arg})
-      list(APPEND other_args ${arg})
+            list(APPEND other_args ${arg})
+        endif()
+    endforeach()
+    foreach(arg WORKING_DIRECTORY TIMEOUT RESULT_VARIABLE RESULTS_VARIABLE OUTPUT_VARIABLE ERROR_VARIABLE INPUT_FILE OUTPUT_FILE ERROR_FILE ENCODING)
+        if(vcpkg_execute_in_download_mode_${arg})
+            list(APPEND other_args ${arg} ${vcpkg_execute_in_download_mode_${arg}})
+        endif()
+    endforeach()
+
+    if (DEFINED VCPKG_DOWNLOAD_MODE)
+        _execute_process(COMMAND ${vcpkg_execute_in_download_mode_COMMAND} ${other_args})
+    else()
+        execute_process(COMMAND ${vcpkg_execute_in_download_mode_COMMAND} ${other_args})
     endif()
-  endforeach()
-  foreach(arg WORKING_DIRECTORY TIMEOUT RESULT_VARIABLE RESULTS_VARIABLE OUTPUT_VARIABLE ERROR_VARIABLE INPUT_FILE OUTPUT_FILE ERROR_FILE ENCODING)
-    if(vcpkg_execute_in_download_mode_${arg})
-      list(APPEND other_args ${arg} ${vcpkg_execute_in_download_mode_${arg}})
-    endif()
-  endforeach()
 
-  if (DEFINED VCPKG_DOWNLOAD_MODE)
+    # pass output parameters back to caller's scope
-    _execute_process(COMMAND ${vcpkg_execute_in_download_mode_COMMAND} ${other_args})
+    foreach(arg RESULT_VARIABLE RESULTS_VARIABLE OUTPUT_VARIABLE ERROR_VARIABLE)
-  else()
+        if(vcpkg_execute_in_download_mode_${arg})
-    execute_process(COMMAND ${vcpkg_execute_in_download_mode_COMMAND} ${other_args})
+            set(${vcpkg_execute_in_download_mode_${arg}} ${${vcpkg_execute_in_download_mode_${arg}}} PARENT_SCOPE)
-  endif()
+         endif()
-
+    endforeach()
-  # pass output parameters back to caller's scope
-  foreach(arg RESULT_VARIABLE RESULTS_VARIABLE OUTPUT_VARIABLE ERROR_VARIABLE)
-    if(vcpkg_execute_in_download_mode_${arg})
-      set(${vcpkg_execute_in_download_mode_${arg}} ${${vcpkg_execute_in_download_mode_${arg}}} PARENT_SCOPE)
-     endif()
-  endforeach()
 endfunction()

scripts/cmake/vcpkg_execute_required_process.cmake

@@ -1,49 +1,51 @@
-## # vcpkg_execute_required_process
+#[===[.md:
-##
+# vcpkg_execute_required_process
-## Execute a process with logging and fail the build if the command fails.
+
-##
+Execute a process with logging and fail the build if the command fails.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_execute_required_process(
+```cmake
-##     COMMAND <${PERL}> [<arguments>...]
+vcpkg_execute_required_process(
-##     WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg>
+    COMMAND <${PERL}> [<arguments>...]
-##     LOGNAME <build-${TARGET_TRIPLET}-dbg>
+    WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg>
-##     [TIMEOUT <seconds>]
+    LOGNAME <build-${TARGET_TRIPLET}-dbg>
-##     [OUTPUT_VARIABLE <var>]
+    [TIMEOUT <seconds>]
-##     [ERROR_VARIABLE <var>]
+    [OUTPUT_VARIABLE <var>]
-## )
+    [ERROR_VARIABLE <var>]
-## ```
+)
-## ## Parameters
+```
-## ### ALLOW_IN_DOWNLOAD_MODE
+## Parameters
-## Allows the command to execute in Download Mode.  
+### ALLOW_IN_DOWNLOAD_MODE
-## [See execute_process() override](../../scripts/cmake/execute_process.cmake).
+Allows the command to execute in Download Mode.  
-##
+[See execute_process() override](../../scripts/cmake/execute_process.cmake).
-## ### COMMAND
+
-## The command to be executed, along with its arguments.
+### COMMAND
-##
+The command to be executed, along with its arguments.
-## ### WORKING_DIRECTORY
+
-## The directory to execute the command in.
+### WORKING_DIRECTORY
-##
+The directory to execute the command in.
-## ### LOGNAME
+
-## The prefix to use for the log files.
+### LOGNAME
-##
+The prefix to use for the log files.
-## ### TIMEOUT
+
-## Optional timeout after which to terminate the command.
+### TIMEOUT
-##
+Optional timeout after which to terminate the command.
-## ### OUTPUT_VARIABLE
+
-## Optional variable to receive stdout of the command.
+### OUTPUT_VARIABLE
-##
+Optional variable to receive stdout of the command.
-## ### ERROR_VARIABLE
+
-## Optional variable to receive stderr of the command.
+### ERROR_VARIABLE
-##
+Optional variable to receive stderr of the command.
-## This should be a unique name for different triplets so that the logs don't conflict when building multiple at once.
+
-##
+This should be a unique name for different triplets so that the logs don't conflict when building multiple at once.
-## ## Examples
+
-##
+## Examples
-## * [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
+
-## * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
+* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
-## * [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
+* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
-## * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
+* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
+* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
+#]===]
 
 include(vcpkg_prettify_command)
 include(vcpkg_execute_in_download_mode)

scripts/cmake/vcpkg_execute_required_process_repeat.cmake

@@ -1,4 +1,19 @@
-# Usage: vcpkg_execute_required_process_repeat(COUNT <num> COMMAND <cmd> [<args>...] WORKING_DIRECTORY </path/to/dir> LOGNAME <my_log_name>)
+#[===[.md:
+# vcpkg_execute_required_process_repeat
+
+Execute a process until the command succeeds, or until the COUNT is reached.
+
+## Usage
+```cmake
+vcpkg_execute_required_process_repeat(
+    COUNT <num>
+    COMMAND <cmd> [<arguments>]
+    WORKING_DIRECTORY <directory>
+    LOGNAME <name>
+)
+```
+#]===]
+
 include(vcpkg_prettify_command)
 function(vcpkg_execute_required_process_repeat)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased

scripts/cmake/vcpkg_extract_source_archive.cmake

@@ -1,32 +1,35 @@
-## # vcpkg_extract_source_archive
+#[===[.md:
-##
+# vcpkg_extract_source_archive
-## Extract an archive into the source directory. Deprecated in favor of [`vcpkg_extract_source_archive_ex`](vcpkg_extract_source_archive_ex.md).
+
-##
+Extract an archive into the source directory. Deprecated in favor of [`vcpkg_extract_source_archive_ex`](vcpkg_extract_source_archive_ex.md).
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_extract_source_archive(
+```cmake
-##     <${ARCHIVE}> [<${TARGET_DIRECTORY}>]
+vcpkg_extract_source_archive(
-## )
+    <${ARCHIVE}> [<${TARGET_DIRECTORY}>]
-## ```
+)
-## ## Parameters
+```
-## ### ARCHIVE
+## Parameters
-## The full path to the archive to be extracted.
+### ARCHIVE
-##
+The full path to the archive to be extracted.
-## This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md).
+
-##
+This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md).
-## ### TARGET_DIRECTORY
+
-## If specified, the archive will be extracted into the target directory instead of `${CURRENT_BUILDTREES_DIR}\src\`.
+### TARGET_DIRECTORY
-##
+If specified, the archive will be extracted into the target directory instead of `${CURRENT_BUILDTREES_DIR}/src/`.
-## This can be used to mimic git submodules, by extracting into a subdirectory of another archive.
+
-##
+This can be used to mimic git submodules, by extracting into a subdirectory of another archive.
-## ## Notes
+
-## This command will also create a tracking file named <FILENAME>.extracted in the TARGET_DIRECTORY. This file, when present, will suppress the extraction of the archive.
+## Notes
-##
+This command will also create a tracking file named <FILENAME>.extracted in the TARGET_DIRECTORY. This file, when present, will suppress the extraction of the archive.
-## ## Examples
+
-##
+## Examples
-## * [libraw](https://github.com/Microsoft/vcpkg/blob/master/ports/libraw/portfile.cmake)
+
-## * [protobuf](https://github.com/Microsoft/vcpkg/blob/master/ports/protobuf/portfile.cmake)
+* [libraw](https://github.com/Microsoft/vcpkg/blob/master/ports/libraw/portfile.cmake)
-## * [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake)
+* [protobuf](https://github.com/Microsoft/vcpkg/blob/master/ports/protobuf/portfile.cmake)
+* [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake)
+#]===]
+
 include(vcpkg_execute_required_process)
 
 function(vcpkg_extract_source_archive ARCHIVE)

scripts/cmake/vcpkg_extract_source_archive_ex.cmake

@@ -1,56 +1,59 @@
-## # vcpkg_extract_source_archive_ex
+#[===[.md:
-##
+# vcpkg_extract_source_archive_ex
-## Extract an archive into the source directory. Replaces [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md).
+
-##
+Extract an archive into the source directory. Replaces [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md).
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_extract_source_archive_ex(
+```cmake
-##     SKIP_PATCH_CHECK
+vcpkg_extract_source_archive_ex(
-##     OUT_SOURCE_PATH <SOURCE_PATH>
+    SKIP_PATCH_CHECK
-##     ARCHIVE <${ARCHIVE}>
+    OUT_SOURCE_PATH <SOURCE_PATH>
-##     [REF <1.0.0>]
+    ARCHIVE <${ARCHIVE}>
-##     [NO_REMOVE_ONE_LEVEL]
+    [REF <1.0.0>]
-##     [WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/src>]
+    [NO_REMOVE_ONE_LEVEL]
-##     [PATCHES <a.patch>...]
+    [WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/src>]
-## )
+    [PATCHES <a.patch>...]
-## ```
+)
-## ## Parameters
+```
-## ### SKIP_PATCH_CHECK
+## Parameters
-## If this option is set the failure to apply a patch is ignored.
+### SKIP_PATCH_CHECK
-##
+If this option is set the failure to apply a patch is ignored.
-## ### OUT_SOURCE_PATH
+
-## Specifies the out-variable that will contain the extracted location.
+### OUT_SOURCE_PATH
-##
+Specifies the out-variable that will contain the extracted location.
-## This should be set to `SOURCE_PATH` by convention.
+
-##
+This should be set to `SOURCE_PATH` by convention.
-## ### ARCHIVE
+
-## The full path to the archive to be extracted.
+### ARCHIVE
-##
+The full path to the archive to be extracted.
-## This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md).
+
-##
+This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md).
-## ### REF
+
-## A friendly name that will be used instead of the filename of the archive.  If more than 10 characters it will be truncated.
+### REF
-##
+A friendly name that will be used instead of the filename of the archive.  If more than 10 characters it will be truncated.
-## By convention, this is set to the version number or tag fetched
+
-##
+By convention, this is set to the version number or tag fetched
-## ### WORKING_DIRECTORY
+
-## If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`.
+### WORKING_DIRECTORY
-##
+If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`.
-## Note that the archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`).
+
-##
+Note that the archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`).
-## ### PATCHES
+
-## A list of patches to be applied to the extracted sources.
+### PATCHES
-##
+A list of patches to be applied to the extracted sources.
-## Relative paths are based on the port directory.
+
-##
+Relative paths are based on the port directory.
-## ### NO_REMOVE_ONE_LEVEL
+
-## Specifies that the default removal of the top level folder should not occur.
+### NO_REMOVE_ONE_LEVEL
-##
+Specifies that the default removal of the top level folder should not occur.
-## ## Examples
+
-##
+## Examples
-## * [bzip2](https://github.com/Microsoft/vcpkg/blob/master/ports/bzip2/portfile.cmake)
+
-## * [sqlite3](https://github.com/Microsoft/vcpkg/blob/master/ports/sqlite3/portfile.cmake)
+* [bzip2](https://github.com/Microsoft/vcpkg/blob/master/ports/bzip2/portfile.cmake)
-## * [cairo](https://github.com/Microsoft/vcpkg/blob/master/ports/cairo/portfile.cmake)
+* [sqlite3](https://github.com/Microsoft/vcpkg/blob/master/ports/sqlite3/portfile.cmake)
+* [cairo](https://github.com/Microsoft/vcpkg/blob/master/ports/cairo/portfile.cmake)
+#]===]
+
 include(vcpkg_apply_patches)
 include(vcpkg_extract_source_archive)
 

scripts/cmake/vcpkg_fail_port_install.cmake

@@ -1,41 +1,44 @@
-## # vcpkg_fail_port_install
+#[===[.md:
-##
+# vcpkg_fail_port_install
-## Checks common requirements and fails the current portfile with a (default) error message
+
-##
+Checks common requirements and fails the current portfile with a (default) error message
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_fail_port_install(
+```cmake
-##     [ALWAYS]
+vcpkg_fail_port_install(
-##     [MESSAGE <"Reason for failure">]
+    [ALWAYS]
-##     [ON_TARGET <Windows> [<OSX> ...]]
+    [MESSAGE <"Reason for failure">]
-##     [ON_ARCH <x64> [<arm> ...]]
+    [ON_TARGET <Windows> [<OSX> ...]]
-##     [ON_CRT_LINKAGE <static> [<dynamic> ...]])
+    [ON_ARCH <x64> [<arm> ...]]
-##     [ON_LIBRARY_LINKAGE <static> [<dynamic> ...]]
+    [ON_CRT_LINKAGE <static> [<dynamic> ...]])
-## )
+    [ON_LIBRARY_LINKAGE <static> [<dynamic> ...]]
-## ```
+)
-##
+```
-## ## Parameters
+
-## ### MESSAGE
+## Parameters
-## Additional failure message. If none is given, a default message will be displayed depending on the failure condition.
+### MESSAGE
-##
+Additional failure message. If none is given, a default message will be displayed depending on the failure condition.
-## ### ALWAYS
+
-## Will always fail early
+### ALWAYS
-##
+Will always fail early
-## ### ON_TARGET
+
-## Targets for which the build should fail early. Valid targets are `<target>` from `VCPKG_IS_TARGET_<target>` (see `vcpkg_common_definitions.cmake`).
+### ON_TARGET
-##
+Targets for which the build should fail early. Valid targets are `<target>` from `VCPKG_IS_TARGET_<target>` (see `vcpkg_common_definitions.cmake`).
-## ### ON_ARCH
+
-## Architecture for which the build should fail early.
+### ON_ARCH
-##
+Architecture for which the build should fail early.
-## ### ON_CRT_LINKAGE
+
-## CRT linkage for which the build should fail early.
+### ON_CRT_LINKAGE
-##
+CRT linkage for which the build should fail early.
-## ### ON_LIBRARY_LINKAGE
+
-## Library linkage for which the build should fail early.
+### ON_LIBRARY_LINKAGE
-##
+Library linkage for which the build should fail early.
-## ## Examples
+
-##
+## Examples
-## * [aws-lambda-cpp](https://github.com/Microsoft/vcpkg/blob/master/ports/aws-lambda-cpp/portfile.cmake)
+
+* [aws-lambda-cpp](https://github.com/Microsoft/vcpkg/blob/master/ports/aws-lambda-cpp/portfile.cmake)
+#]===]
+
 function(vcpkg_fail_port_install)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
     cmake_parse_arguments(PARSE_ARGV 0 _csc "ALWAYS" "MESSAGE" "ON_TARGET;ON_ARCH;ON_CRT_LINKAGE;ON_LIBRARY_LINKAGE")

scripts/cmake/vcpkg_find_acquire_program.cmake

@@ -1,49 +1,51 @@
-## # vcpkg_find_acquire_program
+#[===[.md:
-##
+# vcpkg_find_acquire_program
-## Download or find a well-known tool.
+
-##
+Download or find a well-known tool.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_find_acquire_program(<VAR>)
+```cmake
-## ```
+vcpkg_find_acquire_program(<VAR>)
-## ## Parameters
+```
-## ### VAR
+## Parameters
-## This variable specifies both the program to be acquired as well as the out parameter that will be set to the path of the program executable.
+### VAR
-##
+This variable specifies both the program to be acquired as well as the out parameter that will be set to the path of the program executable.
-## ## Notes
+
-## The current list of programs includes:
+## Notes
-##
+The current list of programs includes:
-## - 7Z
+
-## - ARIA2 (Downloader)
+* 7Z
-## - BISON
+* ARIA2 (Downloader)
-## - CLANG
+* BISON
-## - DARK
+* CLANG
-## - DOXYGEN
+* DARK
-## - FLEX
+* DOXYGEN
-## - GASPREPROCESSOR
+* FLEX
-## - GPERF
+* GASPREPROCESSOR
-## - PERL
+* GPERF
-## - PYTHON2
+* PERL
-## - PYTHON3
+* PYTHON2
-## - GIT
+* PYTHON3
-## - GN
+* GIT
-## - GO
+* GN
-## - JOM
+* GO
-## - MESON
+* JOM
-## - NASM
+* MESON
-## - NINJA
+* NASM
-## - NUGET
+* NINJA
-## - SCONS
+* NUGET
-## - SWIG
+* SCONS
-## - YASM
+* SWIG
-##
+* YASM
-## Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
+
-##
+Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
-## ## Examples
+
-##
+## Examples
-## * [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
+
-## * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
+* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
-## * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
+* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
+* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
+#]===]
 
 include(vcpkg_execute_in_download_mode)
 
@@ -464,7 +466,7 @@ function(vcpkg_find_acquire_program VAR)
 
   macro(do_version_check)
     if(VERSION_CMD)
-        _execute_process(
+        vcpkg_execute_in_download_mode(
             COMMAND ${${VAR}} ${VERSION_CMD}
             WORKING_DIRECTORY ${DOWNLOADS}
             OUTPUT_VARIABLE ${VAR}_VERSION_OUTPUT

scripts/cmake/vcpkg_find_fortran.cmake

@@ -1,14 +1,15 @@
-## # vcpkg_find_fortran
+#[===[.md:
-##
+# vcpkg_find_fortran
-## Checks if a Fortran compiler can be found.
+
-## Windows(x86/x64) Only: If not it will switch/enable MinGW gfortran 
+Checks if a Fortran compiler can be found.
-##                        and return required cmake args for building. 
+Windows(x86/x64) Only: If not it will switch/enable MinGW gfortran 
-##
+                       and return required cmake args for building. 
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_find_fortran(<additional_cmake_args_out>
+```cmake
-## )
+vcpkg_find_fortran(<additional_cmake_args_out>)
-## ```
+```
+#]===]
 
 function(vcpkg_find_fortran additional_cmake_args_out)
     set(ARGS_OUT)

scripts/cmake/vcpkg_fixup_cmake_targets.cmake

@@ -1,52 +1,55 @@
-## # vcpkg_fixup_cmake_targets
+#[===[.md:
-##
+# vcpkg_fixup_cmake_targets
-## Merge release and debug CMake targets and configs to support multiconfig generators.
+
-##
+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.
+
-##
+Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_fixup_cmake_targets([CONFIG_PATH <share/${PORT}>] [TARGET_PATH <share/${PORT}>] [DO_NOT_DELETE_PARENT_CONFIG_PATH])
+```cmake
-## ```
+vcpkg_fixup_cmake_targets([CONFIG_PATH <share/${PORT}>] [TARGET_PATH <share/${PORT}>] [DO_NOT_DELETE_PARENT_CONFIG_PATH])
-##
+```
-## ## Parameters
+
-##
+## Parameters
-## ### CONFIG_PATH
+
-## Subpath currently containing `*.cmake` files subdirectory (like `lib/cmake/${PORT}`). Should be relative to `${CURRENT_PACKAGES_DIR}`.
+### CONFIG_PATH
-##
+Subpath currently containing `*.cmake` files subdirectory (like `lib/cmake/${PORT}`). Should be relative to `${CURRENT_PACKAGES_DIR}`.
-## Defaults to `share/${PORT}`.
+
-##
+Defaults to `share/${PORT}`.
-## ### TARGET_PATH
+
-## Subpath to which the above `*.cmake` files should be moved. Should be relative to `${CURRENT_PACKAGES_DIR}`.
+### TARGET_PATH
-## This needs to be specified if the port name differs from the `find_package()` name.
+Subpath to which the above `*.cmake` files should be moved. Should be relative to `${CURRENT_PACKAGES_DIR}`.
-##
+This needs to be specified if the port name differs from the `find_package()` name.
-## Defaults to `share/${PORT}`.
+
-##
+Defaults to `share/${PORT}`.
-## ### DO_NOT_DELETE_PARENT_CONFIG_PATH 
+
-## By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
+### DO_NOT_DELETE_PARENT_CONFIG_PATH 
-## Passing this option disable such behavior, as it is convenient for ports that install
+By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
-## more than one CMake package configuration file.
+Passing this option disable such behavior, as it is convenient for ports that install
-##
+more than one CMake package configuration file.
-## ### NO_PREFIX_CORRECTION 
+
-## Disables the correction of_IMPORT_PREFIX done by vcpkg due to moving the targets. 
+### NO_PREFIX_CORRECTION
-## Currently the correction does not take into account how the files are moved and applies
+Disables the correction of_IMPORT_PREFIX done by vcpkg due to moving the targets.
-## I rather simply correction which in some cases will yield the wrong results.
+Currently the correction does not take into account how the files are moved and applies
-##
+I rather simply correction which in some cases will yield the wrong results.
-## ## Notes
+
-## Transform all `/debug/<CONFIG_PATH>/*targets-debug.cmake` files and move them to `/<TARGET_PATH>`.
+## Notes
-## Removes all `/debug/<CONFIG_PATH>/*targets.cmake` and `/debug/<CONFIG_PATH>/*config.cmake`.
+Transform all `/debug/<CONFIG_PATH>/*targets-debug.cmake` files and move them to `/<TARGET_PATH>`.
-##
+Removes all `/debug/<CONFIG_PATH>/*targets.cmake` and `/debug/<CONFIG_PATH>/*config.cmake`.
-## Transform all references matching `/bin/*.exe` to `/tools/<port>/*.exe` on Windows.
+
-## Transform all references matching `/bin/*` to `/tools/<port>/*` on other platforms.
+Transform all references matching `/bin/*.exe` to `/tools/<port>/*.exe` on Windows.
-##
+Transform all references matching `/bin/*` to `/tools/<port>/*` on other platforms.
-## Fix `${_IMPORT_PREFIX}` in auto generated targets to be one folder deeper.
+
-## Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targets.
+Fix `${_IMPORT_PREFIX}` in auto generated targets to be one folder deeper.
-##
+Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targets.
-## ## Examples
+
-##
+## 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)
+* [concurrentqueue](https://github.com/Microsoft/vcpkg/blob/master/ports/concurrentqueue/portfile.cmake)
-## * [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/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)
+#]===]
+
 function(vcpkg_fixup_cmake_targets)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
     cmake_parse_arguments(PARSE_ARGV 0 _vfct "DO_NOT_DELETE_PARENT_CONFIG_PATH" "CONFIG_PATH;TARGET_PATH;NO_PREFIX_CORRECTION" "")

scripts/cmake/vcpkg_fixup_pkgconfig.cmake

@@ -1,44 +1,46 @@
-## # vcpkg_fixup_pkgconfig
+#[===[.md:
-##
+# vcpkg_fixup_pkgconfig
-## Fix common paths in *.pc files and make everything relativ to $(prefix)
-##
-## ## Usage
-## ```cmake
-## vcpkg_fixup_pkgconfig(
-##     [RELEASE_FILES <PATHS>...]
-##     [DEBUG_FILES <PATHS>...]
-##     [SYSTEM_LIBRARIES <NAMES>...]
-##     [IGNORE_FLAGS <FLAGS>]
-##     [SKIP_CHECK]
-## )
-## ```
-##
-## ## Parameters
-## ### RELEASE_FILES
-## Specifies a list of files to apply the fixes for release paths.
-## Defaults to every *.pc file in the folder ${CURRENT_PACKAGES_DIR} without ${CURRENT_PACKAGES_DIR}/debug/
-##
-## ### DEBUG_FILES
-## Specifies a list of files to apply the fixes for debug paths.
-## Defaults to every *.pc file in the folder ${CURRENT_PACKAGES_DIR}/debug/
-##
-## ### SYSTEM_LIBRARIES
-## If the *.pc file contains system libraries outside vcpkg these need to be listed here.
-## VCPKG checks every -l flag for the existence of the required library within vcpkg.
-##
-## ### IGNORE_FLAGS
-## If the *.pc file contains flags in the lib field which are not libraries. These can be listed here
-##
-## ### SKIP_CHECK
-## Skips the library checks in vcpkg_fixup_pkgconfig. Only use if the script itself has unhandled cases. 
-##
-## ## Notes
-## Still work in progress. If there are more cases which can be handled here feel free to add them
-##
-## ## Examples
-## Just call vcpkg_fixup_pkgconfig() after any install step which installs *.pc files.
 
-include(vcpkg_escape_regex_control_characters)
+Fix common paths in *.pc files and make everything relativ to $(prefix)
+
+## Usage
+```cmake
+vcpkg_fixup_pkgconfig(
+    [RELEASE_FILES <PATHS>...]
+    [DEBUG_FILES <PATHS>...]
+    [SYSTEM_LIBRARIES <NAMES>...]
+    [IGNORE_FLAGS <FLAGS>]
+    [SKIP_CHECK]
+)
+```
+
+## Parameters
+### RELEASE_FILES
+Specifies a list of files to apply the fixes for release paths.
+Defaults to every *.pc file in the folder ${CURRENT_PACKAGES_DIR} without ${CURRENT_PACKAGES_DIR}/debug/
+
+### DEBUG_FILES
+Specifies a list of files to apply the fixes for debug paths.
+Defaults to every *.pc file in the folder ${CURRENT_PACKAGES_DIR}/debug/
+
+### SYSTEM_LIBRARIES
+If the *.pc file contains system libraries outside vcpkg these need to be listed here.
+VCPKG checks every -l flag for the existence of the required library within vcpkg.
+
+### IGNORE_FLAGS
+If the *.pc file contains flags in the lib field which are not libraries. These can be listed here
+
+### SKIP_CHECK
+Skips the library checks in vcpkg_fixup_pkgconfig. Only use if the script itself has unhandled cases. 
+
+## Notes
+Still work in progress. If there are more cases which can be handled here feel free to add them
+
+## Examples
+Just call `vcpkg_fixup_pkgconfig()` after any install step which installs *.pc files.
+#]===]
+
+include(vcpkg_internal_escape_regex_control_characters)
 function(vcpkg_fixup_pkgconfig_check_files pkg_cfg_cmd _file _config _system_libs _ignore_flags)
     # Setup pkg-config paths
     set(_VCPKG_INSTALLED_PKGCONF "${CURRENT_INSTALLED_DIR}")
@@ -136,7 +138,7 @@ function(vcpkg_fixup_pkgconfig_check_files pkg_cfg_cmd _file _config _system_lib
     foreach(_search_path IN LISTS _pkg_lib_paths_output)
         debug_message("REMOVING:'${_search_path}'")
         debug_message("FROM:'${_pkg_libs_output}'")
-        vcpkg_escape_regex_control_characters(_search_path "${_search_path}")
+        vcpkg_internal_escape_regex_control_characters(_search_path "${_search_path}")
         string(REGEX REPLACE "(^[\t ]*|[\t ]+|;[\t ]*)-L${_search_path}([\t ]+|[\t ]*$)" ";" _pkg_libs_output "${_pkg_libs_output}") # Remove search paths from libs
     endforeach()
     debug_message("LIBS AFTER -L<path> REMOVAL:'${_pkg_libs_output}'")
@@ -169,7 +171,7 @@ function(vcpkg_fixup_pkgconfig_check_files pkg_cfg_cmd _file _config _system_lib
     debug_message("BEFORE IGNORE FLAGS REMOVAL: ${_pkg_libs_output}")
     foreach(_ignore IN LISTS _ignore_flags)  # Remove ignore with whitespace
         debug_message("REMOVING FLAG:'${_ignore}'")
-        vcpkg_escape_regex_control_characters(_ignore "${_ignore}")
+        vcpkg_internal_escape_regex_control_characters(_ignore "${_ignore}")
         string(REGEX REPLACE "(^[\t ]*|;[\t ]*|[\t ]+)${_ignore}([\t ]+|[\t ]*;|[\t ]*$)" "\\2" _pkg_libs_output "${_pkg_libs_output}")
         debug_message("AFTER REMOVAL: ${_pkg_libs_output}")
     endforeach()
@@ -259,7 +261,7 @@ function(vcpkg_fixup_pkgconfig)
         message(FATAL_ERROR "vcpkg_fixup_pkgconfig was passed extra arguments: ${_vfct_UNPARSED_ARGUMENTS}")
     endif()
 
-    vcpkg_escape_regex_control_characters(_vfpkg_ESCAPED_CURRENT_PACKAGES_DIR "${CURRENT_PACKAGES_DIR}")
+    vcpkg_internal_escape_regex_control_characters(_vfpkg_ESCAPED_CURRENT_PACKAGES_DIR "${CURRENT_PACKAGES_DIR}")
     if(NOT _vfpkg_RELEASE_FILES)
         file(GLOB_RECURSE _vfpkg_RELEASE_FILES "${CURRENT_PACKAGES_DIR}/**/*.pc")
         list(FILTER _vfpkg_RELEASE_FILES EXCLUDE REGEX "${_vfpkg_ESCAPED_CURRENT_PACKAGES_DIR}/debug/")

scripts/cmake/vcpkg_from_bitbucket.cmake

@@ -1,59 +1,62 @@
-## # vcpkg_from_bitbucket
+#[===[.md:
-##
+# vcpkg_from_bitbucket
-## Download and extract a project from Bitbucket.
+
-## Enables support for installing HEAD `vcpkg.exe install --head <port>`.
+Download and extract a project from Bitbucket.
-##
+Enables support for installing HEAD `vcpkg.exe install --head <port>`.
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_from_bitbucket(
+```cmake
-##     OUT_SOURCE_PATH <SOURCE_PATH>
+vcpkg_from_bitbucket(
-##     REPO <Microsoft/cpprestsdk>
+    OUT_SOURCE_PATH <SOURCE_PATH>
-##     [REF <v2.0.0>]
+    REPO <Microsoft/cpprestsdk>
-##     [SHA512 <45d0d7f8cc350...>]
+    [REF <v2.0.0>]
-##     [HEAD_REF <master>]
+    [SHA512 <45d0d7f8cc350...>]
-##     [PATCHES <patch1.patch> <patch2.patch>...]
+    [HEAD_REF <master>]
-## )
+    [PATCHES <patch1.patch> <patch2.patch>...]
-## ```
+)
-##
+```
-## ## Parameters:
+
-## ### OUT_SOURCE_PATH
+## Parameters:
-## Specifies the out-variable that will contain the extracted location.
+### OUT_SOURCE_PATH
-##
+Specifies the out-variable that will contain the extracted location.
-## This should be set to `SOURCE_PATH` by convention.
+
-##
+This should be set to `SOURCE_PATH` by convention.
-## ### REPO
+
-## The organization or user and repository on GitHub.
+### REPO
-##
+The organization or user and repository on GitHub.
-## ### REF
+
-## A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**
+### REF
-##
+A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**
-## For repositories without official releases, this can be set to the full commit id of the current latest master.
+
-##
+For repositories without official releases, this can be set to the full commit id of the current latest master.
-## If `REF` is specified, `SHA512` must also be specified.
+
-##
+If `REF` is specified, `SHA512` must also be specified.
-## ### SHA512
+
-## The SHA512 hash that should match the archive (https://bitbucket.com/${REPO}/get/${REF}.tar.gz).
+### SHA512
-##
+The SHA512 hash that should match the archive (https://bitbucket.com/${REPO}/get/${REF}.tar.gz).
-## This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
+
-##
+This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
-## ### HEAD_REF
+
-## The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
+### HEAD_REF
-##
+The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
-## For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
+
-##
+For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
-## ### PATCHES
+
-## A list of patches to be applied to the extracted sources.
+### PATCHES
-##
+A list of patches to be applied to the extracted sources.
-## Relative paths are based on the port directory.
+
-##
+Relative paths are based on the port directory.
-## ## Notes:
+
-## At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
+## Notes:
-##
+At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
-## This exports the `VCPKG_HEAD_VERSION` variable during head builds.
+
-##
+This exports the `VCPKG_HEAD_VERSION` variable during head builds.
-## ## Examples:
+
-##
+## Examples:
-## * [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake)
+
+* [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake)
+#]===]
+
 function(vcpkg_from_bitbucket)
     set(oneValueArgs OUT_SOURCE_PATH REPO REF SHA512 HEAD_REF)
     set(multipleValuesArgs PATCHES)

scripts/cmake/vcpkg_from_git.cmake

@@ -1,40 +1,42 @@
-## # vcpkg_from_git
+#[===[.md:
-##
+# vcpkg_from_git
-## Download and extract a project from git
+
-##
+Download and extract a project from git
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_from_git(
+```cmake
-##     OUT_SOURCE_PATH <SOURCE_PATH>
+vcpkg_from_git(
-##     URL <https://android.googlesource.com/platform/external/fdlibm>
+    OUT_SOURCE_PATH <SOURCE_PATH>
-##     REF <59f7335e4d...>
+    URL <https://android.googlesource.com/platform/external/fdlibm>
-##     [PATCHES <patch1.patch> <patch2.patch>...]
+    REF <59f7335e4d...>
-## )
+    [PATCHES <patch1.patch> <patch2.patch>...]
-## ```
+)
-##
+```
-## ## Parameters:
+
-## ### OUT_SOURCE_PATH
+## Parameters:
-## Specifies the out-variable that will contain the extracted location.
+### OUT_SOURCE_PATH
-##
+Specifies the out-variable that will contain the extracted location.
-## This should be set to `SOURCE_PATH` by convention.
+
-##
+This should be set to `SOURCE_PATH` by convention.
-## ### URL
+
-## The url of the git repository.
+### URL
-##
+The url of the git repository.
-## ### REF
+
-## The git sha of the commit to download.
+### REF
-##
+The git sha of the commit to download.
-## ### PATCHES
+
-## A list of patches to be applied to the extracted sources.
+### PATCHES
-##
+A list of patches to be applied to the extracted sources.
-## Relative paths are based on the port directory.
+
-##
+Relative paths are based on the port directory.
-## ## Notes:
+
-## `OUT_SOURCE_PATH`, `REF`, and `URL` must be specified.
+## Notes:
-##
+`OUT_SOURCE_PATH`, `REF`, and `URL` must be specified.
-## ## Examples:
+
-##
+## Examples:
-## * [fdlibm](https://github.com/Microsoft/vcpkg/blob/master/ports/fdlibm/portfile.cmake)
+
+* [fdlibm](https://github.com/Microsoft/vcpkg/blob/master/ports/fdlibm/portfile.cmake)
+#]===]
 
 include(vcpkg_execute_in_download_mode)
 

scripts/cmake/vcpkg_from_github.cmake

@@ -1,73 +1,76 @@
-## # vcpkg_from_github
+#[===[.md:
-##
+# vcpkg_from_github
-## Download and extract a project from GitHub. Enables support for `install --head`.
+
-##
+Download and extract a project from GitHub. Enables support for `install --head`.
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_from_github(
+```cmake
-##     OUT_SOURCE_PATH <SOURCE_PATH>
+vcpkg_from_github(
-##     REPO <Microsoft/cpprestsdk>
+    OUT_SOURCE_PATH <SOURCE_PATH>
-##     [REF <v2.0.0>]
+    REPO <Microsoft/cpprestsdk>
-##     [SHA512 <45d0d7f8cc350...>]
+    [REF <v2.0.0>]
-##     [HEAD_REF <master>]
+    [SHA512 <45d0d7f8cc350...>]
-##     [PATCHES <patch1.patch> <patch2.patch>...]
+    [HEAD_REF <master>]
-##     [GITHUB_HOST <https://github.com>]
+    [PATCHES <patch1.patch> <patch2.patch>...]
-##     [AUTHORIZATION_TOKEN <${SECRET_FROM_FILE}>]
+    [GITHUB_HOST <https://github.com>]
-## )
+    [AUTHORIZATION_TOKEN <${SECRET_FROM_FILE}>]
-## ```
+)
-##
+```
-## ## Parameters:
+
-## ### OUT_SOURCE_PATH
+## Parameters:
-## Specifies the out-variable that will contain the extracted location.
+### OUT_SOURCE_PATH
-##
+Specifies the out-variable that will contain the extracted location.
-## This should be set to `SOURCE_PATH` by convention.
+
-##
+This should be set to `SOURCE_PATH` by convention.
-## ### REPO
+
-## The organization or user and repository on GitHub.
+### REPO
-##
+The organization or user and repository on GitHub.
-## ### REF
+
-## A stable git commit-ish (ideally a tag or commit) that will not change contents. **This should not be a branch.**
+### REF
-##
+A stable git commit-ish (ideally a tag or commit) that will not change contents. **This should not be a branch.**
-## For repositories without official releases, this can be set to the full commit id of the current latest master.
+
-##
+For repositories without official releases, this can be set to the full commit id of the current latest master.
-## If `REF` is specified, `SHA512` must also be specified.
+
-##
+If `REF` is specified, `SHA512` must also be specified.
-## ### SHA512
+
-## The SHA512 hash that should match the archive (https://github.com/${REPO}/archive/${REF}.tar.gz).
+### SHA512
-##
+The SHA512 hash that should match the archive (https://github.com/${REPO}/archive/${REF}.tar.gz).
-## This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
+
-##
+This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
-## ### HEAD_REF
+
-## The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
+### HEAD_REF
-##
+The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
-## For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
+
-##
+For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
-## ### PATCHES
+
-## A list of patches to be applied to the extracted sources.
+### PATCHES
-##
+A list of patches to be applied to the extracted sources.
-## Relative paths are based on the port directory.
+
-##
+Relative paths are based on the port directory.
-## ### GITHUB_HOST
+
-## A replacement host for enterprise GitHub instances.
+### GITHUB_HOST
-##
+A replacement host for enterprise GitHub instances.
-## This field should contain the scheme, host, and port of the desired URL without a trailing slash.
+
-##
+This field should contain the scheme, host, and port of the desired URL without a trailing slash.
-## ### AUTHORIZATION_TOKEN
+
-## A token to be passed via the Authorization HTTP header as "token ${AUTHORIZATION_TOKEN}".
+### AUTHORIZATION_TOKEN
-##
+A token to be passed via the Authorization HTTP header as "token ${AUTHORIZATION_TOKEN}".
-## ### FILE_DISAMBIGUATOR
+
-## A token to uniquely identify the resulting filename if the SHA512 changes even though a git ref does not, to avoid stepping on the same file name.
+### FILE_DISAMBIGUATOR
-##
+A token to uniquely identify the resulting filename if the SHA512 changes even though a git ref does not, to avoid stepping on the same file name.
-## ## Notes:
+
-## At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
+## Notes:
-##
+At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
-## This exports the `VCPKG_HEAD_VERSION` variable during head builds.
+
-##
+This exports the `VCPKG_HEAD_VERSION` variable during head builds.
-## ## Examples:
+
-##
+## Examples:
-## * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+
-## * [ms-gsl](https://github.com/Microsoft/vcpkg/blob/master/ports/ms-gsl/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
-## * [beast](https://github.com/Microsoft/vcpkg/blob/master/ports/beast/portfile.cmake)
+* [ms-gsl](https://github.com/Microsoft/vcpkg/blob/master/ports/ms-gsl/portfile.cmake)
+* [beast](https://github.com/Microsoft/vcpkg/blob/master/ports/beast/portfile.cmake)
+#]===]
+
 function(vcpkg_from_github)
     set(oneValueArgs OUT_SOURCE_PATH REPO REF SHA512 HEAD_REF GITHUB_HOST AUTHORIZATION_TOKEN FILE_DISAMBIGUATOR)
     set(multipleValuesArgs PATCHES)

scripts/cmake/vcpkg_from_gitlab.cmake

@@ -1,66 +1,67 @@
-## # vcpkg_from_gitlab
+#[===[.md:
-##
+# vcpkg_from_gitlab
-## Download and extract a project from Gitlab instances. Enables support for `install --head`.
+
-##
+Download and extract a project from Gitlab instances. Enables support for `install --head`.
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_from_gitlab(
+```cmake
-##     GITLAB_URL <https://gitlab.com>
+vcpkg_from_gitlab(
-##     OUT_SOURCE_PATH <SOURCE_PATH>
+    GITLAB_URL <https://gitlab.com>
-##     REPO <gitlab-org/gitlab-ce>
+    OUT_SOURCE_PATH <SOURCE_PATH>
-##     [REF <v10.7.3>]
+    REPO <gitlab-org/gitlab-ce>
-##     [SHA512 <45d0d7f8cc350...>]
+    [REF <v10.7.3>]
-##     [HEAD_REF <master>]
+    [SHA512 <45d0d7f8cc350...>]
-##     [PATCHES <patch1.patch> <patch2.patch>...]
+    [HEAD_REF <master>]
-## )
+    [PATCHES <patch1.patch> <patch2.patch>...]
-## ```
+)
-##
+```
-## ## Parameters:
+
-##
+## Parameters:
-## ### GITLAB_URL
+
-## The URL of the Gitlab instance to use.
+### GITLAB_URL
-##
+The URL of the Gitlab instance to use.
-## ### OUT_SOURCE_PATH
+
-## Specifies the out-variable that will contain the extracted location.
+### OUT_SOURCE_PATH
-##
+Specifies the out-variable that will contain the extracted location.
-## This should be set to `SOURCE_PATH` by convention.
+
-##
+This should be set to `SOURCE_PATH` by convention.
-## ### REPO
+
-## The organization or user plus the repository name on the Gitlab instance.
+### REPO
-##
+The organization or user plus the repository name on the Gitlab instance.
-## ### REF
+
-## A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**
+### REF
-##
+A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**
-## For repositories without official releases, this can be set to the full commit id of the current latest master.
+
-##
+For repositories without official releases, this can be set to the full commit id of the current latest master.
-## If `REF` is specified, `SHA512` must also be specified.
+
-##
+If `REF` is specified, `SHA512` must also be specified.
-## ### SHA512
+
-## The SHA512 hash that should match the archive (${GITLAB_URL}/${REPO}/-/archive/${REF}/${REPO_NAME}-${REF}.tar.gz).
+### SHA512
-## The REPO_NAME variable is parsed from the value of REPO.
+The SHA512 hash that should match the archive (${GITLAB_URL}/${REPO}/-/archive/${REF}/${REPO_NAME}-${REF}.tar.gz).
-##
+The REPO_NAME variable is parsed from the value of REPO.
-## This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
+
-##
+This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
-## ### HEAD_REF
+
-## The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
+### HEAD_REF
-##
+The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
-## For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
+
-##
+For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
-## ### PATCHES
+
-## A list of patches to be applied to the extracted sources.
+### PATCHES
-##
+A list of patches to be applied to the extracted sources.
-## Relative paths are based on the port directory.
+
-##
+Relative paths are based on the port directory.
-## ## Notes:
+
-## At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
+## Notes:
-##
+At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
-## This exports the `VCPKG_HEAD_VERSION` variable during head builds.
+
-##
+This exports the `VCPKG_HEAD_VERSION` variable during head builds.
-## ## Examples:
+
-## * [curl][https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75]
+## Examples:
-## * [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
+* [curl][https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75]
-## * [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
+* [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)
+#]===]
 
 include(vcpkg_execute_in_download_mode)
 

scripts/cmake/vcpkg_from_sourceforge.cmake

@@ -1,68 +1,70 @@
-## # vcpkg_from_sourceforge
+#[===[.md:
-##
+# vcpkg_from_sourceforge
-## Download and extract a project from sourceforge.
+
-##
+Download and extract a project from sourceforge.
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_from_sourceforge(
+```cmake
-##     OUT_SOURCE_PATH SOURCE_PATH
+vcpkg_from_sourceforge(
-##     REPO <cunit/CUnit>
+    OUT_SOURCE_PATH SOURCE_PATH
-##     [REF <2.1-3>]
+    REPO <cunit/CUnit>
-##     SHA512 <547b417109332...>
+    [REF <2.1-3>]
-##     FILENAME <CUnit-2.1-3.tar.bz2>
+    SHA512 <547b417109332...>
-##     [DISABLE_SSL]
+    FILENAME <CUnit-2.1-3.tar.bz2>
-##     [NO_REMOVE_ONE_LEVEL]
+    [DISABLE_SSL]
-##     [PATCHES <patch1.patch> <patch2.patch>...]
+    [NO_REMOVE_ONE_LEVEL]
-## )
+    [PATCHES <patch1.patch> <patch2.patch>...]
-## ```
+)
-##
+```
-## ## Parameters:
+
-## ### OUT_SOURCE_PATH
+## Parameters:
-## Specifies the out-variable that will contain the extracted location.
+### OUT_SOURCE_PATH
-##
+Specifies the out-variable that will contain the extracted location.
-## This should be set to `SOURCE_PATH` by convention.
+
-##
+This should be set to `SOURCE_PATH` by convention.
-## ### REPO
+
-## The organization or user and repository (optional) on sourceforge.
+### REPO
-##
+The organization or user and repository (optional) on sourceforge.
-## ### REF
+
-## A stable version number that will not change contents.
+### REF
-##
+A stable version number that will not change contents.
-## ### FILENAME
+
-## The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.
+### FILENAME
-##
+The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.
-## For example, we can get the download link:
+
-## https://sourceforge.net/settings/mirror_choices?projectname=mad&filename=libmad/0.15.1b/libmad-0.15.1b.tar.gz&selected=nchc
+For example, we can get the download link:
-## So the REPO is `mad/libmad`, the REF is `0.15.1b`, and the FILENAME is `libmad-0.15.1b.tar.gz`
+https://sourceforge.net/settings/mirror_choices?projectname=mad&filename=libmad/0.15.1b/libmad-0.15.1b.tar.gz&selected=nchc
-##
+So the REPO is `mad/libmad`, the REF is `0.15.1b`, and the FILENAME is `libmad-0.15.1b.tar.gz`
-## For some special links:
+
-## https://sourceforge.net/settings/mirror_choices?projectname=soxr&filename=soxr-0.1.3-Source.tar.xz&selected=nchc
+For some special links:
-## The REPO is `soxr`, REF is not exist, and the FILENAME is `soxr-0.1.3-Source.tar.xz`
+https://sourceforge.net/settings/mirror_choices?projectname=soxr&filename=soxr-0.1.3-Source.tar.xz&selected=nchc
-##
+The REPO is `soxr`, REF is not exist, and the FILENAME is `soxr-0.1.3-Source.tar.xz`
-## ### SHA512
+
-## The SHA512 hash that should match the archive.
+### SHA512
-##
+The SHA512 hash that should match the archive.
-## ### WORKING_DIRECTORY
+
-## If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`.
+### WORKING_DIRECTORY
-##
+If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`.
-## Note that the archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`).
+
-##
+Note that the archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`).
-## ### PATCHES
+
-## A list of patches to be applied to the extracted sources.
+### PATCHES
-##
+A list of patches to be applied to the extracted sources.
-## Relative paths are based on the port directory.
+
-##
+Relative paths are based on the port directory.
-## ### DISABLE_SSL
+
-## Disable ssl when downloading source.
+### DISABLE_SSL
-##
+Disable ssl when downloading source.
-## ### NO_REMOVE_ONE_LEVEL
+
-## Specifies that the default removal of the top level folder should not occur.
+### NO_REMOVE_ONE_LEVEL
-##
+Specifies that the default removal of the top level folder should not occur.
-## ## Examples:
+
-##
+## Examples:
-## * [cunit](https://github.com/Microsoft/vcpkg/blob/master/ports/cunit/portfile.cmake)
+
-## * [polyclipping](https://github.com/Microsoft/vcpkg/blob/master/ports/polyclipping/portfile.cmake)
+* [cunit](https://github.com/Microsoft/vcpkg/blob/master/ports/cunit/portfile.cmake)
-## * [tinyfiledialogs](https://github.com/Microsoft/vcpkg/blob/master/ports/tinyfiledialogs/portfile.cmake)
+* [polyclipping](https://github.com/Microsoft/vcpkg/blob/master/ports/polyclipping/portfile.cmake)
+* [tinyfiledialogs](https://github.com/Microsoft/vcpkg/blob/master/ports/tinyfiledialogs/portfile.cmake)
+#]===]
 
 function(vcpkg_from_sourceforge)
     macro(check_file_content)

scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake

@@ -1,3 +1,16 @@
+#[===[.md:
+# vcpkg_get_program_files_platform_bitness
+
+Get the Program Files directory of the current platform's bitness:
+either `$ENV{ProgramW6432}` on 64-bit windows,
+or `$ENV{PROGRAMFILES}` on 32-bit windows.
+
+## Usage:
+```cmake
+vcpkg_get_program_files_platform_bitness(<variable>)
+```
+#]===]
+
 function(vcpkg_get_program_files_platform_bitness ret)
 
     set(ret_temp $ENV{ProgramW6432})
@@ -7,4 +20,4 @@ function(vcpkg_get_program_files_platform_bitness ret)
 
     set(${ret} ${ret_temp} PARENT_SCOPE)
 
-endfunction()
+endfunction()

scripts/cmake/vcpkg_get_windows_sdk.cmake

@@ -1,6 +1,16 @@
-# Returns Windows SDK number via out variable "ret"
+#[===[.md:
+# vcpkg_get_windows_sdk
+
+Get the Windows SDK number.
+
+## Usage:
+```cmake
+vcpkg_get_windows_sdk(<variable>)
+```
+#]===]
+
 function(vcpkg_get_windows_sdk ret)
     set(WINDOWS_SDK $ENV{WindowsSDKVersion})
     string(REPLACE "\\" "" WINDOWS_SDK "${WINDOWS_SDK}")
     set(${ret} ${WINDOWS_SDK} PARENT_SCOPE)
-endfunction()
+endfunction()

scripts/cmake/vcpkg_install_cmake.cmake

@@ -1,25 +1,28 @@
-## # vcpkg_install_cmake
+#[===[.md:
-##
+# vcpkg_install_cmake
-## Build and install a cmake project.
+
-##
+Build and install a cmake project.
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_install_cmake(...)
+```cmake
-## ```
+vcpkg_install_cmake(...)
-##
+```
-## ## Parameters:
+
-## See [`vcpkg_build_cmake()`](vcpkg_build_cmake.md).
+## Parameters:
-##
+See [`vcpkg_build_cmake()`](vcpkg_build_cmake.md).
-## ## Notes:
+
-## This command transparently forwards to [`vcpkg_build_cmake()`](vcpkg_build_cmake.md), adding a `TARGET install`
+## Notes:
-## parameter.
+This command transparently forwards to [`vcpkg_build_cmake()`](vcpkg_build_cmake.md), adding a `TARGET install`
-##
+parameter.
-## ## Examples:
+
-##
+## 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)
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
-## * [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
-## * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/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)
+#]===]
+
 function(vcpkg_install_cmake)
     vcpkg_build_cmake(LOGFILE_ROOT install TARGET install ${ARGN})
 endfunction()

scripts/cmake/vcpkg_install_gn.cmake

@@ -1,23 +1,25 @@
-## # vcpkg_install_gn
+#[===[.md:
-##
+# vcpkg_install_gn
-## Installs a GN project
+
-##
+Installs a GN project
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_install_gn(
+```cmake
-##      SOURCE_PATH <SOURCE_PATH>
+vcpkg_install_gn(
-##      [TARGETS <target>...]
+     SOURCE_PATH <SOURCE_PATH>
-## )
+     [TARGETS <target>...]
-## ```
+)
-##
+```
-## ## Parameters:
+
-## ### SOURCE_PATH
+## Parameters:
-## The path to the source directory
+### SOURCE_PATH
-## 
+The path to the source directory
-## ### TARGETS
+
-## Only install the specified targets.
+### TARGETS
-##
+Only install the specified targets.
-## Note: includes must be handled separately
+
+Note: includes must be handled separately
+#]===]
 
 function(vcpkg_install_gn)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased
@@ -95,4 +97,4 @@ function(vcpkg_install_gn)
         install_("${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel" "${CURRENT_PACKAGES_DIR}")
     endif()
 
-endfunction()
+endfunction()

scripts/cmake/vcpkg_install_make.cmake

@@ -1,24 +1,26 @@
-## # vcpkg_install_make
+#[===[.md:
-##
+# vcpkg_install_make
-## Build and install a make project.
+
-##
+Build and install a make project.
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_install_make(...)
+```cmake
-## ```
+vcpkg_install_make(...)
-##
+```
-## ## Parameters:
+
-## See [`vcpkg_build_make()`](vcpkg_build_make.md).
+## Parameters:
-##
+See [`vcpkg_build_make()`](vcpkg_build_make.md).
-## ## Notes:
+
-## This command transparently forwards to [`vcpkg_build_make()`](vcpkg_build_make.md), adding `ENABLE_INSTALL`
+## Notes:
-##
+This command transparently forwards to [`vcpkg_build_make()`](vcpkg_build_make.md), adding `ENABLE_INSTALL`
-## ## Examples
+
-##
+## 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)
+* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake)
-## * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
+* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
-## * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/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)
+#]===]
 
 function(vcpkg_install_make)
     vcpkg_build_make(${ARGN} LOGFILE_ROOT ENABLE_INSTALL)

scripts/cmake/vcpkg_install_meson.cmake

@@ -1,16 +1,19 @@
-## # vcpkg_install_meson
+#[===[.md:
-##
+# vcpkg_install_meson
-## Builds a meson project previously configured with `vcpkg_configure_meson()`.
+
-##
+Builds a meson project previously configured with `vcpkg_configure_meson()`.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_install_meson()
+```cmake
-## ```
+vcpkg_install_meson()
-##
+```
-## ## Examples
+
-##
+## Examples
-## * [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake)
+
-## * [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
+* [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake)
+* [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
+#]===]
+
 function(vcpkg_install_meson)
     vcpkg_find_acquire_program(NINJA)
     unset(ENV{DESTDIR}) # installation directory was already specified with '--prefix' option

scripts/cmake/vcpkg_install_msbuild.cmake

@@ -1,93 +1,95 @@
-## # vcpkg_install_msbuild
+#[===[.md:
-##
+# vcpkg_install_msbuild
-## Build and install a msbuild-based project. This replaces `vcpkg_build_msbuild()`.
+
-##
+Build and install a msbuild-based project. This replaces `vcpkg_build_msbuild()`.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_install_msbuild(
+```cmake
-##     SOURCE_PATH <${SOURCE_PATH}>
+vcpkg_install_msbuild(
-##     PROJECT_SUBPATH <port.sln>
+    SOURCE_PATH <${SOURCE_PATH}>
-##     [INCLUDES_SUBPATH <include>]
+    PROJECT_SUBPATH <port.sln>
-##     [LICENSE_SUBPATH <LICENSE>]
+    [INCLUDES_SUBPATH <include>]
-##     [RELEASE_CONFIGURATION <Release>]
+    [LICENSE_SUBPATH <LICENSE>]
-##     [DEBUG_CONFIGURATION <Debug>]
+    [RELEASE_CONFIGURATION <Release>]
-##     [TARGET <Build>]
+    [DEBUG_CONFIGURATION <Debug>]
-##     [TARGET_PLATFORM_VERSION <10.0.15063.0>]
+    [TARGET <Build>]
-##     [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
+    [TARGET_PLATFORM_VERSION <10.0.15063.0>]
-##     [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
+    [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
-##     [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
+    [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
-##     [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
+    [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
-##     [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
+    [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
-##     [USE_VCPKG_INTEGRATION]
+    [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
-##     [ALLOW_ROOT_INCLUDES | REMOVE_ROOT_INCLUDES]
+    [USE_VCPKG_INTEGRATION]
-## )
+    [ALLOW_ROOT_INCLUDES | REMOVE_ROOT_INCLUDES]
-## ```
+)
-##
+```
-## ## Parameters
+
-## ### SOURCE_PATH
+## Parameters
-## The path to the root of the source tree.
+### SOURCE_PATH
-##
+The path to the root of the source tree.
-## Because MSBuild uses in-source builds, the source tree will be copied into a temporary location for the build. This
+
-## parameter is the base for that copy and forms the base for all XYZ_SUBPATH options.
+Because MSBuild uses in-source builds, the source tree will be copied into a temporary location for the build. This
-##
+parameter is the base for that copy and forms the base for all XYZ_SUBPATH options.
-## ### USE_VCPKG_INTEGRATION
+
-## Apply the normal `integrate install` integration for building the project.
+### 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.
+
-##
+By default, projects built with this command will not automatically link libraries or have header paths set.
-## ### PROJECT_SUBPATH
+
-## The subpath to the solution (`.sln`) or project (`.vcxproj`) file relative to `SOURCE_PATH`.
+### PROJECT_SUBPATH
-##
+The subpath to the solution (`.sln`) or project (`.vcxproj`) file relative to `SOURCE_PATH`.
-## ### LICENSE_SUBPATH
+
-## The subpath to the license file relative to `SOURCE_PATH`.
+### LICENSE_SUBPATH
-##
+The subpath to the license file relative to `SOURCE_PATH`.
-## ### INCLUDES_SUBPATH
+
-## The subpath to the includes directory relative to `SOURCE_PATH`.
+### INCLUDES_SUBPATH
-##
+The subpath to the includes directory relative to `SOURCE_PATH`.
-## This parameter should be a directory and should not end in a trailing slash.
+
-##
+This parameter should be a directory and should not end in a trailing slash.
-## ### ALLOW_ROOT_INCLUDES
+
-## Indicates that top-level include files (e.g. `include/zlib.h`) should be allowed.
+### ALLOW_ROOT_INCLUDES
-##
+Indicates that top-level include files (e.g. `include/zlib.h`) should be allowed.
-## ### REMOVE_ROOT_INCLUDES
+
-## Indicates that top-level include files (e.g. `include/Makefile.am`) should be removed.
+### REMOVE_ROOT_INCLUDES
-##
+Indicates that top-level include files (e.g. `include/Makefile.am`) should be removed.
-## ### SKIP_CLEAN
+
-## Indicates that the intermediate files should not be removed.
+### SKIP_CLEAN
-##
+Indicates that the intermediate files should not be removed.
-## Ports using this option should later call [`vcpkg_clean_msbuild()`](vcpkg_clean_msbuild.md) to manually clean up.
+
-##
+Ports using this option should later call [`vcpkg_clean_msbuild()`](vcpkg_clean_msbuild.md) to manually clean up.
-## ### RELEASE_CONFIGURATION
+
-## The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
+### RELEASE_CONFIGURATION
-##
+The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
-## ### DEBUG_CONFIGURATION
+
-## The configuration (``/p:Configuration`` msbuild parameter) used for Debug builds.
+### DEBUG_CONFIGURATION
-##
+The configuration (``/p:Configuration`` msbuild parameter) used for Debug builds.
-## ### TARGET_PLATFORM_VERSION
+
-## The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
+### TARGET_PLATFORM_VERSION
-##
+The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
-## ### TARGET
+
-## The MSBuild target to build. (``/t:<TARGET>``)
+### TARGET
-##
+The MSBuild target to build. (``/t:<TARGET>``)
-## ### PLATFORM
+
-## The platform (``/p:Platform`` msbuild parameter) used for the build.
+### PLATFORM
-##
+The platform (``/p:Platform`` msbuild parameter) used for the build.
-## ### PLATFORM_TOOLSET
+
-## The platform toolset (``/p:PlatformToolset`` 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
-##
+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_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`.
+### OPTIONS_DEBUG
-##
+Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`.
-## ## Examples
+
-##
+## Examples
-## * [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
+
-## * [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
+* [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
+* [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
+#]===]
 
 include(vcpkg_clean_msbuild)
 

scripts/cmake/vcpkg_install_nmake.cmake

@@ -1,66 +1,68 @@
-## # vcpkg_install_nmake
+#[===[.md:
-##
+# vcpkg_install_nmake
-## Build and install a msvc makefile project.
+
-##
+Build and install a msvc makefile project.
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_install_nmake(
+```cmake
-##     SOURCE_PATH <${SOURCE_PATH}>
+vcpkg_install_nmake(
-##     [NO_DEBUG]
+    SOURCE_PATH <${SOURCE_PATH}>
-##     [TARGET <all>]
+    [NO_DEBUG]
-##     PROJECT_SUBPATH <${SUBPATH}>
+    [TARGET <all>]
-##     PROJECT_NAME <${MAKEFILE_NAME}>
+    PROJECT_SUBPATH <${SUBPATH}>
-##     [PRERUN_SHELL <${SHELL_PATH}>]
+    PROJECT_NAME <${MAKEFILE_NAME}>
-##     [PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
+    [PRERUN_SHELL <${SHELL_PATH}>]
-##     [PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
+    [PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    [PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
-##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-##     [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+    [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
-## ```
+    [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
-##
+```
-## ## Parameters
+
-## ### SOURCE_PATH
+## Parameters
-## Specifies the directory containing the source files.
+### SOURCE_PATH
-## By convention, this is usually set in the portfile as the variable `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_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.
+### PROJECT_NAME
-## Default is makefile.vc
+Specifies the name of msvc makefile name.
-##
+Default is makefile.vc
-## ### NO_DEBUG
+
-## This port doesn't support debug mode.
+### NO_DEBUG
-##
+This port doesn't support debug mode.
-## ### PRERUN_SHELL
+
-## Script that needs to be called before 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_DEBUG
-##
+Script that needs to be called before debug build
-## ### PRERUN_SHELL_RELEASE
+
-## Script that needs to be called before release build
+### PRERUN_SHELL_RELEASE
-##
+Script that needs to be called before release build
-## ### OPTIONS
+
-## Additional options passed to generate during the generation.
+### 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_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`.
+### OPTIONS_DEBUG
-##
+Additional options passed to generate during the Debug generation. These are in addition to `OPTIONS`.
-## ## Parameters:
+
-## See [`vcpkg_build_nmake()`](vcpkg_build_nmake.md).
+## Parameters:
-##
+See [`vcpkg_build_nmake()`](vcpkg_build_nmake.md).
-## ## Notes:
+
-## This command transparently forwards to [`vcpkg_build_nmake()`](vcpkg_build_nmake.md), adding `ENABLE_INSTALL`
+## Notes:
-##
+This command transparently forwards to [`vcpkg_build_nmake()`](vcpkg_build_nmake.md), adding `ENABLE_INSTALL`
-## ## Examples
+
-##
+## 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)
+* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
+* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
+#]===]
 
 function(vcpkg_install_nmake)
     # parse parameters such that semicolons in options arguments to COMMAND don't get erased

scripts/cmake/vcpkg_install_qmake.cmake

@@ -1,24 +1,26 @@
-## # vcpkg_install_qmake
+#[===[.md:
-##
+# vcpkg_install_qmake
-## Build and install a qmake project.
+
-##
+Build and install a qmake project.
-## ## Usage:
+
-## ```cmake
+## Usage:
-## vcpkg_install_qmake(...)
+```cmake
-## ```
+vcpkg_install_qmake(...)
-##
+```
-## ## Parameters:
+
-## See [`vcpkg_build_qmake()`](vcpkg_build_qmake.md).
+## Parameters:
-##
+See [`vcpkg_build_qmake()`](vcpkg_build_qmake.md).
-## ## Notes:
+
-## This command transparently forwards to [`vcpkg_build_qmake()`](vcpkg_build_qmake.md).
+## Notes:
-##
+This command transparently forwards to [`vcpkg_build_qmake()`](vcpkg_build_qmake.md).
-## Additionally, this command will copy produced .libs/.dlls/.as/.dylibs/.sos to the appropriate
+
-## staging directories.
+Additionally, this command will copy produced .libs/.dlls/.as/.dylibs/.sos to the appropriate
-##
+staging directories.
-## ## Examples
+
-##
+## Examples
-## * [libqglviewer](https://github.com/Microsoft/vcpkg/blob/master/ports/libqglviewer/portfile.cmake)
+
+* [libqglviewer](https://github.com/Microsoft/vcpkg/blob/master/ports/libqglviewer/portfile.cmake)
+#]===]
 
 function(vcpkg_install_qmake)
     vcpkg_build_qmake(${ARGN})

scripts/cmake/vcpkg_internal_escape_regex_control_characters.cmake

@@ -1,4 +1,4 @@
-function(vcpkg_escape_regex_control_characters out_var string_with_regex_characters)
+function(vcpkg_internal_escape_regex_control_characters out_var string_with_regex_characters)
   string(REGEX REPLACE "[][+.*()^\\$?|]" "\\\\\\0" _escaped_content "${string_with_regex_characters}")
   set(${out_var} "${_escaped_content}" PARENT_SCOPE)
 endfunction()

scripts/cmake/vcpkg_internal_get_cmake_vars.cmake

@@ -1,29 +1,31 @@
-## # vcpkg_internal_get_cmake_vars
+#[===[.md:
-##
+# vcpkg_internal_get_cmake_vars
-## **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
+**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
+## Usage
-## vcpkg_internal_get_cmake_vars(
+```cmake
-##     [OUTPUT_FILE <output_file_with_vars>]
+vcpkg_internal_get_cmake_vars(
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    [OUTPUT_FILE <output_file_with_vars>]
-## )
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-## ```
+)
-##
+```
-## ## Parameters
+
-## ### OPTIONS
+## Parameters
-## Additional options to pass to the test configure call 
+### OPTIONS
-##
+Additional options to pass to the test configure call 
-## ### OUTPUT_FILE
+
-## Variable to return the path to the generated cmake file with the detected `CMAKE_` variables set as `VCKPG_DETECTED_`
+### OUTPUT_FILE
-##
+Variable to return the path to the generated cmake file with the detected `CMAKE_` variables set as `VCKPG_DETECTED_`
-## ## Notes
+
-## If possible avoid usage in portfiles. 
+## Notes
-##
+If possible avoid usage in portfiles. 
-## ## Examples
+
-##
+## Examples
-## * [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
+
+* [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
+#]===]
 
 function(vcpkg_internal_get_cmake_vars)
     cmake_parse_arguments(PARSE_ARGV 0 _gcv "" "OUTPUT_FILE" "OPTIONS")

scripts/cmake/vcpkg_prettify_command.cmake

@@ -1,17 +1,19 @@
-## # vcpkg_prettify_command
+#[===[.md:
-##
+# vcpkg_prettify_command
-## Turns list of command arguments into a formatted string.
+
-##
+Turns list of command arguments into a formatted string.
-## ## Usage
+
-## ```cmake
+## Usage
-## vcpkg_prettify_command(<INPUT_VAR> <OUTPUT_VAR>)
+```cmake
-## ```
+vcpkg_prettify_command(<INPUT_VAR> <OUTPUT_VAR>)
-##
+```
-## ## Examples
+
-##
+## Examples
-## * `scripts/cmake/vcpkg_execute_build_process.cmake`
+
-## * `scripts/cmake/vcpkg_execute_required_process.cmake`
+* `scripts/cmake/vcpkg_execute_build_process.cmake`
-## * `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
+* `scripts/cmake/vcpkg_execute_required_process.cmake`
+* `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
+#]===]
 
 macro(vcpkg_prettify_command INPUT_VAR OUTPUT_VAR)
     set(${OUTPUT_VAR} "")

scripts/cmake/vcpkg_replace_string.cmake

@@ -1,12 +1,14 @@
-#.rst:
+#[===[.md:
-# .. command:: vcpkg_replace_string
+# vcpkg_replace_string
-#
+
-#  Replace a string in a file.
+Replace a string in a file.
-#
+
-#  ::
+```cmake
-#  vcpkg_replace_string(filename match_string replace_string)
+vcpkg_replace_string(filename match_string replace_string)
-#
+```
-#
+
+#]===]
+
 function(vcpkg_replace_string filename match_string replace_string)
     file(READ ${filename} _contents)
     string(REPLACE "${match_string}" "${replace_string}" _contents "${_contents}")

scripts/cmake/vcpkg_test_cmake.cmake

@@ -1,3 +1,4 @@
+# DEPRECATED
 function(vcpkg_test_cmake)
     message("${_VCPKG_BACKCOMPAT_MESSAGE_LEVEL}" "vcpkg_test_cmake was a no-op and has been removed. Please remove the call to `vcpkg_test_cmake()`.")
 endfunction()

test.cmake

@@ -1,9 +0,0 @@
-set(LLVM_EXECUTABLE_REGEX [[^([^.]*|[^.]*\.lld)\.exe$]])
-foreach(el "bugpoint.exe" "ld.lld.exe" "asdf.dll" "asdf")
-	message(STATUS "Matching ${el}")
-	if(el MATCHES "${LLVM_EXECUTABLE_REGEX}")
-		message(STATUS "Matching ${el} - match (${CMAKE_MATCH_1}).")
-	else()
-		message(STATUS "Matching ${el} - no match.")
-	endif()
-endforeach()