[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>...]
-    OUTPUT_QUIET ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_STRIP_TRAILING_WHITESPACE
-    WORKING_DIRECTORY <dir>
-    TIMEOUT <seconds>
-    RESULT_VARIABLE <seconds>
-    OUTPUT_VARIABLE <var_out>
-    ERROR_VARIABLE <var_err>
-    INPUT_FILE <f_in>
-    OUTPUT_FILE <f_out>
-    ERROR_FILE <f_err>
-    ENCODING <enc>
+    COMMAND <cmd> [<arguments>]
+    [WORKING_DIRECTORY <dir>]
+    [TIMEOUT <seconds>]
+    [RESULT_VARIABLE <variable>]
+    [OUTPUT_VARIABLE <variable>]
+    [ERROR_VARIABLE <variable>]
+    [INPUT_FILE <file>]
+    [OUTPUT_FILE <file>]
+    [ERROR_FILE <file>]
+    [OUTPUT_QUIET]
+    [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
-- ARIA2 (Downloader)
-- BISON
-- CLANG
-- DARK
-- DOXYGEN
-- FLEX
-- GASPREPROCESSOR
-- GPERF
-- PERL
-- PYTHON2
-- PYTHON3
-- GIT
-- GN
-- GO
-- JOM
-- MESON
-- NASM
-- NINJA
-- NUGET
-- SCONS
-- SWIG
-- YASM
+* 7Z
+* ARIA2 (Downloader)
+* BISON
+* CLANG
+* DARK
+* DOXYGEN
+* FLEX
+* GASPREPROCESSOR
+* GPERF
+* PERL
+* PYTHON2
+* PYTHON3
+* GIT
+* GN
+* GO
+* JOM
+* MESON
+* NASM
+* NINJA
+* NUGET
+* SCONS
+* SWIG
+* 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 (!$VcpkgRoot) {
-    $VcpkgRoot = ".."
+if ([String]::IsNullOrEmpty($VcpkgRoot)) {
+    $VcpkgRoot = "${PSScriptRoot}/.."
 }
 
 $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))"
-        "- [$($_.BaseName -replace "_","\_")]($($_.BaseName).md)" `
-        | Out-File -Enc Ascii -Append -FilePath "$PSScriptRoot\maintainers\portfile-functions.md"
+        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))"
+        "- [$($filename.BaseName -replace "_","\_")]($($filename.BaseName).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
-##
-## 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.
-##
+#[===[.md:
+# execute_process
+
+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.
+#]===]
+
 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
-##
-## Add a directory to the PATH environment variable
-##
-## ## Usage
-## ```cmake
-## vcpkg_add_to_path([PREPEND] <${PYTHON3_DIR}>)
-## ```
-##
-## ## Parameters
-## ### <positional>
-## The directory to add
-##
-## ### PREPEND
-## Prepends the directory.
-##
-## The default is to append.
-##
-## ## Examples:
-## * [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75)
-## * [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)
-##
+#[===[
+# vcpkg_add_to_path
+
+Add a directory to the PATH environment variable
+
+## Usage
+```cmake
+vcpkg_add_to_path([PREPEND] <${PYTHON3_DIR}>)
+```
+
+## Parameters
+### <positional>
+The directory to add
+
+### PREPEND
+Prepends the directory.
+
+The default is to append.
+
+## Examples:
+* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75)
+* [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
-##
-## 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
-## vcpkg_apply_patches(
-##     SOURCE_PATH <${SOURCE_PATH}>
-##     [QUIET]
-##     PATCHES <patch1.patch>...
-## )
-## ```
-##
-## ## Parameters
-## ### 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.
-##
-## 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.
-##
-## This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
-##
-## ## 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)
+#[===[.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.
+
+## Usage
+```cmake
+vcpkg_apply_patches(
+    SOURCE_PATH <${SOURCE_PATH}>
+    [QUIET]
+    PATCHES <patch1.patch>...
+)
+```
+
+## Parameters
+### 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.
+
+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.
+
+This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
+
+## 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)
+#]===]
 
 include(vcpkg_execute_in_download_mode)
 

scripts/cmake/vcpkg_build_cmake.cmake

@@ -1,34 +1,37 @@
-## # vcpkg_build_cmake
-##
-## Build a cmake project.
-##
-## ## Usage:
-## ```cmake
-## vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET <target>])
-## ```
-##
-## ## Parameters:
-## ### 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
-## 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.
-##
-## ## Notes:
-## This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
-## You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the
-## "install" target
-##
-## ## 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)
-## * [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
-## * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
+#[===[.md:
+# vcpkg_build_cmake
+
+Build a cmake project.
+
+## Usage:
+```cmake
+vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET <target>])
+```
+
+## Parameters:
+### 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
+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.
+
+## Notes:
+This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
+You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the
+"install" target
+
+## 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)
+* [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
-##
-## Build a GN project
-##
-## ## Usage:
-## ```cmake
-## vcpkg_build_gn(
-##     [TARGETS <target>...]
-## )
-## ```
-##
-## ## Parameters:
-## ### TARGETS
-## Only build the specified targets.
+#[===[.md:
+# vcpkg_build_gn
+
+Build a GN project
+
+## Usage:
+```cmake
+vcpkg_build_gn(
+    [TARGETS <target>...]
+)
+```
+
+## Parameters:
+### TARGETS
+Only build the specified targets.
+#]===]
 
 function(vcpkg_build_gn)
     vcpkg_build_ninja(${ARGN})
-endfunction()
+endfunction()

scripts/cmake/vcpkg_build_make.cmake

@@ -1,50 +1,53 @@
-## # vcpkg_build_make
-##
-## Build a linux makefile project.
-##
-## ## Usage:
-## ```cmake
-## vcpkg_build_make([BUILD_TARGET <target>]
-##                  [ADD_BIN_TO_PATH]
-##                  [ENABLE_INSTALL])
-##                  [MAKEFILE <makefileName>]
-##                  [LOGFILE_ROOT <logfileroot>])
-## ```
-##
-## ### BUILD_TARGET
-## 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.
-##
-## ### 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()`
-##
-## ### BUILD_TARGET
-## 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
-##
-## ### 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).
-## You can use the alias [`vcpkg_install_make()`](vcpkg_configure_make.md) function if your CMake script supports the
-## "install" target
-##
-## ## 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)
-## * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
-## * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
+#[===[.md:
+# vcpkg_build_make
+
+Build a linux makefile project.
+
+## Usage:
+```cmake
+vcpkg_build_make([BUILD_TARGET <target>]
+                 [ADD_BIN_TO_PATH]
+                 [ENABLE_INSTALL]
+                 [MAKEFILE <makefileName>]
+                 [LOGFILE_ROOT <logfileroot>])
+```
+
+### BUILD_TARGET
+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.
+
+### 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()`
+
+### BUILD_TARGET
+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
+
+### 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).
+You can use the alias [`vcpkg_install_make()`](vcpkg_install_make.md) function if your CMake script supports the
+"install" target
+
+## 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)
+* [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
-##
-## Build a msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
-##
-## ## Usage
-## ```cmake
-## vcpkg_build_msbuild(
-##     PROJECT_PATH <${SOURCE_PATH}/port.sln>
-##     [RELEASE_CONFIGURATION <Release>]
-##     [DEBUG_CONFIGURATION <Debug>]
-##     [TARGET <Build>]
-##     [TARGET_PLATFORM_VERSION <10.0.15063.0>]
-##     [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
-##     [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
-##     [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
-##     [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
-##     [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
-##     [USE_VCPKG_INTEGRATION]
-## )
-## ```
-##
-## ## Parameters
-## ### 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.
-##
-## ### PROJECT_PATH
-## The path to the solution (`.sln`) or project (`.vcxproj`) file.
-##
-## ### RELEASE_CONFIGURATION
-## The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
-##
-## ### DEBUG_CONFIGURATION
-## The configuration (``/p:Configuration`` msbuild parameter)
-## used for Debug builds.
-##
-## ### TARGET_PLATFORM_VERSION
-## The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
-##
-## ### TARGET
-## The MSBuild target to build. (``/t:<TARGET>``)
-##
-## ### PLATFORM
-## The platform (``/p:Platform`` 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_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`.
-##
-## ## 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)
+#[===[.md:
+# vcpkg_build_msbuild
+
+Build a msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
+
+## Usage
+```cmake
+vcpkg_build_msbuild(
+    PROJECT_PATH <${SOURCE_PATH}/port.sln>
+    [RELEASE_CONFIGURATION <Release>]
+    [DEBUG_CONFIGURATION <Debug>]
+    [TARGET <Build>]
+    [TARGET_PLATFORM_VERSION <10.0.15063.0>]
+    [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
+    [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
+    [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
+    [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
+    [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
+    [USE_VCPKG_INTEGRATION]
+)
+```
+
+## Parameters
+### 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.
+
+### PROJECT_PATH
+The path to the solution (`.sln`) or project (`.vcxproj`) file.
+
+### RELEASE_CONFIGURATION
+The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
+
+### DEBUG_CONFIGURATION
+The configuration (``/p:Configuration`` msbuild parameter)
+used for Debug builds.
+
+### TARGET_PLATFORM_VERSION
+The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
+
+### TARGET
+The MSBuild target to build. (``/t:<TARGET>``)
+
+### PLATFORM
+The platform (``/p:Platform`` 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_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`.
+
+## 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)
+#]===]
 
 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
-##
-## Build a ninja project
-##
-## ## Usage:
-## ```cmake
-## vcpkg_build_ninja(
-##     [TARGETS <target>...]
-## )
-## ```
-##
-## ## Parameters:
-## ### TARGETS
-## Only build the specified targets.
+#[===[.md:
+# vcpkg_build_ninja
+
+Build a ninja project
+
+## Usage:
+```cmake
+vcpkg_build_ninja(
+    [TARGETS <target>...]
+)
+```
+
+## Parameters:
+### 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
-##
-## Build a msvc makefile project.
-##
-## ## Usage:
-## ```cmake
-## vcpkg_build_nmake(
-##     SOURCE_PATH <${SOURCE_PATH}>
-##     [NO_DEBUG]
-##     [TARGET <all>]
-##     [PROJECT_SUBPATH <${SUBPATH}>]
-##     [PROJECT_NAME <${MAKEFILE_NAME}>]
-##     [PRERUN_SHELL <${SHELL_PATH}>]
-##     [PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
-##     [PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
-##     [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
-##     [TARGET <target>])
-## ```
-##
-## ## Parameters
-## ### 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_NAME
-## Specifies the name of msvc makefile name.
-## Default is `makefile.vc`
-##
-## ### NO_DEBUG
-## This port doesn't support debug mode.
-##
-## ### ENABLE_INSTALL
-## Install binaries after 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_RELEASE
-## Script that needs to be called before release build
-##
-## ### 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_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
-## 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.
-##
-## ## 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
-## "install" target
-##
-## ## 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)
+#[===[.md:
+# vcpkg_build_nmake
+
+Build a msvc makefile project.
+
+## Usage:
+```cmake
+vcpkg_build_nmake(
+    SOURCE_PATH <${SOURCE_PATH}>
+    [NO_DEBUG]
+    [TARGET <all>]
+    [PROJECT_SUBPATH <${SUBPATH}>]
+    [PROJECT_NAME <${MAKEFILE_NAME}>]
+    [PRERUN_SHELL <${SHELL_PATH}>]
+    [PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
+    [PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+    [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+    [TARGET <target>])
+```
+
+## Parameters
+### 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_NAME
+Specifies the name of msvc makefile name.
+Default is `makefile.vc`
+
+### NO_DEBUG
+This port doesn't support debug mode.
+
+### ENABLE_INSTALL
+Install binaries after 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_RELEASE
+Script that needs to be called before release build
+
+### 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_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
+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.
+
+## 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_install_nmake.md) function if your CMake script supports the
+"install" target
+
+## 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)
+#]===]
+
 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:
-# .. command:: vcpkg_build_qmake
-#
-#  Build a qmake-based project, previously configured using vcpkg_configure_qmake.
-#
-#  ::
-#  vcpkg_build_qmake()
-#
+#[===[.md:
+# vcpkg_build_qmake
+
+Build a qmake-based project, previously configured using vcpkg_configure_qmake.
+
+```cmake
+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
-## Check if one or more features are a part of a package installation.
-## 
-## ## Usage
-## ```cmake
-## vcpkg_check_features(
-##   OUT_FEATURE_OPTIONS <FEATURE_OPTIONS>  
-##   [FEATURES
-##     <cuda> <WITH_CUDA>
-##     [<opencv> <WITH_OPENCV>]
-##     ...]
-##   [INVERTED_FEATURES
-##     <cuda> <IGNORE_PACKAGE_CUDA>
-##     [<opencv> <IGNORE_PACKAGE_OPENCV>]
-##     ...]
-## )
-## ```
-## `vcpkg_check_features()` accepts these parameters: 
-## 
-## * `OUT_FEATURE_OPTIONS`:  
-##   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.
-##   
-## * `FEATURES`:  
-##   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. 
-## 
-## * `INVERTED_FEATURES`:  
-##   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. 
-## 
-## 
-## ## Notes
-## 
-## 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.
-## 
-## 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, 
-## two conflicting definitions are added to `OUT_FEATURE_OPTIONS`.
-## 
-## 
-## ## Examples
-## 
-## ### Example 1: Regular features
-## 
-## ```cmake
-## $ ./vcpkg install mimalloc[asm,secure]
-## 
-## # ports/mimalloc/portfile.cmake
-## vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-##   # Keyword FEATURES is optional if INVERTED_FEATURES are not used
-##     asm       MI_SEE_ASM
-##     override  MI_OVERRIDE
-##     secure    MI_SECURE
-## )
-## 
-## vcpkg_configure_cmake(
-##   SOURCE_PATH ${SOURCE_PATH}
-##   PREFER_NINJA
-##   OPTIONS
-##     # Expands to "-DMI_SEE_ASM=ON; -DMI_OVERRIDE=OFF; -DMI_SECURE=ON"
-##     ${FEATURE_OPTIONS}
-## )
-## ```
-## 
-## ### Example 2: Inverted features
-## 
-## ```cmake
-## $ ./vcpkg install cpprestsdk[websockets]
-## 
-## # ports/cpprestsdk/portfile.cmake
-## vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-##   INVERTED_FEATURES # <- Keyword INVERTED_FEATURES required
-##     brotli      CPPREST_EXCLUDE_BROTLI
-##     websockets  CPPREST_EXCLUDE_WEBSOCKETS
-## )
-## 
-## vcpkg_configure_cmake(
-##   SOURCE_PATH ${SOURCE_PATH}
-##   PREFER_NINJA
-##   OPTIONS
-##     # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON; -DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
-##     ${FEATURE_OPTIONS}
-## )
-## ```
-## 
-## ### Example 3: Set multiple options for same feature
-## 
-## ```cmake
-## $ ./vcpkg install pcl[cuda]
-## 
-## # ports/pcl/portfile.cmake
-## vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-##     cuda  WITH_CUDA
-##     cuda  BUILD_CUDA
-##     cuda  BUILD_GPU
-## )
-## 
-## vcpkg_configure_cmake(
-##   SOURCE_PATH ${SOURCE_PATH}
-##   PREFER_NINJA
-##   OPTIONS
-##     # Expands to "-DWITH_CUDA=ON; -DBUILD_CUDA=ON; -DBUILD_GPU=ON"
-##     ${FEATURE_OPTIONS}
-## )
-## ``` 
-## 
-## ### Example 4: Use regular and inverted features
-## 
-## ```cmake
-## $ ./vcpkg install rocksdb[tbb]
-## 
-## # ports/rocksdb/portfile.cmake
-## vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-##   FEATURES # <- Keyword FEATURES is required because INVERTED_FEATURES are being used
-##     tbb   WITH_TBB
-##   INVERTED_FEATURES
-##     tbb   ROCKSDB_IGNORE_PACKAGE_TBB
-## )
-## 
-## vcpkg_configure_cmake(
-##   SOURCE_PATH ${SOURCE_PATH}
-##   PREFER_NINJA
-##   OPTIONS
-##     # Expands to "-DWITH_TBB=ON; -DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
-##     ${FEATURE_OPTIONS}
-## )
-## ``` 
-## 
-## ## 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)
-## * [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
-## 
+#[===[.md:
+# vcpkg_check_features
+Check if one or more features are a part of a package installation.
+
+## Usage
+```cmake
+vcpkg_check_features(
+  OUT_FEATURE_OPTIONS <FEATURE_OPTIONS>  
+  [FEATURES
+    <cuda> <WITH_CUDA>
+    [<opencv> <WITH_OPENCV>]
+    ...]
+  [INVERTED_FEATURES
+    <cuda> <IGNORE_PACKAGE_CUDA>
+    [<opencv> <IGNORE_PACKAGE_OPENCV>]
+    ...]
+)
+```
+`vcpkg_check_features()` accepts these parameters: 
+
+* `OUT_FEATURE_OPTIONS`:  
+  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.
+  
+* `FEATURES`:  
+  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. 
+
+* `INVERTED_FEATURES`:  
+  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. 
+
+
+## Notes
+
+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.
+
+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, 
+two conflicting definitions are added to `OUT_FEATURE_OPTIONS`.
+
+
+## Examples
+
+### Example 1: Regular features
+
+```cmake
+$ ./vcpkg install mimalloc[asm,secure]
+
+# ports/mimalloc/portfile.cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+  # Keyword FEATURES is optional if INVERTED_FEATURES are not used
+    asm       MI_SEE_ASM
+    override  MI_OVERRIDE
+    secure    MI_SECURE
+)
+
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    # Expands to "-DMI_SEE_ASM=ON; -DMI_OVERRIDE=OFF; -DMI_SECURE=ON"
+    ${FEATURE_OPTIONS}
+)
+```
+
+### Example 2: Inverted features
+
+```cmake
+$ ./vcpkg install cpprestsdk[websockets]
+
+# ports/cpprestsdk/portfile.cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+  INVERTED_FEATURES # <- Keyword INVERTED_FEATURES required
+    brotli      CPPREST_EXCLUDE_BROTLI
+    websockets  CPPREST_EXCLUDE_WEBSOCKETS
+)
+
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON; -DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
+    ${FEATURE_OPTIONS}
+)
+```
+
+### Example 3: Set multiple options for same feature
+
+```cmake
+$ ./vcpkg install pcl[cuda]
+
+# ports/pcl/portfile.cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+    cuda  WITH_CUDA
+    cuda  BUILD_CUDA
+    cuda  BUILD_GPU
+)
+
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    # Expands to "-DWITH_CUDA=ON; -DBUILD_CUDA=ON; -DBUILD_GPU=ON"
+    ${FEATURE_OPTIONS}
+)
+``` 
+
+### Example 4: Use regular and inverted features
+
+```cmake
+$ ./vcpkg install rocksdb[tbb]
+
+# ports/rocksdb/portfile.cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+  FEATURES # <- Keyword FEATURES is required because INVERTED_FEATURES are being used
+    tbb   WITH_TBB
+  INVERTED_FEATURES
+    tbb   ROCKSDB_IGNORE_PACKAGE_TBB
+)
+
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    # Expands to "-DWITH_TBB=ON; -DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
+    ${FEATURE_OPTIONS}
+)
+``` 
+
+## 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)
+* [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
-##
-## Asserts the available library and CRT linkage options for the port.
-##
-## ## Usage
-## ```cmake
-## vcpkg_check_linkage(
-##     [ONLY_STATIC_LIBRARY | ONLY_DYNAMIC_LIBRARY]
-##     [ONLY_STATIC_CRT | ONLY_DYNAMIC_CRT]
-## )
-## ```
-##
-## ## Parameters
-## ### 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_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.
-##
-## ## 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
-##
-## * [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
+#[===[.md:
+# vcpkg_check_linkage
+
+Asserts the available library and CRT linkage options for the port.
+
+## Usage
+```cmake
+vcpkg_check_linkage(
+    [ONLY_STATIC_LIBRARY | ONLY_DYNAMIC_LIBRARY]
+    [ONLY_STATIC_CRT | ONLY_DYNAMIC_CRT]
+)
+```
+
+## Parameters
+### 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_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.
+
+## 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
+
+* [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
-##
-## 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
-## vcpkg_clean_executables_in_bin(
-##     FILE_NAMES <file1>...
-## )
-## ```
-##
-## ## Parameters
-## ### 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`.
-##
-## ## Examples
-## * [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
+#[===[.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.
+
+## Usage
+```cmake
+vcpkg_clean_executables_in_bin(
+    FILE_NAMES <file1>...
+)
+```
+
+## Parameters
+### 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`.
+
+## 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
-##
-## Clean intermediate files generated by `vcpkg_install_msbuild()`.
-##
-## ## Usage
-## ```cmake
-## vcpkg_clean_msbuild()
-## ```
-##
-## ## Examples
-##
-## * [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
+#[===[.md:
+# vcpkg_clean_msbuild
+
+Clean intermediate files generated by `vcpkg_install_msbuild()`.
+
+## Usage
+```cmake
+vcpkg_clean_msbuild()
+```
+
+## Examples
+
+* [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
-##
-## File contains helpful variabls for portfiles which are commonly needed or used.
-##
-## ## The following variables are available:
-## ```cmake
-## VCPKG_TARGET_IS_<target>                 with <target> being one of the following: WINDOWS, UWP, LINUX, OSX, ANDROID, FREEBSD, OPENBSD. only defined if <target>
-## VCPKG_HOST_IS_<target>                   with <host> being one of the following: WINDOWS, LINUX, OSX, FREEBSD, OPENBSD. only defined if <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_HOST_EXECUTABLE_SUFFIX             executable suffix of the host
-## VCPKG_TARGET_EXECUTABLE_SUFFIX           executable suffix of the target
-## VCPKG_TARGET_STATIC_LIBRARY_PREFIX       static library prefix for target (same as CMAKE_STATIC_LIBRARY_PREFIX)
-## VCPKG_TARGET_STATIC_LIBRARY_SUFFIX       static library suffix for target (same as CMAKE_STATIC_LIBRARY_SUFFIX)
-## VCPKG_TARGET_SHARED_LIBRARY_PREFIX       shared library prefix for target (same as CMAKE_SHARED_LIBRARY_PREFIX)
-## VCPKG_TARGET_SHARED_LIBRARY_SUFFIX       shared library suffix for target (same as CMAKE_SHARED_LIBRARY_SUFFIX)
-## VCPKG_TARGET_IMPORT_LIBRARY_PREFIX       import library prefix for target (same as CMAKE_IMPORT_LIBRARY_PREFIX)
-## VCPKG_TARGET_IMPORT_LIBRARY_SUFFIX       import library suffix for target (same as CMAKE_IMPORT_LIBRARY_SUFFIX)
-## VCPKG_FIND_LIBRARY_PREFIXES              target dependent prefixes used for find_library calls in portfiles
-## 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
-## portfiles are able to use find_library calls to discover dependent libraries within the current triplet for ports.
-##
+#[===[.md:
+# vcpkg_common_definitions
+
+File contains helpful variabls for portfiles which are commonly needed or used.
+
+## The following variables are available:
+```cmake
+VCPKG_TARGET_IS_<target>                 with <target> being one of the following: WINDOWS, UWP, LINUX, OSX, ANDROID, FREEBSD, OPENBSD. only defined if <target>
+VCPKG_HOST_IS_<target>                   with <host> being one of the following: WINDOWS, LINUX, OSX, FREEBSD, OPENBSD. only defined if <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_HOST_EXECUTABLE_SUFFIX             executable suffix of the host
+VCPKG_TARGET_EXECUTABLE_SUFFIX           executable suffix of the target
+VCPKG_TARGET_STATIC_LIBRARY_PREFIX       static library prefix for target (same as CMAKE_STATIC_LIBRARY_PREFIX)
+VCPKG_TARGET_STATIC_LIBRARY_SUFFIX       static library suffix for target (same as CMAKE_STATIC_LIBRARY_SUFFIX)
+VCPKG_TARGET_SHARED_LIBRARY_PREFIX       shared library prefix for target (same as CMAKE_SHARED_LIBRARY_PREFIX)
+VCPKG_TARGET_SHARED_LIBRARY_SUFFIX       shared library suffix for target (same as CMAKE_SHARED_LIBRARY_SUFFIX)
+VCPKG_TARGET_IMPORT_LIBRARY_PREFIX       import library prefix for target (same as CMAKE_IMPORT_LIBRARY_PREFIX)
+VCPKG_TARGET_IMPORT_LIBRARY_SUFFIX       import library suffix for target (same as CMAKE_IMPORT_LIBRARY_SUFFIX)
+VCPKG_FIND_LIBRARY_PREFIXES              target dependent prefixes used for find_library calls in portfiles
+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
+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
-##
-## Configure CMake for Debug and Release builds of a project.
-##
-## ## Usage
-## ```cmake
-## vcpkg_configure_cmake(
-##     SOURCE_PATH <${SOURCE_PATH}>
-##     [PREFER_NINJA]
-##     [DISABLE_PARALLEL_CONFIGURE]
-##     [NO_CHARSET_FLAG]
-##     [GENERATOR <"NMake Makefiles">]
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
-##     [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
-## )
-## ```
-##
-## ## Parameters
-## ### 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.
-## 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.
-## This is needed for libraries which write back into their source directory during configure.
-##
-## 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`.
-##
-## This is needed for libraries that set their own source code's character set.
-##
-## ### 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"`.
-##
-## ### 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_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.
-##
-## ## Notes
-## This command supplies many common arguments to CMake. To see the full list, examine the source.
-##
-## ## 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)
-## * [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
-## * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
+#[===[.md:
+# vcpkg_configure_cmake
+
+Configure CMake for Debug and Release builds of a project.
+
+## Usage
+```cmake
+vcpkg_configure_cmake(
+    SOURCE_PATH <${SOURCE_PATH}>
+    [PREFER_NINJA]
+    [DISABLE_PARALLEL_CONFIGURE]
+    [NO_CHARSET_FLAG]
+    [GENERATOR <"NMake Makefiles">]
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+    [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+)
+```
+
+## Parameters
+### 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.
+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.
+This is needed for libraries which write back into their source directory during configure.
+
+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`.
+
+This is needed for libraries that set their own source code's character set.
+
+### 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"`.
+
+### 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_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.
+
+## Notes
+This command supplies many common arguments to CMake. To see the full list, examine the source.
+
+## 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)
+* [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
-##
-## Generate Ninja (GN) targets
-##
-## ## Usage:
-## ```cmake
-## vcpkg_configure_gn(
-##     SOURCE_PATH <SOURCE_PATH>
-##     [OPTIONS <OPTIONS>]
-##     [OPTIONS_DEBUG <OPTIONS_DEBUG>]
-##     [OPTIONS_RELEASE <OPTIONS_RELEASE>]
-## )
-## ```
-##
-## ## Parameters:
-## ### SOURCE_PATH (required)
-## The path to the GN project.
-##
-## ### OPTIONS
-## 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_RELEASE (space-separated string)
-## Options to be passed to the release target.
+#[===[.md:
+# vcpkg_configure_gn
+
+Generate Ninja (GN) targets
+
+## Usage:
+```cmake
+vcpkg_configure_gn(
+    SOURCE_PATH <SOURCE_PATH>
+    [OPTIONS <OPTIONS>]
+    [OPTIONS_DEBUG <OPTIONS_DEBUG>]
+    [OPTIONS_RELEASE <OPTIONS_RELEASE>]
+)
+```
+
+## Parameters:
+### SOURCE_PATH (required)
+The path to the GN project.
+
+### OPTIONS
+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_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
-##
-## Configure configure for Debug and Release builds of a project.
-##
-## ## Usage
-## ```cmake
-## vcpkg_configure_make(
-##     SOURCE_PATH <${SOURCE_PATH}>
-##     [AUTOCONFIG]
-##     [USE_WRAPPERS]
-##     [DETERMINE_BUILD_TRIPLET]
-##     [BUILD_TRIPLET "--host=x64 --build=i686-unknown-pc"]
-##     [NO_ADDITIONAL_PATHS]
-##     [CONFIG_DEPENDENT_ENVIRONMENT <SOME_VAR>...]
-##     [CONFIGURE_ENVIRONMENT_VARIABLES <SOME_ENVVAR>...]
-##     [ADD_BIN_TO_PATH]
-##     [NO_DEBUG]
-##     [SKIP_CONFIGURE]
-##     [PROJECT_SUBPATH <${PROJ_SUBPATH}>]
-##     [PRERUN_SHELL <${SHELL_PATH}>]
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
-##     [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
-## )
-## ```
-##
-## ## Parameters
-## ### 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`.
-## By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
-##
-## ### SKIP_CONFIGURE
-## Skip configure process
-##
-## ### 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
-##
-## ### 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
-##
-## ### 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)
-##
-## ### 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
-##
-## ### 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_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. 
-## 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. 
-##
-## ## Notes
-## This command supplies many common arguments to configure. To see the full list, examine the source.
-##
-## ## 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)
-## * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
-## * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
+#[===[.md:
+# vcpkg_configure_make
+
+Configure configure for Debug and Release builds of a project.
+
+## Usage
+```cmake
+vcpkg_configure_make(
+    SOURCE_PATH <${SOURCE_PATH}>
+    [AUTOCONFIG]
+    [USE_WRAPPERS]
+    [DETERMINE_BUILD_TRIPLET]
+    [BUILD_TRIPLET "--host=x64 --build=i686-unknown-pc"]
+    [NO_ADDITIONAL_PATHS]
+    [CONFIG_DEPENDENT_ENVIRONMENT <SOME_VAR>...]
+    [CONFIGURE_ENVIRONMENT_VARIABLES <SOME_ENVVAR>...]
+    [ADD_BIN_TO_PATH]
+    [NO_DEBUG]
+    [SKIP_CONFIGURE]
+    [PROJECT_SUBPATH <${PROJ_SUBPATH}>]
+    [PRERUN_SHELL <${SHELL_PATH}>]
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+    [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+)
+```
+
+## Parameters
+### 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`.
+By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+
+### SKIP_CONFIGURE
+Skip configure process
+
+### 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
+
+### 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
+
+### 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)
+
+### 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
+
+### 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_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. 
+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. 
+
+## Notes
+This command supplies many common arguments to configure. To see the full list, examine the source.
+
+## 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)
+* [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
-##
-## Configure Meson for Debug and Release builds of a project.
-##
-## ## Usage
-## ```cmake
-## vcpkg_configure_meson(
-##     SOURCE_PATH <${SOURCE_PATH}>
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
-##     [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
-## )
-## ```
-##
-## ## Parameters
-## ### 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_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`.
-##
-## ## Notes
-## This command supplies many common arguments to Meson. To see the full list, examine the source.
-##
-## ## 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)
+#[===[.md:
+# vcpkg_configure_meson
+
+Configure Meson for Debug and Release builds of a project.
+
+## Usage
+```cmake
+vcpkg_configure_meson(
+    SOURCE_PATH <${SOURCE_PATH}>
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+    [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+)
+```
+
+## Parameters
+### 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_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`.
+
+## Notes
+This command supplies many common arguments to Meson. To see the full list, examine the source.
+
+## 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)
+#]===]
+
 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:
-# .. command:: vcpkg_configure_qmake
-#
-#  Configure a qmake-based project.
-#
-#  ::
-#  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[_RELEASE|_DEBUG]``
-#    The options passed to qmake.
+#[===[.md:
+# 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.
+#]===]
 
 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
-##
-## Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
-##
-## ## Usage
-## ```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.
-##
-## ## Parameters
-## ### 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`.
-##
-## ## 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)
+#[===[.md:
+# vcpkg_copy_pdbs
+
+Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
+
+## Usage
+```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.
+
+## Parameters
+### 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`.
+
+## 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)
+#]===]
+
 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
-##
-## Copy all DLL dependencies of built tools into the tool folder.
-##
-## ## Usage
-## ```cmake
-## vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>)
-## ```
-## ## 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.
-##
-## ## 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)
+#[===[.md:
+# vcpkg_copy_tool_dependencies
+
+Copy all DLL dependencies of built tools into the tool folder.
+
+## Usage
+```cmake
+vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>)
+```
+## 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.
+
+## 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)
+#]===]
+
 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
-##
-## Copy tools and all their DLL dependencies into the `tools` folder.
-##
-## ## Usage
-## ```cmake
-## vcpkg_copy_tools(
-##     TOOL_NAMES <tool1>...
-##     [SEARCH_DIR <${CURRENT_PACKAGES_DIR}/bin>]
-##     [AUTO_CLEAN]
-## )
-## ```
-## ## Parameters
-## ### 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.
-##
-## ### AUTO_CLEAN
-## Auto clean executables in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`.
-##
-## ## 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)
-## * [uriparser](https://github.com/microsoft/vcpkg/blob/master/ports/uriparser/portfile.cmake)
+#[===[.md:
+# vcpkg_copy_tools
+
+Copy tools and all their DLL dependencies into the `tools` folder.
+
+## Usage
+```cmake
+vcpkg_copy_tools(
+    TOOL_NAMES <tool1>...
+    [SEARCH_DIR <${CURRENT_PACKAGES_DIR}/bin>]
+    [AUTO_CLEAN]
+)
+```
+## Parameters
+### 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.
+
+### AUTO_CLEAN
+Auto clean executables in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`.
+
+## 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)
+* [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
-##
-## Download and cache a file needed for this port.
-##
-## This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.
-##
-## ## Usage
-## ```cmake
-## vcpkg_download_distfile(
-##     <OUT_VARIABLE>
-##     URLS <http://mainUrl> <http://mirror1>...
-##     FILENAME <output.zip>
-##     SHA512 <5981de...>
-## )
-## ```
-## ## Parameters
-## ### 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.
-##
-## ### 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.
-##
-## 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
-##
-## ### SKIP_SHA512
-## Skip SHA512 hash check for file.
-##
-## 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 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.
-##
-## ## 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)
-## * [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)
+#[===[.md:
+# vcpkg_download_distfile
+
+Download and cache a file needed for this port.
+
+This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.
+
+## Usage
+```cmake
+vcpkg_download_distfile(
+    <OUT_VARIABLE>
+    URLS <http://mainUrl> <http://mirror1>...
+    FILENAME <output.zip>
+    SHA512 <5981de...>
+)
+```
+## Parameters
+### 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.
+
+### 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.
+
+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
+
+### SKIP_SHA512
+Skip SHA512 hash check for file.
+
+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 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.
+
+## 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)
+* [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
-##
-## Execute a required build process
-##
-## ## Usage
-## ```cmake
-## vcpkg_execute_build_process(
-##     COMMAND <cmd> [<args>...]
-##     [NO_PARALLEL_COMMAND <cmd> [<args>...]]
-##     WORKING_DIRECTORY </path/to/dir>
-##     LOGNAME <log_name>)
-## )
-## ```
-## ## Parameters
-## ### 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
-## failure potentially due to parallelism is detected.
-##
-## ### WORKING_DIRECTORY
-## The directory to execute the command in.
-##
-## ### 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.
-##
-## ## Examples
-##
-## * [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
+#[===[.md:
+# vcpkg_execute_build_process
+
+Execute a required build process
+
+## Usage
+```cmake
+vcpkg_execute_build_process(
+    COMMAND <cmd> [<args>...]
+    [NO_PARALLEL_COMMAND <cmd> [<args>...]]
+    WORKING_DIRECTORY </path/to/dir>
+    LOGNAME <log_name>)
+)
+```
+## Parameters
+### 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
+failure potentially due to parallelism is detected.
+
+### WORKING_DIRECTORY
+The directory to execute the command in.
+
+### 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.
+
+## Examples
+
+* [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
-##
-## Execute a process even in download mode.
-##
-## ## Usage
-## ```cmake
-## vcpkg_execute_in_download_mode(
-##     COMMAND <cmd> [<arguments>...]
-##     OUTPUT_QUIET ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_STRIP_TRAILING_WHITESPACE
-##     WORKING_DIRECTORY <dir>
-##     TIMEOUT <seconds>
-##     RESULT_VARIABLE <seconds>
-##     OUTPUT_VARIABLE <var_out>
-##     ERROR_VARIABLE <var_err>
-##     INPUT_FILE <f_in>
-##     OUTPUT_FILE <f_out>
-##     ERROR_FILE <f_err>
-##     ENCODING <enc>
-## )
-## ```
-##
-## The signature of this function is identical with `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.
+#[===[.md:
+# vcpkg_execute_in_download_mode
+
+Execute a process even in download mode.
+
+## Usage
+```cmake
+vcpkg_execute_in_download_mode(
+    COMMAND <cmd> [<arguments>]
+    [WORKING_DIRECTORY <dir>]
+    [TIMEOUT <seconds>]
+    [RESULT_VARIABLE <variable>]
+    [OUTPUT_VARIABLE <variable>]
+    [ERROR_VARIABLE <variable>]
+    [INPUT_FILE <file>]
+    [OUTPUT_FILE <file>]
+    [ERROR_FILE <file>]
+    [OUTPUT_QUIET]
+    [ERROR_QUIET]
+    [OUTPUT_STRIP_TRAILING_WHITESPACE]
+    [ERROR_STRIP_TRAILING_WHITESPACE]
+    [ENCODING <name>]
+)
+```
+
+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
-  cmake_parse_arguments(PARSE_ARGV 0 vcpkg_execute_in_download_mode
-                        "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"
-                        "COMMAND")
+    # 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
+        "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"
+        "COMMAND")
 
-  # collect all other present parameters
-  set(other_args "")
-  foreach(arg OUTPUT_QUIET ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_STRIP_TRAILING_WHITESPACE)
-    if(vcpkg_execute_in_download_mode_${arg})
-      list(APPEND other_args ${arg})
+    # collect all other present parameters
+    set(other_args "")
+    foreach(arg OUTPUT_QUIET ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_STRIP_TRAILING_WHITESPACE)
+        if(vcpkg_execute_in_download_mode_${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)
-    _execute_process(COMMAND ${vcpkg_execute_in_download_mode_COMMAND} ${other_args})
-  else()
-    execute_process(COMMAND ${vcpkg_execute_in_download_mode_COMMAND} ${other_args})
-  endif()
-
-  # 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()
+    # 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
-##
-## Execute a process with logging and fail the build if the command fails.
-##
-## ## Usage
-## ```cmake
-## vcpkg_execute_required_process(
-##     COMMAND <${PERL}> [<arguments>...]
-##     WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg>
-##     LOGNAME <build-${TARGET_TRIPLET}-dbg>
-##     [TIMEOUT <seconds>]
-##     [OUTPUT_VARIABLE <var>]
-##     [ERROR_VARIABLE <var>]
-## )
-## ```
-## ## Parameters
-## ### ALLOW_IN_DOWNLOAD_MODE
-## 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.
-##
-## ### WORKING_DIRECTORY
-## The directory to execute the command in.
-##
-## ### LOGNAME
-## The prefix to use for the log files.
-##
-## ### TIMEOUT
-## Optional timeout after which to terminate the command.
-##
-## ### OUTPUT_VARIABLE
-## Optional variable to receive stdout 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.
-##
-## ## 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)
-## * [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
-## * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
+#[===[.md:
+# vcpkg_execute_required_process
+
+Execute a process with logging and fail the build if the command fails.
+
+## Usage
+```cmake
+vcpkg_execute_required_process(
+    COMMAND <${PERL}> [<arguments>...]
+    WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg>
+    LOGNAME <build-${TARGET_TRIPLET}-dbg>
+    [TIMEOUT <seconds>]
+    [OUTPUT_VARIABLE <var>]
+    [ERROR_VARIABLE <var>]
+)
+```
+## Parameters
+### ALLOW_IN_DOWNLOAD_MODE
+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.
+
+### WORKING_DIRECTORY
+The directory to execute the command in.
+
+### LOGNAME
+The prefix to use for the log files.
+
+### TIMEOUT
+Optional timeout after which to terminate the command.
+
+### OUTPUT_VARIABLE
+Optional variable to receive stdout 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.
+
+## 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)
+* [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
-##
-## Extract an archive into the source directory. Deprecated in favor of [`vcpkg_extract_source_archive_ex`](vcpkg_extract_source_archive_ex.md).
-##
-## ## Usage
-## ```cmake
-## vcpkg_extract_source_archive(
-##     <${ARCHIVE}> [<${TARGET_DIRECTORY}>]
-## )
-## ```
-## ## Parameters
-## ### ARCHIVE
-## 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\`.
-##
-## 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.
-##
-## ## 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)
-## * [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake)
+#[===[.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).
+
+## Usage
+```cmake
+vcpkg_extract_source_archive(
+    <${ARCHIVE}> [<${TARGET_DIRECTORY}>]
+)
+```
+## Parameters
+### ARCHIVE
+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/`.
+
+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.
+
+## 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)
+* [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
-##
-## Extract an archive into the source directory. Replaces [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md).
-##
-## ## Usage
-## ```cmake
-## vcpkg_extract_source_archive_ex(
-##     SKIP_PATCH_CHECK
-##     OUT_SOURCE_PATH <SOURCE_PATH>
-##     ARCHIVE <${ARCHIVE}>
-##     [REF <1.0.0>]
-##     [NO_REMOVE_ONE_LEVEL]
-##     [WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/src>]
-##     [PATCHES <a.patch>...]
-## )
-## ```
-## ## Parameters
-## ### 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.
-##
-## This should be set to `SOURCE_PATH` by convention.
-##
-## ### ARCHIVE
-## The full path to the archive to be extracted.
-##
-## 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.
-##
-## 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/`.
-##
-## 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.
-##
-## 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.
-##
-## ## 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)
-## * [cairo](https://github.com/Microsoft/vcpkg/blob/master/ports/cairo/portfile.cmake)
+#[===[.md:
+# vcpkg_extract_source_archive_ex
+
+Extract an archive into the source directory. Replaces [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md).
+
+## Usage
+```cmake
+vcpkg_extract_source_archive_ex(
+    SKIP_PATCH_CHECK
+    OUT_SOURCE_PATH <SOURCE_PATH>
+    ARCHIVE <${ARCHIVE}>
+    [REF <1.0.0>]
+    [NO_REMOVE_ONE_LEVEL]
+    [WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/src>]
+    [PATCHES <a.patch>...]
+)
+```
+## Parameters
+### 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.
+
+This should be set to `SOURCE_PATH` by convention.
+
+### ARCHIVE
+The full path to the archive to be extracted.
+
+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.
+
+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/`.
+
+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.
+
+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.
+
+## 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)
+* [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
-##
-## Checks common requirements and fails the current portfile with a (default) error message
-##
-## ## Usage
-## ```cmake
-## vcpkg_fail_port_install(
-##     [ALWAYS]
-##     [MESSAGE <"Reason for failure">]
-##     [ON_TARGET <Windows> [<OSX> ...]]
-##     [ON_ARCH <x64> [<arm> ...]]
-##     [ON_CRT_LINKAGE <static> [<dynamic> ...]])
-##     [ON_LIBRARY_LINKAGE <static> [<dynamic> ...]]
-## )
-## ```
-##
-## ## Parameters
-## ### MESSAGE
-## Additional failure message. If none is given, a default message will be displayed depending on the failure condition.
-##
-## ### 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_ARCH
-## Architecture 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.
-##
-## ## Examples
-##
-## * [aws-lambda-cpp](https://github.com/Microsoft/vcpkg/blob/master/ports/aws-lambda-cpp/portfile.cmake)
+#[===[.md:
+# vcpkg_fail_port_install
+
+Checks common requirements and fails the current portfile with a (default) error message
+
+## Usage
+```cmake
+vcpkg_fail_port_install(
+    [ALWAYS]
+    [MESSAGE <"Reason for failure">]
+    [ON_TARGET <Windows> [<OSX> ...]]
+    [ON_ARCH <x64> [<arm> ...]]
+    [ON_CRT_LINKAGE <static> [<dynamic> ...]])
+    [ON_LIBRARY_LINKAGE <static> [<dynamic> ...]]
+)
+```
+
+## Parameters
+### MESSAGE
+Additional failure message. If none is given, a default message will be displayed depending on the failure condition.
+
+### 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_ARCH
+Architecture 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.
+
+## Examples
+
+* [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
-##
-## Download or find a well-known tool.
-##
-## ## Usage
-## ```cmake
-## vcpkg_find_acquire_program(<VAR>)
-## ```
-## ## Parameters
-## ### 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:
-##
-## - 7Z
-## - ARIA2 (Downloader)
-## - BISON
-## - CLANG
-## - DARK
-## - DOXYGEN
-## - FLEX
-## - GASPREPROCESSOR
-## - GPERF
-## - PERL
-## - PYTHON2
-## - PYTHON3
-## - GIT
-## - GN
-## - GO
-## - JOM
-## - MESON
-## - NASM
-## - NINJA
-## - NUGET
-## - SCONS
-## - SWIG
-## - YASM
-##
-## Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
-##
-## ## 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)
-## * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
+#[===[.md:
+# vcpkg_find_acquire_program
+
+Download or find a well-known tool.
+
+## Usage
+```cmake
+vcpkg_find_acquire_program(<VAR>)
+```
+## Parameters
+### 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:
+
+* 7Z
+* ARIA2 (Downloader)
+* BISON
+* CLANG
+* DARK
+* DOXYGEN
+* FLEX
+* GASPREPROCESSOR
+* GPERF
+* PERL
+* PYTHON2
+* PYTHON3
+* GIT
+* GN
+* GO
+* JOM
+* MESON
+* NASM
+* NINJA
+* NUGET
+* SCONS
+* SWIG
+* YASM
+
+Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
+
+## 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)
+* [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
-##
-## Checks if a Fortran compiler can be found.
-## Windows(x86/x64) Only: If not it will switch/enable MinGW gfortran 
-##                        and return required cmake args for building. 
-##
-## ## Usage
-## ```cmake
-## vcpkg_find_fortran(<additional_cmake_args_out>
-## )
-## ```
+#[===[.md:
+# vcpkg_find_fortran
+
+Checks if a Fortran compiler can be found.
+Windows(x86/x64) Only: If not it will switch/enable MinGW gfortran 
+                       and return required cmake args for building. 
+
+## Usage
+```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
-##
-## 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.
-##
-## ## Usage
-## ```cmake
-## vcpkg_fixup_cmake_targets([CONFIG_PATH <share/${PORT}>] [TARGET_PATH <share/${PORT}>] [DO_NOT_DELETE_PARENT_CONFIG_PATH])
-## ```
-##
-## ## Parameters
-##
-## ### CONFIG_PATH
-## Subpath currently containing `*.cmake` files subdirectory (like `lib/cmake/${PORT}`). Should be relative to `${CURRENT_PACKAGES_DIR}`.
-##
-## Defaults to `share/${PORT}`.
-##
-## ### TARGET_PATH
-## 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}`.
-##
-## ### DO_NOT_DELETE_PARENT_CONFIG_PATH 
-## 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`.
-##
-## 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.
-##
-## ## 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)
-## * [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake)
+#[===[.md:
+# vcpkg_fixup_cmake_targets
+
+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.
+
+## Usage
+```cmake
+vcpkg_fixup_cmake_targets([CONFIG_PATH <share/${PORT}>] [TARGET_PATH <share/${PORT}>] [DO_NOT_DELETE_PARENT_CONFIG_PATH])
+```
+
+## Parameters
+
+### CONFIG_PATH
+Subpath currently containing `*.cmake` files subdirectory (like `lib/cmake/${PORT}`). Should be relative to `${CURRENT_PACKAGES_DIR}`.
+
+Defaults to `share/${PORT}`.
+
+### TARGET_PATH
+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}`.
+
+### DO_NOT_DELETE_PARENT_CONFIG_PATH 
+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`.
+
+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.
+
+## 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)
+* [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
-##
-## 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.
+#[===[.md:
+# vcpkg_fixup_pkgconfig
 
-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
-##
-## Download and extract a project from Bitbucket.
-## Enables support for installing HEAD `vcpkg.exe install --head <port>`.
-##
-## ## Usage:
-## ```cmake
-## vcpkg_from_bitbucket(
-##     OUT_SOURCE_PATH <SOURCE_PATH>
-##     REPO <Microsoft/cpprestsdk>
-##     [REF <v2.0.0>]
-##     [SHA512 <45d0d7f8cc350...>]
-##     [HEAD_REF <master>]
-##     [PATCHES <patch1.patch> <patch2.patch>...]
-## )
-## ```
-##
-## ## Parameters:
-## ### OUT_SOURCE_PATH
-## Specifies the out-variable that will contain the extracted location.
-##
-## This should be set to `SOURCE_PATH` by convention.
-##
-## ### 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.**
-##
-## 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.
-##
-## ### 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.
-##
-## ### 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.
-##
-## ### PATCHES
-## A list of patches to be applied to the extracted sources.
-##
-## 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.
-##
-## This exports the `VCPKG_HEAD_VERSION` variable during head builds.
-##
-## ## Examples:
-##
-## * [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake)
+#[===[.md:
+# vcpkg_from_bitbucket
+
+Download and extract a project from Bitbucket.
+Enables support for installing HEAD `vcpkg.exe install --head <port>`.
+
+## Usage:
+```cmake
+vcpkg_from_bitbucket(
+    OUT_SOURCE_PATH <SOURCE_PATH>
+    REPO <Microsoft/cpprestsdk>
+    [REF <v2.0.0>]
+    [SHA512 <45d0d7f8cc350...>]
+    [HEAD_REF <master>]
+    [PATCHES <patch1.patch> <patch2.patch>...]
+)
+```
+
+## Parameters:
+### OUT_SOURCE_PATH
+Specifies the out-variable that will contain the extracted location.
+
+This should be set to `SOURCE_PATH` by convention.
+
+### 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.**
+
+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.
+
+### 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.
+
+### 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.
+
+### PATCHES
+A list of patches to be applied to the extracted sources.
+
+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.
+
+This exports the `VCPKG_HEAD_VERSION` variable during head builds.
+
+## Examples:
+
+* [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
-##
-## Download and extract a project from git
-##
-## ## Usage:
-## ```cmake
-## vcpkg_from_git(
-##     OUT_SOURCE_PATH <SOURCE_PATH>
-##     URL <https://android.googlesource.com/platform/external/fdlibm>
-##     REF <59f7335e4d...>
-##     [PATCHES <patch1.patch> <patch2.patch>...]
-## )
-## ```
-##
-## ## Parameters:
-## ### OUT_SOURCE_PATH
-## Specifies the out-variable that will contain the extracted location.
-##
-## This should be set to `SOURCE_PATH` by convention.
-##
-## ### URL
-## The url of the git repository.
-##
-## ### REF
-## The git sha of the commit to download.
-##
-## ### PATCHES
-## A list of patches to be applied to the extracted sources.
-##
-## Relative paths are based on the port directory.
-##
-## ## Notes:
-## `OUT_SOURCE_PATH`, `REF`, and `URL` must be specified.
-##
-## ## Examples:
-##
-## * [fdlibm](https://github.com/Microsoft/vcpkg/blob/master/ports/fdlibm/portfile.cmake)
+#[===[.md:
+# vcpkg_from_git
+
+Download and extract a project from git
+
+## Usage:
+```cmake
+vcpkg_from_git(
+    OUT_SOURCE_PATH <SOURCE_PATH>
+    URL <https://android.googlesource.com/platform/external/fdlibm>
+    REF <59f7335e4d...>
+    [PATCHES <patch1.patch> <patch2.patch>...]
+)
+```
+
+## Parameters:
+### OUT_SOURCE_PATH
+Specifies the out-variable that will contain the extracted location.
+
+This should be set to `SOURCE_PATH` by convention.
+
+### URL
+The url of the git repository.
+
+### REF
+The git sha of the commit to download.
+
+### PATCHES
+A list of patches to be applied to the extracted sources.
+
+Relative paths are based on the port directory.
+
+## Notes:
+`OUT_SOURCE_PATH`, `REF`, and `URL` must be specified.
+
+## Examples:
+
+* [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
-##
-## Download and extract a project from GitHub. Enables support for `install --head`.
-##
-## ## Usage:
-## ```cmake
-## vcpkg_from_github(
-##     OUT_SOURCE_PATH <SOURCE_PATH>
-##     REPO <Microsoft/cpprestsdk>
-##     [REF <v2.0.0>]
-##     [SHA512 <45d0d7f8cc350...>]
-##     [HEAD_REF <master>]
-##     [PATCHES <patch1.patch> <patch2.patch>...]
-##     [GITHUB_HOST <https://github.com>]
-##     [AUTHORIZATION_TOKEN <${SECRET_FROM_FILE}>]
-## )
-## ```
-##
-## ## Parameters:
-## ### OUT_SOURCE_PATH
-## Specifies the out-variable that will contain the extracted location.
-##
-## This should be set to `SOURCE_PATH` by convention.
-##
-## ### 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.**
-##
-## 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.
-##
-## ### 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.
-##
-## ### 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.
-##
-## ### PATCHES
-## A list of patches to be applied to the extracted sources.
-##
-## Relative paths are based on the port directory.
-##
-## ### 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.
-##
-## ### 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.
-##
-## ## 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.
-##
-## ## 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)
-## * [beast](https://github.com/Microsoft/vcpkg/blob/master/ports/beast/portfile.cmake)
+#[===[.md:
+# vcpkg_from_github
+
+Download and extract a project from GitHub. Enables support for `install --head`.
+
+## Usage:
+```cmake
+vcpkg_from_github(
+    OUT_SOURCE_PATH <SOURCE_PATH>
+    REPO <Microsoft/cpprestsdk>
+    [REF <v2.0.0>]
+    [SHA512 <45d0d7f8cc350...>]
+    [HEAD_REF <master>]
+    [PATCHES <patch1.patch> <patch2.patch>...]
+    [GITHUB_HOST <https://github.com>]
+    [AUTHORIZATION_TOKEN <${SECRET_FROM_FILE}>]
+)
+```
+
+## Parameters:
+### OUT_SOURCE_PATH
+Specifies the out-variable that will contain the extracted location.
+
+This should be set to `SOURCE_PATH` by convention.
+
+### 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.**
+
+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.
+
+### 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.
+
+### 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.
+
+### PATCHES
+A list of patches to be applied to the extracted sources.
+
+Relative paths are based on the port directory.
+
+### 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.
+
+### 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.
+
+## 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.
+
+## 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)
+* [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
-##
-## Download and extract a project from Gitlab instances. Enables support for `install --head`.
-##
-## ## Usage:
-## ```cmake
-## vcpkg_from_gitlab(
-##     GITLAB_URL <https://gitlab.com>
-##     OUT_SOURCE_PATH <SOURCE_PATH>
-##     REPO <gitlab-org/gitlab-ce>
-##     [REF <v10.7.3>]
-##     [SHA512 <45d0d7f8cc350...>]
-##     [HEAD_REF <master>]
-##     [PATCHES <patch1.patch> <patch2.patch>...]
-## )
-## ```
-##
-## ## Parameters:
-##
-## ### GITLAB_URL
-## The URL of the Gitlab instance to use.
-##
-## ### OUT_SOURCE_PATH
-## Specifies the out-variable that will contain the extracted location.
-##
-## This should be set to `SOURCE_PATH` by convention.
-##
-## ### 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.**
-##
-## 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.
-##
-## ### SHA512
-## 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.
-##
-## ### 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.
-##
-## ### PATCHES
-## A list of patches to be applied to the extracted sources.
-##
-## 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.
-##
-## This exports the `VCPKG_HEAD_VERSION` variable during head builds.
-##
-## ## Examples:
-## * [curl][https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75]
-## * [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)
-##
+#[===[.md:
+# vcpkg_from_gitlab
+
+Download and extract a project from Gitlab instances. Enables support for `install --head`.
+
+## Usage:
+```cmake
+vcpkg_from_gitlab(
+    GITLAB_URL <https://gitlab.com>
+    OUT_SOURCE_PATH <SOURCE_PATH>
+    REPO <gitlab-org/gitlab-ce>
+    [REF <v10.7.3>]
+    [SHA512 <45d0d7f8cc350...>]
+    [HEAD_REF <master>]
+    [PATCHES <patch1.patch> <patch2.patch>...]
+)
+```
+
+## Parameters:
+
+### GITLAB_URL
+The URL of the Gitlab instance to use.
+
+### OUT_SOURCE_PATH
+Specifies the out-variable that will contain the extracted location.
+
+This should be set to `SOURCE_PATH` by convention.
+
+### 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.**
+
+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.
+
+### SHA512
+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.
+
+### 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.
+
+### PATCHES
+A list of patches to be applied to the extracted sources.
+
+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.
+
+This exports the `VCPKG_HEAD_VERSION` variable during head builds.
+
+## Examples:
+* [curl][https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75]
+* [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
-##
-## Download and extract a project from sourceforge.
-##
-## ## Usage:
-## ```cmake
-## vcpkg_from_sourceforge(
-##     OUT_SOURCE_PATH SOURCE_PATH
-##     REPO <cunit/CUnit>
-##     [REF <2.1-3>]
-##     SHA512 <547b417109332...>
-##     FILENAME <CUnit-2.1-3.tar.bz2>
-##     [DISABLE_SSL]
-##     [NO_REMOVE_ONE_LEVEL]
-##     [PATCHES <patch1.patch> <patch2.patch>...]
-## )
-## ```
-##
-## ## Parameters:
-## ### OUT_SOURCE_PATH
-## Specifies the out-variable that will contain the extracted location.
-##
-## This should be set to `SOURCE_PATH` by convention.
-##
-## ### REPO
-## The organization or user and repository (optional) on sourceforge.
-##
-## ### 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.
-##
-## 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
-## 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
-## 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.
-##
-## ### 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}/`).
-##
-## ### PATCHES
-## A list of patches to be applied to the extracted sources.
-##
-## Relative paths are based on the port directory.
-##
-## ### DISABLE_SSL
-## Disable ssl when downloading source.
-##
-## ### NO_REMOVE_ONE_LEVEL
-## Specifies that the default removal of the top level folder should not occur.
-##
-## ## 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)
-## * [tinyfiledialogs](https://github.com/Microsoft/vcpkg/blob/master/ports/tinyfiledialogs/portfile.cmake)
+#[===[.md:
+# vcpkg_from_sourceforge
+
+Download and extract a project from sourceforge.
+
+## Usage:
+```cmake
+vcpkg_from_sourceforge(
+    OUT_SOURCE_PATH SOURCE_PATH
+    REPO <cunit/CUnit>
+    [REF <2.1-3>]
+    SHA512 <547b417109332...>
+    FILENAME <CUnit-2.1-3.tar.bz2>
+    [DISABLE_SSL]
+    [NO_REMOVE_ONE_LEVEL]
+    [PATCHES <patch1.patch> <patch2.patch>...]
+)
+```
+
+## Parameters:
+### OUT_SOURCE_PATH
+Specifies the out-variable that will contain the extracted location.
+
+This should be set to `SOURCE_PATH` by convention.
+
+### REPO
+The organization or user and repository (optional) on sourceforge.
+
+### 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.
+
+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
+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
+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.
+
+### 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}/`).
+
+### PATCHES
+A list of patches to be applied to the extracted sources.
+
+Relative paths are based on the port directory.
+
+### DISABLE_SSL
+Disable ssl when downloading source.
+
+### NO_REMOVE_ONE_LEVEL
+Specifies that the default removal of the top level folder should not occur.
+
+## 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)
+* [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
-##
-## Build and install a cmake project.
-##
-## ## Usage:
-## ```cmake
-## vcpkg_install_cmake(...)
-## ```
-##
-## ## 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`
-## parameter.
-##
-## ## 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)
-## * [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
-## * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
+#[===[.md:
+# vcpkg_install_cmake
+
+Build and install a cmake project.
+
+## Usage:
+```cmake
+vcpkg_install_cmake(...)
+```
+
+## 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`
+parameter.
+
+## 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)
+* [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
-##
-## Installs a GN project
-##
-## ## Usage:
-## ```cmake
-## vcpkg_install_gn(
-##      SOURCE_PATH <SOURCE_PATH>
-##      [TARGETS <target>...]
-## )
-## ```
-##
-## ## Parameters:
-## ### SOURCE_PATH
-## The path to the source directory
-## 
-## ### TARGETS
-## Only install the specified targets.
-##
-## Note: includes must be handled separately
+#[===[.md:
+# vcpkg_install_gn
+
+Installs a GN project
+
+## Usage:
+```cmake
+vcpkg_install_gn(
+     SOURCE_PATH <SOURCE_PATH>
+     [TARGETS <target>...]
+)
+```
+
+## Parameters:
+### SOURCE_PATH
+The path to the source directory
+
+### TARGETS
+Only install the specified targets.
+
+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
-##
-## Build and install a make project.
-##
-## ## Usage:
-## ```cmake
-## vcpkg_install_make(...)
-## ```
-##
-## ## 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`
-##
-## ## 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)
-## * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
-## * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
+#[===[.md:
+# vcpkg_install_make
+
+Build and install a make project.
+
+## Usage:
+```cmake
+vcpkg_install_make(...)
+```
+
+## 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`
+
+## 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)
+* [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
-##
-## Builds a meson project previously configured with `vcpkg_configure_meson()`.
-##
-## ## Usage
-## ```cmake
-## vcpkg_install_meson()
-## ```
-##
-## ## 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)
+#[===[.md:
+# vcpkg_install_meson
+
+Builds a meson project previously configured with `vcpkg_configure_meson()`.
+
+## Usage
+```cmake
+vcpkg_install_meson()
+```
+
+## 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)
+#]===]
+
 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
-##
-## Build and install a msbuild-based project. This replaces `vcpkg_build_msbuild()`.
-##
-## ## Usage
-## ```cmake
-## vcpkg_install_msbuild(
-##     SOURCE_PATH <${SOURCE_PATH}>
-##     PROJECT_SUBPATH <port.sln>
-##     [INCLUDES_SUBPATH <include>]
-##     [LICENSE_SUBPATH <LICENSE>]
-##     [RELEASE_CONFIGURATION <Release>]
-##     [DEBUG_CONFIGURATION <Debug>]
-##     [TARGET <Build>]
-##     [TARGET_PLATFORM_VERSION <10.0.15063.0>]
-##     [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
-##     [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
-##     [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
-##     [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
-##     [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
-##     [USE_VCPKG_INTEGRATION]
-##     [ALLOW_ROOT_INCLUDES | REMOVE_ROOT_INCLUDES]
-## )
-## ```
-##
-## ## Parameters
-## ### 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.
-##
-## ### 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.
-##
-## ### 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`.
-##
-## ### 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.
-##
-## ### 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.
-##
-## ### 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.
-##
-## ### RELEASE_CONFIGURATION
-## The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
-##
-## ### DEBUG_CONFIGURATION
-## The configuration (``/p:Configuration`` msbuild parameter) used for Debug builds.
-##
-## ### TARGET_PLATFORM_VERSION
-## The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
-##
-## ### TARGET
-## The MSBuild target to build. (``/t:<TARGET>``)
-##
-## ### PLATFORM
-## The platform (``/p:Platform`` 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_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`.
-##
-## ## 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)
+#[===[.md:
+# vcpkg_install_msbuild
+
+Build and install a msbuild-based project. This replaces `vcpkg_build_msbuild()`.
+
+## Usage
+```cmake
+vcpkg_install_msbuild(
+    SOURCE_PATH <${SOURCE_PATH}>
+    PROJECT_SUBPATH <port.sln>
+    [INCLUDES_SUBPATH <include>]
+    [LICENSE_SUBPATH <LICENSE>]
+    [RELEASE_CONFIGURATION <Release>]
+    [DEBUG_CONFIGURATION <Debug>]
+    [TARGET <Build>]
+    [TARGET_PLATFORM_VERSION <10.0.15063.0>]
+    [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
+    [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
+    [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
+    [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
+    [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
+    [USE_VCPKG_INTEGRATION]
+    [ALLOW_ROOT_INCLUDES | REMOVE_ROOT_INCLUDES]
+)
+```
+
+## Parameters
+### 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.
+
+### 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.
+
+### 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`.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### RELEASE_CONFIGURATION
+The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
+
+### DEBUG_CONFIGURATION
+The configuration (``/p:Configuration`` msbuild parameter) used for Debug builds.
+
+### TARGET_PLATFORM_VERSION
+The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
+
+### TARGET
+The MSBuild target to build. (``/t:<TARGET>``)
+
+### PLATFORM
+The platform (``/p:Platform`` 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_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`.
+
+## 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)
+#]===]
 
 include(vcpkg_clean_msbuild)
 

scripts/cmake/vcpkg_install_nmake.cmake

@@ -1,66 +1,68 @@
-## # vcpkg_install_nmake
-##
-## Build and install a msvc makefile project.
-##
-## ## Usage:
-## ```cmake
-## vcpkg_install_nmake(
-##     SOURCE_PATH <${SOURCE_PATH}>
-##     [NO_DEBUG]
-##     [TARGET <all>]
-##     PROJECT_SUBPATH <${SUBPATH}>
-##     PROJECT_NAME <${MAKEFILE_NAME}>
-##     [PRERUN_SHELL <${SHELL_PATH}>]
-##     [PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
-##     [PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
-##     [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
-## ```
-##
-## ## Parameters
-## ### 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_NAME
-## Specifies the name of msvc makefile name.
-## Default is makefile.vc
-##
-## ### NO_DEBUG
-## This port doesn't support debug mode.
-##
-## ### PRERUN_SHELL
-## Script that needs to be called before 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
-##
-## ### 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_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).
-##
-## ## Notes:
-## This command transparently forwards to [`vcpkg_build_nmake()`](vcpkg_build_nmake.md), adding `ENABLE_INSTALL`
-##
-## ## 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)
+#[===[.md:
+# vcpkg_install_nmake
+
+Build and install a msvc makefile project.
+
+## Usage:
+```cmake
+vcpkg_install_nmake(
+    SOURCE_PATH <${SOURCE_PATH}>
+    [NO_DEBUG]
+    [TARGET <all>]
+    PROJECT_SUBPATH <${SUBPATH}>
+    PROJECT_NAME <${MAKEFILE_NAME}>
+    [PRERUN_SHELL <${SHELL_PATH}>]
+    [PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
+    [PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+    [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+    [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+```
+
+## Parameters
+### 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_NAME
+Specifies the name of msvc makefile name.
+Default is makefile.vc
+
+### NO_DEBUG
+This port doesn't support debug mode.
+
+### PRERUN_SHELL
+Script that needs to be called before 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
+
+### 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_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).
+
+## Notes:
+This command transparently forwards to [`vcpkg_build_nmake()`](vcpkg_build_nmake.md), adding `ENABLE_INSTALL`
+
+## 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)
+#]===]
 
 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
-##
-## Build and install a qmake project.
-##
-## ## Usage:
-## ```cmake
-## vcpkg_install_qmake(...)
-## ```
-##
-## ## Parameters:
-## See [`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.
-##
-## ## Examples
-##
-## * [libqglviewer](https://github.com/Microsoft/vcpkg/blob/master/ports/libqglviewer/portfile.cmake)
+#[===[.md:
+# vcpkg_install_qmake
+
+Build and install a qmake project.
+
+## Usage:
+```cmake
+vcpkg_install_qmake(...)
+```
+
+## Parameters:
+See [`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.
+
+## Examples
+
+* [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
-##
-## **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
-## vcpkg_internal_get_cmake_vars(
-##     [OUTPUT_FILE <output_file_with_vars>]
-##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-## )
-## ```
-##
-## ## Parameters
-## ### 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_`
-##
-## ## Notes
-## If possible avoid usage in portfiles. 
-##
-## ## Examples
-##
-## * [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
+#[===[.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
+
+## Usage
+```cmake
+vcpkg_internal_get_cmake_vars(
+    [OUTPUT_FILE <output_file_with_vars>]
+    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+)
+```
+
+## Parameters
+### 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_`
+
+## Notes
+If possible avoid usage in portfiles. 
+
+## Examples
+
+* [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
-##
-## Turns list of command arguments into a formatted string.
-##
-## ## Usage
-## ```cmake
-## vcpkg_prettify_command(<INPUT_VAR> <OUTPUT_VAR>)
-## ```
-##
-## ## Examples
-##
-## * `scripts/cmake/vcpkg_execute_build_process.cmake`
-## * `scripts/cmake/vcpkg_execute_required_process.cmake`
-## * `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
+#[===[.md:
+# vcpkg_prettify_command
+
+Turns list of command arguments into a formatted string.
+
+## Usage
+```cmake
+vcpkg_prettify_command(<INPUT_VAR> <OUTPUT_VAR>)
+```
+
+## Examples
+
+* `scripts/cmake/vcpkg_execute_build_process.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:
-# .. command:: vcpkg_replace_string
-#
-#  Replace a string in a file.
-#
-#  ::
-#  vcpkg_replace_string(filename match_string replace_string)
-#
-#
+#[===[.md:
+# vcpkg_replace_string
+
+Replace a string in a file.
+
+```cmake
+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()