[docs] Document overlay ports/triplets in vcpkg-configuration.json

docs/users/manifests.md

@@ -38,6 +38,7 @@ manifest mode.
   - [`"supports"`](#supports)
   - [`"features"`](#features)
   - [`"default-features"`](#default-features)
+  - [`"vcpkg-configuration"`](#vcpkg-configuration)
 
 ## Simple Example Manifest
 
@@ -323,3 +324,33 @@ and that's the `"default-features"` field, which is an array of feature names.
   }
 }
 ```
+
+### `"vcpkg-configuration"`
+
+Allows to embed vcpkg configuration properties inside the `vcpkg.json` file. Everything inside
+the `vcpkg-configuration` property is treated as if was defined in a `vcpkg-configuration.json` file. 
+See the [`vcpkg-configuration.json` documentation](registries.md) for details.
+
+Having a `vcpkg-configuration` defined in `vcpkg.json` while also having a `vcpkg-configuration.json` 
+file is not allowed and will result in the vcpkg command terminating with an error message.
+
+#### Example:
+
+```json
+  "name": "test",
+  "version": "1.0.0",
+  "dependencies": [ "beison", "zlib" ],
+  "vcpkg-configuration": {
+    "registries": [
+      {
+        "kind": "git",
+        "baseline": "dacf4de488094a384ca2c202b923ccc097956e0c",
+        "repository": "https://github.com/northwindtraders/vcpkg-registry",
+        "packages": [ "beicode", "beison" ]
+      }
+    ],
+    "overlay-ports": [ "./my-ports/fmt", 
+                       "./team-ports"
+    ]
+  }
+```

docs/users/registries.md

@@ -18,8 +18,11 @@ use, please read [this documentation](../maintainers/registries.md).
       - [Registry Objects: `"path"`](#registry-objects-path)
     - [Configuration: `"default-registry"`](#configuration-default-registry)
     - [Configuration: `"registries"`](#configuration-registries)
+    - [Configuration: `"overlay-ports"`](#configuration-overlay-ports)
+    - [Configuration: `"overlay-triplets"`](#configuration-overlay-triplets)
     - [Example Configuration File](#example-configuration-file)
   - [Package Name Resolution](#package-name-resolution)
+  - [Overlays Resolution](#overlays-resolution)
     - [Versioning Support](#versioning-support)
 
 ## `vcpkg-configuration.json`
@@ -87,13 +90,27 @@ the specific packages named by the `"packages"` field.
 
 The `"packages"` fields of all the package registries must be disjoint.
 
+### Configuration: `"overlay-ports"`
+
+The `"overlay-ports"` field must contain an array of paths. Each path in the array must point
+to either: 
+* a particular port directory (a directory containing `vcpkg.json` and `portfile.cmake`), or
+* a directory containing port directories.
+Relative paths are resolved relative to the `vcpkg-configuration.json` file. Absolute paths can be used but are discouraged.
+
+### Configuration: `"overlay-triplets"`
+
+The `"overlay-triplets"` field must contain an array of paths. Each path in the array must point to a directory of triplet files ([see triplets documentation](../triplets.md)).
+Relative paths are resolved relative to the `vcpkg-configuration.json` file. Absolute paths can be used but are discouraged.
+
 ### Example Configuration File
 
 Let's assume that you have mirrored <https://github.com/microsoft/vcpkg> at
 <https://git.example.com/vcpkg>: this will be your default registry.
 Additionally, you want to use North Wind Trader's registry for their
-beison and beicode libraries. The following `vcpkg-configuration.json`
-will work:
+beison and beicode libraries, as well as configure overlay ports and 
+overlay triplets from your custom directories. The following
+`vcpkg-configuration.json` will work:
 
 ```json
 {
@@ -109,7 +126,12 @@ will work:
       "baseline": "dacf4de488094a384ca2c202b923ccc097956e0c",
       "packages": [ "beicode", "beison" ]
     }
-  ]
+  ],
+  "overlay-ports": [ "./team-ports",
+                     "c:/project/my-ports/fmt",
+                     "./custom-ports"
+   ],
+  "overlay-triplets": [ "./my-triplets" ]
 }
 ```
 
@@ -129,9 +151,23 @@ The name resolution algorithm is as follows:
 - If the default registry is set to `null`, error out; otherwise
 - use the built-in registry.
 
+## Overlays Resolution
+
+Overlay ports and triplets are evaluated in this order:
+
+1. Overlays from the command line
+2. Overlays from `vcpkg-configuration.json`
+3. Overlays from the `VCPKG_OVERLAY_[PORTS|TRIPLETS]` environment variable.
+
+Additionaly, each method has its own evaluation order:
+
+* Overlays from the command line are evaluated from left-to-right in the order each argument is passed, with each `--overlay-[ports|triplets]` argument adding a new overlay location.
+* Overlays from `vcpkg-configuration.json` are evaluated in the order of the `"overlay-[ports|triplets]"` array.
+* Overlays set by `VCPKG_OVERLAY_[PORTS|TRIPLETS]` are evaluated from left-to-right. Overlay locations are separated by an OS-specific path separator (`;` on Windows and `:` on non-Windows).
+
 ### Versioning Support
 
 Versioning with custom registries works exactly as it does in the built-in
 registry. You can read more about that in the [versioning documentation].
 
-[versioning documentation]: versioning.md
+[versioning documentation]: versioning.md