From 04126ffbb30a4f6a21710dd8d205640a5adce8fe Mon Sep 17 00:00:00 2001 From: Billy O'Neal Date: Fri, 7 Oct 2022 18:23:42 -0700 Subject: [PATCH] Document several commands. This change documents the world after these land: * https://github.com/microsoft/vcpkg-tool/pull/731 deletes --project in favor of --x-manifest-root * https://github.com/microsoft/vcpkg-tool/pull/732 fixes warning messages to say vcpkg-artifacts instead of vcpkg-ce * https://github.com/microsoft/vcpkg-tool/pull/733 fixes emitting warnings from vcpkg-configuration.json * https://github.com/microsoft/vcpkg-tool/pull/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 --- docs/README.md | 7 ++ docs/commands/acquire-project.md | 54 +++++++++++++ docs/commands/acquire.md | 46 +++++++++++ docs/commands/activate.md | 73 +++++++++++++++++ docs/commands/add.md | 73 +++++++++++++++++ docs/commands/artifacts-context-options.md | 93 ++++++++++++++++++++++ docs/commands/deactivate.md | 69 ++++++++++++++++ docs/commands/use.md | 63 +++++++++++++++ 8 files changed, 478 insertions(+) create mode 100644 docs/commands/acquire-project.md create mode 100644 docs/commands/acquire.md create mode 100644 docs/commands/activate.md create mode 100644 docs/commands/add.md create mode 100644 docs/commands/artifacts-context-options.md create mode 100644 docs/commands/deactivate.md create mode 100644 docs/commands/use.md diff --git a/docs/README.md b/docs/README.md index 5eec48b7cd5b2e..a38caac6f740f5 100644 --- 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 new file mode 100644 index 00000000000000..04bc4fdfc6b744 --- /dev/null +++ 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). + + + +### `--force` + +Acquires the indicated artifacts, even if they are already acquired. diff --git a/docs/commands/acquire.md b/docs/commands/acquire.md new file mode 100644 index 00000000000000..65104c75770f45 --- /dev/null +++ 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] ... +``` + +## 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. + + + +### `--version` + +The requested version of the artifact to acquire. If this switch is used, there must be one switch per artifact listed. + + + +### `--force` + +Acquires the indicated artifacts, even if they are already acquired. diff --git a/docs/commands/activate.md b/docs/commands/activate.md new file mode 100644 index 00000000000000..f117a3c39cc4a1 --- /dev/null +++ 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). + + + +### `--force` + +Acquires the indicated artifacts, even if they are already acquired. + + + +### `--msbuild-props path` + +Generates a file at `path` which contains MSBuild activation context. + + + +### `--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 new file mode 100644 index 00000000000000..1122d883b2c8b4 --- /dev/null +++ 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 ... + +vcpkg add port ... +``` + +## 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 new file mode 100644 index 00000000000000..ed1c9ec86fcaaa --- /dev/null +++ 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. + + + +## `--windows` + +Indicates that the host is a Windows system. Causes the constant `windows` to become true in demands. + + + +## `--osx` + +Indicates that the host is a MacOS / osx system. Causes the constant `osx` to become true in demands. + + + +## `--linux` + +Indicates that the host is a Linux system. Causes the constant `linux` to become true in demands. + + + +## `--freebsd` + +Indicates that the host is a FreeBSD system. Causes the constant `freebsd` to become true in demands. + + + +## `--x64` + +Indicates that the host is an x64 / amd64 system. Causes the constant `x64` to become true in demands. + + + +## `--x86` + +Indicates that the host is an x86 system. Causes the constant `x86` to become true in demands. + + + +## `--arm` + +Indicates that the host is an arm system. Causes the constant `arm` to become true in demands. + + + +## `--arm64` + +Indicates that the host is an arm64 system. Causes the constant `arm64` to become true in demands. + + + +## `--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 +``` diff --git a/docs/commands/deactivate.md b/docs/commands/deactivate.md new file mode 100644 index 00000000000000..f6920a82982fd0 --- /dev/null +++ b/docs/commands/deactivate.md @@ -0,0 +1,69 @@ +# vcpkg deactivate + +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/deactivate.md).** + +**This command is part of the experimental feature, vcpkg-artifacts.** + +## Synopsis +```no-highlight +vcpkg deactivate +``` + +## Description + +Undoes any terminal manipulation previously performed by a call to `activate`. + +## Example +```no-highlight +$ type .\vcpkg-configuration.json +{ + "default-registry": { /* ... */ }, + "registries": [ /* ... */ ], + "requires": { + "microsoft:tools/kitware/cmake": "* 3.20.1", + "microsoft:tools/ninja-build/ninja": "* 1.10.2" + } +} +$ cmake +cmake: The term 'cmake' 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. +$ ninja +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. +$ vcpkg activate +warning: vcpkg-artifacts are experimental and may change at any time. + Artifact Version Status Dependency Summary + microsoft:tools/kitware/cmake 3.20.1 installed Kitware's cmake tool + 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 +$ cmake +Usage + + cmake [options] + cmake [options] + cmake [options] -S -B + +Specify a source directory to (re-)generate a build system for it in the +current working directory. Specify an existing build directory to +re-generate its build system. + +Run 'cmake --help' for more information. + +$ ninja +ninja: error: loading 'build.ninja': The system cannot find the file specified. + +$ vcpkg deactivate +warning: vcpkg-artifacts are experimental and may change at any time. +Deactivating project c:\Dev\test\vcpkg-configuration.json +$ cmake +cmake: The term 'cmake' 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. +$ ninja +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. +``` + +## Options + +All vcpkg commands support a set of [common options](common-options.md). diff --git a/docs/commands/use.md b/docs/commands/use.md new file mode 100644 index 00000000000000..1a654d202bb89d --- /dev/null +++ b/docs/commands/use.md @@ -0,0 +1,63 @@ +# vcpkg use + +**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/use.md).** + +**This command is part of the experimental feature, vcpkg-artifacts.** + +## Synopsis +```no-highlight +vcpkg use ... +``` + +## Description + +Activates a single artifact for use in the calling terminal. + +## Example +```no-highlight +$ cmake +cmake: The term 'cmake' 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. +$ vcpkg use cmake +warning: vcpkg-artifacts are experimental and may change at any time. + Artifact Version Status Dependency Summary + microsoft:tools/kitware/cmake 3.20.1 installed Kitware's cmake tool + +Activating individual artifacts +$ cmake +Usage + + cmake [options] + cmake [options] + cmake [options] -S -B + +Specify a source directory to (re-)generate a build system for it in the +current working directory. Specify an existing build directory to +re-generate its build system. + +Run 'cmake --help' for more information. +``` + +## 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). + + + +### `--version` + +The requested version of the artifact to acquire. If this switch is used, there must be one switch per artifact listed. + + + +### `--force` + +Acquires the indicated artifacts, even if they are already acquired. + + + +### `--msbuild-props path` + +Generates a file at `path` which contains MSBuild activation context.