[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

3 files changed, 82 insertions, 2 deletions

diff --git a/toolsrc/src/vcpkg-test/commands.cpp b/toolsrc/src/vcpkg-test/commands.cpp
index c19fd30ea..38346291c 100644
--- a/toolsrc/src/vcpkg-test/commands.cpp
+++ b/toolsrc/src/vcpkg-test/commands.cpp
@@ -55,11 +55,11 @@ TEST_CASE ("get_available_paths_commands works", "[commands]")
         "autocomplete",
         "hash",
         "fetch",
+        "format-manifest",
         "x-ci-clean",
         "x-history",
         "x-package-info",
         "x-vsinstances",
-        "x-format-manifest",
         });
 }
 
diff --git a/toolsrc/src/vcpkg-test/manifests.cpp b/toolsrc/src/vcpkg-test/manifests.cpp
index 9a0ca94e2..0d5c9782a 100644
--- a/toolsrc/src/vcpkg-test/manifests.cpp
+++ b/toolsrc/src/vcpkg-test/manifests.cpp
@@ -250,7 +250,7 @@ TEST_CASE ("SourceParagraph manifest empty supports", "[manifests]")
 
 TEST_CASE ("Serialize all the ports", "[manifests]")
 {
-    std::vector<std::string> args_list = {"x-format-manifest"};
+    std::vector<std::string> args_list = {"format-manifest"};
     auto& fs = Files::get_real_filesystem();
     auto args = VcpkgCmdArguments::create_from_arg_sequence(args_list.data(), args_list.data() + args_list.size());
     VcpkgPaths paths{fs, args};
diff --git a/toolsrc/src/vcpkg-test/platform-expression.cpp b/toolsrc/src/vcpkg-test/platform-expression.cpp
new file mode 100644
index 000000000..aef999230
--- /dev/null
+++ b/toolsrc/src/vcpkg-test/platform-expression.cpp
@@ -0,0 +1,80 @@
+#include <catch2/catch.hpp>
+
+#include <vcpkg/platform-expression.h>
+
+using vcpkg::StringView;
+using namespace vcpkg::PlatformExpression;
+
+static vcpkg::ExpectedS<Expr> parse_expr(StringView s)
+{
+    return parse_platform_expression(s, MultipleBinaryOperators::Deny);
+}
+
+TEST_CASE ("platform-expression-identifier", "[platform-expression]")
+{
+    auto m_expr = parse_expr("windows");
+    REQUIRE(m_expr);
+    auto& expr = *m_expr.get();
+
+    CHECK(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", ""}}));
+    CHECK(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", "WindowsStore"}}));
+    CHECK_FALSE(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", "Linux"}}));
+    CHECK_FALSE(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", "Darwin"}}));
+}
+
+TEST_CASE ("platform-expression-not", "[platform-expression]")
+{
+    auto m_expr = parse_expr("!windows");
+    REQUIRE(m_expr);
+    auto& expr = *m_expr.get();
+
+    CHECK_FALSE(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", ""}}));
+    CHECK_FALSE(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", "WindowsStore"}}));
+    CHECK(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", "Linux"}}));
+    CHECK(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", "Darwin"}}));
+}
+
+TEST_CASE ("platform-expression-and", "[platform-expression]")
+{
+    auto m_expr = parse_expr("!windows & !arm");
+    REQUIRE(m_expr);
+    auto& expr = *m_expr.get();
+
+    CHECK_FALSE(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", ""}}));
+    CHECK_FALSE(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", "WindowsStore"}}));
+    CHECK(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", "Linux"}}));
+    CHECK_FALSE(expr.evaluate({
+        {"VCPKG_CMAKE_SYSTEM_NAME", "Linux"},
+        {"VCPKG_TARGET_ARCHITECTURE", "arm"},
+    }));
+}
+
+TEST_CASE ("platform-expression-or", "[platform-expression]")
+{
+    auto m_expr = parse_expr("!windows | arm");
+    REQUIRE(m_expr);
+    auto& expr = *m_expr.get();
+
+    CHECK_FALSE(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", ""}}));
+    CHECK(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", ""}, {"VCPKG_TARGET_ARCHITECTURE", "arm"}}));
+    CHECK(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", "Linux"}}));
+}
+
+TEST_CASE ("weird platform-expressions whitespace", "[platform-expression]")
+{
+    auto m_expr = parse_expr(" ! \t  windows \n| arm \r");
+    REQUIRE(m_expr);
+    auto& expr = *m_expr.get();
+
+    CHECK_FALSE(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", ""}}));
+    CHECK(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", ""}, {"VCPKG_TARGET_ARCHITECTURE", "arm"}}));
+    CHECK(expr.evaluate({{"VCPKG_CMAKE_SYSTEM_NAME", "Linux"}}));
+}
+
+TEST_CASE ("no mixing &, | in platform expressions", "[platform-expression]")
+{
+    auto m_expr = parse_expr("windows & arm | linux");
+    CHECK_FALSE(m_expr);
+    m_expr = parse_expr("windows | !arm & linux");
+    CHECK_FALSE(m_expr);
+}