Merge from master

9 files changed, 101 insertions, 11 deletions

diff --git a/docs/about/faq.md b/docs/about/faq.md
index 8234216e0..88f88bad0 100644
--- a/docs/about/faq.md
+++ b/docs/about/faq.md
@@ -50,7 +50,9 @@ By saving the changes to the portfile (and checking them in), you'll get the sam
 
 Yes. While Vcpkg will only produce the standard "Release" and "Debug" configurations when building a library, you can get integration support for your projects' custom configurations, in addition to your project's standard configurations.
 
-The MSBuild $(VcpkgConfiguration) macro, if not set in your project, will identify either the "Release" or the "Debug" configuration. You only need to override this macro in your project file (.vcxproj) to declare the compatibility between your configuration, and the target standard configuration.
+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 example, you can add support for your "MyRelease" configuration by adding in your project file:
 ```
diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md
index e446fe6fa..17cb50311 100644
--- a/docs/maintainers/control-files.md
+++ b/docs/maintainers/control-files.md
@@ -42,10 +42,10 @@ Unlike dpkg, Vcpkg does not distinguish between build-only dependencies and runt
 
 *For example: websocketpp is a header only library, and thus does not require any dependencies at install time. However, downstream users need boost and openssl to make use of the library. Therefore, websocketpp lists boost and openssl as dependencies*
 
-Dependencies can be filtered based on the target triplet to support different requirements on Windows Desktop versus the Universal Windows Platform. Currently, the string inside brackets is substring-compared against the triplet name. __This will change in a future version to not depend on the triplet name.__
+Dependencies can be filtered based on the target triplet to support different requirements on Windows Desktop versus the Universal Windows Platform. Currently, the string inside parentheses is substring-compared against the triplet name. __This will change in a future version to not depend on the triplet name.__
 
 Example:
 ```no-highlight
-Build-Depends: zlib [windows], openssl [windows], boost [windows], websocketpp [windows]
+Build-Depends: zlib (windows), openssl (windows), boost (windows), websocketpp (windows)
 ```
 
diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index 705d65b7e..e16147f7d 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -3,6 +3,7 @@
 # Portfile helper functions

 - [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)

 - [vcpkg\_apply\_patches](vcpkg_apply_patches.md)

+- [vcpkg\_build\_cmake](vcpkg_build_cmake.md)

 - [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)

 - [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)

 - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)

@@ -11,5 +12,6 @@
 - [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)

 - [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)

 - [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)

+- [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)

 - [vcpkg\_from\_github](vcpkg_from_github.md)

 - [vcpkg\_install\_cmake](vcpkg_install_cmake.md)

diff --git a/docs/maintainers/vcpkg_acquire_msys.md b/docs/maintainers/vcpkg_acquire_msys.md
index 46cda81fd..53aa6532e 100644
--- a/docs/maintainers/vcpkg_acquire_msys.md
+++ b/docs/maintainers/vcpkg_acquire_msys.md
@@ -32,7 +32,7 @@ message(STATUS "Installing MSYS Packages")
 vcpkg_execute_required_process(
     COMMAND
         ${BASH} --noprofile --norc -c
-            "pacman -Sy --noconfirm --needed make"
+            'PATH=/usr/bin:\$PATH pacman -Sy --noconfirm --needed make'
     WORKING_DIRECTORY ${MSYS_ROOT}
     LOGNAME pacman-${TARGET_TRIPLET})
 ```
diff --git a/docs/maintainers/vcpkg_build_cmake.md b/docs/maintainers/vcpkg_build_cmake.md
new file mode 100644
index 000000000..ddfa46f6b
--- /dev/null
+++ b/docs/maintainers/vcpkg_build_cmake.md
@@ -0,0 +1,31 @@
+# vcpkg_build_cmake
+
+Build a cmake project.
+
+## Usage:
+```cmake
+vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET <target>])
+```
+
+## Parameters:
+### DISABLE_PARALLEL
+The underlying buildsystem will be instructed to not parallelize
+
+### TARGET
+The target passed to the cmake build command (`cmake --build . --target <target>`). If not specified, no target will
+be passed.
+
+## Notes:
+This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
+You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the
+"install" target
+
+## Examples:
+
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
+* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_build_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_cmake.cmake)

diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md
index bc50ef4c8..8107c8dd2 100644
--- a/docs/maintainers/vcpkg_find_acquire_program.md
+++ b/docs/maintainers/vcpkg_find_acquire_program.md
@@ -16,6 +16,7 @@ The current list of programs includes:
 - 7Z
 - BISON
 - FLEX
+- GASPREPROCESSOR
 - PERL
 - PYTHON2
 - PYTHON3
@@ -24,7 +25,6 @@ The current list of programs includes:
 - NASM
 - NINJA
 - YASM
-- GASPREPROCESSOR
 
 Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
 
diff --git a/docs/maintainers/vcpkg_from_bitbucket.md b/docs/maintainers/vcpkg_from_bitbucket.md
new file mode 100644
index 000000000..c8850b725
--- /dev/null
+++ b/docs/maintainers/vcpkg_from_bitbucket.md
@@ -0,0 +1,53 @@
+# vcpkg_from_bitbucket
+
+Download and extract a project from Bitbucket.
+Enables support for installing HEAD `vcpkg.exe install --head <port>`.
+
+## Usage:
+```cmake
+vcpkg_from_bitbucket(
+    OUT_SOURCE_PATH <SOURCE_PATH>
+    REPO <Microsoft/cpprestsdk>
+    [REF <v2.0.0>]
+    [SHA512 <45d0d7f8cc350...>]
+    [HEAD_REF <master>]
+)
+```
+
+## Parameters:
+### OUT_SOURCE_PATH
+Specifies the out-variable that will contain the extracted location.
+
+This should be set to `SOURCE_PATH` by convention.
+
+### REPO
+The organization or user and repository on GitHub.
+
+### REF
+A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**
+
+For repositories without official releases, this can be set to the full commit id of the current latest master.
+
+If `REF` is specified, `SHA512` must also be specified.
+
+### SHA512
+The SHA512 hash that should match the archive (https://bitbucket.com/${REPO}/get/${REF}.tar.gz).
+
+This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
+
+### HEAD_REF
+The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
+
+For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
+
+## Notes:
+At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
+
+This exports the `VCPKG_HEAD_VERSION` variable during head builds.
+
+## Examples:
+
+* [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_from_bitbucket.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_bitbucket.cmake)

diff --git a/docs/maintainers/vcpkg_from_github.md b/docs/maintainers/vcpkg_from_github.md
index cb7849fcc..cf50dc445 100644
--- a/docs/maintainers/vcpkg_from_github.md
+++ b/docs/maintainers/vcpkg_from_github.md
@@ -23,7 +23,9 @@ This should be set to `SOURCE_PATH` by convention.
 The organization or user and repository on GitHub.
 
 ### REF
-A stable git commit-ish (ideally a tag) that will not change contents.
+A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**
+
+For repositories without official releases, this can be set to the full commit id of the current latest master.
 
 If `REF` is specified, `SHA512` must also be specified.
 
@@ -38,7 +40,7 @@ The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
 For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
 
 ## Notes:
-At least one of `REF` and `HEAD_REF` must be specified.
+At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
 
 This exports the `VCPKG_HEAD_VERSION` variable during head builds.
 
diff --git a/docs/maintainers/vcpkg_install_cmake.md b/docs/maintainers/vcpkg_install_cmake.md
index e199d1292..1b132b4f1 100644
--- a/docs/maintainers/vcpkg_install_cmake.md
+++ b/docs/maintainers/vcpkg_install_cmake.md
@@ -4,15 +4,15 @@ Build and install a cmake project.
 
 ## Usage:
 ```cmake
-vcpkg_install_cmake([MSVC_64_TOOLSET])
+vcpkg_install_cmake(...)
 ```
 
 ## Parameters:
-### MSVC_64_TOOLSET
-This adds the `/p:PreferredToolArchitecture=x64` switch if the underlying buildsystem is MSBuild. Some large projects can run out of memory when linking if they use the 32-bit hosted tools.
+See [`vcpkg_build_cmake()`](vcpkg_build_cmake.md).
 
 ## Notes:
-This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
+This command transparently forwards to [`vcpkg_build_cmake()`](vcpkg_build_cmake.md), adding a `TARGET install`
+parameter.
 
 ## Examples: