cargo-new(1)

1CARGO-NEW(1)                General Commands Manual               CARGO-NEW(1)
2
3
4

NAME

6       cargo-new - Create a new Cargo package
7

SYNOPSIS

9       cargo new [options] path
10

DESCRIPTION

12       This command will create a new Cargo package in the given directory.
13       This includes a simple template with a Cargo.toml manifest, sample
14       source file, and a VCS ignore file. If the directory is not already in
15       a VCS repository, then a new repository is created (see --vcs below).
16
17       The "authors" field in the manifest is determined from the environment
18       or configuration settings. A name is required and is determined from
19       (first match wins):
20
21       ·  cargo-new.name Cargo config value
22
23       ·  CARGO_NAME environment variable
24
25       ·  GIT_AUTHOR_NAME environment variable
26
27       ·  GIT_COMMITTER_NAME environment variable
28
29       ·  user.name git configuration value
30
31       ·  USER environment variable
32
33       ·  USERNAME environment variable
34
35       ·  NAME environment variable
36
37       The email address is optional and is determined from:
38
39       ·  cargo-new.email Cargo config value
40
41       ·  CARGO_EMAIL environment variable
42
43       ·  GIT_AUTHOR_EMAIL environment variable
44
45       ·  GIT_COMMITTER_EMAIL environment variable
46
47       ·  user.email git configuration value
48
49       ·  EMAIL environment variable
50
51       See the reference
52       <https://doc.rust-lang.org/cargo/reference/config.html> for more
53       information about configuration files.
54
55       See cargo-init(1) for a similar command which will create a new
56       manifest in an existing directory.
57

OPTIONS

59   New Options
60       --bin
61           Create a package with a binary target (src/main.rs). This is the
62           default behavior.
63
64       --lib
65           Create a package with a library target (src/lib.rs).
66
67       --edition edition
68           Specify the Rust edition to use. Default is 2018. Possible values:
69           2015, 2018, 2021
70
71       --name name
72           Set the package name. Defaults to the directory name.
73
74       --vcs vcs
75           Initialize a new VCS repository for the given version control
76           system (git, hg, pijul, or fossil) or do not initialize any version
77           control at all (none). If not specified, defaults to git or the
78           configuration value cargo-new.vcs, or none if already inside a VCS
79           repository.
80
81       --registry registry
82           This sets the publish field in Cargo.toml to the given registry
83           name which will restrict publishing only to that registry.
84
85           Registry names are defined in Cargo config files
86           <https://doc.rust-lang.org/cargo/reference/config.html>. If not
87           specified, the default registry defined by the registry.default
88           config key is used. If the default registry is not set and
89           --registry is not used, the publish field will not be set which
90           means that publishing will not be restricted.
91
92   Display Options
93       -v, --verbose
94           Use verbose output. May be specified twice for "very verbose"
95           output which includes extra output such as dependency warnings and
96           build script output. May also be specified with the term.verbose
97           config value
98           <https://doc.rust-lang.org/cargo/reference/config.html>.
99
100       -q, --quiet
101           No output printed to stdout.
102
103       --color when
104           Control when colored output is used. Valid values:
105
106           ·  auto (default): Automatically detect if color support is
107               available on the terminal.
108
109           ·  always: Always display colors.
110
111           ·  never: Never display colors.
112
113           May also be specified with the term.color config value
114           <https://doc.rust-lang.org/cargo/reference/config.html>.
115
116   Common Options
117       +toolchain
118           If Cargo has been installed with rustup, and the first argument to
119           cargo begins with +, it will be interpreted as a rustup toolchain
120           name (such as +stable or +nightly). See the rustup documentation
121           <https://rust-lang.github.io/rustup/overrides.html> for more
122           information about how toolchain overrides work.
123
124       -h, --help
125           Prints help information.
126
127       -Z flag
128           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
129           details.
130

ENVIRONMENT

132       See the reference
133       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
134       for details on environment variables that Cargo reads.
135

EXIT STATUS

137       ·  0: Cargo succeeded.
138
139       ·  101: Cargo failed to complete.
140

EXAMPLES

142        1. Create a binary Cargo package in the given directory:
143
144               cargo new foo
145