Skip to content

Commit

Permalink
Auto merge of #12276 - dimo414:patch-1, r=weihanglo
Browse files Browse the repository at this point in the history
Clarify the default behavior of cargo-install.

The man page for `cargo install` is not explicit about what the default behavior is. This is important to clarify because `examples/` are typically unneeded and may not be maintained with the same care as "real" binaries, so it should be clear to users that example binaries won't be installed without directly asking for them.

Small doc-only update, hopefully this is acceptable. Please let me know if I need to seek further approval first (and, if so, apologies for the noise).
  • Loading branch information
bors committed Jun 16, 2023
2 parents 0c14026 + 9624861 commit d93b018
Show file tree
Hide file tree
Showing 4 changed files with 9 additions and 8 deletions.
4 changes: 2 additions & 2 deletions src/doc/man/cargo-install.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ cargo-install --- Build and install a Rust binary
This command manages Cargo's local set of installed binary crates. Only
packages which have executable `[[bin]]` or `[[example]]` targets can be
installed, and all executables are installed into the installation root's
`bin` folder.
`bin` folder. By default only binaries, not examples, are installed.

{{> description-install-root }}

Expand Down Expand Up @@ -141,7 +141,7 @@ Install only the specified binary.
{{/option}}

{{#option "`--bins`" }}
Install all binaries.
Install all binaries. This is the default behavior.
{{/option}}

{{#option "`--example` _name_..." }}
Expand Down
5 changes: 3 additions & 2 deletions src/doc/man/generated_txt/cargo-install.txt
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ DESCRIPTION
This command manages Cargo’s local set of installed binary crates.
Only packages which have executable [[bin]] or [[example]] targets can
be installed, and all executables are installed into the installation
root’s bin folder.
root’s bin folder. By default only binaries, not examples, are
installed.

The installation root is determined, in order of precedence:

Expand Down Expand Up @@ -137,7 +138,7 @@ OPTIONS
Install only the specified binary.

--bins
Install all binaries.
Install all binaries. This is the default behavior.

--example name…
Install only the specified example.
Expand Down
4 changes: 2 additions & 2 deletions src/doc/src/commands/cargo-install.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ cargo-install --- Build and install a Rust binary
This command manages Cargo's local set of installed binary crates. Only
packages which have executable `[[bin]]` or `[[example]]` targets can be
installed, and all executables are installed into the installation root's
`bin` folder.
`bin` folder. By default only binaries, not examples, are installed.

The installation root is determined, in order of precedence:

Expand Down Expand Up @@ -150,7 +150,7 @@ same time.</dd>


<dt class="option-term" id="option-cargo-install---bins"><a class="option-anchor" href="#option-cargo-install---bins"></a><code>--bins</code></dt>
<dd class="option-desc">Install all binaries.</dd>
<dd class="option-desc">Install all binaries. This is the default behavior.</dd>


<dt class="option-term" id="option-cargo-install---example"><a class="option-anchor" href="#option-cargo-install---example"></a><code>--example</code> <em>name</em>…</dt>
Expand Down
4 changes: 2 additions & 2 deletions src/etc/man/cargo-install.1
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ cargo\-install \[em] Build and install a Rust binary
This command manages Cargo\[cq]s local set of installed binary crates. Only
packages which have executable \fB[[bin]]\fR or \fB[[example]]\fR targets can be
installed, and all executables are installed into the installation root\[cq]s
\fBbin\fR folder.
\fBbin\fR folder. By default only binaries, not examples, are installed.
.sp
The installation root is determined, in order of precedence:
.sp
Expand Down Expand Up @@ -177,7 +177,7 @@ Install only the specified binary.
.sp
\fB\-\-bins\fR
.RS 4
Install all binaries.
Install all binaries. This is the default behavior.
.RE
.sp
\fB\-\-example\fR \fIname\fR\[u2026]
Expand Down

0 comments on commit d93b018

Please sign in to comment.