| '\" t |
| .TH "CARGO\-NEW" "1" |
| .nh |
| .ad l |
| .ss \n[.ss] 0 |
| .SH "NAME" |
| cargo\-new \- Create a new Cargo package |
| .SH "SYNOPSIS" |
| \fBcargo new\fR [\fIoptions\fR] \fIpath\fR |
| .SH "DESCRIPTION" |
| This command will create a new Cargo package in the given directory. This |
| includes a simple template with a \fBCargo.toml\fR manifest, sample source file, |
| and a VCS ignore file. If the directory is not already in a VCS repository, |
| then a new repository is created (see \fB\-\-vcs\fR below). |
| .sp |
| See \fBcargo\-init\fR(1) for a similar command which will create a new manifest |
| in an existing directory. |
| .SH "OPTIONS" |
| .SS "New 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 2018. |
| 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 "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 <https://doc.rust\-lang.org/cargo/reference/config.html>\&. |
| .RE |
| .sp |
| \fB\-q\fR, |
| \fB\-\-quiet\fR |
| .RS 4 |
| No output printed to stdout. |
| .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\-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 given directory: |
| .sp |
| .RS 4 |
| .nf |
| cargo new foo |
| .fi |
| .RE |
| .RE |
| .SH "SEE ALSO" |
| \fBcargo\fR(1), \fBcargo\-init\fR(1) |