Document several commands.

This change documents the world after these land: * microsoft/vcpkg-tool#731 deletes --project in favor of --x-manifest-root * microsoft/vcpkg-tool#732 fixes warning messages to say vcpkg-artifacts instead of vcpkg-ce * microsoft/vcpkg-tool#733 fixes emitting warnings from vcpkg-configuration.json * microsoft/vcpkg-tool#734 deletes the almost unused --verbose The following are added here: * acquire * acquire-project * activate * add * deactivate * use --language and --allLanguages are intentionally undocumented for now while we figure out what we want to do with localization. Remaining issues I haven't fixed I noticed while doing this: * Artifacts doesn't appear to understand & or | in demands * `vcpkg use` doesn't work with deactivate
BillyONeal · Oct 8, 2022 · 04126ff · 04126ff
1 parent e2667a4
commit 04126ff
Show file tree

Hide file tree

Showing 8 changed files with 478 additions and 0 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -18,11 +18,18 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 ### Command Line Reference
 
 - [Common Options](commands/common-options.md)
+- [Artifacts Context Options](commands/artifacts-context-options.md)
 - Commands
+  - [vcpkg acquire](commands/acquire.md)
+  - [vcpkg acquire-project](commands/acquire-project.md)
+  - [vcpkg activate](commands/activate.md)
+  - [vcpkg add](commands/add.md)
+  - [vcpkg deactivate](commands/deactivate.md)
   - [vcpkg install](commands/install.md)
   - [vcpkg integrate](commands/integrate.md)
   - [vcpkg remove](commands/remove.md)
   - [vcpkg search](commands/search.md)
+  - [vcpkg use](commands/use.md)
 
 ### User Help
 

diff --git a/docs/commands/acquire-project.md b/docs/commands/acquire-project.md
@@ -0,0 +1,54 @@
+# vcpkg acquire-project
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/acquire-project.md).**
+
+**This command is part of the experimental feature, vcpkg-artifacts.**
+
+## Synopsis
+```no-highlight
+vcpkg acquire-project [artifacts context options]
+```
+
+## Description
+
+Downloads artifacts to the artifact cache specified in a vcpkg-configuration.json, without activating them.
+
+## Example
+```no-highlight
+$ type .\vcpkg-configuration.json
+{
+  "default-registry": {
+    "kind": "git",
+    "baseline": "e2667a41fc2fc578474e9521d7eb90b769569c83",
+    "repository": "https://github.com/microsoft/vcpkg"
+  },
+  "registries": [
+    {
+      "kind": "artifact",
+      "location": "https://aka.ms/vcpkg-ce-default",
+      "name": "microsoft"
+    }
+  ],
+  "requires": {
+    "microsoft:compilers/arm/gcc": "* 2020.10.0",
+    "microsoft:tools/ninja-build/ninja": "* 1.10.2"
+  }
+}
+$ vcpkg acquire-project
+warning: vcpkg-artifacts are experimental and may change at any time.
+ Artifact                           Version    Status        Dependency  Summary
+ microsoft:compilers/arm/gcc        2020.10.0  will install              GCC compiler for ARM CPUs.
+ microsoft:tools/ninja-build/ninja  1.10.2     will install              Ninja is a small build system with a focus on speed.
+```
+
+## Options
+
+All vcpkg commands support a set of [common options](common-options.md).
+
+All unrecognized options are considered [artifacts context options](artifacts-context-options.md).
+
+<a name="force"></a>
+
+### `--force`
+
+Acquires the indicated artifacts, even if they are already acquired.
diff --git a/docs/commands/acquire.md b/docs/commands/acquire.md
@@ -0,0 +1,46 @@
+# vcpkg acquire
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/acquire.md).**
+
+**This command is part of the experimental feature, vcpkg-artifacts.**
+
+## Synopsis
+```no-highlight
+vcpkg acquire [options] <artifact>...
+```
+
+## Description
+
+Download artifacts to the artifact cache, without activating them.
+
+## Example
+```no-highlight
+$ vcpkg acquire gcc
+warning: vcpkg-artifacts are experimental and may change at any time.
+ Artifact                     Version    Status        Dependency  Summary
+ microsoft:compilers/arm/gcc  2020.10.0  will install              GCC compiler for ARM CPUs.
+
+1 artifacts installed successfully
+```
+
+## Options
+
+All vcpkg commands support a set of [common options](common-options.md).
+
+All unrecognized options are considered [artifacts context options](artifacts-context-options.md).
+
+### artifact
+
+An artifact id or reference.
+
+<a name="version"></a>
+
+### `--version`
+
+The requested version of the artifact to acquire. If this switch is used, there must be one switch per artifact listed.
+
+<a name="force"></a>
+
+### `--force`
+
+Acquires the indicated artifacts, even if they are already acquired.
diff --git a/docs/commands/activate.md b/docs/commands/activate.md
@@ -0,0 +1,73 @@
+# vcpkg activate
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/activate.md).**
+
+**This command is part of the experimental feature, vcpkg-artifacts.**
+
+## Synopsis
+```no-highlight
+vcpkg activate [artifacts context options]
+```
+
+## Description
+
+Downloads and activates artifacts in the calling terminal as specified by vcpkg-configuration.json.
+
+## Example
+```no-highlight
+$ ninja --version
+ninja: The term 'ninja' is not recognized as a name of a cmdlet, function, script file, or executable program.
+Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
+$ type .\vcpkg-configuration.json
+{
+  "default-registry": {
+    "kind": "git",
+    "baseline": "e2667a41fc2fc578474e9521d7eb90b769569c83",
+    "repository": "https://github.com/microsoft/vcpkg"
+  },
+  "registries": [
+    {
+      "kind": "artifact",
+      "location": "https://aka.ms/vcpkg-ce-default",
+      "name": "microsoft"
+    }
+  ],
+  "requires": {
+    "microsoft:compilers/arm/gcc": "* 2020.10.0",
+    "microsoft:tools/ninja-build/ninja": "* 1.10.2"
+  }
+}
+$ vcpkg activate
+warning: vcpkg-artifacts are experimental and may change at any time.
+ Artifact                           Version    Status     Dependency  Summary
+ microsoft:compilers/arm/gcc        2020.10.0  installed              GCC compiler for ARM CPUs.
+ microsoft:tools/ninja-build/ninja  1.10.2     installed              Ninja is a small build system with a focus on speed.
+
+Project c:\Dev\test activated
+$ ninja --version
+1.10.2
+```
+
+## Options
+
+All vcpkg commands support a set of [common options](common-options.md).
+
+All unrecognized options are considered [artifacts context options](artifacts-context-options.md).
+
+<a name="force"></a>
+
+### `--force`
+
+Acquires the indicated artifacts, even if they are already acquired.
+
+<a name="msbuild-props"></a>
+
+### `--msbuild-props path`
+
+Generates a file at `path` which contains MSBuild activation context.
+
+<a name="json"></a>
+
+### `--json path`
+
+Generates a file at `path` which contains the activation context that is being set on the terminal.
diff --git a/docs/commands/add.md b/docs/commands/add.md
@@ -0,0 +1,73 @@
+# vcpkg add
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/add.md).**
+
+**This command is part of the experimental feature, vcpkg-artifacts.**
+
+## Synopsis
+```no-highlight
+vcpkg add artifact <artifact>...
+
+vcpkg add port <port> <port options>...
+```
+
+## Description
+
+Adds a new artifact or port dependency reference to a manifest.
+
+## Example
+```no-highlight
+$ type vcpkg.json
+{}
+$ type vcpkg-configuration.json
+{
+  "default-registry": {
+    "kind": "git",
+    "baseline": "e2667a41fc2fc578474e9521d7eb90b769569c83",
+    "repository": "https://github.com/microsoft/vcpkg"
+  },
+  "registries": [
+    {
+      "kind": "artifact",
+      "location": "https://aka.ms/vcpkg-ce-default",
+      "name": "microsoft"
+    }
+  ]
+}
+$ vcpkg add port zlib
+Succeeded in adding ports to vcpkg.json file.
+$ vcpkg add artifact gcc
+warning: vcpkg-artifacts are experimental and may change at any time.
+ Artifact                     Version    Status     Dependency  Summary
+ microsoft:compilers/arm/gcc  2020.10.0  installed              GCC compiler for ARM CPUs.
+
+Run `vcpkg activate` to apply to the current terminal
+$ type vcpkg.json
+{
+  "dependencies": [
+    "zlib"
+  ]
+}
+$ type .\vcpkg-configuration.json
+{
+  "default-registry": {
+    "kind": "git",
+    "baseline": "e2667a41fc2fc578474e9521d7eb90b769569c83",
+    "repository": "https://github.com/microsoft/vcpkg"
+  },
+  "registries": [
+    {
+      "kind": "artifact",
+      "location": "https://aka.ms/vcpkg-ce-default",
+      "name": "microsoft"
+    }
+  ],
+  "requires": {
+    "microsoft:compilers/arm/gcc": "* 2020.10.0"
+  }
+}
+```
+
+## Options
+
+All vcpkg commands support a set of [common options](common-options.md).
diff --git a/docs/commands/artifacts-context-options.md b/docs/commands/artifacts-context-options.md
@@ -0,0 +1,93 @@
+# Artifacts Context Options
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/artifacts-context-options.md).**
+
+Many vcpkg-artifacts commands accept an arbitrary number of extra arguments which control resolving which artifacts are used, usually for selecting the correct host or target architecture.
+
+<a name="windows"></a>
+
+## `--windows`
+
+Indicates that the host is a Windows system. Causes the constant `windows` to become true in demands.
+
+<a name="osx"></a>
+
+## `--osx`
+
+Indicates that the host is a MacOS / osx system. Causes the constant `osx` to become true in demands.
+
+<a name="linux"></a>
+
+## `--linux`
+
+Indicates that the host is a Linux system. Causes the constant `linux` to become true in demands.
+
+<a name="freebsd"></a>
+
+## `--freebsd`
+
+Indicates that the host is a FreeBSD system. Causes the constant `freebsd` to become true in demands.
+
+<a name="x64"></a>
+
+## `--x64`
+
+Indicates that the host is an x64 / amd64 system. Causes the constant `x64` to become true in demands.
+
+<a name="x86"></a>
+
+## `--x86`
+
+Indicates that the host is an x86 system. Causes the constant `x86` to become true in demands.
+
+<a name="arm"></a>
+
+## `--arm`
+
+Indicates that the host is an arm system. Causes the constant `arm` to become true in demands.
+
+<a name="arm64"></a>
+
+## `--arm64`
+
+Indicates that the host is an arm64 system. Causes the constant `arm64` to become true in demands.
+
+<a name="otherwise"></a>
+
+## `--anything value`
+
+Causes the constant `anything:value` to become true in demands. Note that `anything` can be anything. For example:
+
+```no-highlight
+$ type .\vcpkg-configuration.json
+{
+  "default-registry": { /* ... */ },
+  "registries": [ /* ... */ ],
+  "demands": {
+    "example:hello": {
+      "error": "example:hello matched"
+    },
+    "example:world and x86": {
+      "error": "example:world and x86 matched"
+    },
+    "example:world and x64": {
+      "error": "example:world and x64 matched"
+    },
+    "arm": {
+      "error": "arm matched"
+    }
+  }
+}
+$ vcpkg activate --example hello
+warning: vcpkg-artifacts are experimental and may change at any time.
+ERROR: c:\Dev\test\vcpkg-configuration.json - example:hello matched
+$ vcpkg activate --example world
+warning: vcpkg-artifacts are experimental and may change at any time.
+ERROR: c:\Dev\test\vcpkg-configuration.json - example:world & x64 matched
+$ vcpkg activate --example world --x86
+warning: vcpkg-artifacts are experimental and may change at any time.
+ERROR: c:\Dev\test\vcpkg-configuration.json - example:world & x86 matched
+$ vcpkg activate --arm
+warning: vcpkg-artifacts are experimental and may change at any time.
+ERROR: c:\Dev\test\vcpkg-configuration.json - arm matched
+```