diff options
Diffstat (limited to 'src/tools/cargo/src/etc/man/cargo-init.1')
| -rw-r--r-- | src/tools/cargo/src/etc/man/cargo-init.1 | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/src/tools/cargo/src/etc/man/cargo-init.1 b/src/tools/cargo/src/etc/man/cargo-init.1 new file mode 100644 index 000000000..56d1aca9f --- /dev/null +++ b/src/tools/cargo/src/etc/man/cargo-init.1 @@ -0,0 +1,171 @@ +'\" t +.TH "CARGO\-INIT" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-init \[em] Create a new Cargo package in an existing directory +.SH "SYNOPSIS" +\fBcargo init\fR [\fIoptions\fR] [\fIpath\fR] +.SH "DESCRIPTION" +This command will create a new Cargo manifest in the current directory. Give a +path as an argument to create in the given directory. +.sp +If there are typically\-named Rust source files already in the directory, those +will be used. If not, then a sample \fBsrc/main.rs\fR file will be created, or +\fBsrc/lib.rs\fR if \fB\-\-lib\fR is passed. +.sp +If the directory is not already in a VCS repository, then a new repository +is created (see \fB\-\-vcs\fR below). +.sp +See \fBcargo\-new\fR(1) for a similar command which will create a new package in +a new directory. +.SH "OPTIONS" +.SS "Init Options" +.sp +\fB\-\-bin\fR +.RS 4 +Create a package with a binary target (\fBsrc/main.rs\fR). +This is the default behavior. +.RE +.sp +\fB\-\-lib\fR +.RS 4 +Create a package with a library target (\fBsrc/lib.rs\fR). +.RE +.sp +\fB\-\-edition\fR \fIedition\fR +.RS 4 +Specify the Rust edition to use. Default is 2021. +Possible values: 2015, 2018, 2021 +.RE +.sp +\fB\-\-name\fR \fIname\fR +.RS 4 +Set the package name. Defaults to the directory name. +.RE +.sp +\fB\-\-vcs\fR \fIvcs\fR +.RS 4 +Initialize a new VCS repository for the given version control system (git, +hg, pijul, or fossil) or do not initialize any version control at all +(none). If not specified, defaults to \fBgit\fR or the configuration value +\fBcargo\-new.vcs\fR, or \fBnone\fR if already inside a VCS repository. +.RE +.sp +\fB\-\-registry\fR \fIregistry\fR +.RS 4 +This sets the \fBpublish\fR field in \fBCargo.toml\fR to the given registry name +which will restrict publishing only to that registry. +.sp +Registry names are defined in \fICargo config files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +If not specified, the default registry defined by the \fBregistry.default\fR +config key is used. If the default registry is not set and \fB\-\-registry\fR is not +used, the \fBpublish\fR field will not be set which means that publishing will not +be restricted. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] 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 <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.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 <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.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 <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.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 <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must +appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.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 <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> 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'Create a binary Cargo package in the current directory: +.sp +.RS 4 +.nf +cargo init +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-new\fR(1) |