Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document having only src/bin/*.rs binaries is valid #14463

Closed
nekomachi-touge opened this issue Aug 28, 2024 · 3 comments · Fixed by #14515
Closed

Document having only src/bin/*.rs binaries is valid #14463

nekomachi-touge opened this issue Aug 28, 2024 · 3 comments · Fixed by #14515
Labels
A-documenting-cargo-itself Area: Cargo's documentation C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` S-triage Status: This issue is waiting on initial triage.

Comments

@nekomachi-touge
Copy link
Contributor

Problem

I found the following section of the cargo book could make readers think they must provide src/main.rs.

Binary targets are executable programs that can be run after being compiled.
The default binary filename is `src/main.rs`, which defaults to the name of
the package. Additional binaries are stored in the [`src/bin/`
directory][package layout]. The settings for each binary can be [customized]
in the `[[bin]]` tables in `Cargo.toml`.

However, it is also valid to have only src/bin/*.rs binaries and not to have src/main.rs.
I believe clarifying this situation on the book will help readers when arranging codes for binaries.

Proposed Solution

Changing the section like below should work:

Binary targets are executable programs that can be run after being compiled. 
The default binary filename is `src/main.rs`, which defaults to the name of 
the package. Additionally one or more binaries are stored in the [`src/bin/`
 directory][package layout]. In this case the default binary `src/main.rs` 
is not required. The settings for each binary can be [customized] in the
`[[bin]]` tables in `Cargo.toml`.

Notes

No response

@nekomachi-touge nekomachi-touge added C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` S-triage Status: This issue is waiting on initial triage. labels Aug 28, 2024
@nekomachi-touge nekomachi-touge changed the title Document having only src/bin/*.rs binaries are valid Document having only src/bin/*.rs binaries is valid Aug 28, 2024
@epage epage added the A-documenting-cargo-itself Area: Cargo's documentation label Aug 28, 2024
@epage
Copy link
Contributor

epage commented Aug 28, 2024

Thanks for providing this feedback on the confusion you had! It looks like the suggested change is the addition of

n this case the default binary src/main.rs is not required.

It feels odd to call out that a default is not required, that is generally the case for a default.

For brainstorming purposes, another approach is something like

Binary targets are executable programs that can be run after being compiled. 
A binary's source can be `src/main.rs` and/or stored in the  [`src/bin/` 
directory][package layout].  For `src/main.rs`, the default binary name is the package name. The settings for each binary can be [customized] 
in the `[[bin]]` tables in `Cargo.toml`. 

@nekomachi-touge
Copy link
Contributor Author

nekomachi-touge commented Aug 29, 2024

@epage Thank you for the quick response!

I support your fix.
Using and/or make the section much clearer than my take, and also stating *.rs are sources sounds more natural than the original text.
Maybe we need to make sure the text is wrapped at 80 characters though.

I'm considering making a PR after waiting feedbacks for a couple of days.
Nevermind, I'll wait for the removal of the S-triage tag.

@nekomachi-touge
Copy link
Contributor Author

Since no one seems to submit another proposal, I’m going to make a PR based on the @epage ‘s text to keep this issue from being stale.

nekomachi-touge added a commit to nekomachi-touge/cargo that referenced this issue Sep 7, 2024
This commit clarifies the doc by stating we can place a binary source as `src/main.rs` and/or in `src/bin/`.
Wording is suggested by Ed Page (@epage).

Closes rust-lang#14463.
nekomachi-touge added a commit to nekomachi-touge/cargo that referenced this issue Sep 7, 2024
This commit clarifies the doc by stating we can place a binary source as `src/main.rs` and/or in `src/bin/`.
Wording is suggested by Ed Page (@epage).

Closes rust-lang#14463.
bors added a commit that referenced this issue Sep 8, 2024
docs: bin source can be `src/main.rs` and/or in `src/bin/`

### What does this PR try to resolve?
This commit clarifies the doc by stating we can place a binary source as `src/main.rs` and/or in `src/bin/`.
Wording is suggested by Ed Page (`@epage).`

### How should we test and review this PR?
(It seems the only way is to check the chenge visually...)

### Additional information
Closes #14463.
@bors bors closed this as completed in 059c7e4 Sep 8, 2024
dingxiangfei2009 pushed a commit to dingxiangfei2009/cargo that referenced this issue Sep 17, 2024
This commit clarifies the doc by stating we can place a binary source as `src/main.rs` and/or in `src/bin/`.
Wording is suggested by Ed Page (@epage).

Closes rust-lang#14463.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-documenting-cargo-itself Area: Cargo's documentation C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` S-triage Status: This issue is waiting on initial triage.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants
@epage @nekomachi-touge and others