[docs] Initial addition of CLI Reference docs

docs/README.md

@@ -12,6 +12,10 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 - [Patching Example: Patching libpng to work for x64-uwp](examples/patching.md)
 - [Getting Started with Versioning](examples/versioning.getting-started.md)
 
+### Command Line Reference
+
+- [Command Line Reference](commands/index.md)
+
 ### User Help
 
 - [Buildsystem Integration](users/integration.md)

docs/commands/common-options.md

@@ -0,0 +1,115 @@
+# Common Command Options
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/common-options.md).**
+
+All vcpkg commands accept a group of common options that control cross-cutting aspects of the tool.
+
+<a name="triplet"></a>
+
+## `--triplet=<triplet>`
+
+Specify the target [architecture triplet][triplets].
+
+If unset, defaults to the `VCPKG_DEFAULT_TRIPLET` environment variable. If that is unset, it is deduced based on the host architecture and operating system.
+
+<a name="host-triplet"></a>
+
+## `--host-triplet=<triplet>`
+
+Specify the host [architecture triplet][triplets].
+
+If unset, defaults to the `VCPKG_DEFAULT_HOST_TRIPLET` environment variable. If that is unset, it is deduced based on the host architecture and operating system.
+
+<a name="overlay-ports"></a>
+
+## `--overlay-ports=<path>`
+
+Specify a directory to be considered for [overlay ports](../specifications/ports-overlay.md).
+
+This option can be specified multiple times; ports will resolve to the first match.
+
+<a name="overlay-triplets"></a>
+
+## `--overlay-triplets=<path>`
+
+Specify a directory to be considered for [overlay triplets](../examples/overlay-triplets-linux-dynamic.md).
+
+This option can be specified multiple times; [triplets][] will resolve to the first match.
+
+<a name="binarysource"></a>
+
+## `--binarysource=<config>`
+
+Add a source for [Binary Caching](../users/binarycaching.md).
+
+This option can be specified multiple times; see the Binary Caching documentation for how multiple binary sources interact.
+
+<a name="x-asset-sources"></a>
+
+## `--x-asset-sources=<config>`
+
+**Experimental: will change or be removed at any time**
+
+Add a source for [Asset Caching](../users/assetcaching.md).
+
+This option can be specified multiple times; see the Asset Caching documentation for how multiple binary sources interact.
+
+## `--downloads-root=<path>`
+
+Specify where downloaded tools and source code archives should be kept.
+
+If unset, defaults to the `VCPKG_DOWNLOADS` environment variable. If that is unset, defaults to `downloads/` under the vcpkg root folder.
+
+## `--vcpkg-root=<path>`
+
+Specifies the vcpkg root folder.
+
+This folder should be a valid vcpkg instance, such as a `git clone` of `https://github.com/microsoft/vcpkg`.
+
+### `--x-manifest-root=<path>`
+
+**Experimental: will change or be removed at any time**
+
+Specifies the directory containing [`vcpkg.json`](../users/manifests.md).
+
+Defaults to searching upwards from the current working directory.
+
+## `--x-buildtrees-root=<path>`
+
+**Experimental: will change or be removed at any time**
+
+Specifies the temporary path to store intermediate build files, such as objects or unpacked source code.
+
+If unset, defaults to `buildtrees/` under the vcpkg root folder.
+
+## `--x-install-root=<path>`
+
+**Experimental: will change or be removed at any time**
+
+Specifies the path to lay out installed packages.
+
+If unset in classic mode, defaults to `installed/` under the vcpkg root folder. If unset in manifest mode, defaults to `vcpkg_installed/` under the manifest folder.
+
+## `--x-packages-root=<path>`
+
+**Experimental: will change or be removed at any time**
+
+Specifies the temporary path to stage intermediate package files before final install.
+
+If unset, defaults to `packages/` under the vcpkg root folder.
+
+## `--x-json`
+
+**Experimental: will change or be removed at any time**
+
+Requests structured JSON output from the command instead of human-readable output.
+
+*Note: most commands do not currently respect this option.*
+
+## Response Files (`@<file>`)
+
+The vcpkg command line accepts text files containing newline-separated command line parameters.
+
+The tool will act as though the items in the file were spliced into the command line in place of the `@` reference. Response files cannot contain additional response files.
+
+[triplets]: ../users/triplets.md

docs/commands/index.md

@@ -0,0 +1,13 @@
+# vcpkg Command Line Reference
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/index.md).**
+
+## Contents
+
+- [Common Options](common-options.md)
+- Commands
+  - [vcpkg install](install.md)
+
+## Source
+
+The vcpkg command line is developed in a separate repository on GitHub: [microsoft/vcpkg-tool](https://github.com/microsoft/vcpkg-tool). Issues should be posted to [microsoft/vcpkg](https://github.com/microsoft/vcpkg/issues).

docs/commands/install.md

@@ -0,0 +1,165 @@
+# vcpkg install
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/install.md).**
+
+## Synopsis
+
+**Classic Mode**
+```no-highlight
+vcpkg install [options] [<package>...]
+```
+
+**Manifest Mode**
+```no-highlight
+vcpkg install [options]
+```
+
+## Description
+
+Build and install packages.
+
+### Classic Mode
+
+In Classic Mode, this verb adds packages to the existing set in the installed directory. This may require rebuilding existing packages with new features.
+
+**Package Syntax**
+```
+name[feature1,feature2]:triplet
+```
+
+Package references without a triplet are automatically qualified by the [default target triplet](common-options.md#triplet). Package references that do not explicitly list `core` are considered to imply all default features.
+
+### Manifest Mode
+
+In [Manifest Mode][], this verb sets the installed directory to the state specified by the manifest file, adding, removing, or rebuilding packages as needed.
+
+## Options
+
+All vcpkg commands support a set of [common options](common-options.md).
+
+### `--allow-unsupported`
+
+Instead of erroring on an unsupported port, continue with a warning.
+
+By default, vcpkg will refuse to execute an install plan that contains a port installation for an unsupported triplet. This flag allows the plan to be executed ignoring the [`"supports"`][] field, although the build is likely to fail.
+
+### `--clean-after-build`
+
+Clean buildtrees, packages, and downloads after building each package.
+
+### `--clean-buildtrees-after-build`
+
+Clean all subdirectories from the buildtrees temporary subfolder after building each package.
+
+All top-level files in the buildtrees subfolder (e.g. `buildtrees/zlib/config-x64-windows-out.log`) will be kept.
+
+### `--clean-downloads-after-build`
+
+Clean all unextracted assets from the `downloads/` folder after building each package.
+
+Extracted tools will be kept even with this flag.
+
+### `--clean-packages-after-build`
+
+Clean the packages temporary subfolder after building each package.
+
+### `--dry-run`
+
+Only print the install plan, do not remove or install any packages.
+
+### `--editable`
+
+**Classic Mode Only**
+
+Perform editable builds for all directly referenced packages on the command line.
+
+When vcpkg builds packages, it purges and re-extracts the source code each time to ensure it can accurately track what inputs were used. This is necessary for [Manifest Mode][] as well as [Binary Caching][].
+
+However, while developing a package it can be useful to edit the sources in-place and quickly request a new package build using the edited sources. Editable builds will not clean out the sources each time, enabling them to be modified with a text editor in the `buildtrees/` folder and quickly rebuilt.
+
+### `--enforce-port-checks`
+
+Fail install if a port has detected problems or attempts to use a deprecated feature.
+
+By default, vcpkg will run several checks on built packages and emit warnings if any issues are detected. This flag upgrades those warnings to an error.
+
+### `--x-feature=<feature>`
+
+**Experimental and may change or be removed at any time**
+
+**[Manifest Mode][] Only**
+
+Specify an additional feature from the `vcpkg.json` to install dependencies for.
+
+### `--head`
+
+**Classic Mode Only**
+
+Request that all packages explicitly referenced on the command line fetch the latest sources available when building.
+
+This flag is only intended for temporary testing and is not intended for production or long-term use.
+
+This disables Binary Caching for all referenced packages and any packages that depend upon them, since vcpkg cannot accurately track all inputs.
+
+### `--keep-going`
+
+Continue the install plan after the first failure.
+
+Without this flag, vcpkg will stop at the first package build failure. With this flag, vcpkg will continue to build and install other parts of the install plan that don't depend on the failed package.
+
+### `--x-no-default-features`
+
+**Experimental and may change or be removed at any time**
+
+**[Manifest Mode][] Only**
+
+Don't install the default features from the top-level manifest.
+
+When using `install` in Manifest Mode, by default all dependencies of the features listed in [`"default-features"`][] will be installed. This flag disables that behavior so (without any `TODO` flags) only the dependencies listed in [`"dependencies"`][] will be installed.
+
+### `--no-downloads`
+
+When building a package, prevent recipes from downloading new assets during the build.
+
+By default, recipes will acquire source code and tools on demand from the internet (subject to [Asset Caching][]). This parameter blocks downloads and restricts recipes to only the assets that were previously downloaded and cached on the machine.
+
+### `--only-downloads`
+
+Attempt to download all assets required for an install plan without performing any builds.
+
+When passed this option, vcpkg will run every recipe in the plan until they make their first non-downloading external process call. Most recipes perform all required downloads before this call (which is usually to their buildsystem), so this procedure will successfully run all download steps without executing the underlying build.
+
+### `--only-binarycaching`
+
+Refuse to perform any builds. Only restore packages from [Binary Caches][Binary Caching].
+
+This flag blocks vcpkg from performing builds on demand and will fail if a package cannot be found in any binary caches.
+
+### `--recurse`
+
+**Classic Mode Only**
+
+Approve an install plan that requires rebuilding packages.
+
+In order to modify the set of features of an installed package, vcpkg must remove and rebuild that package. Because this has the potential of failing and leaving the install tree with fewer packages than the user started with, the user must approve plans that rebuild packages by passing this flag.
+
+### `--x-use-aria2`
+
+**Experimental and may change or be removed at any time**
+
+Use aria2 to perform download tasks.
+
+### `--x-write-nuget-packages-config`
+
+**Experimental and may change or be removed at any time**
+
+Writes out a NuGet `packages.config`-formatted file for use with [Binary Caching][].
+
+This option can be used in conjunction with `--dry-run` to obtain the list of NuGet packages required from [Binary Caching][] without building or installing any packages. This enables the NuGet command line to be invoked separately for advanced scenarios, such as using alternate protocols to acquire the `.nupkg` files.
+
+[Asset Caching]: ../users/assetcaching.md
+[Binary Caching]: ../users/binarycaching.md
+[Manifest Mode]: ../users/manifests.md
+[`"supports"`]: ../users/manifests.md#supports
+[`"default-features"`]: ../users/manifests.md#default-features
+[`"dependencies"`]: ../users/manifests.md#dependencies