From 9cfcc711469778370af64830086cc62afd523dfc Mon Sep 17 00:00:00 2001
From: Robert Schumacher <roschuma@microsoft.com>
Date: Fri, 21 Jun 2019 21:33:29 -0700
Subject: [docs] Add maintainer guidelines (#6871)

* [maintainer-guide] Initial commit of maintainer guidelines

* [maintainer-guide] Rearrange sections

* [maintainer-guide] Add note about GitHub Draft PRs

* [maintainer-guide] Improvements

* [maintainer-guide] Address comments about versioning conventions

* [maintainer-guide] Add section about how portfiles interact with CMakeLists.txt

* [maintainer-guidelines] Add link from docs index
---
 docs/index.md                        |   1 +
 docs/maintainers/control-files.md    |  17 +++-
 docs/maintainers/maintainer-guide.md | 178 +++++++++++++++++++++++++++++++++++
 3 files changed, 193 insertions(+), 3 deletions(-)
 create mode 100644 docs/maintainers/maintainer-guide.md

(limited to 'docs')

diff --git a/docs/index.md b/docs/index.md
index cde241e92..5d83b5804 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -19,6 +19,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 
 - [Control files](maintainers/control-files.md)
 - [Portfile functions](maintainers/portfile-functions.md)
+- [Maintainer Guidelines](maintainers/maintainer-guide.md)
 
 ### Specifications
 
diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md
index ac4afa265..03bfa113a 100644
--- a/docs/maintainers/control-files.md
+++ b/docs/maintainers/control-files.md
@@ -43,16 +43,27 @@ The port version.
 
 This field is an alphanumeric string that may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bit strings and are only evaluated for equality.
 
-By convention, if a portfile is modified without incrementing the "upstream" version, a `-#` is appended to create a unique version string.
+For tagged-release ports, we follow the following convention:
 
-Some projects do not have named releases.  In these cases use the date of the version   do not have labeled releases, in these cases use the date of the last commit in `YYYY-MM-DD` format.  See the `abseil` port as an example.
+1. If the port follows a scheme like `va.b.c`, we remove the leading `v`. In this case, it becomes `a.b.c`.
+2. If the port includes its own name in the version like `curl-7_65_1`, we remove the leading name: `7_65_1`
+3. If the port has been modified, we append a `-N` to distinguish the versions: `1.2.1-4`
+
+For rolling-release ports, we use the date that the _commit was accessed by you_, formatted as `YYYY-MM-DD`. Stated another way: if someone had a time machine and went to that date, they would see this commit as the latest master.
+
+For example, given:
+1. The latest commit was made on 2019-04-19
+2. The current version string is `2019-02-14-1`
+3. Today's date is 2019-06-01.
+
+Then if you update the source version today, you should give it version `2019-06-01`. If you need to make a change which doesn't adjust the source version, you should give it version `2019-02-14-2`.
 
 Example:
 ```no-highlight
 Version: 1.0.5-2
 ```
 ```no-highlight
-Version: 2019-3-21
+Version: 2019-03-21
 ```
 
 #### Description
diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md
new file mode 100644
index 000000000..0baa45a02
--- /dev/null
+++ b/docs/maintainers/maintainer-guide.md
@@ -0,0 +1,178 @@
+# Maintainer Guidelines and Policies
+
+This document lists a set of policies that you should apply when adding or updating a port recipe. It is intended to serve the role of [Debian's Policy Manual](https://www.debian.org/doc/debian-policy/), [Homebrew's Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines), and [Homebrew's Formula Cookbook](https://docs.brew.sh/Formula-Cookbook).
+
+## PR Structure
+
+### Make separate Pull Requests per port
+
+Whenever possible, separate changes into multiple PR's. This makes them significantly easier to review and prevents issues with one set of changes from holding up every other change.
+
+### Avoid trivial changes in untouched files
+
+For example, avoid reformatting or renaming variables in portfiles that otherwise have no reason to be modified for the issue at hand. However, if you need to modify the file for the primary purpose of the PR (updating the library), then obviously beneficial changes like fixing typos are appreciated!
+
+### Check names against other repositories
+
+A good service to check many at once is [Repology](https://repology.org/). If the library you are adding could be confused with another one, consider renaming to make it clear.
+
+### Use GitHub Draft PRs
+
+GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge. Most new PRs should be opened as drafts and converted to normal PRs once the CI passes.
+
+More information about GitHub Draft PRs: https://github.blog/2019-02-14-introducing-draft-pull-requests/
+
+## Portfiles
+
+### Avoid deprecated helper functions
+
+At this time, the following helpers are deprecated:
+
+1. `vcpkg_extract_archive()` should be replaced by `vcpkg_extract_archive_ex()`
+2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. `vcpkg_from_github()`)
+3. `vcpkg_build_msbuild()` should be replaced by `vcpkg_install_msbuild()`
+
+### Avoid excessive comments in portfiles
+
+Ideally, portfiles should be short, simple, and as declarative as possible. Remove any helper comments introduced by the `create` command before submitting a PR.
+
+## Build Techniques
+
+### Do not use vendored dependencies
+
+Do not use embedded copies of libraries. All dependencies should be split out and packaged separately so they can be updated and maintained.
+
+### Prefer using CMake
+
+When multiple buildsystems are available, prefer using CMake. Additionally, when appropriate, it can be easier and more maintainable to rewrite alternative buildsystems into CMake using `file(GLOB)` directives.
+
+Examples: [abseil](../../ports/abseil/portfile.cmake)
+
+### Choose either static or shared binaries
+
+By default, `vcpkg_configure_cmake()` will pass in the appropriate setting for `BUILD_SHARED_LIBS`, however for libraries that don't respect that variable, you can switch on `VCPKG_LIBRARY_LINKAGE`:
+
+```cmake
+string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)
+string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED)
+
+vcpkg_configure_cmake(
+    SOURCE_PATH ${SOURCE_PATH}
+    PREFER_NINJA
+    OPTIONS
+        -DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC}
+        -DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED}
+)
+```
+
+### When defining features, explicitly control dependencies
+
+When defining a feature that captures an optional dependency, ensure that the dependency will not be used accidentally when the feature is not explicitly enabled. For example:
+
+```cmake
+set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
+if("zlib" IN_LIST FEATURES)
+    set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
+endif()
+
+vcpkg_configure_cmake(
+    SOURCE_PATH ${SOURCE_PATH}
+    PREFER_NINJA
+    OPTIONS
+        -DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
+)
+```
+
+Note that `ZLIB` in the above is case-sensitive. See the [cmake documentation](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html) for more details.
+
+## Versioning
+
+### Follow common conventions for the `Version:` field
+
+See our [CONTROL files document](control-files.md#version) for a full explanation of our conventions.
+
+### Update the `Version:` field in the `CONTROL` file of any modified ports
+
+Vcpkg uses this field to determine whether a given port is out-of-date and should be changed whenever the port's behavior changes.
+
+Our convention for this field is to append a `-N` to the upstream version when changes need to be made.
+
+For Example:
+
+- Zlib's package version is currently `1.2.1`.
+- You've discovered that the wrong copyright file has been deployed, and fixed that in the portfile.
+- You should update the `Version:` field in the control file to `1.2.1-1`.
+
+See our [CONTROL files document](control-files.md#version) for a full explanation of our conventions.
+
+## Patching
+
+### Prefer options over patching
+
+It is preferable to set options in a call to `vcpkg_configure_xyz()` over patching the settings directly.
+
+Common options that allow avoiding patching:
+1. [MSBUILD] `<PropertyGroup>` settings inside the project file can be overridden via `/p:` parameters
+2. [CMAKE] Calls to `find_package(XYz)` in CMake scripts can be disabled via [`-DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON`](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html)
+3. [CMAKE] Cache variables (declared as `set(VAR "value" CACHE STRING "Documentation")` or `option(VAR "Documentation" "Default Value")`) can be overriden by just passing them in on the command line as `-DVAR:STRING=Foo`. One notable exception is if the `FORCE` parameter is passed to `set()`. See also the [CMake `set` documentation](https://cmake.org/cmake/help/v3.15/command/set.html)
+
+### Minimize patches
+
+When making changes to a library, strive to minimize the final diff. This means you should _not_ reformat the upstream source code when making changes that affect a region. Also, when disabling a conditional, it is better to add a `AND FALSE` or `&& 0` to the condition than to delete every line of the conditional.
+
+This helps to keep the size of the vcpkg repository down as well as improves the likelihood that the patch will apply to future code versions.
+
+### Do not implement features in patches
+
+The purpose of patching in vcpkg is to enable compatibility with compilers, libraries, and platforms. It is not to implement new features in lieu of following proper Open Source procedure (submitting an Issue/PR/etc).
+
+## Do not build tests/docs/examples by default
+
+When submitting a new port, check for any options like `BUILD_TESTS` or `WITH_TESTS` or `POCO_ENABLE_SAMPLES` and ensure the additional binaries are disabled. This minimizes build times and dependencies for the average user.
+
+Optionally, you can add a `test` feature which enables building the tests, however this should not be in the `Default-Features` list.
+
+## Enable existing users of the library to switch to vcpkg
+
+### Do not add `CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS`
+
+Unless the author of the library is already using it, we should not use this CMake functionality because it interacts poorly with C++ templates and breaks certain compiler features. Libraries that don't provide a .def file and do not use __declspec() declarations simply do not support shared builds for Windows and should be marked as such with `vcpkg_check_linkage(ONLY_STATIC_LIBRARY)`.
+
+### Do not rename binaries outside the names given by upstream
+
+This means that if the upstream library has different names in release and debug (libx versus libxd), then the debug library should not be renamed to `libx`. Vice versa, if the upstream library has the same name in release and debug, we should not introduce a new name.
+
+Important caveat:
+- Static and shared variants often should be renamed to a common scheme. This enables consumers to use a common name and be ignorant of the downstream linkage. This is safe because we only make one at a time available.
+
+Note that if a library generates CMake integration files (`foo-config.cmake`), renaming must be done through patching the CMake build itself instead of simply calling `file(RENAME)` on the output archives/LIBs.
+
+Finally, DLL files on Windows should never be renamed post-build because it breaks the generated LIBs.
+
+## Useful implementation notes
+
+### Portfiles are run in Script Mode
+
+While `portfile.cmake`'s and `CMakeLists.txt`'s share a common syntax and core CMake language constructs, portfiles run in "Script Mode", whereas `CMakeLists.txt` files run in "Build Mode" (unofficial term). The most important difference between these two modes is that "Script Mode" does not have a concept of "Target" -- any behaviors that depend on the "target" machine (`CMAKE_CXX_COMPILER`, `CMAKE_EXECUTABLE_SUFFIX`, `CMAKE_SYSTEM_NAME`, etc) will not be correct.
+
+Portfiles have direct access to variables set in the triplet file, but `CMakeLists.txt`s do not (though there is often a translation that happens -- `VCPKG_LIBRARY_LINKAGE` versus `BUILD_SHARED_LIBS`).
+
+Finally, portfiles and CMake builds invoked by portfiles are run in different processes. Conceptually:
+
+```no-highlight
++----------------------------+       +------------------------------------+
+| CMake.exe                  |       | CMake.exe                          |
++----------------------------+       +------------------------------------+
+| Triplet file               | ====> | Toolchain file                     |
+| (x64-windows.cmake)        |       | (scripts/buildsystems/vcpkg.cmake) |
++----------------------------+       +------------------------------------+
+| Portfile                   | ====> | CMakeLists.txt                     |
+| (ports/foo/portfile.cmake) |       | (buildtrees/../CMakeLists.txt)     |
++----------------------------+       +------------------------------------+
+```
+
+To determine the host in a portfile, the standard CMake variables are fine (`CMAKE_HOST_WIN32`).
+
+To determine the target in a portfile, the vcpkg triplet variables should be used (`VCPKG_CMAKE_SYSTEM_NAME`).
+
+See also our [triplet documentation](../users/triplets.md) for a full enumeration of possible settings.
-- 
cgit v1.2.3


From f3db66b403840b24ea2612d09cca30a5285f5ea3 Mon Sep 17 00:00:00 2001
From: Victor Romero <romerosanchezv@gmail.com>
Date: Fri, 21 Jun 2019 23:50:05 -0700
Subject: Ports Overlay partial implementation (#6981)

* Ports Overlay feature spec

* Ports Overlay implementation

* [--overlay-ports] Refactor handling of additional paths

* Code cleanup

* [--overlay-ports] Add help

* [depend-info] Support --overlay-ports

* Add method to load all ports using PathsPortFileProvider

* Make PortFileProvider::load_all_control_files() const

* Remove unused code

* [vcpkg] Avoid double-load of source control file between Build::perform_and_exit and Build::perform_and_exit_ex

* [vcpkg] Clang format

* [vcpkg] Fixup build failure introduced in b069ceb2f231

* Report errors from Paragraphs::try_load_port()
---
 docs/specifications/ports-overlay.md | 178 +++++++++++++++++++++++++++++++++++
 1 file changed, 178 insertions(+)
 create mode 100644 docs/specifications/ports-overlay.md

(limited to 'docs')

diff --git a/docs/specifications/ports-overlay.md b/docs/specifications/ports-overlay.md
new file mode 100644
index 000000000..e877f5010
--- /dev/null
+++ b/docs/specifications/ports-overlay.md
@@ -0,0 +1,178 @@
+# Ports Overlay (Jun 19, 2019)
+
+
+## 1. Motivation
+
+### A. Allow users to override ports with alternate versions
+
+It's a common scenario for `vcpkg` users to keep specific versions of libraries to use in their own projects. The current recommendation for users is to fork `vcpkg`'s repository and create tags for commits containing the specific versions of the ports they want to use.
+
+This proposal adds an alternative to solve this problem. By allowing `vcpkg` users to specify additional locations in their file system containing ports for:
+
+  * older or newer versions of libraries,
+  * modified libraries, or
+  * libraries not available in `vcpkg`.
+
+These locations will be searched when resolving port names during package installation, and override ports in `<vcpkg-root>/ports`.
+
+### B. Allow users to keep unmodified upstream ports
+
+Users will be able to keep unmodified versions of the ports shipped with `vcpkg` and update them via `vcpkg update` and `vcpkg upgrade` without having to solve merge conflicts.
+
+
+## 2. Other design concerns
+
+* Allow a set of `vcpkg` commands to optionally accept additional paths to be used when searching for ports.
+* Additional paths must take precedence when resolving names of ports to install.
+* Allow users to specify multiple additional paths.
+* Provide a simple disambiguation mechanism to resolve ambiguous port names.
+* After resolving a port name, the installation process has to work the same as for ports shipped by `vcpkg`.
+* This **DOES NOT ENABLE MULTIPLE VERSIONS** of a same library to be **INSTALLED SIDE-BY-SIDE**.
+
+
+## 3. Proposed solution
+
+This document proposes allowing additional locations to search for ports during package installation that will override and complement the set of ports provided by `vcpkg` (ports under the `<vcpkg_root>/ports` directory).`
+
+A new option `--overlay-ports` will be added to the `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, `vcpkg export`, and `vcpkg depend-info` commands to specify additional paths containing ports. 
+
+From a user experience perspective, a user expresses interest in adding additional lookup locations by passing the `--overlay-ports` option followed by a path to:
+
+* an individual port (directory containing a `CONTROL` file),
+  * `vcpkg install sqlite3 --overlay-ports="C:\custom-ports\sqlite3"`
+
+* a directory containing ports,
+  * `vcpkg install sqlite3 --overlay-ports=\\share\org\custom-ports`
+
+* a file listing paths to the former two.
+  * `vcpkg install sqlite3 --overlay-ports=..\port-repos.txt`
+
+    _port-repos.txt_
+    
+    ```
+    .\experimental-ports\sqlite3
+    C:\custom-ports
+    \\share\team\custom-ports
+    \\share\org\custom-ports
+    ```
+    *Relative paths inside this file are resolved relatively to the file's location. In this case a `experimental-ports` directory should exist at the same level as the `port-repos.txt` file.*
+
+_NOTE: It is not the goal of this document to discuss library versioning or project dependency management solutions, which require the ability to install multiple versions of a same library side-by-side._ 
+
+### Multiple additional paths 
+
+Users can provide multiple additional paths by repeating the `--overlay-ports` option.
+
+```
+vcpkg install sqlite3 
+    --overlay-ports="..\experimental-ports\sqlite3" 
+    --overlay-ports="C:\custom-ports" 
+    --overlay-ports="\\share\team\custom-ports
+```
+
+### Overlaying ports
+
+Port name resolution follows the order in which additional paths are specified, with the first match being selected for installation, and falling back to `<vcpkg-root>/ports` if the port is not found in any of the additional paths.
+
+No effort is made to compare version numbers inside the `CONTROL` files, or to determine which port contains newer or older files.
+
+### Examples
+
+Given the following directory structure:
+
+  ```
+  team-ports/
+  |-- sqlite3/
+  |---- CONTROL
+  |-- rapidjson/
+  |---- CONTROL
+  |-- curl/
+  |---- CONTROL
+
+  my-ports/
+  |-- sqlite3/
+  |---- CONTROL
+  |-- rapidjson/
+  |---- CONTROL
+
+  vcpkg
+  |-- ports/
+  |---- <upstream ports>
+  |-- vcpkg.exe
+  |-- preferred-ports.txt
+  ```
+* #### Example #1:
+
+  Running:
+
+  ```
+  vcpkg/vcpkg.exe install sqlite3 --overlay-ports=my-ports --overlay-ports=team-ports
+  ```
+
+  Results in `my-ports/sqlite3` getting installed as that location appears first in the command line arguments.
+
+* #### Example #2:
+  
+  A specific version of a port can be given priority by adding its path first in the list of arguments:
+
+  ```
+  vcpkg/vcpkg.exe install sqlite3 rapidjson curl 
+      --overlay-ports=my-ports/rapidjson 
+      --overlay-ports=vcpkg/ports/curl
+      --overlay-ports=team-ports
+  ```
+
+  Installs:
+    * `sqlite3` from `team-ports/sqlite3`
+    * `rapidjson` from `my-ports/rapidjson`
+    * `curl` from `vcpkg/ports/curl`
+
+* #### Example #3:
+
+  Given the content of `preferred-ports.txt` as:
+
+  ```
+  ./ports/curl
+  /my-ports/rapidjson
+  /team-ports
+  ```
+
+  A location can be appended or prepended to those included in `preferred-ports.txt` via the command line, like this:
+
+  ```
+  vcpkg/vcpkg.exe install sqlite3 curl --overlay-ports=my-ports --overlay-ports=vcpkg/preferred-ports.txt
+  ```
+
+  Which results in `my-ports/sqlite3` and `vcpkg/ports/curl` getting installed.
+
+
+## 4. Proposed User experience
+
+### i. User wants to preserve an older version of a port
+
+Developer Alice and her team use `vcpkg` to acquire **OpenCV** and some other packages. She has even contributed many patches to add features to the **OpenCV 3** port in `vcpkg`. But, one day, she notices that a PR to update **OpenCV** to the next major version has been merged. 
+
+Alice wants to update some packages available in `vcpkg`. Unfortunately, updating her project to use the latest **OpenCV** is not immediately possible. 
+
+Alice creates a private GitHub repository and checks in the set of ports that she wants to preserve. Then provides her teammates with the link to clone her private ports repository.
+
+```
+mkdir vcpkg-custom-ports
+cd vcpkg-custom-ports
+git init 
+cp -r %VCPKG_ROOT%/ports/opencv .
+git add .
+git commit -m "[opencv] Add OpenCV 3 port"
+git remote add origin https://github.com/<Alice's GitHub username>/vcpkg-custom-ports.git
+git push -u origin master
+```
+
+Now her team is able to use: 
+
+```
+git clone https://github.com/<Alice's GitHub username>/vcpkg-custom-ports.git
+vcpkg update --overlay-ports=./vcpkg-custom-ports
+vcpkg upgrade --no-dry-run --overlay-ports=./vcpkg-custom-ports
+``` 
+
+to upgrade their packages and preserve the old version of **OpenCV** they require.
-- 
cgit v1.2.3


From 1ce24dd0db6d9cf6cdb348ff29aa8454b3f1b028 Mon Sep 17 00:00:00 2001
From: Phil Christensen <philc@microsoft.com>
Date: Tue, 25 Jun 2019 16:08:18 -0700
Subject: [docs]Update cmake docs (#7039)

---
 docs/maintainers/portfile-functions.md             |  1 +
 docs/maintainers/vcpkg_configure_cmake.md          |  1 +
 docs/maintainers/vcpkg_execute_build_process.md    | 36 ++++++++++++++++++++++
 .../maintainers/vcpkg_extract_source_archive_ex.md |  2 +-
 docs/maintainers/vcpkg_find_acquire_program.md     |  1 +
 5 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 docs/maintainers/vcpkg_execute_build_process.md

(limited to 'docs')

diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index f159f7f64..c4b810dc0 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -12,6 +12,7 @@
 - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)
 - [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)
 - [vcpkg\_download\_distfile](vcpkg_download_distfile.md)
+- [vcpkg\_execute\_build\_process](vcpkg_execute_build_process.md)
 - [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)
 - [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)
 - [vcpkg\_extract\_source\_archive\_ex](vcpkg_extract_source_archive_ex.md)
diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md
index 200d358ae..f61a6fa20 100644
--- a/docs/maintainers/vcpkg_configure_cmake.md
+++ b/docs/maintainers/vcpkg_configure_cmake.md
@@ -7,6 +7,7 @@ Configure CMake for Debug and Release builds of a project.
 vcpkg_configure_cmake(
     SOURCE_PATH <${SOURCE_PATH}>
     [PREFER_NINJA]
+    [DISABLE_PARALLEL_CONFIGURE]
     [GENERATOR <"NMake Makefiles">]
     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
diff --git a/docs/maintainers/vcpkg_execute_build_process.md b/docs/maintainers/vcpkg_execute_build_process.md
new file mode 100644
index 000000000..d5b3593d9
--- /dev/null
+++ b/docs/maintainers/vcpkg_execute_build_process.md
@@ -0,0 +1,36 @@
+# 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)
+
+## Source
+[scripts/cmake/vcpkg_execute_build_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake)
diff --git a/docs/maintainers/vcpkg_extract_source_archive_ex.md b/docs/maintainers/vcpkg_extract_source_archive_ex.md
index 92c90b296..8f525c3ce 100644
--- a/docs/maintainers/vcpkg_extract_source_archive_ex.md
+++ b/docs/maintainers/vcpkg_extract_source_archive_ex.md
@@ -25,7 +25,7 @@ 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.
+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
 
diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md
index 57a2bf75a..b868ea418 100644
--- a/docs/maintainers/vcpkg_find_acquire_program.md
+++ b/docs/maintainers/vcpkg_find_acquire_program.md
@@ -24,6 +24,7 @@ The current list of programs includes:
 - MESON
 - NASM
 - NINJA
+- NUGET
 - YASM
 - ARIA2 (Downloader)
 
-- 
cgit v1.2.3


From 53a02456a0f457e78d4b2d98a6b43cdd090b9c69 Mon Sep 17 00:00:00 2001
From: Victor Romero <romerosanchezv@gmail.com>
Date: Thu, 27 Jun 2019 16:32:38 -0700
Subject: Update ports-overlay.md

---
 docs/specifications/ports-overlay.md | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'docs')

diff --git a/docs/specifications/ports-overlay.md b/docs/specifications/ports-overlay.md
index e877f5010..d486cfe19 100644
--- a/docs/specifications/ports-overlay.md
+++ b/docs/specifications/ports-overlay.md
@@ -45,6 +45,8 @@ From a user experience perspective, a user expresses interest in adding addition
   * `vcpkg install sqlite3 --overlay-ports=\\share\org\custom-ports`
 
 * a file listing paths to the former two.
+  > NOTE: Reading paths from a text file is not available in the current implementation, some revisions to this part of the specification are being made and will be implemented in a future date.
+  
   * `vcpkg install sqlite3 --overlay-ports=..\port-repos.txt`
 
     _port-repos.txt_
@@ -129,6 +131,8 @@ Given the following directory structure:
 
 * #### Example #3:
 
+  > NOTE: Reading paths from a text file is not available in the current implementation, some revisions to this part of the specification are being made and will be implemented in a future date.
+  
   Given the content of `preferred-ports.txt` as:
 
   ```
-- 
cgit v1.2.3


From b4675fd65a5baebe93d0e60e082ae43013ed246f Mon Sep 17 00:00:00 2001
From: myd7349 <myd7349@gmail.com>
Date: Sat, 29 Jun 2019 01:17:39 +0800
Subject: [vcpkg] Add vcpkg_check_features (#6958)

* [vcpkg] Add vcpkg_check_feature, vcpkg_check_features

* [vcpkg] Remove vcpkg_check_feature

* [oniguruma,xtensor] Use vcpkg_check_features
---
 docs/maintainers/portfile-functions.md   |  1 +
 docs/maintainers/vcpkg_check_features.md | 41 ++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 docs/maintainers/vcpkg_check_features.md

(limited to 'docs')

diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index c4b810dc0..b98d89192 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -6,6 +6,7 @@
 - [vcpkg\_apply\_patches](vcpkg_apply_patches.md)
 - [vcpkg\_build\_cmake](vcpkg_build_cmake.md)
 - [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
+- [vcpkg\_check\_features](vcpkg_check_features.md)
 - [vcpkg\_check\_linkage](vcpkg_check_linkage.md)
 - [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)
 - [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
diff --git a/docs/maintainers/vcpkg_check_features.md b/docs/maintainers/vcpkg_check_features.md
new file mode 100644
index 000000000..ca2debf85
--- /dev/null
+++ b/docs/maintainers/vcpkg_check_features.md
@@ -0,0 +1,41 @@
+# vcpkg_check_features
+
+Check if one or more features are part of the package installation. 
+
+## Usage
+```cmake
+vcpkg_check_features(
+    <feature1> <output_variable1>
+    [<feature2> <output_variable2>]
+    ...
+)
+```
+
+`vcpkg_check_features` accepts a list of (feature, output_variable) pairs.
+The syntax is similar to the `PROPERTIES` argument of `set_target_properties`.
+
+`vcpkg_check_features` will create a variable `FEATURE_OPTIONS` in the
+parent scope, which you can pass as a part of `OPTIONS` argument when
+calling functions like `vcpkg_config_cmake`:
+```cmake
+vcpkg_config_cmake(
+    SOURCE_PATH ${SOURCE_PATH}
+    PREFER_NINJA
+    OPTIONS
+        -DBUILD_TESTING=ON
+        ${FEATURE_OPTIONS}
+)
+```
+
+## Notes
+`vcpkg_check_features` is supposed to be called only once. Otherwise, the
+`FEATURE_OPTIONS` variable set by a previous call will be overwritten.
+
+## Examples
+
+* [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
+* [oniguruma](https://github.com/microsoft/vcpkg/blob/master/ports/oniguruma/portfile.cmake)
+* [xtensor](https://github.com/microsoft/vcpkg/blob/master/ports/xtensor/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_check_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)
-- 
cgit v1.2.3


From a7bbee315276d37344a464eb95b02ca20ff1b0c2 Mon Sep 17 00:00:00 2001
From: myd7349 <myd7349@gmail.com>
Date: Sat, 29 Jun 2019 23:29:13 +0800
Subject: [vcpkg] Update vcpkg_check_features document (#7091)

* [oniguruma] Fix misusage of vcpkg_check_features

* [xsimd] Use vcpkg_check_features
---
 docs/maintainers/vcpkg_check_features.md | 48 ++++++++++++++++++++++++++------
 1 file changed, 39 insertions(+), 9 deletions(-)

(limited to 'docs')

diff --git a/docs/maintainers/vcpkg_check_features.md b/docs/maintainers/vcpkg_check_features.md
index ca2debf85..46ee9051a 100644
--- a/docs/maintainers/vcpkg_check_features.md
+++ b/docs/maintainers/vcpkg_check_features.md
@@ -1,6 +1,6 @@
 # vcpkg_check_features
 
-Check if one or more features are part of the package installation. 
+Check if one or more features are a part of the package installation.
 
 ## Usage
 ```cmake
@@ -11,12 +11,9 @@ vcpkg_check_features(
 )
 ```
 
-`vcpkg_check_features` accepts a list of (feature, output_variable) pairs.
-The syntax is similar to the `PROPERTIES` argument of `set_target_properties`.
+`vcpkg_check_features` accepts a list of (feature, output_variable) pairs. If a feature is specified, the corresponding output variable will be set as `ON`, or `OFF` otherwise. The syntax is similar to the `PROPERTIES` argument of `set_target_properties`.
 
-`vcpkg_check_features` will create a variable `FEATURE_OPTIONS` in the
-parent scope, which you can pass as a part of `OPTIONS` argument when
-calling functions like `vcpkg_config_cmake`:
+`vcpkg_check_features` will create a variable `FEATURE_OPTIONS` in the parent scope, which you can pass as a part of `OPTIONS` argument when calling functions like `vcpkg_config_cmake`:
 ```cmake
 vcpkg_config_cmake(
     SOURCE_PATH ${SOURCE_PATH}
@@ -28,13 +25,46 @@ vcpkg_config_cmake(
 ```
 
 ## Notes
-`vcpkg_check_features` is supposed to be called only once. Otherwise, the
-`FEATURE_OPTIONS` variable set by a previous call will be overwritten.
+```cmake
+vcpkg_check_features(<feature> <output_variable>)
+```
+can be used as a replacement of:
+```cmake
+if(<feature> IN_LIST FEATURES)
+    set(<output_variable> ON)
+else()
+    set(<output_variable> OFF)
+endif()
+```
+
+However, if you have a feature that was checked like this before:
+```cmake
+if(<feature> IN_LIST FEATURES)
+    set(<output_variable> OFF)
+else()
+    set(<output_variable> ON)
+endif()
+```
+then you should not use `vcpkg_check_features` instead. [```oniguruma```](https://github.com/microsoft/vcpkg/blob/master/ports/oniguruma/portfile.cmake), for example, has a feature named `non-posix` which is checked with:
+```cmake
+if("non-posix" IN_LIST FEATURES)
+    set(ENABLE_POSIX_API OFF)
+else()
+    set(ENABLE_POSIX_API ON)
+endif()
+```
+and by replacing these code with:
+```cmake
+vcpkg_check_features(non-posix ENABLE_POSIX_API)
+```
+is totally wrong.
+
+`vcpkg_check_features` is supposed to be called only once. Otherwise, the `FEATURE_OPTIONS` variable set by a previous call will be overwritten.
 
 ## Examples
 
 * [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
-* [oniguruma](https://github.com/microsoft/vcpkg/blob/master/ports/oniguruma/portfile.cmake)
+* [xsimd](https://github.com/microsoft/vcpkg/blob/master/ports/xsimd/portfile.cmake)
 * [xtensor](https://github.com/microsoft/vcpkg/blob/master/ports/xtensor/portfile.cmake)
 
 ## Source
-- 
cgit v1.2.3


From e2049cb9754006b6a2abed781d34030e16702fad Mon Sep 17 00:00:00 2001
From: Victor Romero <romerosanchezv@gmail.com>
Date: Sun, 30 Jun 2019 09:31:22 -0700
Subject: [vcpkg_configure_cmake] Add NO_CHARSET_FLAG option (#7074)

* [vcpkg_configure_cmake] Add NO_CHARSET_FLAG option

* [vcpkg_configure_cmake] Add documentation for new NO_CHARSET_FLAG option

* [vcpkg_configure_cmake, windows toolchain] Handle NO_CHARSET_FLAG in toolchain

* [build.cpp] Add Windows toolchain to package hash

* [duilib,msix,thrift,tidy-html5] Use NO_CHARSET_FLAG to fix regressions
---
 docs/maintainers/vcpkg_configure_cmake.md | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'docs')

diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md
index f61a6fa20..b78ef54d9 100644
--- a/docs/maintainers/vcpkg_configure_cmake.md
+++ b/docs/maintainers/vcpkg_configure_cmake.md
@@ -8,6 +8,7 @@ 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>...]
@@ -27,6 +28,11 @@ Disables running the CMake configure step in parallel.
 
 This is needed for libraries which write back into their source directory during configure.
 
+### 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.
 
-- 
cgit v1.2.3


From d2b3ef9e88fcb51b7273a76abe6e78d49d73a329 Mon Sep 17 00:00:00 2001
From: Phil Christensen <philc@microsoft.com>
Date: Mon, 1 Jul 2019 22:39:51 -0700
Subject: Fix vcpkg_from_git (#7082)

* [vcpkg_from_git/fdlibm] Fix flaky sha256 issues
* [doc] regenerate docs
---
 docs/maintainers/vcpkg_from_git.md | 14 +++-----------
 1 file changed, 3 insertions(+), 11 deletions(-)

(limited to 'docs')

diff --git a/docs/maintainers/vcpkg_from_git.md b/docs/maintainers/vcpkg_from_git.md
index 6b24a558d..4b9a26c62 100644
--- a/docs/maintainers/vcpkg_from_git.md
+++ b/docs/maintainers/vcpkg_from_git.md
@@ -8,7 +8,6 @@ vcpkg_from_git(
     OUT_SOURCE_PATH <SOURCE_PATH>
     URL <https://android.googlesource.com/platform/external/fdlibm>
     REF <59f7335e4d...>
-    SHA512 <abcdef123...>
     [PATCHES <patch1.patch> <patch2.patch>...]
 )
 ```
@@ -20,17 +19,10 @@ 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.
-
-### SHA512
-The SHA512 hash that should match the archive form of the commit.
-
-This is most easily determined by first setting it to `0`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
+The url of the git repository.  Must start with `https`.
 
 ### 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.
+The git sha of the commit to download.
 
 ### PATCHES
 A list of patches to be applied to the extracted sources.
@@ -38,7 +30,7 @@ A list of patches to be applied to the extracted sources.
 Relative paths are based on the port directory.
 
 ## Notes:
-`OUT_SOURCE_PATH`, `REF`, `SHA512`, and `URL` must be specified.
+`OUT_SOURCE_PATH`, `REF`, and `URL` must be specified.
 
 ## Examples:
 
-- 
cgit v1.2.3


From 30a3e3256f27623a3fce643d8d56170e9d3dc256 Mon Sep 17 00:00:00 2001
From: Victor Romero <romerosanchezv@gmail.com>
Date: Wed, 17 Jul 2019 11:34:31 -0700
Subject: Example: Building dynamic libraries on Linux using overlay triplets
 (#7291)

* Example building dynamic libraries on Linux using overlay triplets

* Change triplets list to multi-columns

* Override default triplets example
---
 docs/examples/overlay-triplets-linux-dynamic.md | 158 ++++++++++++++++++++++++
 1 file changed, 158 insertions(+)
 create mode 100644 docs/examples/overlay-triplets-linux-dynamic.md

(limited to 'docs')

diff --git a/docs/examples/overlay-triplets-linux-dynamic.md b/docs/examples/overlay-triplets-linux-dynamic.md
new file mode 100644
index 000000000..6168d85e6
--- /dev/null
+++ b/docs/examples/overlay-triplets-linux-dynamic.md
@@ -0,0 +1,158 @@
+# Overlay triplets example: build dynamic libraries on Linux
+
+Using **vcpkg** you can build libraries for the following triplets:
+
+<div>
+    <ul style="columns: 3;">
+        <li> arm-uwp</li>
+        <li> arm-windows</li>
+        <li> arm64-uwp</li>
+        <li> arm64-windows</li>
+        <li> x86-uwp</li>
+        <li> x86-windows</li>
+        <li> x86-windows-static</li>
+        <li> x64-uwp</li>
+        <li> x64-linux</li>
+        <li> x64-osx</li>
+        <li> x64-windows</li>
+        <li> x64-windows-static</li>
+    </ul>
+</div>
+
+
+
+By design **vcpkg** builds only static libraries for Linux and Mac OS.
+However, this doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms.
+
+This document will guide you through creating your own custom triplets to build dynamic libraries on Linux using **vcpkg**.
+
+### Step 1: Create a folder to contain your custom triplets
+
+```
+~/vcpkg$ mkdir ../custom-triplets
+```
+
+### Step 2: Create the custom triplet files
+
+To save time, copy the existing `x64-linux.cmake` triplet file.
+
+```
+~/vcpkg$ cp ./triplets/x64-linux.cmake ../custom-triplets/x64-linux-dynamic.cmake
+```
+
+And modify `custom-triplets/x64-linux-dynamic.cmake` to match the contents below:
+```
+set(VCPKG_TARGET_ARCHITECTURE x64)
+set(VCPKG_CRT_LINKAGE dynamic)
+# Change VCPKG_LIBRARY_LINKAGE from static to dynamic
+set(VCPKG_LIBRARY_LINKAGE dynamic)
+
+set(VCPKG_CMAKE_SYSTEM_NAME Linux)
+```
+
+### Step 3: Use `--overlay-triplets` to build dynamic libraries
+
+Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory. 
+
+```
+./vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=../custom-triplets
+The following packages will be built and installed:
+    sqlite3[core]:x64-linux
+Starting package 1/1: sqlite3:x64-linux-dynamic
+Building package sqlite3[core]:x64-linux-dynamic...
+-- Loading triplet configuration from: /home/custom-triplets/x64-linux-dynamic.cmake
+-- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...
+-- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip
+-- Applying patch fix-arm-uwp.patch
+-- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92
+-- Configuring x64-linux-dynamic-dbg
+-- Configuring x64-linux-dynamic-rel
+-- Building x64-linux-dynamic-dbg
+-- Building x64-linux-dynamic-rel
+-- Performing post-build validation
+-- Performing post-build validation done
+Building package sqlite3[core]:x64-linux-dynamic... done
+Installing package sqlite3[core]:x64-linux-dynamic...
+Installing package sqlite3[core]:x64-linux-dynamic... done
+Elapsed time for package sqlite3:x64-linux-dynamic: 44.82 s
+
+Total elapsed time: 44.82 s
+
+The package sqlite3:x64-linux-dynamic provides CMake targets:
+
+    find_package(sqlite3 CONFIG REQUIRED)
+    target_link_libraries(main PRIVATE sqlite3)
+```
+
+Overlay triplets will add your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`.
+
+When using the `--overlay-triplets` option, a message like the following lets you know that a custom triplet is being used: 
+
+```
+-- Loading triplet configuration from: /home/custom-triplets/x64-linux-dynamic.cmake
+```
+
+## Overriding default triplets
+
+As you may have noticed, the default triplets for Windows (`x86-windows` and `x64-windows`) install dynamic libraries, while a suffix (`-static`) is needed for static libraries. This is inconsistent with Linux and Mac OS where only static libraries are built.
+
+Using `--overlay-ports` it is possible to override the default triplets to accomplish the same behavior on Linux:
+
+* `x64-linux`: Builds dynamic libraries,
+* `x64-linux-static`: Builds static libraries.
+
+### Step 1: Create the overriden triplet
+
+Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`.
+
+```
+~/vcpkg$ mv ../custom-triplets/x64-linux-dynamic.cmake ../custom-triplets/x64-linux.cmake
+```
+
+### Step 2: Copy and rename the default triplet
+
+Then, copy the default `x64-linux` triplet (which builds static libraries) in your `/custom-triplets` folder and rename it to `x64-linux-static.cmake`.
+
+```
+~/vcpkg$ cp ./triplets/x64-linux.cmake ../custom-triplets/x64-linux-static.cmake
+```
+
+### Step 3: Use `--overlay-ports` to override default triplets
+
+Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory.
+
+```
+./vcpkg install sqlite3:x64-linux --overlay-triplets=../custom-triplets
+The following packages will be built and installed:
+    sqlite3[core]:x64-linux
+Starting package 1/1: sqlite3:x64-linux
+Building package sqlite3[core]:x64-linux...
+-- Loading triplet configuration from: /home/custom-triplets/x64-linux.cmake
+-- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...
+-- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip
+-- Applying patch fix-arm-uwp.patch
+-- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92
+-- Configuring x64-linux-dbg
+-- Configuring x64-linux-rel
+-- Building x64-linux-dbg
+-- Building x64-linux-rel
+-- Performing post-build validation
+-- Performing post-build validation done
+Building package sqlite3[core]:x64-linux... done
+Installing package sqlite3[core]:x64-linux...
+Installing package sqlite3[core]:x64-linux... done
+Elapsed time for package sqlite3:x64-linux: 44.82 s
+
+Total elapsed time: 44.82 s
+
+The package sqlite3:x64-linux provides CMake targets:
+
+    find_package(sqlite3 CONFIG REQUIRED)
+    target_link_libraries(main PRIVATE sqlite3)
+```
+
+Note that the default triplet is masked by your custom triplet:
+
+```
+-- Loading triplet configuration from: /home/custom-triplets/x64-linux.cmake
+```
-- 
cgit v1.2.3


From 0079c186f0fd8f8f64afc7e0796dd2aa2882e2e3 Mon Sep 17 00:00:00 2001
From: Phil Christensen <philc@microsoft.com>
Date: Tue, 23 Jul 2019 14:49:45 -0700
Subject: [docs] add notes about manual-link (#7390)

---
 docs/maintainers/maintainer-guide.md | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md
index 0baa45a02..e4938844f 100644
--- a/docs/maintainers/maintainer-guide.md
+++ b/docs/maintainers/maintainer-guide.md
@@ -34,7 +34,7 @@ At this time, the following helpers are deprecated:
 
 ### Avoid excessive comments in portfiles
 
-Ideally, portfiles should be short, simple, and as declarative as possible. Remove any helper comments introduced by the `create` command before submitting a PR.
+Ideally, portfiles should be short, simple, and as declarative as possible. Remove any boiler plate comments introduced by the `create` command before submitting a PR.
 
 ## Build Techniques
 
@@ -85,6 +85,15 @@ vcpkg_configure_cmake(
 
 Note that `ZLIB` in the above is case-sensitive. See the [cmake documentation](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html) for more details.
 
+### Place conflicting libs in a `manual-link` directory
+
+A lib is considered conflicting if it does any of the following:
++ Define `main`
++ Define malloc
++ Define symbols that are also declared in other libraries
+
+Conflicting libs are typically by design and not considered a defect.  Because some build systems link against everything in the lib directory, these should be moved into a subdirectory named `manual-link`.
+
 ## Versioning
 
 ### Follow common conventions for the `Version:` field
@@ -157,7 +166,7 @@ While `portfile.cmake`'s and `CMakeLists.txt`'s share a common syntax and core C
 
 Portfiles have direct access to variables set in the triplet file, but `CMakeLists.txt`s do not (though there is often a translation that happens -- `VCPKG_LIBRARY_LINKAGE` versus `BUILD_SHARED_LIBS`).
 
-Finally, portfiles and CMake builds invoked by portfiles are run in different processes. Conceptually:
+Portfiles and CMake builds invoked by portfiles are run in different processes. Conceptually:
 
 ```no-highlight
 +----------------------------+       +------------------------------------+
-- 
cgit v1.2.3


From 165907550c8f6ce7506beef591f55cd3f8458d78 Mon Sep 17 00:00:00 2001
From: nicole mazzuca <mazzucan@outlook.com>
Date: Fri, 2 Aug 2019 09:52:39 -0700
Subject: Update tests, and add documentation! (#7506)

This PR does the following:

* fix tests -- now, they're always built in the CMake scripts, and they work on VS2015
  *add a new flag, BUILD_TESTING, which allows one to turn off testing builds
* Add documentation for running tests
---
 docs/index.md                    |   5 ++
 docs/tool-maintainers/testing.md | 162 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 167 insertions(+)
 create mode 100644 docs/tool-maintainers/testing.md

(limited to 'docs')

diff --git a/docs/index.md b/docs/index.md
index 5d83b5804..b2f0a53b2 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -21,6 +21,11 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 - [Portfile functions](maintainers/portfile-functions.md)
 - [Maintainer Guidelines](maintainers/maintainer-guide.md)
 
+### Tool Maintainer Help
+
+- [Testing](tool-maintainers/testing.md)
+- [Maintainer Guidelines](maintainers/maintainer-guide.md)
+
 ### Specifications
 
 - [Export](specifications/export-command.md)
diff --git a/docs/tool-maintainers/testing.md b/docs/tool-maintainers/testing.md
new file mode 100644
index 000000000..28cc9e099
--- /dev/null
+++ b/docs/tool-maintainers/testing.md
@@ -0,0 +1,162 @@
+Testing
+=======
+
+Testing vcpkg is important whenever one makes changes to the tool itself, and
+writing new tests and keeping them up to date is also very important. If one's
+code is subtly broken, we'd rather find it out right away than a few weeks down
+the line when someone complains!
+
+Running Tests
+-------------
+
+Before anything else, we should know whether you can actually run the tests!
+All you should need is a way to build vcpkg -- anything will do! All you have to
+do is follow the guide 😄
+
+With `$VCPKG_DIRECTORY` being the directory where you have cloned vcpkg, create
+a build directory in `$VCPKG_DIRECTORY/toolsrc` (commonly named `out`), and
+`cd` into it. Make sure to clean it out if it already exists!
+
+```sh
+$ cmake .. -DCMAKE_BUILD_TYPE=Debug -G Ninja
+$ cmake --build .
+$ ./vcpkg-test # ./vcpkg-test [$SPECIFIC_TEST] for a specific set of tests
+$ # i.e., ./vcpkg-test [arguments]
+```
+
+If you make any modifications to `vcpkg`, you'll have to do the
+`cmake --build .` step again.
+
+Writing Tests
+-------------
+
+In your journey to write new tests, and to modify existing tests, reading the
+[Catch2 documentation] will be very helpful! Come back after reading those 😀
+
+You'll want to place your tests in one of the existing files, or, if it doesn't
+belong in any of those, in a [new file](#adding-new-test-files).
+
+The layout of these tests is as follows:
+
+```cpp
+// ... includes
+
+TEST_CASE("Name of test", "[filename without the .cpp]") {
+  // setup and the like
+  REQUIRE(some boolean expression);
+}
+
+// etc.
+```
+
+You want to give these test cases good, descriptive, unique names, like
+`SourceParagraph construct minimum` -- it doesn't need to be extremely clear
+english, and shorthand is good, but make sure it's clear what the test is from
+the name. For the latter parameter, known as "tags", you should at least put the
+name of the file which the test case is in -- e.g., in `arguments.cpp`, you'd
+tag all of the test cases with `[arguments]`.
+
+If you wish to add helper functions, make sure to place them in an anonymous
+namespace -- this will ensure that they don't trample over anybody else's
+space. Additionally, there are a few helper functions that live in
+`<vcpkg-test/util.h>` and `src/vcpkg-test/util.cpp` -- make sure to look into
+them so that you're not rewriting functionality.
+
+That should be all you need to know to start writing your own tests!
+Remember to check out the [Catch2 documentation]
+if you'd like to get more advanced with your tests,
+and good luck on your testing journey!
+
+Adding New Test Files
+---------------------
+
+Adding new test files should be easy and straightforward. All it requires is
+creating a new source file in `toolsrc/src/vcpkg-test`, and then rerunning
+`CMake` in order to pick up the glob changes.
+
+### Example
+
+Let's try writing a new test file called `example` (very creative, I know).
+
+First, we should create a file, `example.cpp`, in `toolsrc/src/vcpkg-test`:
+
+```cpp
+// vcpkg-test/example.cpp
+#include <vcpkg-test/catch.h>
+```
+
+This is the minimum file needed for tests; let's rebuild our CMake directory.
+You'll have to clean out the existing `out` directory for CMake to rerun
+globbing.
+
+```sh
+$ cmake .. -DCMAKE_BUILD_TYPE=Debug -G Ninja
+# ...
+-- Build files have been written to: $VCPKG_DIRECTORY/toolsrc/out
+$ cmake --build .
+[80/80] Linking CXX executable vcpkg.exe
+```
+
+Okay, now let's make sure this worked; add a test case to `example.cpp`:
+
+```cpp
+TEST_CASE("Example 1 - fail", "[example]") {
+  REQUIRE(false);
+}
+```
+
+Now build the tests again, and run them:
+
+```sh
+$ cmake --build .
+[2/2] Linking CXX executable vcpkg-test.exe
+$ ./vcpkg-test
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vcpkg-test.exe is a Catch v2.9.1 host application.
+Run with -? for options
+
+-------------------------------------------------------------------------------
+Example 1 - fail
+-------------------------------------------------------------------------------
+$VCPKG_DIRECTORY/toolsrc/src/vcpkg-test/example.cpp(3)
+...............................................................................
+
+$VCPKG_DIRECTORY/toolsrc/src/vcpkg-test/example.cpp(14): FAILED:
+  REQUIRE( false )
+
+===============================================================================
+test cases:  102 |  101 passed | 1 failed
+assertions: 3611 | 3610 passed | 1 failed
+```
+
+Hopefully, that worked! It should compile correctly, and have one failing test.
+Now let's try a more complex test, after deleting the old one;
+
+```cpp
+// add #include <vcpkg/base/strings.h> to the top of the file
+namespace Strings = vcpkg::Strings;
+
+TEST_CASE("Example 2 - success", "[example]") {
+  std::string hello = "Hello";
+  REQUIRE(Strings::case_insensitive_ascii_equals(hello, "hELLo"));
+  REQUIRE_FALSE(Strings::case_insensitive_ascii_starts_with(hello, "E"));
+}
+```
+
+Now compile and build the tests, and this time let's only run our example tests:
+
+```sh
+$ cmake --build .
+[2/2] Linking CXX executable vcpkg-test.exe
+$ ./vcpkg-test [example]
+Filters: [example]
+===============================================================================
+All tests passed (2 assertions in 1 test case)
+```
+
+Hopefully you have one test running and succeeding! If you have that, you have
+succeeded at adding a new file to vcpkg's tests. Congratulations! Have fun on
+the rest of your journey 🐱‍👤😁
+
+[Catch2 documentation]: https://github.com/catchorg/Catch2/blob/master/docs/tutorial.md#top
-- 
cgit v1.2.3


From 4d551ff4b3cea2f387b02ed69486a23b1be2fd73 Mon Sep 17 00:00:00 2001
From: Robert Schumacher <roschuma@microsoft.com>
Date: Fri, 2 Aug 2019 15:42:17 -0700
Subject: [vcpkg-docs] Reword and reorganize overlay-triplets-linux-dynamic.md
 (#7502)

---
 docs/examples/overlay-triplets-linux-dynamic.md | 84 ++++++++-----------------
 1 file changed, 26 insertions(+), 58 deletions(-)

(limited to 'docs')

diff --git a/docs/examples/overlay-triplets-linux-dynamic.md b/docs/examples/overlay-triplets-linux-dynamic.md
index 6168d85e6..b2868e2fd 100644
--- a/docs/examples/overlay-triplets-linux-dynamic.md
+++ b/docs/examples/overlay-triplets-linux-dynamic.md
@@ -1,66 +1,41 @@
-# Overlay triplets example: build dynamic libraries on Linux
+# Overlay triplets example
 
-Using **vcpkg** you can build libraries for the following triplets:
+## Building dynamic libraries on Linux
 
-<div>
-    <ul style="columns: 3;">
-        <li> arm-uwp</li>
-        <li> arm-windows</li>
-        <li> arm64-uwp</li>
-        <li> arm64-windows</li>
-        <li> x86-uwp</li>
-        <li> x86-windows</li>
-        <li> x86-windows-static</li>
-        <li> x64-uwp</li>
-        <li> x64-linux</li>
-        <li> x64-osx</li>
-        <li> x64-windows</li>
-        <li> x64-windows-static</li>
-    </ul>
-</div>
+Using **vcpkg** you can build libraries for many configurations out of the box. However, this doesn't currently include shared libraries on Linux and Mac OS.
 
+This doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms! This document will guide you through creating your own custom triplets with `--overlay-triplets` to easily build dynamic libraries on Linux.
 
-
-By design **vcpkg** builds only static libraries for Linux and Mac OS.
-However, this doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms.
-
-This document will guide you through creating your own custom triplets to build dynamic libraries on Linux using **vcpkg**.
-
-### Step 1: Create a folder to contain your custom triplets
-
-```
-~/vcpkg$ mkdir ../custom-triplets
-```
-
-### Step 2: Create the custom triplet files
+### Step 1: Create the custom triplet files
 
 To save time, copy the existing `x64-linux.cmake` triplet file.
 
-```
-~/vcpkg$ cp ./triplets/x64-linux.cmake ../custom-triplets/x64-linux-dynamic.cmake
+```sh
+~/git$ mkdir custom-triplets
+~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-dynamic.cmake
 ```
 
 And modify `custom-triplets/x64-linux-dynamic.cmake` to match the contents below:
-```
+```cmake
+# ~/git/custom-triplets/x64-linux-dynamic.cmake
 set(VCPKG_TARGET_ARCHITECTURE x64)
 set(VCPKG_CRT_LINKAGE dynamic)
-# Change VCPKG_LIBRARY_LINKAGE from static to dynamic
-set(VCPKG_LIBRARY_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE dynamic) # This changed from static to dynamic
 
 set(VCPKG_CMAKE_SYSTEM_NAME Linux)
 ```
 
-### Step 3: Use `--overlay-triplets` to build dynamic libraries
+### Step 2: Use `--overlay-triplets` to build dynamic libraries
 
 Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory. 
 
 ```
-./vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=../custom-triplets
+~/git$ vcpkg/vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=custom-triplets
 The following packages will be built and installed:
-    sqlite3[core]:x64-linux
+    sqlite3[core]:x64-linux-dynamic
 Starting package 1/1: sqlite3:x64-linux-dynamic
 Building package sqlite3[core]:x64-linux-dynamic...
--- Loading triplet configuration from: /home/custom-triplets/x64-linux-dynamic.cmake
+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux-dynamic.cmake
 -- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...
 -- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip
 -- Applying patch fix-arm-uwp.patch
@@ -84,7 +59,7 @@ The package sqlite3:x64-linux-dynamic provides CMake targets:
     target_link_libraries(main PRIVATE sqlite3)
 ```
 
-Overlay triplets will add your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`.
+Overlay triplets enables your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`.
 
 When using the `--overlay-triplets` option, a message like the following lets you know that a custom triplet is being used: 
 
@@ -94,40 +69,33 @@ When using the `--overlay-triplets` option, a message like the following lets yo
 
 ## Overriding default triplets
 
-As you may have noticed, the default triplets for Windows (`x86-windows` and `x64-windows`) install dynamic libraries, while a suffix (`-static`) is needed for static libraries. This is inconsistent with Linux and Mac OS where only static libraries are built.
+As you may have noticed, the default triplets for Windows (`x86-windows` and `x64-windows`) install dynamic libraries, while a suffix (`-static`) is needed for static libraries. This is different with Linux and Mac OS where static libraries are built by `x64-linux` and `x64-osx`.
 
 Using `--overlay-ports` it is possible to override the default triplets to accomplish the same behavior on Linux:
 
 * `x64-linux`: Builds dynamic libraries,
 * `x64-linux-static`: Builds static libraries.
 
-### Step 1: Create the overriden triplet
-
-Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`.
-
-```
-~/vcpkg$ mv ../custom-triplets/x64-linux-dynamic.cmake ../custom-triplets/x64-linux.cmake
-```
+### Step 1: Create the overlay triplets
 
-### Step 2: Copy and rename the default triplet
+Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`. Then, copy the default `x64-linux` triplet (which builds static libraries) in your `custom-triplets` folder and rename it to `x64-linux-static.cmake`.
 
-Then, copy the default `x64-linux` triplet (which builds static libraries) in your `/custom-triplets` folder and rename it to `x64-linux-static.cmake`.
-
-```
-~/vcpkg$ cp ./triplets/x64-linux.cmake ../custom-triplets/x64-linux-static.cmake
+```sh
+~/git$ mv custom-triplets/x64-linux-dynamic.cmake custom-triplets/x64-linux.cmake
+~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-static.cmake
 ```
 
-### Step 3: Use `--overlay-ports` to override default triplets
+### Step 2: Use `--overlay-ports` to override default triplets
 
 Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory.
 
 ```
-./vcpkg install sqlite3:x64-linux --overlay-triplets=../custom-triplets
+~/git$ vcpkg/vcpkg install sqlite3:x64-linux --overlay-triplets=custom-triplets
 The following packages will be built and installed:
     sqlite3[core]:x64-linux
 Starting package 1/1: sqlite3:x64-linux
 Building package sqlite3[core]:x64-linux...
--- Loading triplet configuration from: /home/custom-triplets/x64-linux.cmake
+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake
 -- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...
 -- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip
 -- Applying patch fix-arm-uwp.patch
@@ -154,5 +122,5 @@ The package sqlite3:x64-linux provides CMake targets:
 Note that the default triplet is masked by your custom triplet:
 
 ```
--- Loading triplet configuration from: /home/custom-triplets/x64-linux.cmake
+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake
 ```
-- 
cgit v1.2.3


From a3a6530631df905eb5c0e26d0b20d7d548e0c465 Mon Sep 17 00:00:00 2001
From: Victor Romero <romerosanchezv@gmail.com>
Date: Tue, 13 Aug 2019 20:13:55 -0700
Subject: [vcpkg_check_features] Set output variable explicitly and allow
 reverse-logic check (#7558)

* [vcpkg_check_features] Set OUT_EXPAND_OPTIONS explicitly

* [vcpkg_check_features] Allow reverse logic for features

* [vcpkg_check_features] Document new parameters

* [vcpkg_check_features] Remove unnecessary logging

* Do not create variables for each feature only set OUT_FEATURE_OPTIONS

* Improve documentation

* Update ports that use vcpkg_check_features()

* Missing documentation updates

* [pcl] Fix tools feature

* [opencv,opencv4] Fix usage of vcpkg_check_features()

* [opencv4] Fix typo
---
 docs/maintainers/portfile-functions.md     |   1 +
 docs/maintainers/vcpkg_check_features.md   | 171 +++++++++++++++++++++--------
 docs/maintainers/vcpkg_configure_cmake.md  |  10 +-
 docs/maintainers/vcpkg_prettify_command.md |  17 +++
 4 files changed, 148 insertions(+), 51 deletions(-)
 create mode 100644 docs/maintainers/vcpkg_prettify_command.md

(limited to 'docs')

diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index b98d89192..eadebf49a 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -24,4 +24,5 @@
 - [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md)
 - [vcpkg\_install\_cmake](vcpkg_install_cmake.md)
 - [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md)
+- [vcpkg\_prettify\_command](vcpkg_prettify_command.md)
 - [vcpkg\_test\_cmake](vcpkg_test_cmake.md)
diff --git a/docs/maintainers/vcpkg_check_features.md b/docs/maintainers/vcpkg_check_features.md
index 46ee9051a..cec01dde2 100644
--- a/docs/maintainers/vcpkg_check_features.md
+++ b/docs/maintainers/vcpkg_check_features.md
@@ -1,71 +1,148 @@
 # vcpkg_check_features
-
-Check if one or more features are a part of the package installation.
+Check if one or more features are a part of a package installation.
 
 ## Usage
 ```cmake
 vcpkg_check_features(
-    <feature1> <output_variable1>
-    [<feature2> <output_variable2>]
-    ...
+  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: 
 
-`vcpkg_check_features` accepts a list of (feature, output_variable) pairs. If a feature is specified, the corresponding output variable will be set as `ON`, or `OFF` otherwise. The syntax is similar to the `PROPERTIES` argument of `set_target_properties`.
+* `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. 
 
-`vcpkg_check_features` will create a variable `FEATURE_OPTIONS` in the parent scope, which you can pass as a part of `OPTIONS` argument when calling functions like `vcpkg_config_cmake`:
-```cmake
-vcpkg_config_cmake(
-    SOURCE_PATH ${SOURCE_PATH}
-    PREFER_NINJA
-    OPTIONS
-        -DBUILD_TESTING=ON
-        ${FEATURE_OPTIONS}
-)
-```
 
 ## 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_check_features(<feature> <output_variable>)
-```
-can be used as a replacement of:
-```cmake
-if(<feature> IN_LIST FEATURES)
-    set(<output_variable> ON)
-else()
-    set(<output_variable> OFF)
-endif()
+$ ./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}
+)
 ```
 
-However, if you have a feature that was checked like this before:
+### Example 2: Inverted features
+
 ```cmake
-if(<feature> IN_LIST FEATURES)
-    set(<output_variable> OFF)
-else()
-    set(<output_variable> ON)
-endif()
+$ ./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}
+)
 ```
-then you should not use `vcpkg_check_features` instead. [```oniguruma```](https://github.com/microsoft/vcpkg/blob/master/ports/oniguruma/portfile.cmake), for example, has a feature named `non-posix` which is checked with:
+
+### Example 3: Set multiple options for same feature
+
 ```cmake
-if("non-posix" IN_LIST FEATURES)
-    set(ENABLE_POSIX_API OFF)
-else()
-    set(ENABLE_POSIX_API ON)
-endif()
-```
-and by replacing these code with:
+$ ./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_check_features(non-posix ENABLE_POSIX_API)
-```
-is totally wrong.
+$ ./vcpkg install rocksdb[tbb]
 
-`vcpkg_check_features` is supposed to be called only once. Otherwise, the `FEATURE_OPTIONS` variable set by a previous call will be overwritten.
+# 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
+)
 
-## Examples
+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)
 
-* [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
-* [xsimd](https://github.com/microsoft/vcpkg/blob/master/ports/xsimd/portfile.cmake)
-* [xtensor](https://github.com/microsoft/vcpkg/blob/master/ports/xtensor/portfile.cmake)
 
 ## Source
 [scripts/cmake/vcpkg_check_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)
diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md
index b78ef54d9..ebbd92ed1 100644
--- a/docs/maintainers/vcpkg_configure_cmake.md
+++ b/docs/maintainers/vcpkg_configure_cmake.md
@@ -18,14 +18,15 @@ vcpkg_configure_cmake(
 
 ## Parameters
 ### SOURCE_PATH
-Specifies the directory containing the `CMakeLists.txt`. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+Specifies the directory containing the `CMakeLists.txt`.
+By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
 
 ### PREFER_NINJA
-Indicates that, when available, Vcpkg should use Ninja to perform the build. This should be specified unless the port is known to not work under Ninja.
+Indicates that, when available, Vcpkg should use Ninja to perform the build.
+This should be specified unless the port is known to not work under Ninja.
 
 ### DISABLE_PARALLEL_CONFIGURE
 Disables running the CMake configure step in parallel.
-
 This is needed for libraries which write back into their source directory during configure.
 
 ### NO_CHARSET_FLAG
@@ -36,7 +37,8 @@ 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".
+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.
diff --git a/docs/maintainers/vcpkg_prettify_command.md b/docs/maintainers/vcpkg_prettify_command.md
new file mode 100644
index 000000000..1856e06b4
--- /dev/null
+++ b/docs/maintainers/vcpkg_prettify_command.md
@@ -0,0 +1,17 @@
+# vcpkg_prettify_command
+
+Turns list of command arguments into a formatted string.
+
+## Usage
+```cmake
+vcpkg_prettify_command()
+```
+
+## Examples
+
+* `scripts/cmake/vcpkg_execute_build_process.cmake`
+* `scripts/cmake/vcpkg_execute_required_process.cmake`
+* `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
+
+## Source
+[scripts/cmake/vcpkg_prettify_command.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_prettify_command.cmake)
-- 
cgit v1.2.3


From 8e7ce6d91a060bba5f9e252a5d9aad92f5bd4a56 Mon Sep 17 00:00:00 2001
From: Victor Romero <romerosanchezv@gmail.com>
Date: Mon, 19 Aug 2019 12:28:30 -0700
Subject: Add guideline for VCPKG_<LANG>_FLAGS (#7751)

---
 docs/maintainers/maintainer-guide.md | 85 ++++++++++++++++++++++++++++--------
 1 file changed, 67 insertions(+), 18 deletions(-)

(limited to 'docs')

diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md
index e4938844f..f52172356 100644
--- a/docs/maintainers/maintainer-guide.md
+++ b/docs/maintainers/maintainer-guide.md
@@ -1,26 +1,37 @@
 # Maintainer Guidelines and Policies
 
-This document lists a set of policies that you should apply when adding or updating a port recipe. It is intended to serve the role of [Debian's Policy Manual](https://www.debian.org/doc/debian-policy/), [Homebrew's Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines), and [Homebrew's Formula Cookbook](https://docs.brew.sh/Formula-Cookbook).
+This document lists a set of policies that you should apply when adding or updating a port recipe. 
+It is intended to serve the role of 
+[Debian's Policy Manual](https://www.debian.org/doc/debian-policy/), 
+[Homebrew's Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines), and 
+[Homebrew's Formula Cookbook](https://docs.brew.sh/Formula-Cookbook).
 
 ## PR Structure
 
 ### Make separate Pull Requests per port
 
-Whenever possible, separate changes into multiple PR's. This makes them significantly easier to review and prevents issues with one set of changes from holding up every other change.
+Whenever possible, separate changes into multiple PRs. 
+This makes them significantly easier to review and prevents issues with one set of changes from holding up every other change.
 
 ### Avoid trivial changes in untouched files
 
-For example, avoid reformatting or renaming variables in portfiles that otherwise have no reason to be modified for the issue at hand. However, if you need to modify the file for the primary purpose of the PR (updating the library), then obviously beneficial changes like fixing typos are appreciated!
+For example, avoid reformatting or renaming variables in portfiles that otherwise have no reason to be modified for the issue at hand. 
+However, if you need to modify the file for the primary purpose of the PR (updating the library), 
+then obviously beneficial changes like fixing typos are appreciated!
 
 ### Check names against other repositories
 
-A good service to check many at once is [Repology](https://repology.org/). If the library you are adding could be confused with another one, consider renaming to make it clear.
+A good service to check many at once is [Repology](https://repology.org/). 
+If the library you are adding could be confused with another one, 
+consider renaming to make it clear.
 
 ### Use GitHub Draft PRs
 
-GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge. Most new PRs should be opened as drafts and converted to normal PRs once the CI passes.
+GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge. 
+Most new PRs should be opened as drafts and converted to normal PRs once the CI passes.
 
-More information about GitHub Draft PRs: https://github.blog/2019-02-14-introducing-draft-pull-requests/
+More information about GitHub Draft PRs: 
+https://github.blog/2019-02-14-introducing-draft-pull-requests/
 
 ## Portfiles
 
@@ -28,29 +39,33 @@ More information about GitHub Draft PRs: https://github.blog/2019-02-14-introduc
 
 At this time, the following helpers are deprecated:
 
-1. `vcpkg_extract_archive()` should be replaced by `vcpkg_extract_archive_ex()`
-2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. `vcpkg_from_github()`)
-3. `vcpkg_build_msbuild()` should be replaced by `vcpkg_install_msbuild()`
+1. `vcpkg_extract_archive()` should be replaced by [`vcpkg_extract_archive_ex()`](vcpkg_extract_archive_ex.md)
+2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md))
+3. `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md)
 
 ### Avoid excessive comments in portfiles
 
-Ideally, portfiles should be short, simple, and as declarative as possible. Remove any boiler plate comments introduced by the `create` command before submitting a PR.
+Ideally, portfiles should be short, simple, and as declarative as possible. 
+Remove any boiler plate comments introduced by the `create` command before submitting a PR.
 
 ## Build Techniques
 
 ### Do not use vendored dependencies
 
-Do not use embedded copies of libraries. All dependencies should be split out and packaged separately so they can be updated and maintained.
+Do not use embedded copies of libraries. 
+All dependencies should be split out and packaged separately so they can be updated and maintained.
 
 ### Prefer using CMake
 
-When multiple buildsystems are available, prefer using CMake. Additionally, when appropriate, it can be easier and more maintainable to rewrite alternative buildsystems into CMake using `file(GLOB)` directives.
+When multiple buildsystems are available, prefer using CMake. 
+Additionally, when appropriate, it can be easier and more maintainable to rewrite alternative buildsystems into CMake using `file(GLOB)` directives.
 
 Examples: [abseil](../../ports/abseil/portfile.cmake)
 
 ### Choose either static or shared binaries
 
-By default, `vcpkg_configure_cmake()` will pass in the appropriate setting for `BUILD_SHARED_LIBS`, however for libraries that don't respect that variable, you can switch on `VCPKG_LIBRARY_LINKAGE`:
+By default, `vcpkg_configure_cmake()` will pass in the appropriate setting for `BUILD_SHARED_LIBS`, 
+however for libraries that don't respect that variable, you can switch on `VCPKG_LIBRARY_LINKAGE`:
 
 ```cmake
 string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)
@@ -67,19 +82,37 @@ vcpkg_configure_cmake(
 
 ### When defining features, explicitly control dependencies
 
-When defining a feature that captures an optional dependency, ensure that the dependency will not be used accidentally when the feature is not explicitly enabled. For example:
+When defining a feature that captures an optional dependency, 
+ensure that the dependency will not be used accidentally when the feature is not explicitly enabled. 
 
 ```cmake
-set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
-if("zlib" IN_LIST FEATURES)
-    set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
+if ("zlib" IN_LIST FEATURES)
+  set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
+else()
+  set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
 endif()
 
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    -CMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
+)
+```
+
+The snippet below using `vcpkg_check_features()` is equivalent,  [see the documentation](vcpkg_check_features.md).
+
+```cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+  INVERTED_FEATURES
+    "zlib"    CMAKE_DISABLE_FIND_PACKAGE_ZLIB
+)
+
 vcpkg_configure_cmake(
     SOURCE_PATH ${SOURCE_PATH}
     PREFER_NINJA
     OPTIONS
-        -DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
+      ${FEATURE_OPTIONS}    
 )
 ```
 
@@ -125,6 +158,22 @@ Common options that allow avoiding patching:
 2. [CMAKE] Calls to `find_package(XYz)` in CMake scripts can be disabled via [`-DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON`](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html)
 3. [CMAKE] Cache variables (declared as `set(VAR "value" CACHE STRING "Documentation")` or `option(VAR "Documentation" "Default Value")`) can be overriden by just passing them in on the command line as `-DVAR:STRING=Foo`. One notable exception is if the `FORCE` parameter is passed to `set()`. See also the [CMake `set` documentation](https://cmake.org/cmake/help/v3.15/command/set.html)
 
+### Prefer patching over overriding `VCPKG_<VARIABLE>` values
+
+Some variables prefixed with `VCPKG_<VARIABLE>` have an equivalent `CMAKE_<VARIABLE>`.  
+However, not all of them are passed to the internal package build [(see implementation: Windows toolchain)](../../scripts/toolchains/windows.cmake).
+
+Consider the following example:
+
+```cmake
+set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}")
+set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}")
+```
+
+Using `vcpkg`'s built-in toolchains this works, because the value of `VCPKG_<LANG>_FLAGS` is forwarded to the appropriate `CMAKE_LANG_FLAGS` variable. But, a custom toolchain that is not aware of `vcpkg`'s variables will not forward them.
+
+Because of this, it is preferable to patch the buildsystem directly when setting `CMAKE_<LANG>_FLAGS`.
+
 ### Minimize patches
 
 When making changes to a library, strive to minimize the final diff. This means you should _not_ reformat the upstream source code when making changes that affect a region. Also, when disabling a conditional, it is better to add a `AND FALSE` or `&& 0` to the condition than to delete every line of the conditional.
-- 
cgit v1.2.3


From 2a81a2d3220353fa8a5890e234b77cadc2c4b589 Mon Sep 17 00:00:00 2001
From: nicole mazzuca <mazzucan@outlook.com>
Date: Sat, 24 Aug 2019 11:36:12 -0700
Subject: [vcpkg docs] More tool maintainer docs! (#7821)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* [vcpkg docs] Add benchmarking 🏎 to the docs!

Also, minor changes to the testing docs.

* add documentation for the layout of the project
---
 docs/index.md                         |   2 +
 docs/tool-maintainers/benchmarking.md | 195 ++++++++++++++++++++++++++++++++++
 docs/tool-maintainers/layout.md       |  85 +++++++++++++++
 docs/tool-maintainers/testing.md      |  36 +++----
 4 files changed, 295 insertions(+), 23 deletions(-)
 create mode 100644 docs/tool-maintainers/benchmarking.md
 create mode 100644 docs/tool-maintainers/layout.md

(limited to 'docs')

diff --git a/docs/index.md b/docs/index.md
index b2f0a53b2..579b0e4c8 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -24,6 +24,8 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 ### Tool Maintainer Help
 
 - [Testing](tool-maintainers/testing.md)
+- [Benchmarking](tool-maintainers/benchmarking.md)
+- [Layout of the vcpkg source tree](tool-maintainers/layout.md)
 - [Maintainer Guidelines](maintainers/maintainer-guide.md)
 
 ### Specifications
diff --git a/docs/tool-maintainers/benchmarking.md b/docs/tool-maintainers/benchmarking.md
new file mode 100644
index 000000000..e0295be50
--- /dev/null
+++ b/docs/tool-maintainers/benchmarking.md
@@ -0,0 +1,195 @@
+# Benchmarking
+
+Benchmarking new code against old code is extremely important whenever making
+large changes to how something works. If you are attempting to make something
+faster, and you end up slowing it down, you'll never know if you don't
+benchmark! We have benchmarks in the `toolsrc/src/vcpkg-test` directory, just
+like the tests -- they're treated as a special kind of test.
+
+## Running Benchmarks
+
+Unlike normal tests, benchmarks are hidden behind a special define -- `CATCH_CONFIG_ENABLE_BENCHMARKING` -- so that you never try to run benchmarks
+unless you specifically want to. This is because benchmarks actually take quite
+a long time! However, if you want to run benchmarks (and I recommend running
+only specific benchmarks at a time), you can do so by passing the
+`VCPKG_ENABLE_BENCHMARKING` option at cmake configure time.
+
+```sh
+$ cmake -B toolsrc/out -S toolsrc -G Ninja \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DVCPKG_BUILD_BENCHMARKING=On
+
+-- The C compiler identification is MSVC 19.22.27905.0
+-- The CXX compiler identification is MSVC 19.22.27905.0
+-- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe
+-- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe -- works
+-- Detecting C compiler ABI info
+-- Detecting C compiler ABI info - done
+-- Detecting C compile features
+-- Detecting C compile features - done
+-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe
+-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe -- works
+-- Detecting CXX compiler ABI info
+-- Detecting CXX compiler ABI info - done
+-- Detecting CXX compile features
+-- Detecting CXX compile features - done
+-- Looking for pthread.h
+-- Looking for pthread.h - not found
+-- Found Threads: TRUE
+-- Configuring done
+-- Generating done
+-- Build files have been written to: C:/Users/t-nimaz/src/vcpkg/toolsrc/out
+
+$ cmake --build toolsrc/out
+
+[0/2] Re-checking globbed directories...
+[80/80] Linking CXX executable vcpkg-test.exe
+```
+
+You can then run benchmarks easily with the following command (which run the
+files benchmarks):
+
+```sh
+$ ./toolsrc/out/vcpkg-test [!benchmark][file]
+```
+
+You can switch out `[file]` for a different set -- `[hash]`, for example.
+
+## Writing Benchmarks
+
+First, before anything else, I recommend reading the
+[benchmarking documentation] at Catch2's repository.
+
+Now, after that, let's say that you wanted to benchmark, say, our ASCII
+case-insensitive string compare against your new implementation. We place
+benchmarks for code in the same file as their tests, so open
+`vcpkg-test/strings.cpp`, and add the following at the bottom:
+
+```cpp
+#if defined(CATCH_CONFIG_ENABLE_BENCHMARKING)
+TEST_CASE ("case insensitive ascii equals: benchmark", "[strings][!benchmark]")
+{
+    BENCHMARK("qwertyuiop") {
+        return vcpkg::Strings::case_insensitive_ascii_equals("qwertyuiop", "QWERTYUIOP");
+    };
+}
+#endif
+```
+
+Remember the `;` at the end of the benchmark -- it's not required for
+`TEST_CASE`s, but is for `BENCHMARK`s.
+
+Now, let's rebuild and run:
+
+```sh
+$ cmake --build toolsrc/out
+[0/2] Re-checking globbed directories...
+[2/2] Linking CXX executable vcpkg-test.exe
+$ ./toolsrc/out/vcpkg-test [strings][!benchmark]
+Filters: [strings][!benchmark]
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vcpkg-test.exe is a Catch v2.9.1 host application.
+Run with -? for options
+
+-------------------------------------------------------------------------------
+case insensitive ascii equals: benchmark
+-------------------------------------------------------------------------------
+C:\Users\t-nimaz\src\vcpkg\toolsrc\src\vcpkg-test\strings.cpp(36)
+...............................................................................
+
+benchmark name                                  samples       iterations    estimated
+                                                mean          low mean      high mean
+                                                std dev       low std dev   high std dev
+-------------------------------------------------------------------------------
+qwertyuiop                                              100         2088    3.9672 ms
+                                                      25 ns        24 ns        26 ns
+                                                       6 ns         5 ns         8 ns
+
+
+===============================================================================
+test cases: 1 | 1 passed
+assertions: - none -
+```
+
+You've now written your first benchmark!
+
+But wait. This seems kind of silly. Benchmarking the comparison of literal
+strings is great and all, but could we make it a little more realistic?
+
+This is where `BENCHMARK_ADVANCED` comes in. `BENCHMARK_ADVANCED` allows one to
+write a benchmark that has a little setup to it without screwing up the numbers.
+Let's try it now:
+
+```cpp
+TEST_CASE ("case insensitive ascii equals: benchmark", "[strings][!benchmark]")
+{
+    BENCHMARK_ADVANCED("equal strings")(Catch::Benchmark::Chronometer meter)
+    {
+        std::vector<std::string> strings;
+        strings.resize(meter.runs());
+        std::mt19937_64 urbg;
+        std::uniform_int_distribution<std::uint64_t> data_generator;
+
+        std::generate(strings.begin(), strings.end(), [&] {
+            std::string result;
+            for (std::size_t i = 0; i < 1000; ++i)
+            {
+                result += vcpkg::Strings::b32_encode(data_generator(urbg));
+            }
+
+            return result;
+        });
+
+        meter.measure(
+            [&](int run) { return vcpkg::Strings::case_insensitive_ascii_equals(strings[run], strings[run]); });
+    };
+}
+```
+
+Then, run it again!
+
+```sh
+$ cmake --build toolsrc/out
+[0/2] Re-checking globbed directories...
+[2/2] Linking CXX executable vcpkg-test.exe
+$ toolsrc/out/vcpkg-test [strings][!benchmark]
+Filters: [strings][!benchmark]
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vcpkg-test.exe is a Catch v2.9.1 host application.
+Run with -? for options
+
+-------------------------------------------------------------------------------
+case insensitive ascii equals: benchmark
+-------------------------------------------------------------------------------
+C:\Users\t-nimaz\src\vcpkg\toolsrc\src\vcpkg-test\strings.cpp(36)
+...............................................................................
+
+benchmark name                                  samples       iterations    estimated
+                                                mean          low mean      high mean
+                                                std dev       low std dev   high std dev
+-------------------------------------------------------------------------------
+equal strings                                           100            2    5.4806 ms
+                                                  22.098 us    21.569 us    23.295 us
+                                                   3.842 us     2.115 us      7.41 us
+
+
+===============================================================================
+test cases: 1 | 1 passed
+assertions: - none -
+```
+
+And now you have a working benchmark to test the speed of the existing code, and
+of new code!
+
+If you're writing a lot of benchmarks that follow the same sort of pattern, with
+some differences in constants, look into `vcpkg-test/files.cpp`'s benchmarks --
+there are a lot of things one can do to make writing new benchmarks really easy.
+
+If you wish to add a benchmark for a piece of code that has not yet been tested,
+please read the [testing documentation], and please write some unit tests.
+The speed of your code isn't very important if it doesn't work at all!
+
+[benchmarking documentation]: https://github.com/catchorg/Catch2/blob/master/docs/benchmarks.md#top
+[testing documentation]: ./testing.md#adding-new-test-files
diff --git a/docs/tool-maintainers/layout.md b/docs/tool-maintainers/layout.md
new file mode 100644
index 000000000..9779b0434
--- /dev/null
+++ b/docs/tool-maintainers/layout.md
@@ -0,0 +1,85 @@
+# Layout of the vcpkg source tree
+
+All vcpkg sources and build systems are in `toolsrc`. If you'd like to
+contribute to the vcpkg tool itself, most of your time will be spent in here.
+
+## Build Files
+
+These are the files used to build and configure the project. In order to build
+with CMake, the only files you should be interested in are `CMakeLists.txt`, and
+`.clang-format`; in order to build with msbuild or the Visual Studio IDE, you
+will be interested in `dirs.proj` or `vcpkg.sln`. However, if you add or remove
+files, you will need to edit the MSBuild project files in the `vcpkg*`
+directories no matter what system you use.
+
+### Top Level
+
+We have six files in this directory -- one `.clang-format` file, one
+`CMakeLists.txt` file, three Visual Studio files, and `VERSION.txt`.
+
+  - `.clang-format`: This is where we store the formatting settings of the
+    project. If you want to format the project, you can use the `format` target
+    with the CMake build system.
+  - `CMakeLists.txt`: This is where the CMake build system definition lives. If
+    you want to modify how one builds the project, or add a target, you can do
+    it here.
+  - `VERSION.txt`: This is a file which tells `vcpkg` to tell the user to
+    rebuild. If this version is different from the version when the user built
+    the binary (for example, after a `git pull` or a `vcpkg update`), then
+    `vcpkg` will print a message to re-bootstrap. This is updated whenever major
+    changes are made to the `vcpkg` tool.
+  - The Visual Studio files:
+    - `vcpkg.natvis`: NATVIS files allow one to visualize objects of user
+      defined type in the debugger -- this one contains the definitions for
+      `vcpkg`'s types.
+    - `dirs.proj`: This is how one builds with `msbuild` without calling into
+      the IDE.
+    - `vcpkg.sln`: The solution file is how one opens the project in the VS IDE.
+
+### `vcpkg`, `vcpkglib`, `vcpkgmetricsuploader`, and `vcpkgtest`
+
+These four contain exactly one `<name>.vcxproj` and one
+`<name>.vcxproj.filters`. The `<name>.vcxproj` file contains the source files
+and the `<name>.vcxproj.filters` contains information on how Visual Studio
+should lay out the project's source files in the IDE's project view.
+
+`vcpkgtest` should not be touched. It's likely that it will be deleted soon. If
+you want to test your code, use the cmake build system.
+
+## Source Files
+
+If you're modifying the project, it's likely that these are the directories that
+you're going to deal with.
+
+### `include`
+
+There's one file in here -- `pch.h`. This contains most of the C++ standard
+library, and acts as a [precompiled header]. You can read more at the link.
+
+There are three directories:
+
+  - `catch2` -- This contains the single-header library [catch2]. We use this
+    library for both [testing] and [benchmarking].
+  - `vcpkg` -- This contains the header files for the `vcpkg` project. All of
+    the interfaces for building, installing, and generally "port stuff" live
+    here.
+    - `vcpkg/base` -- This contains the interfaces for the
+      "vcpkg standard library" -- file handling, hashing, strings,
+      `Span<T>`, printing, etc.
+  - `vcpkg-test` -- This contains the interfaces for any common utilities
+    required by the tests.
+
+### `src`
+
+The source files live here. `pch.cpp` is the source file for the
+[precompiled header]; `vcpkg.cpp` is where the `vcpkg` binary lives; and
+`vcpkgmetricsuploader.cpp` is where the metrics uploader lives.
+
+The interesting files live in the `vcpkg` and `vcpkg-test` directories. In
+`vcpkg`, you have the implementation for the interfaces that live in
+`include/vcpkg`; and in `vcpkg-test`, you have the tests and benchmarks.
+
+[precompiled header]: https://en.wikipedia.org/wiki/Precompiled_header
+[catch2]: https://github.com/catchorg/Catch2
+[testing]: ./testing.md
+[benchmarking]: ./benchmarking.md
diff --git a/docs/tool-maintainers/testing.md b/docs/tool-maintainers/testing.md
index 28cc9e099..0284a2650 100644
--- a/docs/tool-maintainers/testing.md
+++ b/docs/tool-maintainers/testing.md
@@ -1,13 +1,11 @@
-Testing
-=======
+# Testing
 
 Testing vcpkg is important whenever one makes changes to the tool itself, and
 writing new tests and keeping them up to date is also very important. If one's
 code is subtly broken, we'd rather find it out right away than a few weeks down
 the line when someone complains!
 
-Running Tests
--------------
+## Running Tests
 
 Before anything else, we should know whether you can actually run the tests!
 All you should need is a way to build vcpkg -- anything will do! All you have to
@@ -27,8 +25,7 @@ $ # i.e., ./vcpkg-test [arguments]
 If you make any modifications to `vcpkg`, you'll have to do the
 `cmake --build .` step again.
 
-Writing Tests
--------------
+## Writing Tests
 
 In your journey to write new tests, and to modify existing tests, reading the
 [Catch2 documentation] will be very helpful! Come back after reading those 😀
@@ -42,8 +39,8 @@ The layout of these tests is as follows:
 // ... includes
 
 TEST_CASE("Name of test", "[filename without the .cpp]") {
-  // setup and the like
-  REQUIRE(some boolean expression);
+    // setup and the like
+    REQUIRE(some boolean expression);
 }
 
 // etc.
@@ -67,12 +64,10 @@ Remember to check out the [Catch2 documentation]
 if you'd like to get more advanced with your tests,
 and good luck on your testing journey!
 
-Adding New Test Files
----------------------
+## Adding New Test Files
 
 Adding new test files should be easy and straightforward. All it requires is
-creating a new source file in `toolsrc/src/vcpkg-test`, and then rerunning
-`CMake` in order to pick up the glob changes.
+creating a new source file in `toolsrc/src/vcpkg-test`.
 
 ### Example
 
@@ -85,14 +80,9 @@ First, we should create a file, `example.cpp`, in `toolsrc/src/vcpkg-test`:
 #include <vcpkg-test/catch.h>
 ```
 
-This is the minimum file needed for tests; let's rebuild our CMake directory.
-You'll have to clean out the existing `out` directory for CMake to rerun
-globbing.
+This is the minimum file needed for tests; let's rebuild!
 
 ```sh
-$ cmake .. -DCMAKE_BUILD_TYPE=Debug -G Ninja
-# ...
--- Build files have been written to: $VCPKG_DIRECTORY/toolsrc/out
 $ cmake --build .
 [80/80] Linking CXX executable vcpkg.exe
 ```
@@ -101,7 +91,7 @@ Okay, now let's make sure this worked; add a test case to `example.cpp`:
 
 ```cpp
 TEST_CASE("Example 1 - fail", "[example]") {
-  REQUIRE(false);
+    REQUIRE(false);
 }
 ```
 
@@ -123,7 +113,7 @@ $VCPKG_DIRECTORY/toolsrc/src/vcpkg-test/example.cpp(3)
 ...............................................................................
 
 $VCPKG_DIRECTORY/toolsrc/src/vcpkg-test/example.cpp(14): FAILED:
-  REQUIRE( false )
+    REQUIRE( false )
 
 ===============================================================================
 test cases:  102 |  101 passed | 1 failed
@@ -138,9 +128,9 @@ Now let's try a more complex test, after deleting the old one;
 namespace Strings = vcpkg::Strings;
 
 TEST_CASE("Example 2 - success", "[example]") {
-  std::string hello = "Hello";
-  REQUIRE(Strings::case_insensitive_ascii_equals(hello, "hELLo"));
-  REQUIRE_FALSE(Strings::case_insensitive_ascii_starts_with(hello, "E"));
+    std::string hello = "Hello";
+    REQUIRE(Strings::case_insensitive_ascii_equals(hello, "hELLo"));
+    REQUIRE_FALSE(Strings::case_insensitive_ascii_starts_with(hello, "E"));
 }
 ```
 
-- 
cgit v1.2.3


From 65d4bc146bf7c1c21989b680497b1f6f9a09c967 Mon Sep 17 00:00:00 2001
From: Victor Romero <romerosanchezv@gmail.com>
Date: Wed, 28 Aug 2019 11:47:17 -0700
Subject: [vcpkg install] Enable Download Mode (#7797)

* [portfile functions] Override execute_process() to accept ALLOW_IN_DOWNLOAD_MODE option

* [vcpkg install] Set VCPKG_DOWNLOAD_MODE when using --only-downloads option

* [vcpkg_find_acquire_program] Allow in Download Mode

* Don't stop when build fails for a package

* Download sources for all packages in dependency graph

* Improve output messages

* Enable acquiring MSYS packages in download mode

* Documentation

* Update documentation

* execute_process() always fails on Download Mode

* Regenerate docs and fix formatting

* Run clang-format

* Use _execute_process on vcpkg_from_<source> helpers
---
 docs/maintainers/execute_process.md                | 10 +++++++
 docs/maintainers/portfile-functions.md             |  3 ++
 docs/maintainers/vcpkg_common_definitions.md       | 19 ++++++++++++
 docs/maintainers/vcpkg_execute_required_process.md |  4 +++
 docs/maintainers/vcpkg_fail_port_install.md        | 34 ++++++++++++++++++++++
 5 files changed, 70 insertions(+)
 create mode 100644 docs/maintainers/execute_process.md
 create mode 100644 docs/maintainers/vcpkg_common_definitions.md
 create mode 100644 docs/maintainers/vcpkg_fail_port_install.md

(limited to 'docs')

diff --git a/docs/maintainers/execute_process.md b/docs/maintainers/execute_process.md
new file mode 100644
index 000000000..cbb339509
--- /dev/null
+++ b/docs/maintainers/execute_process.md
@@ -0,0 +1,10 @@
+# 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 `_execute_process()` instead.
+
+
+## Source
+[scripts/cmake/execute_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)
diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index eadebf49a..bbd5d23ab 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -1,6 +1,7 @@
 <!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->
 
 # Portfile helper functions
+- [execute\_process](execute_process.md)
 - [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
 - [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
 - [vcpkg\_apply\_patches](vcpkg_apply_patches.md)
@@ -9,6 +10,7 @@
 - [vcpkg\_check\_features](vcpkg_check_features.md)
 - [vcpkg\_check\_linkage](vcpkg_check_linkage.md)
 - [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)
+- [vcpkg\_common\_definitions](vcpkg_common_definitions.md)
 - [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
 - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)
 - [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)
@@ -17,6 +19,7 @@
 - [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.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)
 - [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
 - [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)
 - [vcpkg\_from\_git](vcpkg_from_git.md)
diff --git a/docs/maintainers/vcpkg_common_definitions.md b/docs/maintainers/vcpkg_common_definitions.md
new file mode 100644
index 000000000..3bb922b17
--- /dev/null
+++ b/docs/maintainers/vcpkg_common_definitions.md
@@ -0,0 +1,19 @@
+# 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. only defined if <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)
+```
+
+CMAKE_STATIC_LIBRARY_PREFIX, CMAKE_STATIC_LIBRARY_SUFFIX, CMAKE_SHARED_LIBRARY_PREFIX, CMAKE_SHARED_LIBRARY_SUFFIX are 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)
diff --git a/docs/maintainers/vcpkg_execute_required_process.md b/docs/maintainers/vcpkg_execute_required_process.md
index 4b1a7e081..26a116782 100644
--- a/docs/maintainers/vcpkg_execute_required_process.md
+++ b/docs/maintainers/vcpkg_execute_required_process.md
@@ -11,6 +11,10 @@ vcpkg_execute_required_process(
 )
 ```
 ## 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.
 
diff --git a/docs/maintainers/vcpkg_fail_port_install.md b/docs/maintainers/vcpkg_fail_port_install.md
new file mode 100644
index 000000000..b3b48ad5e
--- /dev/null
+++ b/docs/maintainers/vcpkg_fail_port_install.md
@@ -0,0 +1,34 @@
+# vcpkg_fail_port_install
+
+Fails the current portfile with a (default) error message
+
+## Usage
+```cmake
+vcpkg_fail_port_install([MESSAGE <message>] 	[ON_TARGET <target1> [<target2> ...]]
+```
+
+## Parameters
+### MESSAGE
+Additional failure message. If non 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)
+
+## Source
+[scripts/cmake/vcpkg_fail_port_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake)
-- 
cgit v1.2.3


From 4b404e8cfbdde4277733adaacc399fa4e1b57320 Mon Sep 17 00:00:00 2001
From: Victor Romero <romerosanchezv@gmail.com>
Date: Wed, 28 Aug 2019 11:59:30 -0700
Subject: Revert "[vcpkg install] Enable Download Mode (#7797)" (#7949)

This reverts commit 65d4bc146bf7c1c21989b680497b1f6f9a09c967.
---
 docs/maintainers/execute_process.md                | 10 -------
 docs/maintainers/portfile-functions.md             |  3 --
 docs/maintainers/vcpkg_common_definitions.md       | 19 ------------
 docs/maintainers/vcpkg_execute_required_process.md |  4 ---
 docs/maintainers/vcpkg_fail_port_install.md        | 34 ----------------------
 5 files changed, 70 deletions(-)
 delete mode 100644 docs/maintainers/execute_process.md
 delete mode 100644 docs/maintainers/vcpkg_common_definitions.md
 delete mode 100644 docs/maintainers/vcpkg_fail_port_install.md

(limited to 'docs')

diff --git a/docs/maintainers/execute_process.md b/docs/maintainers/execute_process.md
deleted file mode 100644
index cbb339509..000000000
--- a/docs/maintainers/execute_process.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# 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 `_execute_process()` instead.
-
-
-## Source
-[scripts/cmake/execute_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)
diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index bbd5d23ab..eadebf49a 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -1,7 +1,6 @@
 <!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->
 
 # Portfile helper functions
-- [execute\_process](execute_process.md)
 - [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
 - [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
 - [vcpkg\_apply\_patches](vcpkg_apply_patches.md)
@@ -10,7 +9,6 @@
 - [vcpkg\_check\_features](vcpkg_check_features.md)
 - [vcpkg\_check\_linkage](vcpkg_check_linkage.md)
 - [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)
-- [vcpkg\_common\_definitions](vcpkg_common_definitions.md)
 - [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
 - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)
 - [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)
@@ -19,7 +17,6 @@
 - [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.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)
 - [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
 - [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)
 - [vcpkg\_from\_git](vcpkg_from_git.md)
diff --git a/docs/maintainers/vcpkg_common_definitions.md b/docs/maintainers/vcpkg_common_definitions.md
deleted file mode 100644
index 3bb922b17..000000000
--- a/docs/maintainers/vcpkg_common_definitions.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# 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. only defined if <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)
-```
-
-CMAKE_STATIC_LIBRARY_PREFIX, CMAKE_STATIC_LIBRARY_SUFFIX, CMAKE_SHARED_LIBRARY_PREFIX, CMAKE_SHARED_LIBRARY_SUFFIX are 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)
diff --git a/docs/maintainers/vcpkg_execute_required_process.md b/docs/maintainers/vcpkg_execute_required_process.md
index 26a116782..4b1a7e081 100644
--- a/docs/maintainers/vcpkg_execute_required_process.md
+++ b/docs/maintainers/vcpkg_execute_required_process.md
@@ -11,10 +11,6 @@ vcpkg_execute_required_process(
 )
 ```
 ## 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.
 
diff --git a/docs/maintainers/vcpkg_fail_port_install.md b/docs/maintainers/vcpkg_fail_port_install.md
deleted file mode 100644
index b3b48ad5e..000000000
--- a/docs/maintainers/vcpkg_fail_port_install.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# vcpkg_fail_port_install
-
-Fails the current portfile with a (default) error message
-
-## Usage
-```cmake
-vcpkg_fail_port_install([MESSAGE <message>] 	[ON_TARGET <target1> [<target2> ...]]
-```
-
-## Parameters
-### MESSAGE
-Additional failure message. If non 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)
-
-## Source
-[scripts/cmake/vcpkg_fail_port_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake)
-- 
cgit v1.2.3


From f5c732b40d43f062278f247036b773477823813b Mon Sep 17 00:00:00 2001
From: Victor Romero <romerosanchezv@gmail.com>
Date: Wed, 28 Aug 2019 13:49:29 -0700
Subject: Download Mode (#7950)

* [portfile functions] Override execute_process() to accept ALLOW_IN_DOWNLOAD_MODE option

* [vcpkg install] Set VCPKG_DOWNLOAD_MODE when using --only-downloads option

* [vcpkg_find_acquire_program] Allow in Download Mode

* Don't stop when build fails for a package

* Download sources for all packages in dependency graph

* Improve output messages

* Enable acquiring MSYS packages in download mode

* Documentation

* Update documentation

* execute_process() always fails on Download Mode

* Regenerate docs and fix formatting

* Run clang-format

* Use _execute_process on vcpkg_from_<source> helpers

* Fix calls to _execute_process() when not in Download Mode
---
 docs/maintainers/execute_process.md                | 10 +++++++
 docs/maintainers/portfile-functions.md             |  3 ++
 docs/maintainers/vcpkg_common_definitions.md       | 19 ++++++++++++
 docs/maintainers/vcpkg_execute_required_process.md |  4 +++
 docs/maintainers/vcpkg_fail_port_install.md        | 34 ++++++++++++++++++++++
 5 files changed, 70 insertions(+)
 create mode 100644 docs/maintainers/execute_process.md
 create mode 100644 docs/maintainers/vcpkg_common_definitions.md
 create mode 100644 docs/maintainers/vcpkg_fail_port_install.md

(limited to 'docs')

diff --git a/docs/maintainers/execute_process.md b/docs/maintainers/execute_process.md
new file mode 100644
index 000000000..cbb339509
--- /dev/null
+++ b/docs/maintainers/execute_process.md
@@ -0,0 +1,10 @@
+# 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 `_execute_process()` instead.
+
+
+## Source
+[scripts/cmake/execute_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)
diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index eadebf49a..bbd5d23ab 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -1,6 +1,7 @@
 <!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->
 
 # Portfile helper functions
+- [execute\_process](execute_process.md)
 - [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
 - [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
 - [vcpkg\_apply\_patches](vcpkg_apply_patches.md)
@@ -9,6 +10,7 @@
 - [vcpkg\_check\_features](vcpkg_check_features.md)
 - [vcpkg\_check\_linkage](vcpkg_check_linkage.md)
 - [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)
+- [vcpkg\_common\_definitions](vcpkg_common_definitions.md)
 - [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
 - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)
 - [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)
@@ -17,6 +19,7 @@
 - [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.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)
 - [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
 - [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)
 - [vcpkg\_from\_git](vcpkg_from_git.md)
diff --git a/docs/maintainers/vcpkg_common_definitions.md b/docs/maintainers/vcpkg_common_definitions.md
new file mode 100644
index 000000000..3bb922b17
--- /dev/null
+++ b/docs/maintainers/vcpkg_common_definitions.md
@@ -0,0 +1,19 @@
+# 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. only defined if <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)
+```
+
+CMAKE_STATIC_LIBRARY_PREFIX, CMAKE_STATIC_LIBRARY_SUFFIX, CMAKE_SHARED_LIBRARY_PREFIX, CMAKE_SHARED_LIBRARY_SUFFIX are 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)
diff --git a/docs/maintainers/vcpkg_execute_required_process.md b/docs/maintainers/vcpkg_execute_required_process.md
index 4b1a7e081..26a116782 100644
--- a/docs/maintainers/vcpkg_execute_required_process.md
+++ b/docs/maintainers/vcpkg_execute_required_process.md
@@ -11,6 +11,10 @@ vcpkg_execute_required_process(
 )
 ```
 ## 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.
 
diff --git a/docs/maintainers/vcpkg_fail_port_install.md b/docs/maintainers/vcpkg_fail_port_install.md
new file mode 100644
index 000000000..b3b48ad5e
--- /dev/null
+++ b/docs/maintainers/vcpkg_fail_port_install.md
@@ -0,0 +1,34 @@
+# vcpkg_fail_port_install
+
+Fails the current portfile with a (default) error message
+
+## Usage
+```cmake
+vcpkg_fail_port_install([MESSAGE <message>] 	[ON_TARGET <target1> [<target2> ...]]
+```
+
+## Parameters
+### MESSAGE
+Additional failure message. If non 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)
+
+## Source
+[scripts/cmake/vcpkg_fail_port_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake)
-- 
cgit v1.2.3


From 5d90c36ad5885b679ea24ff329e7fd62b6ff9464 Mon Sep 17 00:00:00 2001
From: shogerr <shogerr@oregonstate.edu>
Date: Thu, 19 Sep 2019 16:01:17 -0600
Subject: Add detailed instructions for custom configurations (#8258)

Resolves #2346
---
 docs/about/faq.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/about/faq.md b/docs/about/faq.md
index 504738479..6517774cf 100644
--- a/docs/about/faq.md
+++ b/docs/about/faq.md
@@ -52,11 +52,12 @@ Yes. While Vcpkg will only produce the standard "Release" and "Debug" configurat
 
 First of all, Vcpkg will automatically assume any custom configuration starting with "Release" (resp. "Debug") as a configuration that is compatible with the standard "Release" (resp. "Debug") configuration and will act accordingly.
 
-For other configurations, you only need to override the MSBuild `$(VcpkgConfiguration)` macro in your project file (.vcxproj) to declare the compatibility between your configuration, and the target standard configuration.
+For other configurations, you only need to override the MSBuild `$(VcpkgConfiguration)` macro in your project file (.vcxproj) to declare the compatibility between your configuration, and the target standard configuration. Unfortunately, due to the sequential nature of MSBuild, you'll need to add those settings much higher in your vcxproj so that it is declared before the Vcpk integration is loaded. It is recommend that the `$(VcpkgConfiguration)` macro is added to the "Globals" PropertyGroup.
 
 For example, you can add support for your "MyRelease" configuration by adding in your project file:
 ```
-<PropertyGroup>
+<PropertyGroup Label="Globals">
+  ...
   <VcpkgConfiguration Condition="'$(Configuration)' == 'MyRelease'">Release</VcpkgConfiguration>
 </PropertyGroup>
 ```
-- 
cgit v1.2.3


From d9932608863f57512db4b415ae6e14ff0bd6e11d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Wolfgang=20St=C3=B6ggl?= <c72578@yahoo.de>
Date: Sun, 29 Sep 2019 19:50:13 +0200
Subject: Fix a typo in maintainer-guide.md (#8383)

---
 docs/maintainers/maintainer-guide.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md
index f52172356..3a3a3a15a 100644
--- a/docs/maintainers/maintainer-guide.md
+++ b/docs/maintainers/maintainer-guide.md
@@ -156,7 +156,7 @@ It is preferable to set options in a call to `vcpkg_configure_xyz()` over patchi
 Common options that allow avoiding patching:
 1. [MSBUILD] `<PropertyGroup>` settings inside the project file can be overridden via `/p:` parameters
 2. [CMAKE] Calls to `find_package(XYz)` in CMake scripts can be disabled via [`-DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON`](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html)
-3. [CMAKE] Cache variables (declared as `set(VAR "value" CACHE STRING "Documentation")` or `option(VAR "Documentation" "Default Value")`) can be overriden by just passing them in on the command line as `-DVAR:STRING=Foo`. One notable exception is if the `FORCE` parameter is passed to `set()`. See also the [CMake `set` documentation](https://cmake.org/cmake/help/v3.15/command/set.html)
+3. [CMAKE] Cache variables (declared as `set(VAR "value" CACHE STRING "Documentation")` or `option(VAR "Documentation" "Default Value")`) can be overridden by just passing them in on the command line as `-DVAR:STRING=Foo`. One notable exception is if the `FORCE` parameter is passed to `set()`. See also the [CMake `set` documentation](https://cmake.org/cmake/help/v3.15/command/set.html)
 
 ### Prefer patching over overriding `VCPKG_<VARIABLE>` values
 
-- 
cgit v1.2.3


From 5ebf65665dfbf29abeb49410070c2102490fd476 Mon Sep 17 00:00:00 2001
From: Vinny <vpaladino778@gmail.com>
Date: Tue, 1 Oct 2019 11:21:04 -0400
Subject: [Documentation] Added documentation page for
 vcpkg_fixup_cmake_targets.cmake (#8365)

* Added documentation page for vcpkg_fixup_cmake_targets.cmake, added example usage comment to .cmake file

* Update cmake_fixup_cmake_targets.md

* Update cmake_fixup_cmake_targets.md
---
 docs/maintainers/cmake_fixup_cmake_targets.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 docs/maintainers/cmake_fixup_cmake_targets.md

(limited to 'docs')

diff --git a/docs/maintainers/cmake_fixup_cmake_targets.md b/docs/maintainers/cmake_fixup_cmake_targets.md
new file mode 100644
index 000000000..9bbaddbba
--- /dev/null
+++ b/docs/maintainers/cmake_fixup_cmake_targets.md
@@ -0,0 +1,25 @@
+# vcpkg_fixup_cmake_targets
+
+Transforms all /debug/share/\<port\>/\*targets-debug.cmake files and move them to /share/\<port\>.
+Removes all /debug/share/\<port\>/\*targets.cmake and /debug/share/\<port\>/\*config.cmake.
+
+Transforms all references matching /bin/\*.exe tools/\<port\>/\*.exe on Windows.
+Transforms all references matching /bin/\* to /tools/\<port\>/\* on other platforms.
+
+Fixups ${_IMPORT_PREFIX} in auto generated targets to be one folder deeper. 
+Replaces ${CURRENT_INSTALLED_DIR} with ${_IMPORT_PREFIX} in config files and targets.
+
+
+## Usage
+```cmake
+vcpkg_fixup_cmake_targets(CONFIG_PATH <config_path>)
+```
+
+## Parameters:
+### CONFIG_PATH
+*.cmake files subdirectory (e.g. "lib/cmake/${PORT}" or "cmake/${PORT}).
+### TARGET_PATH
+Optional location to place fixup'd files. Unecessary if target is "share/${PORT}".
+
+## Source
+[scripts/cmake/cmake_fixup_cmake_targets.cmake](https://github.com/microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake)
-- 
cgit v1.2.3


From 85e7e815f17d3a316089f9aa3bc0ee3c2a13039d Mon Sep 17 00:00:00 2001
From: Vinny <vpaladino778@gmail.com>
Date: Wed, 2 Oct 2019 10:08:51 -0400
Subject: Update and rename cmake_fixup_cmake_targets.md to
 vcpkg_fixup_cmake_targets.md (#8424)

Corrected incorrect file name.
Added inline code for reading clarity
Added examples
---
 docs/maintainers/cmake_fixup_cmake_targets.md | 25 ----------------------
 docs/maintainers/vcpkg_fixup_cmake_targets.md | 30 +++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 25 deletions(-)
 delete mode 100644 docs/maintainers/cmake_fixup_cmake_targets.md
 create mode 100644 docs/maintainers/vcpkg_fixup_cmake_targets.md

(limited to 'docs')

diff --git a/docs/maintainers/cmake_fixup_cmake_targets.md b/docs/maintainers/cmake_fixup_cmake_targets.md
deleted file mode 100644
index 9bbaddbba..000000000
--- a/docs/maintainers/cmake_fixup_cmake_targets.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# vcpkg_fixup_cmake_targets
-
-Transforms all /debug/share/\<port\>/\*targets-debug.cmake files and move them to /share/\<port\>.
-Removes all /debug/share/\<port\>/\*targets.cmake and /debug/share/\<port\>/\*config.cmake.
-
-Transforms all references matching /bin/\*.exe tools/\<port\>/\*.exe on Windows.
-Transforms all references matching /bin/\* to /tools/\<port\>/\* on other platforms.
-
-Fixups ${_IMPORT_PREFIX} in auto generated targets to be one folder deeper. 
-Replaces ${CURRENT_INSTALLED_DIR} with ${_IMPORT_PREFIX} in config files and targets.
-
-
-## Usage
-```cmake
-vcpkg_fixup_cmake_targets(CONFIG_PATH <config_path>)
-```
-
-## Parameters:
-### CONFIG_PATH
-*.cmake files subdirectory (e.g. "lib/cmake/${PORT}" or "cmake/${PORT}).
-### TARGET_PATH
-Optional location to place fixup'd files. Unecessary if target is "share/${PORT}".
-
-## Source
-[scripts/cmake/cmake_fixup_cmake_targets.cmake](https://github.com/microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake)
diff --git a/docs/maintainers/vcpkg_fixup_cmake_targets.md b/docs/maintainers/vcpkg_fixup_cmake_targets.md
new file mode 100644
index 000000000..5bad80656
--- /dev/null
+++ b/docs/maintainers/vcpkg_fixup_cmake_targets.md
@@ -0,0 +1,30 @@
+# vcpkg_fixup_cmake_targets
+
+Transforms all `/debug/share/\<port\>/\*targets-debug.cmake` files and move them to `/share/\<port\>`.
+Removes all `/debug/share/\<port\>/\*targets.cmake and /debug/share/\<port\>/\*config.cmake`.
+
+Transforms all references matching `/bin/\*.exe tools/\<port\>/\*.exe` on Windows.
+Transforms all references matching `/bin/\* to /tools/\<port\>/\*` on other platforms.
+
+Fixups *${_IMPORT_PREFIX}* in auto generated targets to be one folder deeper. 
+Replaces *${CURRENT_INSTALLED_DIR}* with *${_IMPORT_PREFIX}* in config files and targets.
+
+
+## Usage
+```cmake
+vcpkg_fixup_cmake_targets(CONFIG_PATH <config_path>)
+```
+
+## Parameters:
+### CONFIG_PATH
+*.cmake files subdirectory (e.g. "lib/cmake/${PORT}" or "cmake/${PORT}).
+### TARGET_PATH
+Optional location to place fixup'd files. Unecessary if target is "share/${PORT}".
+
+## Examples:
+  - [Azure-uamqp-c](https://github.com/microsoft/vcpkg/blob/master/ports/azure-uamqp-c/portfile.cmake)
+  - [Brigand](https://github.com/microsoft/vcpkg/blob/master/ports/brigand/portfile.cmake)
+  - [cctz](https://github.com/microsoft/vcpkg/blob/master/ports/cctz/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_fixup_cmake_targets.cmake](https://github.com/microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake)
-- 
cgit v1.2.3


From ad493fd8600c13f75dabcad60e6bd8d644f83c6b Mon Sep 17 00:00:00 2001
From: JackBoosY <47264268+JackBoosY@users.noreply.github.com>
Date: Sat, 5 Oct 2019 22:51:07 +0800
Subject: Add function
 vcpkg_configure_make/vcpkg_build_make/vcpkg_install_make/vcpkg_build_nmake/vcpkg_install_nmake
 (#8267)

* Add function vcpkg_configure_make/vcpkg_build_make.

* Fix autoreconf command and add log.

* Add vcpkg_install_make.

* Fix call function name.

* support non-debug mode.

* Add nmake support.

* [tcl]Add new port for testing.

* [vcpkg_configure_make]Fix prefix in linux.

* restart CI systen.

* Separate vcpkg_build_nmake/vcpkg_install_nmake. Add arg PROJECT_NAME.

* fix copy source file. add samples.

* Remove uncommon options.
Add force install para to autoreconf.

* fix build error.

* fix options judgment.

* enable nmake in windows.

* fix some envs and macros. Disable NMAKE in vcpkg_configure_make currently.

* update docs.

* fix environments.

* Modify libosip2 to use vcpkg_configure_make/vcpkg_install_make.

* [tcl]Tcl separates PR.

* trigger PR-EAGER.

* [freexl]Fix options name and remove option NMAKE.

* use tool-chain instead of set environments manually.

* fix autoreconf para.

* use vcpkg_execute_build_process instead.
---
 docs/maintainers/portfile-functions.md   | 11 +++--
 docs/maintainers/vcpkg_build_make.md     | 30 +++++++++++++
 docs/maintainers/vcpkg_build_nmake.md    | 63 +++++++++++++++++++++++++++
 docs/maintainers/vcpkg_configure_make.md | 74 ++++++++++++++++++++++++++++++++
 docs/maintainers/vcpkg_install_make.md   | 24 +++++++++++
 docs/maintainers/vcpkg_install_nmake.md  | 48 +++++++++++++++++++++
 6 files changed, 247 insertions(+), 3 deletions(-)
 create mode 100644 docs/maintainers/vcpkg_build_make.md
 create mode 100644 docs/maintainers/vcpkg_build_nmake.md
 create mode 100644 docs/maintainers/vcpkg_configure_make.md
 create mode 100644 docs/maintainers/vcpkg_install_make.md
 create mode 100644 docs/maintainers/vcpkg_install_nmake.md

(limited to 'docs')

diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index bbd5d23ab..dac417acf 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -6,12 +6,15 @@
 - [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
 - [vcpkg\_apply\_patches](vcpkg_apply_patches.md)
 - [vcpkg\_build\_cmake](vcpkg_build_cmake.md)
-- [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
+- [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
+- [vcpkg\_build\_make](vcpkg_build_make.md)
+- [vcpkg\_build\_nmake](vcpkg_build_nmake.md)
 - [vcpkg\_check\_features](vcpkg_check_features.md)
 - [vcpkg\_check\_linkage](vcpkg_check_linkage.md)
 - [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)
 - [vcpkg\_common\_definitions](vcpkg_common_definitions.md)
-- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
+- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
+- [vcpkg\_configure\_make](vcpkg_configure_make.md)
 - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)
 - [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)
 - [vcpkg\_download\_distfile](vcpkg_download_distfile.md)
@@ -26,6 +29,8 @@
 - [vcpkg\_from\_github](vcpkg_from_github.md)
 - [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md)
 - [vcpkg\_install\_cmake](vcpkg_install_cmake.md)
-- [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md)
+- [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md)
+- [vcpkg\_install\_make](vcpkg_install_make.md)
+- [vcpkg\_install\_nmake](vcpkg_install_nmake.md)
 - [vcpkg\_prettify\_command](vcpkg_prettify_command.md)
 - [vcpkg\_test\_cmake](vcpkg_test_cmake.md)
diff --git a/docs/maintainers/vcpkg_build_make.md b/docs/maintainers/vcpkg_build_make.md
new file mode 100644
index 000000000..5161ba3ce
--- /dev/null
+++ b/docs/maintainers/vcpkg_build_make.md
@@ -0,0 +1,30 @@
+# vcpkg_build_make
+
+Build a linux makefile project.
+
+## Usage:
+```cmake
+vcpkg_build_make([TARGET <target>])
+```
+
+### TARGET
+The target passed to the configure/make build command (`./configure/make/make 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_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)
+
+## Source
+[scripts/cmake/vcpkg_build_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_make.cmake)
diff --git a/docs/maintainers/vcpkg_build_nmake.md b/docs/maintainers/vcpkg_build_nmake.md
new file mode 100644
index 000000000..296fbbd7d
--- /dev/null
+++ b/docs/maintainers/vcpkg_build_nmake.md
@@ -0,0 +1,63 @@
+# vcpkg_build_nmake
+
+Build a msvc makefile project.
+
+## Usage:
+```cmake
+vcpkg_build_nmake(
+    SOURCE_PATH <${SOURCE_PATH}>
+    [NO_DEBUG]
+    PROJECT_SUBPATH <${SUBPATH}>
+    PROJECT_NAME <${MAKEFILE_NAME}>
+    [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.
+
+### 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)
+
+## Source
+[scripts/cmake/vcpkg_build_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_nmake.cmake)
diff --git a/docs/maintainers/vcpkg_configure_make.md b/docs/maintainers/vcpkg_configure_make.md
new file mode 100644
index 000000000..7b5ef3c48
--- /dev/null
+++ b/docs/maintainers/vcpkg_configure_make.md
@@ -0,0 +1,74 @@
+# vcpkg_configure_make
+
+Configure `configure` for Debug and Release builds of a project.
+
+## Usage
+```cmake
+vcpkg_configure_make(
+    SOURCE_PATH <${SOURCE_PATH}>
+    [AUTOCONFIG]
+    [DISABLE_AUTO_HOST]
+    [DISABLE_AUTO_DST]
+    [GENERATOR]
+    [NO_DEBUG]
+    [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`.
+Should use `GENERATOR NMake` first.
+
+### NO_DEBUG
+This port doesn't support debug mode.
+
+### AUTOCONFIG
+Need to use autoconfig to generate configure file.
+
+### DISABLE_AUTO_HOST
+Don't set host automatically, the default value is `i686`.
+If use this option, you will need to set host manually.
+
+### DISABLE_AUTO_DST
+Don't set installation path automatically, the default value is `${CURRENT_PACKAGES_DIR}` and `${CURRENT_PACKAGES_DIR}/debug`
+If use this option, you will need to set dst path manually.
+
+### GENERATOR
+Specifies the precise generator to use.
+NMake: nmake(windows) make(unix)
+MAKE: make(windows) make(unix)
+
+### PRERUN_SHELL
+Script that needs to be called before configuration
+
+### OPTIONS
+Additional options passed to configure during the configuration.
+
+### OPTIONS_RELEASE
+Additional options passed to configure during the Release configuration. These are in addition to `OPTIONS`.
+
+### OPTIONS_DEBUG
+Additional options passed to configure during the Debug configuration. These are in addition to `OPTIONS`.
+
+## 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)
+
+## Source
+[scripts/cmake/vcpkg_configure_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
diff --git a/docs/maintainers/vcpkg_install_make.md b/docs/maintainers/vcpkg_install_make.md
new file mode 100644
index 000000000..3460778cc
--- /dev/null
+++ b/docs/maintainers/vcpkg_install_make.md
@@ -0,0 +1,24 @@
+# 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)
+
+## Source
+[scripts/cmake/vcpkg_install_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_make.cmake)
diff --git a/docs/maintainers/vcpkg_install_nmake.md b/docs/maintainers/vcpkg_install_nmake.md
new file mode 100644
index 000000000..e45ae107c
--- /dev/null
+++ b/docs/maintainers/vcpkg_install_nmake.md
@@ -0,0 +1,48 @@
+# vcpkg_install_nmake
+
+Build and install a msvc makefile project.
+
+## Usage:
+```cmake
+vcpkg_install_nmake(
+    SOURCE_PATH <${SOURCE_PATH}>
+    [NO_DEBUG]
+    PROJECT_SUBPATH <${SUBPATH}>
+    PROJECT_NAME <${MAKEFILE_NAME}>
+    [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.
+
+### 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`
+
+## Source
+[scripts/cmake/vcpkg_install_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_nmake.cmake)
-- 
cgit v1.2.3


From 988b1c989797380b92ef19c651e391bac546e0dc Mon Sep 17 00:00:00 2001
From: JackBoosY <47264268+JackBoosY@users.noreply.github.com>
Date: Tue, 22 Oct 2019 07:23:52 +0800
Subject: support SKIP_CONFIGURE in vcpkg_configure_make. (#8647)

---
 docs/maintainers/vcpkg_configure_make.md | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'docs')

diff --git a/docs/maintainers/vcpkg_configure_make.md b/docs/maintainers/vcpkg_configure_make.md
index 7b5ef3c48..73b46bafc 100644
--- a/docs/maintainers/vcpkg_configure_make.md
+++ b/docs/maintainers/vcpkg_configure_make.md
@@ -11,6 +11,7 @@ vcpkg_configure_make(
     [DISABLE_AUTO_DST]
     [GENERATOR]
     [NO_DEBUG]
+    [SKIP_CONFIGURE]
     [PROJECT_SUBPATH <${PROJ_SUBPATH}>]
     [PRERUN_SHELL <${SHELL_PATH}>]
     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
@@ -32,6 +33,9 @@ Should use `GENERATOR NMake` first.
 ### NO_DEBUG
 This port doesn't support debug mode.
 
+### SKIP_CONFIGURE
+Skip configure process
+
 ### AUTOCONFIG
 Need to use autoconfig to generate configure file.
 
-- 
cgit v1.2.3


From 92af850c1cf514a9045f05502392311b528e8311 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Wolfgang=20St=C3=B6ggl?= <c72578@yahoo.de>
Date: Fri, 25 Oct 2019 00:51:16 +0200
Subject: maintainer-guide.md - Fix link (#8720)

"source_" was missing in the name of the helper function. Fix typo:
vcpkg_extract_archive_ex -> vcpkg_extract_source_archive_ex
---
 docs/maintainers/maintainer-guide.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md
index 3a3a3a15a..624aa46d3 100644
--- a/docs/maintainers/maintainer-guide.md
+++ b/docs/maintainers/maintainer-guide.md
@@ -39,7 +39,7 @@ https://github.blog/2019-02-14-introducing-draft-pull-requests/
 
 At this time, the following helpers are deprecated:
 
-1. `vcpkg_extract_archive()` should be replaced by [`vcpkg_extract_archive_ex()`](vcpkg_extract_archive_ex.md)
+1. `vcpkg_extract_source_archive()` should be replaced by [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md)
 2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md))
 3. `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md)
 
-- 
cgit v1.2.3


From 934275b7125e89caeaeff167d567574bf41e8264 Mon Sep 17 00:00:00 2001
From: JackBoosY <47264268+JackBoosY@users.noreply.github.com>
Date: Wed, 30 Oct 2019 14:23:36 +0800
Subject: [libxslt]Using vcpkg_install_nmake in Windows, support unix. (#8589)

* [libxslt]Using vcpkg_install_nmake in Windows, support unix.

* support PRERUN_SHELL/PRERUN_SHELL_DEBUG/PRERUN_SHELL_RELEASE

* Re-trigger CI.
---
 docs/maintainers/vcpkg_build_nmake.md   | 12 ++++++++++++
 docs/maintainers/vcpkg_install_nmake.md | 12 ++++++++++++
 2 files changed, 24 insertions(+)

(limited to 'docs')

diff --git a/docs/maintainers/vcpkg_build_nmake.md b/docs/maintainers/vcpkg_build_nmake.md
index 296fbbd7d..e5c177b1b 100644
--- a/docs/maintainers/vcpkg_build_nmake.md
+++ b/docs/maintainers/vcpkg_build_nmake.md
@@ -9,6 +9,9 @@ vcpkg_build_nmake(
     [NO_DEBUG]
     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>...]
@@ -33,6 +36,15 @@ 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.
 
diff --git a/docs/maintainers/vcpkg_install_nmake.md b/docs/maintainers/vcpkg_install_nmake.md
index e45ae107c..3f397c195 100644
--- a/docs/maintainers/vcpkg_install_nmake.md
+++ b/docs/maintainers/vcpkg_install_nmake.md
@@ -9,6 +9,9 @@ vcpkg_install_nmake(
     [NO_DEBUG]
     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>...]
@@ -29,6 +32,15 @@ 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.
 
-- 
cgit v1.2.3