Merge branch 'master' into sx-init

5 files changed, 449 insertions, 24 deletions

diff --git a/docs/about/faq.md b/docs/about/faq.md
index b83674d05..504738479 100644
--- a/docs/about/faq.md
+++ b/docs/about/faq.md
@@ -1,7 +1,7 @@
 # Frequently Asked Questions
 
 ## Can I contribute a new library?
-Yes! Start out by reading our [contribution guidelines](https://github.com/Microsoft/vcpkg/blob/master/CONTRIBUTING.md).
+Yes! Start out by reading our [contribution guidelines](https://github.com/Microsoft/vcpkg/blob/master/CONTRIBUTING.md).  If you want to contribute but don't have a particular library in mind then take a look at the list of [new port requests](https://github.com/Microsoft/vcpkg/issues?q=is%3Aissue+is%3Aopen+label%3A%22new+port+request+-+consider+making+a+PR%21%22).
 
 ## Can Vcpkg create pre-built binary packages? What is the binary format used by Vcpkg?
 Yes! See [the `export` command](../users/integration.md#export).
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 eb03f1d94..03bfa113a 100644
--- a/docs/maintainers/control-files.md
+++ b/docs/maintainers/control-files.md
@@ -1,81 +1,149 @@
 # CONTROL files
 
-Each port has some static metadata in the form of a `CONTROL` file. This file uses the same syntax and a subset of the fields from [the Debian `control` format][debian].
+The `CONTROL` file contains metadata about the port.  The syntax is based on [the Debian `control` format][debian] although we only support the subset of fields documented here.
 
-Field names are case-sensitive.
+Field names are case-sensitive and start the line without leading whitespace.  Paragraphs are separated by one or more empty lines.
 
 [debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html
 
 ## Source Paragraph
 
-The first paragraph appearing in a `CONTROL` file is the Source paragraph, which defines the core attributes of the package (name, version, and so on).
+The first paragraph in a `CONTROL` file is the Source paragraph.  It must have a `Source`, `Version`, and `Description` field.  It can optionally have a `Build-Depends` and `Default-Features` field.
+
+### Examples:
+```no-highlight
+Source: ace
+Version: 6.5.5-1
+Description: The ADAPTIVE Communication Environment
+```
 
-### Example:
 ```no-highlight
 Source: vtk
-Version: 8.1.0-1
+Version: 8.2.0-2
 Description: Software system for 3D computer graphics, image processing, and visualization
-Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype
+Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype, expat, hdf5, libjpeg-turbo, proj4, lz4, libtheora, atlmfc (windows), eigen3, double-conversion, pugixml, libharu, sqlite3, netcdf-c
 ```
 
+
 ### Recognized fields
 
 #### Source
 The name of the port.
 
+When adding new ports be aware that the name may conflict with other projects that are not a part of vcpkg.  For example `json` conflicts with too many other projects so you should add a scope to the name such as `taocpp-json` to make it unique.  Verify there are no conflicts on a search engine as well as on other package collections.
+
+Package collections to check for conflicts:
+
++ [Repology](https://repology.org/projects/)
++ [Debian packages](https://www.debian.org/distrib/packages)
++ [Packages search](https://pkgs.org/)
+
 #### Version
 The port version.
 
-This field should be an alphanumeric string which may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bitstrings and are only evaluated for equality.
+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.
+
+For tagged-release ports, we follow the following convention:
 
-By convention, if a portfile is modified without incrementing the "upstream" version, a `-#` is appended to create a unique version string.
+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-03-21
+```
 
 #### Description
-A description of the library
+A description of the library.
 
-The first sentence of the description should concisely describe the purpose and contents of the library. Then, a larger description including the library's "proper name" should follow.
+By convention the first line of the description is a summary of the library.  An optional detailed description follows.  The detailed description can be multiple lines, all starting with whitespace.
 
-#### Maintainer
-Reserved for future use.
+Example:
+```no-highlight
+Description: C++ header-only JSON library
+```
+```no-highlight
+Description: Mosquitto is an open source message broker that implements the MQ Telemetry Transport protocol versions 3.1 and 3.1.1.
+  MQTT provides a lightweight method of carrying out messaging using a publish/subscribe model. This makes it suitable for "machine 
+  to machine" messaging such as with low power sensors or mobile devices such as phones, embedded computers or microcontrollers like the Arduino.
+````
 
-#### Build-Depends
-The list of dependencies required to build and use this library.
+#### Homepage
+The URL of the homepage for the library where a user is able to find additional documentation or the original source code.
 
 Example:
 ```no-highlight
-Build-Depends: zlib, libpng, libjpeg-turbo, tiff
+Homepage: https://github.com/Microsoft/vcpkg
 ```
 
-Unlike dpkg, Vcpkg does not distinguish between build-only dependencies and runtime dependencies. The complete list of dependencies needed to successfully use the library should be specified.
+#### Build-Depends
+Comma separated list of vcpkg ports the library has a dependency on.
+
+Vcpkg does not distinguish between build-only dependencies and runtime dependencies. The complete list of dependencies needed to successfully use the library should be specified.
 
 *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 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, libpng, libjpeg-turbo, tiff
+```
+If the port is dependent on optional features of another library those can be specified using the `portname[featurelist]` syntax.
+
+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.  There must be a space between the name of the port and the filter. __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: curl[openssl] (!windows&!osx), curl[winssl] (windows), curl[darwinssl] (osx)
+```
+
+#### Default-Feature
+Comma separated list of optional port features to install by default.
+
+This field is optional.
+
+```no-highlight
+Default-Features: dynamodb, s3, kinesis
 ```
 
 ## Feature Paragraphs
 
-After the Source Paragraph, `CONTROL` files can list zero or more Feature Paragraphs which declare features.
+Multiple optional features can be specified in the `CONTROL` files.  It must have a `Feature` and `Description` field.  It can optionally have a `Build-Depends` field.  It must be separated from other paragraphs by one or more empty lines.
 
 ### Example:
 ```no-highlight
 Source: vtk
-Version: 8.1.0-1
+Version: 8.2.0-2
 Description: Software system for 3D computer graphics, image processing, and visualization
-Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype
+Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype, expat, hdf5, libjpeg-turbo, proj4, lz4, libtheora, atlmfc (windows), eigen3, double-conversion, pugixml, libharu, sqlite3, netcdf-c
+
+Feature: openvr
+Description: OpenVR functionality for VTK
+Build-Depends: sdl2, openvr
+
+Feature: qt
+Description: Qt functionality for VTK
+Build-Depends: qt5
 
 Feature: mpi
 Description: MPI functionality for VTK
 Build-Depends: msmpi, hdf5[parallel]
+
+Feature: python
+Description: Python functionality for VTK
+Build-Depends: python3
 ```
 
 ### Recognized fields
@@ -84,9 +152,9 @@ Build-Depends: msmpi, hdf5[parallel]
 The name of the feature.
 
 #### Description
-A description of the feature
+A description of the feature using the same syntax as the port  `Description` field.
 
 #### Build-Depends
 The list of dependencies required to build and use this feature.
 
-All dependencies from selected features are unioned together to produce the final dependency set for the build. This field follows the same syntax as `Build-Depends` in the Source Paragraph.
+On installation the dependencies from all selected features are combined to produce the full dependency list for the build. This field follows the same syntax as `Build-Depends` in the Source Paragraph.
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.

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.