[vcpkg manifest] Add documentation! (#13488)

* [vcpkg docs] add docs for manifest files

These are just for the maintainer docs,
not user docs.

* [vcpkg] EBNF-ify platform expression parsing

this modifies nothing about what strings are accepted or rejected,
it just moves stuff around.

also adds tests.

* [vcpkg docs] add manifest mode example

* [wip] docs for augustin

also fix tabs

* [vcpkg manifest] switch to using maps for features

* Apply suggestions from code review

* un-experimentize format-manifest

* flesh out the user manifest mode docs

* CRs

* billy CRs

* final personal pass-thru

2 files changed, 260 insertions, 1 deletions

diff --git a/docs/users/manifests.md b/docs/users/manifests.md
new file mode 100644
index 000000000..331665f2f
--- /dev/null
+++ b/docs/users/manifests.md
@@ -0,0 +1,259 @@
+# Manifest Mode
+
+vcpkg has two modes of operation - classic mode and manifest mode.
+
+In classic mode, vcpkg produces an "installed" tree,
+whose contents are changed by explicit calls to `vcpkg install` or `vcpkg remove`.
+The installed tree is intended for consumption by any number of projects:
+for example, installing a bunch of libraries and then using those libraries from Visual Studio,
+without additional configuration.
+Because the installed tree is not associated with an individual project,
+it's similar to tools like `brew` or `apt`,
+except that the installed tree is vcpkg-installation-local,
+rather than global to a system or user.
+
+In manifest mode, an installed tree is associated with a particular project rather than the vcpkg installation.
+The set of installed ports is controlled by editing the project's "manifest file",
+and the installed tree is placed in the project directory or build directory.
+This mode acts more similarly to language package managers like Cargo, or npm. 
+We recommend using this manifest mode whenever possible,
+because it allows one to encode a project's dependencies explicitly in a project file,
+rather than in the documentation, making your project much easier to consume.
+
+Manifest mode is in beta, but one can use it from the CMake integration,
+which will be stable when used via things like `find_package`.
+This is the recommended way to use manifest mode.
+
+In this document, we have basic information on [Writing a Manifest](#writing-a-manifest),
+the [vcpkg Command Line Interface](#command-line-interface),
+and a little more information on [CMake](#cmake-integration) integration.
+
+Check out the [manifest cmake example](../examples/manifest-mode-cmake.md) for an example project using CMake and manifest mode.
+
+## Writing a Manifest
+
+A manifest is a JSON-formatted file which lies at the root of your project.
+It contains all the information a person needs to know to get dependencies for your project,
+as well as all the metadata about your project that a person who depends on you might be interested in.
+
+Every manifest is named `vcpkg.json`, and has a top level object. It is a strict JSON file,
+and can't contain things like comments or trailing commas - however,
+you can use field names that start with `$` to write your comments.
+
+All of the fields that `vcpkg.json` supports are as follows; the most important ones are [`"name"`](#name),
+the [version fields](#version-fields), and [`"dependencies"`](#dependencies):
+
+### `"name"`
+
+This is the name of your project! It must be formatted in a way that vcpkg understands - in other words,
+it must be lowercase alphabetic characters, digits, and hyphens, and it must not start nor end with a hyphen.
+For example, `Boost.Asio` might be given the name `boost-asio`.
+
+This is a required field.
+
+### Version fields
+
+There is, at this point, only one version field - `"version-string"`. However, more will be added in the future.
+You must have one (and only one) version field. There are different reasons to use each version field:
+
+* `"version-string"` - used for packages that don't have orderable versions. This is pretty uncommon,
+  but since we don't have any versioning constraints yet, this is the only one that you can use.
+
+Additionally, the `"port-version"` field is used by registries of packages,
+as a way to version "the package gotten from `vcpkg install`" differently from the upstream package version.
+You shouldn't need to worry about this at all.
+
+### `"description"`
+
+This is where you describe your project. Give it a good description to help in searching for it!
+This can be a single string, or it can be an array of strings;
+in the latter case, the first string is treated as a summary,
+while the remaining strings are treated as the full description.
+
+### `"dependencies"`
+
+This field lists all the dependencies you'll need to build your library (as well as any your dependents might need,
+if they were to use you). It's an array of strings and objects:
+
+* A string dependency (e.g., `"dependencies": [ "zlib" ]`) is the simplest way one can depend on a library;
+  it means you don't depend on a single version, and don't need to write down any more information.
+* On the other hand, an object dependency (e.g., `"dependencies": [ { "name": "zlib" } ]`)
+  allows you to add that extra information.
+
+An object dependency can have the following fields:
+
+#### `"name"`
+
+The name of the dependency. This follows the same restrictions as the [`"name"`](#name) property for a project.
+
+#### `"features"` and `"default-features"`
+
+`"features"` is an array of feature names which tell you the set of features that the
+dependencies need to have at a minimum,
+while `"default-features"` is a boolean that tells vcpkg whether or not to
+install the features the package author thinks should be "most common for most people to use".
+
+For example, `ffmpeg` is a library which supports many, many audio and video codecs;
+however, for your specific project, you may only need mp3 encoding.
+Then, you might just ask for:
+
+```json
+{
+  "name": "ffmpeg",
+  "default-features": false,
+  "features": [ "mp3lame" ]
+}
+```
+
+#### `"platform"`
+
+The `"platform"` field defines the platforms where the dependency should be installed - for example,
+you might need to use sha256, and so you use platform primitives on Windows, but `picosha2` on non-Windows platforms.
+
+```json
+{
+  "name": "picosha2",
+  "platform": "!windows"
+}
+```
+
+This is a string field which takes boolean expressions of the form `<identifier>`,
+`!expression`, `expression { & expression & expression...}`, and `expression { | expression | expression...}`,
+along with parentheses to denote precedence.
+For example, a dependency that's only installed on the Windows OS, for the ARM64 architecture,
+and on Linux on x64, would be written `(windows & arm64) | (linux & x64)`.
+
+The common identifiers are:
+
+- The operating system: `windows`, `uwp`, `linux`, `osx` (includes macOS), `android`, `emscripten`
+- The architecture: `x86`, `x64`, `wasm32`, `arm64`, `arm` (includes both arm32 and arm64 due to backwards compatibility)
+
+although one can define their own.
+
+#### Example:
+
+```json
+{
+  "dependencies": [
+    {
+      "name": "arrow",
+      "default-features": false,
+      "features": [ "json" ]
+    },
+    "boost-asio",
+    "openssl",
+    {
+      "name": "picosha2",
+      "platform": "!windows"
+    }
+  ]
+}
+```
+
+### `"supports"`
+
+If your project doesn't support common platforms, you can tell your users this with the `"supports"` field.
+It uses the same platform expressions as [`"platform"`](#platform), from dependencies, as well as the
+`"supports"` field of features.
+For example, if your library doesn't support linux, you might write `{ "supports": "!linux" }`.
+
+
+### `"features"` and `"default-features"`
+
+The `"features"` field defines _your_ project's optional features, that others may either depend on or not.
+It's an object, where the keys are the names of the features, and the values are objects describing the feature.
+`"description"` is required,
+and acts exactly like the [`"description"`](#description) field on the global package,
+and `"dependencies"` are optional,
+and again act exactly like the [`"dependencies"`](#dependencies) field on the global package.
+There's also the `"supports"` field,
+which again acts exactly like the [`"supports"`](#supports) field on the global package.
+
+You also have control over which features are default, if a person doesn't ask for anything specific,
+and that's the `"default-features"` field, which is an array of feature names.
+
+#### Example:
+
+```
+{
+  "name": "libdb",
+  "description": [
+    "An example database library.",
+    "Optionally uses one of CBOR, JSON, or CSV as a backend."
+  ],
+  "default-features": [ "cbor", "csv", "json" ],
+  "features": {
+    "cbor": {
+      "description": "The CBOR backend",
+      "dependencies": [
+        {
+          "$explanation": [
+            "This is currently how you tell vcpkg that the cbor feature depends on the json feature of this package",
+            "We're looking into making this easier"
+          ],
+          "name": "libdb",
+          "default-features": false,
+          "features": [ "json" ]
+        }
+      ]
+    },
+    "csv": {
+      "description": "The CSV backend",
+      "dependencies": [
+        "fast-cpp-csv-parser"
+      ]
+    },
+    "gui": {
+      "description": "The GUI libdb database viewer.",
+      "supports": "windows | osx"
+    }
+    "json": {
+      "description": "The JSON backend",
+      "dependencies": [
+        "jsoncons"
+      ]
+    },
+  }
+}
+```
+
+## Command Line Interface
+
+The command line interface around the new manifest mode is pretty simple.
+There's only one command that one really needs to worry about, `vcpkg install`,
+although `vcpkg search` is still useful.
+Since manifest mode is still in beta, you'll need to pass a feature flag: `manifests`.
+There are a few ways to pass this feature flag:
+
+* `--feature-flag` option: On any vcpkg command, you can pass `--feature-flag=manifests`
+* `VCPKG_FEATURE_FLAGS` environment variable: one can set the environment variable `VCPKG_FEATURE_FLAGS` to
+  `manifests`.
+
+### `vcpkg install`
+
+Once one has written a manifest file,
+they can run `vcpkg install` in any subdirectory of the directory containing `vcpkg.json`.
+It will install all of the dependencies for the default triplet into
+`<directory containing vcpkg.json>/vcpkg_installed`.
+If you want to switch the triplet (for example, this is very common on windows, where the default triplet is x86-windows, not x64-windows),
+you can pass it with the `--triplet` option: `vcpkg install --triplet x64-windows` (or whatever).
+Then, vcpkg will install all the dependencies, and you're ready to go!
+
+## CMake Integration
+
+The CMake integration acts exactly like the existing CMake integration.
+One passes the toolchain file, located at `[vcpkg root]/scripts/buildsystems/vcpkg.cmake`,
+to the CMake invocation via the `CMAKE_TOOLCHAIN_FILE` variable.
+Then, CMake will install all dependencies into the build directory, and you're good!
+It ends up that you only have to run CMake, and vcpkg is called only as part of the build process.
+Unlike bare vcpkg, the feature flag is not required,
+since the CMake integration won't break as long as you depending on the exact naming of vcpkg's installed directory.
+
+### Example:
+
+```
+> cmake -B builddir -S . -DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
+> cmake --build builddir
+```
+
+with a `vcpkg.json` in the same directory as `CMakeLists.txt` should Just Work!
diff --git a/docs/users/triplets.md b/docs/users/triplets.md
index b587a91e5..9903b197c 100644
--- a/docs/users/triplets.md
+++ b/docs/users/triplets.md
@@ -93,7 +93,7 @@ Replaces the default computed list of triplet "Supports" terms.
 
 This option (if set) will override the default set of terms used for qualified dependency resolution and "Supports" field evaluation.
 
-See the [`Supports`](../maintainers/control-files.md#Supports) control file field documentation for more details.
+See the [`"supports"`](../maintainers/manifest-files.md#supports) manifest file field documentation for more details.
 
 > Implementers' Note: this list is extracted via the `vcpkg_get_dep_info` mechanism.