3party/vcpkg
0
0
Fork 0
mirror of https://github.com/microsoft/vcpkg.git synced 2024-12-27 18:31:15 +08:00
Code Issues Projects Releases Wiki Activity

[docs] Initial addition of CLI Reference docs (#24754)

Browse Source 
* [docs] Initial addition of CLI Reference docs

* PR comments round 1

* [docs] Fix manifests.md TOC

* [docs] Sort common options

* [docs] Apply PR comments
This commit is contained in:
Robert Schumacher 2022-05-27 09:34:11 -07:00 committed by GitHub
parent a97ebbef7f
commit 36b6831d19
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 358 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/README.md
View File

@ -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/buildsystems/integration.md)

121
docs/commands/common-options.md Normal file
View File

@ -0,0 +1,121 @@
# 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).**
Most vcpkg commands accept a group of common options that control cross-cutting aspects of the tool. Not all options affect every command. For example, a command that does not download any files will be unaffected by changing the downloads directory.
<a name="asset-sources"></a>
## `--x-asset-sources=<config>`
**Experimental: will change or be removed at any time**
Specify the cache configuration for [Asset Caching](../users/assetcaching.md).
<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="buildtrees-root"></a>
## `--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.
Defaults to `buildtrees/` under the vcpkg root folder.
<a name="downloads-root"></a>
## `--downloads-root=<path>`
Specify where downloaded tools and source code archives should be kept.
Defaults to the `VCPKG_DOWNLOADS` environment variable. If that is unset, defaults to `downloads/` under the vcpkg root folder.
<a name="host-triplet"></a>
## `--host-triplet=<triplet>`
Specify the host [architecture triplet][triplets].
Defaults to the `VCPKG_DEFAULT_HOST_TRIPLET` environment variable. If that is unset, deduced based on the host architecture and operating system.
<a name="install-root"></a>
## `--x-install-root=<path>`
**Experimental: will change or be removed at any time**
Specifies the path to lay out installed packages.
In Classic Mode, defaults to `installed/` under the vcpkg root folder.
In [Manifest Mode][../users/manifests.md], defaults to `vcpkg_installed/` under the manifest folder.
<a name="manifest-root"></a>
### `--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 for the nearest `vcpkg.json`.
<a name="overlay-ports"></a>
## `--overlay-ports=<path>`
Specifies a directory containing [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>`
Specifies a directory containing [overlay triplets](../examples/overlay-triplets-linux-dynamic.md).
This option can be specified multiple times; [triplets][] will resolve to the first match.
<a name="packages-root"></a>
## `--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.
Defaults to `packages/` under the vcpkg root folder.
<a name="triplet"></a>
## `--triplet=<triplet>`
Specify the target [architecture triplet][triplets].
Defaults to the `VCPKG_DEFAULT_TRIPLET` environment variable. If that is unset, deduced based on the host architecture and operating system.
Note that on Windows operating systems, the architecture is always deduced as x86 for legacy reasons.
<a name="vcpkg-root"></a>
## `--vcpkg-root=<path>`
Specifies the vcpkg root folder.
Defaults to the directory containing the vcpkg program. The directory must be a valid vcpkg instance, such as a `git clone` of `https://github.com/microsoft/vcpkg`. This option can be used to run a custom-built copy of the tool directly from the build folder.
## 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

13
docs/commands/index.md Normal file
View File

@ -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).

183
docs/commands/install.md Normal file
View File

@ -0,0 +1,183 @@
# 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 port packages.
### Classic Mode
In Classic Mode, this verb adds port packages to the existing set in the [installed directory][] (defaults to `installed/` under the vcpkg root). This can require removing and rebuilding existing packages, which can fail.
**Package Syntax**
```
portname[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 `vcpkg.json` manifest file, adding, removing, or rebuilding packages as needed.
[installed directory]: common-options.md#install-root
## Options
All vcpkg commands support a set of [common options](common-options.md).
### `--allow-unsupported`
Instead of stopping on an unsupported port, continue with a warning.
By default, vcpkg refuses to execute an install plan containing a port installation for a triplet outside its [`"supports"`][] clause. The [`"supports"`][] clause of a package describes the full set of platforms a package is expected to be buildable on. This flag instructs vcpkg to warn that the build is expected to fail instead of stopping.
### `--clean-after-build`
Clean buildtrees, packages, and downloads after building each package.
This option has the same effect as passing [`--clean-buildtrees-after-build`](#clean-buildtrees-after-build), [`--clean-downloads-after-build`](#clean-downloads-after-build), and [`--clean-packages-after-build`](#clean-packages-after-build).
<a id="clean-buildtrees-after-build"></a>
### `--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. All subdirectories will be deleted.
<a id="clean-downloads-after-build"></a>
### `--clean-downloads-after-build`
Clean all unextracted assets from the `downloads/` folder after building each package.
All top level files in the `downloads/` folder will be deleted. Extracted tools will be kept.
<a id="clean-packages-after-build"></a>
### `--clean-packages-after-build`
Clean the packages temporary subfolder after building each package.
The packages subfolder for the built package (for example, `packages/zlib_x64-windows`) will be deleted after installation.
### `--dry-run`
Print the install plan, but do not remove or install any packages.
The install plan lists all packages and features that will be installed, as well as any other packages that need to be removed and rebuilt.
### `--editable`
**Classic Mode Only**
Perform editable builds for all directly referenced packages on the command line.
When vcpkg builds ports, it purges and re-extracts the source code each time to ensure inputs are accurately. This is necessary for [Manifest Mode][] to accurately update what is installed and [Binary Caching][] to ensure cached content is correct.
Passing the `--editable` flag disables this behavior, preserving edits to the extracted sources in the `buildtrees/` folder. This helps develop patches quickly by avoiding the need to write a file on each change.
Sources extracted during an editable build do not have a `.clean/` suffix on the directory name and will not be cleared by subsequent non-editable builds.
### `--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](../users/manifests.md#features) from the `vcpkg.json` to install dependencies for.
By default, only [`"dependencies"`](../users/manifests.md#dependencies) and the dependencies of the [`"default-features"`](../users/manifests.md#default-features) will be installed.
### `--head`
**Classic Mode Only**
Request all packages explicitly referenced on the command line to 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 explicitly referenced packages and their dependents because vcpkg cannot accurately track all inputs.
### `--keep-going`
Continue the install plan after the first failure.
By default, vcpkg will stop at the first package build failure. This flag instructs vcpkg to continue building and installing other parts of the install plan that don't depend upon 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 ports from downloading new assets during the build.
By default, ports will acquire source code and tools on demand from the internet (subject to [Asset Caching][]). This parameter blocks downloads and restricts ports 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 each build in the plan until it makes its first non-downloading external process call. Most ports perform all downloads before the first external process call (usually to their buildsystem), so this procedure will download all required assets. Ports that do not follow this procedure will not have their assets predownloaded.
### `--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.
<a id="write-nuget-packages-config"></a>
### `--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

77
docs/users/manifests.md
View File

@ -23,7 +23,20 @@ manifest mode.
- [Simple Example Manifest](#simple-example-manifest)
- [Manifest Syntax Reference](#manifest-syntax-reference)
- [Command Line Interface](#command-line-interface)
- [`"name"`](#name)
- [Version Fields](#version-fields)
- [`"description"`](#description)
- [`"builtin-baseline"`](#builtin-baseline)
- [`"dependencies"`](#dependencies)
- [`"name"`](#dependencies-name)
- [`"default-features"`](#dependencies-default-features)
- [`"features"`](#dependencies-features)
- [`"platform"`](#platform)
- [`"version>="`](#version-gt)
- [`"overrides"`](#overrides)
- [`"supports"`](#supports)
- [`"features"`](#features)
- [`"default-features"`](#default-features)
See also [the original specification](../specifications/manifests.md) for more low-level details.
@ -59,6 +72,8 @@ These comment fields are not allowed in any objects which permit user-defined ke
Each manifest contains a top level object with the fields documented below; the most important ones are
[`"name"`](#name), the [version fields](#version-fields), and [`"dependencies"`](#dependencies):
<a id="name"></a>
### `"name"`
This is the name of your project! It must be formatted in a way that vcpkg understands - in other words,
@ -67,7 +82,7 @@ For example, `Boost.Asio` might be given the name `boost-asio`.
This is a required field.
### Version fields
### Version Fields
There are four version field options, depending on how the port orders its
releases.
@ -89,6 +104,8 @@ field should not be used.
See [versioning](versioning.md#version-schemes) for more details.
<a id="description"></a>
### `"description"`
This is where you describe your project. Give it a good description to help in searching for it!
@ -96,6 +113,8 @@ This can be a single string, or it can be an array of strings;
in the latter case, the first string is treated as a summary,
while the remaining strings are treated as the full description.
<a id="builtin-baseline"></a>
### `"builtin-baseline"`
This field indicates the commit of vcpkg which provides global minimum version
@ -108,6 +127,8 @@ registry in
See [versioning](versioning.md#builtin-baseline) for more semantic details.
<a id="dependencies"></a>
### `"dependencies"`
This field lists all the dependencies you'll need to build your library (as well as any your dependents might need,
@ -136,10 +157,15 @@ if they were to use you). It's an array of strings and objects:
]
```
<a id="dependencies-name"></a>
#### `"name"` Field
The name of the dependency. This follows the same restrictions as the [`"name"`](#name) property for a project.
<a id="dependencies-default-features"></a>
<a id="dependencies-features"></a>
#### `"features"` and `"default-features"` Fields
`"features"` is an array of feature names which tell you the set of features that the
@ -160,6 +186,7 @@ Then, you might just ask for:
```
<a id="platform"></a>
#### `"platform"` Field
The `"platform"` field defines the platforms where the dependency should be installed - for example,
@ -185,6 +212,8 @@ The common identifiers are:
although one can define their own.
<a id="version-gt"></a>
#### `"version>="` Field
A minimum version constraint on the dependency.
@ -194,6 +223,8 @@ This field specifies the minimum version of the dependency, optionally using a
See also [versioning](versioning.md#version-1) for more semantic details.
<a id="overrides"></a>
### `"overrides"`
This field pins exact versions for individual dependencies.
@ -212,6 +243,8 @@ See also [versioning](versioning.md#overrides) for more semantic details.
]
```
<a id="supports"></a>
### `"supports"`
If your project doesn't support common platforms, you can tell your users this with the `"supports"` field.
@ -219,6 +252,8 @@ It uses the same platform expressions as [`"platform"`](#platform), from depende
`"supports"` field of features.
For example, if your library doesn't support linux, you might write `{ "supports": "!linux" }`.
<a id="default-features"></a>
<a id="features"></a>
### `"features"` and `"default-features"`
@ -275,41 +310,3 @@ and that's the `"default-features"` field, which is an array of feature names.
}
}
```
## Command Line Interface
When invoked from any subdirectory of the directory containing `vcpkg.json`, `vcpkg install` with no package arguments
will install all manifest dependencies into `<directory containing vcpkg.json>/vcpkg_installed/`. Most of `vcpkg
install`'s classic mode parameters function the same in manifest mode.
### `--x-install-root=<path>`
**Experimental and may change or be removed at any time**
Specifies an alternate install location than `<directory containing vcpkg.json>/vcpkg_installed/`.
### `--triplet=<triplet>`
Specify the triplet to be used for installation.
Defaults to the same default triplet as in classic mode.
### `--x-feature=<feature>`
**Experimental and may change or be removed at any time**
Specify an additional feature from the `vcpkg.json` to install dependencies from.
### `--x-no-default-features`
**Experimental and may change or be removed at any time**
Disables automatic activation of all default features listed in the `vcpkg.json`.
### `--x-manifest-root=<path>`
**Experimental and may change or be removed at any time**
Specifies the directory containing `vcpkg.json`.
Defaults to searching upwards from the current working directory.