| <h2 id="cargo_new_name">NAME</h2> |
| <div class="sectionbody"> |
| <p>cargo-new - Create a new Cargo package</p> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_new_synopsis">SYNOPSIS</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><code>cargo new [<em>OPTIONS</em>] <em>PATH</em></code></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_new_description">DESCRIPTION</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This command will create a new Cargo package in the given directory. This |
| includes a simple template with a <code>Cargo.toml</code> 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 <code>--vcs</code> below).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The "authors" field in the manifest is determined from the environment or |
| configuration settings. A name is required and is determined from (first match |
| wins):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>cargo-new.name</code> Cargo config value</p> |
| </li> |
| <li> |
| <p><code>CARGO_NAME</code> environment variable</p> |
| </li> |
| <li> |
| <p><code>GIT_AUTHOR_NAME</code> environment variable</p> |
| </li> |
| <li> |
| <p><code>GIT_COMMITTER_NAME</code> environment variable</p> |
| </li> |
| <li> |
| <p><code>user.name</code> git configuration value</p> |
| </li> |
| <li> |
| <p><code>USER</code> environment variable</p> |
| </li> |
| <li> |
| <p><code>USERNAME</code> environment variable</p> |
| </li> |
| <li> |
| <p><code>NAME</code> environment variable</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The email address is optional and is determined from:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>cargo-new.email</code> Cargo config value</p> |
| </li> |
| <li> |
| <p><code>CARGO_EMAIL</code> environment variable</p> |
| </li> |
| <li> |
| <p><code>GIT_AUTHOR_EMAIL</code> environment variable</p> |
| </li> |
| <li> |
| <p><code>GIT_COMMITTER_EMAIL</code> environment variable</p> |
| </li> |
| <li> |
| <p><code>user.email</code> git configuration value</p> |
| </li> |
| <li> |
| <p><code>EMAIL</code> environment variable</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="../reference/config.html">the reference</a> for more information about |
| configuration files.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="cargo-init.html">cargo-init(1)</a> for a similar command which will create a new manifest |
| in an existing directory.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_new_options">OPTIONS</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="cargo_new_new_options">New Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--bin</strong></dt> |
| <dd> |
| <p>Create a package with a binary target (<code>src/main.rs</code>). |
| This is the default behavior.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--lib</strong></dt> |
| <dd> |
| <p>Create a package with a library target (<code>src/lib.rs</code>).</p> |
| </dd> |
| <dt class="hdlist1"><strong>--edition</strong> <em>EDITION</em></dt> |
| <dd> |
| <p>Specify the Rust edition to use. Default is 2018. |
| Possible values: 2015, 2018</p> |
| </dd> |
| <dt class="hdlist1"><strong>--name</strong> <em>NAME</em></dt> |
| <dd> |
| <p>Set the package name. Defaults to the directory name.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--vcs</strong> <em>VCS</em></dt> |
| <dd> |
| <p>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 <code>git</code> or the configuration value |
| <code>cargo-new.vcs</code>, or <code>none</code> if already inside a VCS repository.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--registry</strong> <em>REGISTRY</em></dt> |
| <dd> |
| <p>This sets the <code>publish</code> field in <code>Cargo.toml</code> to the given registry name |
| which will restrict publishing only to that registry.</p> |
| <div class="paragraph"> |
| <p>Registry names are defined in <a href="../reference/config.html">Cargo config files</a>. |
| If not specified, the default registry defined by the <code>registry.default</code> |
| config key is used. If the default registry is not set and <code>--registry</code> is not |
| used, the <code>publish</code> field will not be set which means that publishing will not |
| be restricted.</p> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_new_display_options">Display Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>-v</strong></dt> |
| <dt class="hdlist1"><strong>--verbose</strong></dt> |
| <dd> |
| <p>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 <code>term.verbose</code> |
| <a href="../reference/config.html">config value</a>.</p> |
| </dd> |
| <dt class="hdlist1"><strong>-q</strong></dt> |
| <dt class="hdlist1"><strong>--quiet</strong></dt> |
| <dd> |
| <p>No output printed to stdout.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--color</strong> <em>WHEN</em></dt> |
| <dd> |
| <p>Control when colored output is used. Valid values:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>auto</code> (default): Automatically detect if color support is available on the |
| terminal.</p> |
| </li> |
| <li> |
| <p><code>always</code>: Always display colors.</p> |
| </li> |
| <li> |
| <p><code>never</code>: Never display colors.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>May also be specified with the <code>term.color</code> |
| <a href="../reference/config.html">config value</a>.</p> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_new_common_options">Common Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>-h</strong></dt> |
| <dt class="hdlist1"><strong>--help</strong></dt> |
| <dd> |
| <p>Prints help information.</p> |
| </dd> |
| <dt class="hdlist1"><strong>-Z</strong> <em>FLAG</em>…​</dt> |
| <dd> |
| <p>Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for |
| details.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_new_environment">ENVIRONMENT</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>See <a href="../reference/environment-variables.html">the reference</a> for |
| details on environment variables that Cargo reads.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_new_exit_status">Exit Status</h2> |
| <div class="sectionbody"> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">0</dt> |
| <dd> |
| <p>Cargo succeeded.</p> |
| </dd> |
| <dt class="hdlist1">101</dt> |
| <dd> |
| <p>Cargo failed to complete.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_new_examples">EXAMPLES</h2> |
| <div class="sectionbody"> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Create a binary Cargo package in the given directory:</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>cargo new foo</pre> |
| </div> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_new_see_also">SEE ALSO</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a href="index.html">cargo(1)</a>, <a href="cargo-init.html">cargo-init(1)</a></p> |
| </div> |
| </div> |
| </div> |
