src/tools/cargo/src/etc/man/cargo-pkgid.1

   1 '\" t
   2 .TH "CARGO\-PKGID" "1"
   3 .nh
   4 .ad l
   5 .ss \n[.ss] 0
   6 .SH "NAME"
   7 cargo\-pkgid \[em] Print a fully qualified package specification
   8 .SH "SYNOPSIS"
   9 \fBcargo pkgid\fR [\fIoptions\fR] [\fIspec\fR]
  10 .SH "DESCRIPTION"
  11 Given a \fIspec\fR argument, print out the fully qualified package ID specifier
  12 for a package or dependency in the current workspace. This command will
  13 generate an error if \fIspec\fR is ambiguous as to which package it refers to in
  14 the dependency graph. If no \fIspec\fR is given, then the specifier for the local
  15 package is printed.
  16 .sp
  17 This command requires that a lockfile is available and dependencies have been
  18 fetched.
  19 .sp
  20 A package specifier consists of a name, version, and source URL. You are
  21 allowed to use partial specifiers to succinctly match a specific package as
  22 long as it matches only one package. The format of a \fIspec\fR can be one of the
  23 following:
  24
  25 .TS
  26 allbox tab(:);
  27 lt lt.
  28 T{
  29 SPEC Structure
  30 T}:T{
  31 Example SPEC
  32 T}
  33 T{
  34 \fIname\fR
  35 T}:T{
  36 \fBbitflags\fR
  37 T}
  38 T{
  39 \fIname\fR\fB@\fR\fIversion\fR
  40 T}:T{
  41 \fBbitflags@1.0.4\fR
  42 T}
  43 T{
  44 \fIurl\fR
  45 T}:T{
  46 \fBhttps://github.com/rust\-lang/cargo\fR
  47 T}
  48 T{
  49 \fIurl\fR\fB#\fR\fIversion\fR
  50 T}:T{
  51 \fBhttps://github.com/rust\-lang/cargo#0.33.0\fR
  52 T}
  53 T{
  54 \fIurl\fR\fB#\fR\fIname\fR
  55 T}:T{
  56 \fBhttps://github.com/rust\-lang/crates.io\-index#bitflags\fR
  57 T}
  58 T{
  59 \fIurl\fR\fB#\fR\fIname\fR\fB@\fR\fIversion\fR
  60 T}:T{
  61 \fBhttps://github.com/rust\-lang/cargo#crates\-io@0.21.0\fR
  62 T}
  63 .TE
  64 .sp
  65 .SH "OPTIONS"
  66 .SS "Package Selection"
  67 .sp
  68 \fB\-p\fR \fIspec\fR,
  69 \fB\-\-package\fR \fIspec\fR
  70 .RS 4
  71 Get the package ID for the given package instead of the current package.
  72 .RE
  73 .SS "Display Options"
  74 .sp
  75 \fB\-v\fR,
  76 \fB\-\-verbose\fR
  77 .RS 4
  78 Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
  79 includes extra output such as dependency warnings and build script output.
  80 May also be specified with the \fBterm.verbose\fR
  81 \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
  82 .RE
  83 .sp
  84 \fB\-q\fR,
  85 \fB\-\-quiet\fR
  86 .RS 4
  87 Do not print cargo log messages.
  88 May also be specified with the \fBterm.quiet\fR
  89 \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
  90 .RE
  91 .sp
  92 \fB\-\-color\fR \fIwhen\fR
  93 .RS 4
  94 Control when colored output is used. Valid values:
  95 .sp
  96 .RS 4
  97 \h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
  98 terminal.
  99 .RE
 100 .sp
 101 .RS 4
 102 \h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
 103 .RE
 104 .sp
 105 .RS 4
 106 \h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
 107 .RE
 108 .sp
 109 May also be specified with the \fBterm.color\fR
 110 \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
 111 .RE
 112 .SS "Manifest Options"
 113 .sp
 114 \fB\-\-manifest\-path\fR \fIpath\fR
 115 .RS 4
 116 Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
 117 \fBCargo.toml\fR file in the current directory or any parent directory.
 118 .RE
 119 .sp
 120 \fB\-\-frozen\fR,
 121 \fB\-\-locked\fR
 122 .RS 4
 123 Either of these flags requires that the \fBCargo.lock\fR file is
 124 up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will
 125 exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from
 126 attempting to access the network to determine if it is out\-of\-date.
 127 .sp
 128 These may be used in environments where you want to assert that the
 129 \fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network
 130 access.
 131 .RE
 132 .sp
 133 \fB\-\-offline\fR
 134 .RS 4
 135 Prevents Cargo from accessing the network for any reason. Without this
 136 flag, Cargo will stop with an error if it needs to access the network and
 137 the network is not available. With this flag, Cargo will attempt to
 138 proceed without the network if possible.
 139 .sp
 140 Beware that this may result in different dependency resolution than online
 141 mode. Cargo will restrict itself to crates that are downloaded locally, even
 142 if there might be a newer version as indicated in the local copy of the index.
 143 See the \fBcargo\-fetch\fR(1) command to download dependencies before going
 144 offline.
 145 .sp
 146 May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
 147 .RE
 148 .SS "Common Options"
 149 .sp
 150 \fB+\fR\fItoolchain\fR
 151 .RS 4
 152 If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
 153 begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
 154 as \fB+stable\fR or \fB+nightly\fR).
 155 See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
 156 for more information about how toolchain overrides work.
 157 .RE
 158 .sp
 159 \fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
 160 .RS 4
 161 Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
 162 or provided as a path to an extra configuration file. This flag may be specified multiple times.
 163 See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
 164 .RE
 165 .sp
 166 \fB\-C\fR \fIPATH\fR
 167 .RS 4
 168 Changes the current working directory before executing any specified operations. This affects
 169 things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
 170 the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
 171 appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
 172 .sp
 173 This option is only available on the \fInightly
 174 channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
 175 requires the \fB\-Z unstable\-options\fR flag to enable (see
 176 \fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
 177 .RE
 178 .sp
 179 \fB\-h\fR,
 180 \fB\-\-help\fR
 181 .RS 4
 182 Prints help information.
 183 .RE
 184 .sp
 185 \fB\-Z\fR \fIflag\fR
 186 .RS 4
 187 Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
 188 .RE
 189 .SH "ENVIRONMENT"
 190 See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
 191 details on environment variables that Cargo reads.
 192 .SH "EXIT STATUS"
 193 .sp
 194 .RS 4
 195 \h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
 196 .RE
 197 .sp
 198 .RS 4
 199 \h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
 200 .RE
 201 .SH "EXAMPLES"
 202 .sp
 203 .RS 4
 204 \h'-04' 1.\h'+01'Retrieve package specification for \fBfoo\fR package:
 205 .sp
 206 .RS 4
 207 .nf
 208 cargo pkgid foo
 209 .fi
 210 .RE
 211 .RE
 212 .sp
 213 .RS 4
 214 \h'-04' 2.\h'+01'Retrieve package specification for version 1.0.0 of \fBfoo\fR:
 215 .sp
 216 .RS 4
 217 .nf
 218 cargo pkgid foo@1.0.0
 219 .fi
 220 .RE
 221 .RE
 222 .sp
 223 .RS 4
 224 \h'-04' 3.\h'+01'Retrieve package specification for \fBfoo\fR from crates.io:
 225 .sp
 226 .RS 4
 227 .nf
 228 cargo pkgid https://github.com/rust\-lang/crates.io\-index#foo
 229 .fi
 230 .RE
 231 .RE
 232 .sp
 233 .RS 4
 234 \h'-04' 4.\h'+01'Retrieve package specification for \fBfoo\fR from a local package:
 235 .sp
 236 .RS 4
 237 .nf
 238 cargo pkgid file:///path/to/local/package#foo
 239 .fi
 240 .RE
 241 .RE
 242 .SH "SEE ALSO"
 243 \fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1), \fBcargo\-metadata\fR(1)