[vcpkg manifest] Add documentation!

README.md

@@ -274,56 +274,6 @@ This will still allow people to not use vcpkg,
 by passing the `CMAKE_TOOLCHAIN_FILE` directly,
 but it will make the configure-build step slightly easier.
 
-## Quick Start: Manifests
-
-So, you want to look at what the future of vcpkg is going to be like!
-We really appreciate it 😄. First, though, a warning:
-manifest support in vcpkg is still in beta! Mostly, it should just work,
-but there are no guarantees and it's likely you'll hit at least a bug or two
-while you're using vcpkg in this mode. Additionally,
-we will likely break behavior before stabilizing, so be forewarned.
-Please [open issues][contributing:submit-issue] if you hit any bugs!
-
-First, install vcpkg as normal for [Windows](#quick-start-windows) or
-[Unix](#quick-start-unix).
-You may wish to install vcpkg in a central place,
-as the installed directory exists locally,
-and it's fine to run multiple vcpkg commands from the same
-vcpkg directory at the same time.
-
-Then, we must turn on the `manifests` vcpkg feature flag by adding
-`manifests` to the comma-separated `--feature-flags` option,
-or by adding it to the comma-separated `VCPKG_FEATURE_FLAGS`
-environment variable.
-
-You may also want to add vcpkg to the `PATH`.
-
-Then, all one has to do is create a manifest;
-create a file called `vcpkg.json`, and type the following:
-
-```json
-{
-  "name": "<name of your project>",
-  "version-string": "<version of your project>",
-  "dependencies": [
-    "abseil",
-    "boost"
-  ]
-}
-```
-
-The libraries will be installed into the `vcpkg_installed`
-directory, in the same directory as your `vcpkg.json`.
-If you can use the regular CMake toolchain,
-or the Visual Studio/MSBuild integration,
-it will install the dependencies automatically,
-although you will need to set `VcpkgManifestEnabled` to `On` for MSBuild.
-If you wish to install your dependencies without using either CMake or MSBuild,
-you may use a simple `vcpkg install --feature-flags=manifests`
-
-For more information, check out the [manifest][getting-started:manifest-spec]
-specification.
-
 [getting-started:using-a-package]: docs/examples/installing-and-using-packages.md
 [getting-started:integration]: docs/users/integration.md
 [getting-started:git]: https://git-scm.com/downloads
@@ -333,7 +283,6 @@ specification.
 [getting-started:macos-brew]: #installing-gcc-on-macos
 [getting-started:macos-gcc]: #installing-gcc-on-macos
 [getting-started:visual-studio]: https://visualstudio.microsoft.com/
-[getting-started:manifest-spec]: docs/specifications/manifests.md
 
 # Tab-Completion/Auto-Completion
 

docs/examples/manifest-mode-cmake.md

@@ -0,0 +1,199 @@
+# Manifest Mode: CMake Example
+
+We would like to add vcpkg manifest support to an existing cmake project!
+Let's create a simple project that prints the fibonacci sequence up to a certain number,
+using some common dependencies.
+
+## Initial Layout
+
+Let's create the following file layout:
+
+```no-highlight
+fibo/
+  src/
+    main.cxx
+  CMakeLists.txt
+```
+
+And we wish to use [fmt](https://github.com/fmtlib/fmt), [range-v3](https://github.com/ericniebler/range-v3),
+and [cxxopts](https://github.com/jarro2783/cxxopts).
+
+Let's write our `CMakeLists.txt` first:
+
+```cmake
+cmake_minimum_required(VERSION 3.15)
+
+project(fibo CXX)
+
+find_package(fmt REQUIRED)
+find_package(range-v3 REQUIRED)
+find_package(cxxopts REQUIRED)
+
+add_executable(fibo src/main.cxx)
+
+target_link_libraries(fibo
+  PRIVATE
+    fmt::fmt
+    range-v3::range-v3
+    cxxopts::cxxopts)
+```
+
+And then we should add `main.cxx`:
+
+```cxx
+#include <cxxopts.hpp>
+#include <fmt/format.h>
+#include <range/v3/view.hpp>
+
+namespace view = ranges::view;
+
+int fib(int x) {
+  int a = 0, b = 1;
+
+  for (int it : view::repeat(0) | view::take(x)) {
+    (void)it;
+    int tmp = a;
+    a += b;
+    b = tmp;
+  }
+
+  return a;
+}
+
+int main(int argc, char** argv) {
+  cxxopts::Options options("fibo", "Print the fibonacci sequence up to a value 'n'");
+    options.add_options()
+      ("n,value", "The value to print to", cxxopts::value<int>()->default_value("10"));
+
+  auto result = options.parse(argc, argv);
+  auto n = result["value"].as<int>();
+
+  for (int x : view::iota(1) | view::take(n)) {
+    fmt::print("fib({}) = {}\n", x, fib(x));
+  }
+}
+```
+
+This is a simple project of course, but it should give us a clean project to start with.
+Let's try it out!
+
+Let's assume you have `fmt`, `range-v3`, and `cxxopts` installed with vcpkg classic mode;
+then, you can just do a simple:
+
+```cmd
+D:\src\fibo> cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake
+-- Building for: Visual Studio 16 2019
+-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.19041.
+-- The CXX compiler identification is MSVC 19.27.29111.0
+-- Detecting CXX compiler ABI info
+-- Detecting CXX compiler ABI info - done
+-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx64/x64/cl.exe - skipped
+-- Detecting CXX compile features
+-- Detecting CXX compile features - done
+-- Configuring done
+-- Generating done
+-- Build files have been written to: D:/src/fibo/build
+D:\src\fibo> cmake --build build
+Microsoft (R) Build Engine version 16.7.0+b89cb5fde for .NET Framework
+Copyright (C) Microsoft Corporation. All rights reserved.
+
+  Checking Build System
+  Building Custom Rule D:/src/fibo/CMakeLists.txt
+  main.cxx
+  The contents of <span> are available only with C++20 or later.
+  fibo.vcxproj -> D:\src\fibo\build\Debug\fibo.exe
+  Building Custom Rule D:/src/fibo/CMakeLists.txt
+```
+
+And now we can try out the `fibo` binary!
+
+```cmd
+D:\src\fibo> .\build\Debug\fibo.exe -n 7 
+fib(1) = 1
+fib(2) = 1
+fib(3) = 2
+fib(4) = 3
+fib(5) = 5
+fib(6) = 8
+fib(7) = 13
+```
+
+it works!
+
+## Converting to Manifest Mode
+
+We now wish to use manifest mode, so all of our dependencies are managed for us! Let's write a `vcpkg.json`:
+
+```json
+{
+  "name": "fibo",
+  "version-string": "0.1.0",
+  "dependencies": [
+    "cxxopts",
+    "fmt",
+    "range-v3"
+  ]
+}
+```
+
+Let's delete the build directory and rerun the build:
+
+```cmd
+D:\src\fibo> rmdir /S /Q build
+D:\src\fibo> cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake
+-- Running vcpkg install
+Detecting compiler hash for triplet x64-windows...
+The following packages will be built and installed:
+    cxxopts[core]:x64-windows
+    fmt[core]:x64-windows
+    range-v3[core]:x64-windows
+Starting package 1/3: cxxopts:x64-windows
+Building package cxxopts[core]:x64-windows...
+Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\d2\d2d1e5302cdfefef2fd090d8eda84cc0c1fbe6f1.zip
+Building package cxxopts[core]:x64-windows... done
+Installing package cxxopts[core]:x64-windows...
+Installing package cxxopts[core]:x64-windows... done
+Elapsed time for package cxxopts:x64-windows: 50.64 ms
+Starting package 2/3: fmt:x64-windows
+Building package fmt[core]:x64-windows...
+Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\bf\bf00d5214e912d71414b545b241f54ef87fdf6e5.zip
+Building package fmt[core]:x64-windows... done
+Installing package fmt[core]:x64-windows...
+Installing package fmt[core]:x64-windows... done
+Elapsed time for package fmt:x64-windows: 225 ms
+Starting package 3/3: range-v3:x64-windows
+Building package range-v3[core]:x64-windows...
+Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\fe\fe2cdedef6953bf954e8ddca471bf3cc8d9b06d7.zip
+Building package range-v3[core]:x64-windows... done
+Installing package range-v3[core]:x64-windows...
+Installing package range-v3[core]:x64-windows... done
+Elapsed time for package range-v3:x64-windows: 1.466 s
+
+Total elapsed time: 1.742 s
+
+-- Running vcpkg install - done
+-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.19041.
+-- The CXX compiler identification is MSVC 19.27.29111.0
+-- Detecting CXX compiler ABI info
+-- Detecting CXX compiler ABI info - done
+-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx64/x64/cl.exe - skipped
+-- Detecting CXX compile features
+-- Detecting CXX compile features - done
+-- Configuring done
+-- Generating done
+-- Build files have been written to: D:/src/fibo/build
+D:\src\fibo> cmake --build build
+Microsoft (R) Build Engine version 16.7.0+b89cb5fde for .NET Framework
+Copyright (C) Microsoft Corporation. All rights reserved.
+
+  Checking Build System
+  Building Custom Rule D:/src/fibo/CMakeLists.txt
+  main.cxx
+  The contents of <span> are available only with C++20 or later.
+  fibo.vcxproj -> D:\src\fibo\build\Debug\fibo.exe
+  Building Custom Rule D:/src/fibo/CMakeLists.txt
+```
+
+You can see that with just a _single file_, we've changed over to manifests without _any_ trouble.
+The build system doesn't change _at all_! We just add a `vcpkg.json` file, delete the build directory,
+and reconfigure. And we're done!

docs/examples/packaging-github-repos.md

@@ -1,18 +1,22 @@
 ## Packaging Github Repos Example: libogg
-### Create the CONTROL file
-The `CONTROL` file is a simple set of fields describing the package's metadata.
-
-*For libogg, we'll create the file `ports\libogg\CONTROL` with the following contents:*
-```no-highlight
-Source: libogg
-Version: 1.3.3
-Description: Ogg is a multimedia container format, and the native file and stream format for the Xiph.org multimedia codecs.
+### Create the manifest file
+The manifest file (called `vcpkg.json`) is a json file describing the package's metadata.
+
+*For libogg, we'll create the file `ports/libogg/vcpkg.json` with the following contents:*
+```json
+{
+  "name": "libogg",
+  "version-string": "1.3.3",
+  "description": "Ogg is a multimedia container format, and the native file and stream format for the Xiph.org multimedia codecs."
+}
 ```
 
+You can format the manifest file to our specifications with `vcpkg x-format-manifest ports/libogg/vcpkg.json`.
+
 ### Create the portfile
 `portfile.cmake` describes how to build and install the package. First we download the project from Github with [`vcpkg_from_github`](../maintainers/vcpkg_from_github.md):
 
-```no-highlight
+```cmake
 vcpkg_from_github(
     OUT_SOURCE_PATH SOURCE_PATH
     REPO xiph/ogg
@@ -26,7 +30,7 @@ The important parts to update are `REPO` for the GitHub repository path, `REF` f
 
 Finally, we configure the project with CMake, install the package, and copy over the license file:
 
-```no-highlight
+```cmake
 vcpkg_configure_cmake(
     SOURCE_PATH ${SOURCE_PATH}
     PREFER_NINJA
@@ -40,14 +44,14 @@ Check the documentation for [`vcpkg_configure_cmake`](../maintainers/vcpkg_confi
 Now you can run `vcpkg install libogg` to build and install the package.
 
 ### Suggested example portfiles
-In the `ports\` directory are many libraries that can be used as examples, including many that are not based on CMake.
+In the `ports/` directory are many libraries that can be used as examples, including many that are not based on CMake.
 
 - Header only libraries
-    - rapidjson
-    - range-v3
+  - rapidjson
+  - range-v3
 - MSBuild-based
-    - cppunit
-    - mpg123
+  - cppunit
+  - mpg123
 - Non-CMake, custom buildsystem
-    - openssl
-    - ffmpeg
+  - openssl
+  - ffmpeg

docs/examples/packaging-zipfiles.md

@@ -13,28 +13,30 @@ Finally, if the server's name for the archive is not very descriptive (such as d
 
 *`zlib1211.zip` is a fine name, so no change needed.*
 
-All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports\<packagename>`.
+All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports/<packagename>`.
 
 ```no-highlight
-PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib-1.2.11.tar.gz zlib1211.tar.gz
+PS D:\src\vcpkg> ./vcpkg create zlib2 http://zlib.net/zlib-1.2.11.tar.gz zlib1211.tar.gz
 -- Generated portfile: D:/src/vcpkg/ports/zlib2/portfile.cmake
 ```
 
-### Create the CONTROL file
-In addition to the generated `ports\<package>\portfile.cmake`, we also need a `ports\<package>\CONTROL` file. This file is a simple set of fields describing the package's metadata.
+### Create the manifest file
+In addition to the generated `ports/<package>/portfile.cmake`, we also need a `ports/<package>/vcpkg.json` file. This file is a simple set of fields describing the package's metadata.
 
-*For zlib2, we'll create the file `ports\zlib2\CONTROL` with the following contents:*
-```no-highlight
-Source: zlib2
-Version: 1.2.11
-Description: A Massively Spiffy Yet Delicately Unobtrusive Compression Library
+*For zlib2, we'll create the file `ports/zlib2/vcpkg.json` with the following contents:*
+```json
+{
+  "name": "zlib2",
+  "version-string": "1.2.11",
+  "description": "A Massively Spiffy Yet Delicately Unobtrusive Compression Library"
+}
 ```
 
 ### Tweak the generated portfile
 The generated `portfile.cmake` will need some editing to correctly package most libraries in the wild, however we can start by trying out the build.
 
 ```no-highlight
-PS D:\src\vcpkg> .\vcpkg install zlib2
+PS D:\src\vcpkg> ./vcpkg install zlib2
 Computing installation plan...
 The following packages will be built and installed:
     zlib2[core]:x64-uwp
@@ -62,7 +64,7 @@ Found 3 error(s). Please correct the portfile:
 At this point, it is a matter of reading the error messages and log files while steadily improving the quality of the portfile. Zlib required providing a discrete copy of the LICENSE to copy into the package, suppressing the build and installation of executables and headers, and removing the static libraries after they were installed.
 
 ### Suggested example portfiles
-In the `ports\` directory are many libraries that can be used as examples, including many that are not based on CMake.
+In the `ports/` directory are many libraries that can be used as examples, including many that are not based on CMake.
 
 - Header only libraries
     - rapidjson