diff --git a/src/bin/cargo/cli.rs b/src/bin/cargo/cli.rs index 89f27f1019a..19e40d588e8 100644 --- a/src/bin/cargo/cli.rs +++ b/src/bin/cargo/cli.rs @@ -438,6 +438,7 @@ Some common cargo commands are (see all commands with --list): doc, d Build this package's and its dependencies' documentation new Create a new cargo package init Create a new cargo package in an existing directory + add Add dependencies to a manifest file run, r Run a binary or example of the local package test, t Run the tests bench Run the benchmarks diff --git a/src/doc/man/cargo-add.md b/src/doc/man/cargo-add.md new file mode 100644 index 00000000000..9f92d7508a2 --- /dev/null +++ b/src/doc/man/cargo-add.md @@ -0,0 +1,157 @@ +# cargo-add(1) +{{*set actionverb="Add"}} +{{*set nouns="adds"}} + +## NAME + +cargo-add - Add dependencies to a Cargo.toml manifest file + +## SYNOPSIS + +`cargo add` [_options_] _crate_...\ +`cargo add` [_options_] `--path` _path_\ +`cargo add` [_options_] `--git` _url_ [_crate_...]\ + + +## DESCRIPTION + +This command can add or modify dependencies. + +The source for the dependency can be specified with: + +* _crate_`@`_version_: Fetch from a registry with a version constraint of "_version_" +* `--path` _path_: Fetch from the specified _path_ +* `--git` _url_: Pull from a git repo at _url_ + +If no source is specified, then a best effort will be made to select one, including: + +* Existing dependencies in other tables (like `dev-dependencies`) +* Workspace members +* Latest release in the registry + +When you add a package that is already present, the existing entry will be updated with the flags specified. + +## OPTIONS + +### Source options + +{{#options}} + +{{#option "`--git` _url_" }} +[Git URL to add the specified crate from](../reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories). +{{/option}} + +{{#option "`--branch` _branch_" }} +Branch to use when adding from git. +{{/option}} + +{{#option "`--tag` _tag_" }} +Tag to use when adding from git. +{{/option}} + +{{#option "`--rev` _sha_" }} +Specific commit to use when adding from git. +{{/option}} + +{{#option "`--path` _path_" }} +[Filesystem path](../reference/specifying-dependencies.html#specifying-path-dependencies) to local crate to add. +{{/option}} + +{{> options-registry }} + +{{/options}} + +### Section options + +{{#options}} + +{{#option "`--dev`" }} +Add as a [development dependency](../reference/specifying-dependencies.html#development-dependencies). +{{/option}} + +{{#option "`--build`" }} +Add as a [build dependency](../reference/specifying-dependencies.html#build-dependencies). +{{/option}} + +{{#option "`--target` _target_" }} +Add as a dependency to the [given target platform](../reference/specifying-dependencies.html#platform-specific-dependencies). +{{/option}} + +{{/options}} + + + + +### Dependency options + +{{#options}} + +{{#option "`--rename` _name_" }} +[Rename](../reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml) the dependency. +{{/option}} + +{{#option "`--optional`" }} +Mark the dependency as [optional](../reference/features.html#optional-dependencies). +{{/option}} + +{{#option "`--no-optional`" }} +Mark the dependency as [required](../reference/features.html#optional-dependencies). +{{/option}} + +{{#option "`--no-default-features`" }} +Disable the [default features](../reference/features.html#dependency-features). +{{/option}} + +{{#option "`--default-features`" }} +Re-enable the [default features](../reference/features.html#dependency-features). +{{/option}} + +{{#option "`--features` _features_" }} +Space or comma separated list of [features to +activate](../reference/features.html#dependency-features). When adding multiple +crates, the features for a specific crate may be enabled with +`package-name/feature-name` syntax. This flag may be specified multiple times, +which enables all specified features. +{{/option}} + +{{/options}} + + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Add `regex` as a dependency + + cargo add regex + +2. Add `trybuild` as a dev-dependency + + cargo add --dev trybuild + +3. Add an older version of `nom` as a dependency + + cargo add nom@5 + +4. Add support for serializing data structures to json with `derive`s + + cargo add serde serde_json -F serde/derive + +## SEE ALSO +{{man "cargo" 1}} diff --git a/src/doc/man/generated_txt/cargo-add.txt b/src/doc/man/generated_txt/cargo-add.txt new file mode 100644 index 00000000000..e7abc000cf0 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-add.txt @@ -0,0 +1,180 @@ +CARGO-ADD(1) + +NAME + cargo-add - Add dependencies to a Cargo.toml manifest file + +SYNOPSIS + cargo add [options] crate... + cargo add [options] --path path + cargo add [options] --git url [crate...] + +DESCRIPTION + This command can add or modify dependencies. + + The source for the dependency can be specified with: + + o crate@version: Fetch from a registry with a version constraint of + "version" + + o --path path: Fetch from the specified path + + o --git url: Pull from a git repo at url + + If no source is specified, then a best effort will be made to select + one, including: + + o Existing dependencies in other tables (like dev-dependencies) + + o Workspace members + + o Latest release in the registry + + When you add a package that is already present, the existing entry will + be updated with the flags specified. + +OPTIONS + Source options + --git url + Git URL to add the specified crate from + . + + --branch branch + Branch to use when adding from git. + + --tag tag + Tag to use when adding from git. + + --rev sha + Specific commit to use when adding from git. + + --path path + Filesystem path + + to local crate to add. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + . If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Section options + --dev + Add as a development dependency + . + + --build + Add as a build dependency + . + + --target target + Add as a dependency to the given target platform + . + + + + Dependency options + --rename name + Rename + + the dependency. + + --optional + Mark the dependency as optional + . + + --no-optional + Mark the dependency as required + . + + --no-default-features + Disable the default features + . + + --default-features + Re-enable the default features + . + + --features features + Space or comma separated list of features to activate + . + When adding multiple crates, the features for a specific crate may + be enabled with package-name/feature-name syntax. This flag may be + specified multiple times, which enables all specified features. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + . + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more + information about how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Add regex as a dependency + + cargo add regex + + 2. Add trybuild as a dev-dependency + + cargo add --dev trybuild + + 3. Add an older version of nom as a dependency + + cargo add nom@5 + + 4. Add support for serializing data structures to json with derives + + cargo add serde serde_json -F serde/derive + +SEE ALSO + cargo(1) + diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md index 198567c3223..453d1121da8 100644 --- a/src/doc/src/SUMMARY.md +++ b/src/doc/src/SUMMARY.md @@ -61,6 +61,7 @@ * [cargo test](commands/cargo-test.md) * [cargo report](commands/cargo-report.md) * [Manifest Commands](commands/manifest-commands.md) + * [cargo add](commands/cargo-add.md) * [cargo generate-lockfile](commands/cargo-generate-lockfile.md) * [cargo locate-project](commands/cargo-locate-project.md) * [cargo metadata](commands/cargo-metadata.md) diff --git a/src/doc/src/commands/cargo-add.md b/src/doc/src/commands/cargo-add.md new file mode 100644 index 00000000000..e7f7e1d5164 --- /dev/null +++ b/src/doc/src/commands/cargo-add.md @@ -0,0 +1,223 @@ +# cargo-add(1) + + + +## NAME + +cargo-add - Add dependencies to a Cargo.toml manifest file + +## SYNOPSIS + +`cargo add` [_options_] _crate_...\ +`cargo add` [_options_] `--path` _path_\ +`cargo add` [_options_] `--git` _url_ [_crate_...]\ + + +## DESCRIPTION + +This command can add or modify dependencies. + +The source for the dependency can be specified with: + +* _crate_`@`_version_: Fetch from a registry with a version constraint of "_version_" +* `--path` _path_: Fetch from the specified _path_ +* `--git` _url_: Pull from a git repo at _url_ + +If no source is specified, then a best effort will be made to select one, including: + +* Existing dependencies in other tables (like `dev-dependencies`) +* Workspace members +* Latest release in the registry + +When you add a package that is already present, the existing entry will be updated with the flags specified. + +## OPTIONS + +### Source options + +
+ +
--git url
+
Git URL to add the specified crate from.
+ + +
--branch branch
+
Branch to use when adding from git.
+ + +
--tag tag
+
Tag to use when adding from git.
+ + +
--rev sha
+
Specific commit to use when adding from git.
+ + +
--path path
+
Filesystem path to local crate to add.
+ + +
--registry registry
+
Name of the registry to use. Registry names are defined in Cargo config +files. If not specified, the default registry is used, +which is defined by the registry.default config key which defaults to +crates-io.
+ + + +
+ +### Section options + +
+ +
--dev
+
Add as a development dependency.
+ + +
--build
+
Add as a build dependency.
+ + +
--target target
+
Add as a dependency to the given target platform.
+ + +
+ + + + +### Dependency options + +
+ +
--rename name
+
Rename the dependency.
+ + +
--optional
+
Mark the dependency as optional.
+ + +
--no-optional
+
Mark the dependency as required.
+ + +
--no-default-features
+
Disable the default features.
+ + +
--default-features
+
Re-enable the default features.
+ + +
--features features
+
Space or comma separated list of features to +activate. When adding multiple +crates, the features for a specific crate may be enabled with +package-name/feature-name syntax. This flag may be specified multiple times, +which enables all specified features.
+ + +
+ + +### Display Options + +
+
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-q
+
--quiet
+
Do not print cargo log messages. +May also be specified with the term.quiet +config value.
+ + +
--color when
+
Control when colored output is used. Valid values:

+
    +
  • auto (default): Automatically detect if color support is available on the +terminal.
    • +
  • always: Always display colors.
    • +
  • never: Never display colors.
    • +
+

May also be specified with the term.color +config value.

+ + +
+ +### Manifest Options + +
+
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Add `regex` as a dependency + + cargo add regex + +2. Add `trybuild` as a dev-dependency + + cargo add --dev trybuild + +3. Add an older version of `nom` as a dependency + + cargo add nom@5 + +4. Add support for serializing data structures to json with `derive`s + + cargo add serde serde_json -F serde/derive + +## SEE ALSO +[cargo(1)](cargo.html) diff --git a/src/doc/src/commands/manifest-commands.md b/src/doc/src/commands/manifest-commands.md index e9b5c708d40..2f4017a71ca 100644 --- a/src/doc/src/commands/manifest-commands.md +++ b/src/doc/src/commands/manifest-commands.md @@ -1,4 +1,5 @@ # Manifest Commands +* [cargo add](cargo-add.md) * [cargo generate-lockfile](cargo-generate-lockfile.md) * [cargo locate-project](cargo-locate-project.md) * [cargo metadata](cargo-metadata.md) diff --git a/src/etc/man/cargo-add.1 b/src/etc/man/cargo-add.1 new file mode 100644 index 00000000000..f7803405346 --- /dev/null +++ b/src/etc/man/cargo-add.1 @@ -0,0 +1,254 @@ +'\" t +.TH "CARGO\-ADD" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-add \- Add dependencies to a Cargo.toml manifest file +.SH "SYNOPSIS" +\fBcargo add\fR [\fIoptions\fR] \fIcrate\fR\&... +.br +\fBcargo add\fR [\fIoptions\fR] \fB\-\-path\fR \fIpath\fR +.br +\fBcargo add\fR [\fIoptions\fR] \fB\-\-git\fR \fIurl\fR [\fIcrate\fR\&...] +.SH "DESCRIPTION" +This command can add or modify dependencies. +.sp +The source for the dependency can be specified with: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fIcrate\fR\fB@\fR\fIversion\fR: Fetch from a registry with a version constraint of "\fIversion\fR" +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB\-\-path\fR \fIpath\fR: Fetch from the specified \fIpath\fR +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB\-\-git\fR \fIurl\fR: Pull from a git repo at \fIurl\fR +.RE +.sp +If no source is specified, then a best effort will be made to select one, including: +.sp +.RS 4 +\h'-04'\(bu\h'+02'Existing dependencies in other tables (like \fBdev\-dependencies\fR) +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Workspace members +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Latest release in the registry +.RE +.sp +When you add a package that is already present, the existing entry will be updated with the flags specified. +.SH "OPTIONS" +.SS "Source options" +.sp +\fB\-\-git\fR \fIurl\fR +.RS 4 +\fIGit URL to add the specified crate from\fR \&. +.RE +.sp +\fB\-\-branch\fR \fIbranch\fR +.RS 4 +Branch to use when adding from git. +.RE +.sp +\fB\-\-tag\fR \fItag\fR +.RS 4 +Tag to use when adding from git. +.RE +.sp +\fB\-\-rev\fR \fIsha\fR +.RS 4 +Specific commit to use when adding from git. +.RE +.sp +\fB\-\-path\fR \fIpath\fR +.RS 4 +\fIFilesystem path\fR to local crate to add. +.RE +.sp +\fB\-\-registry\fR \fIregistry\fR +.RS 4 +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. +.RE +.SS "Section options" +.sp +\fB\-\-dev\fR +.RS 4 +Add as a \fIdevelopment dependency\fR \&. +.RE +.sp +\fB\-\-build\fR +.RS 4 +Add as a \fIbuild dependency\fR \&. +.RE +.sp +\fB\-\-target\fR \fItarget\fR +.RS 4 +Add as a dependency to the \fIgiven target platform\fR \&. +.RE + +.SS "Dependency options" +.sp +\fB\-\-rename\fR \fIname\fR +.RS 4 +\fIRename\fR the dependency. +.RE +.sp +\fB\-\-optional\fR +.RS 4 +Mark the dependency as \fIoptional\fR \&. +.RE +.sp +\fB\-\-no\-optional\fR +.RS 4 +Mark the dependency as \fIrequired\fR \&. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Disable the \fIdefault features\fR \&. +.RE +.sp +\fB\-\-default\-features\fR +.RS 4 +Re\-enable the \fIdefault features\fR \&. +.RE +.sp +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of \fIfeatures to +activate\fR \&. When adding multiple +crates, the features for a specific crate may be enabled with +\fBpackage\-name/feature\-name\fR syntax. This flag may be specified multiple times, +which enables all specified features. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR \&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR +for more information about how toolchain overrides work. +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Add \fBregex\fR as a dependency +.sp +.RS 4 +.nf +cargo add regex +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Add \fBtrybuild\fR as a dev\-dependency +.sp +.RS 4 +.nf +cargo add \-\-dev trybuild +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Add an older version of \fBnom\fR as a dependency +.sp +.RS 4 +.nf +cargo add nom@5 +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 4.\h'+01'Add support for serializing data structures to json with \fBderive\fRs +.sp +.RS 4 +.nf +cargo add serde serde_json \-F serde/derive +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1)