[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,26 @@ 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, which point
+to a particular port or a directory containing ports to overlay. Paths should be
+absolute or relative to `vcpkg-configuration.json`.
+
+### Configuration: `"overlay-triplets"`
+
+The `"overlay-triplets"` field must contain an array of paths, which point
+to a directory containing triplets to overlay. Paths should be absolute
+or relative to `vcpkg-configuration.json`.
+
 ### 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 +125,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 +150,21 @@ 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 overlay triplets will be resolved in the order in which
+additional paths are specified, with the first match being selected for installation,
+and falling back to `{vcpkg root}/ports` (or as specified by `--x-builtin-ports-root`) if the port is not found in any of the additional paths.
+
+If configured in multiple places, overlays will follow the following priority:
+
+- Overlays configured through the command line
+- Overlays configured in `vcpkg-configuration.json`
+- Overlays configured via environment variables
+
 ### 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