Explain the --bin flag more clearly

[nathanl]

Explain the --bin flag in terms of the difference
between shipping binary and library code

I'm not sure if my explanation is even quite correct, but as a newbie coming from Ruby, this is my best guess. (In Rubyland, libraries always ship with the source code because there's no other form you can ship. :) )

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @huonw (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. The way Github handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see CONTRIBUTING.md for more information.

[steveklabnik]

This is not accurate, actually. Libraries are also compiled, and can be distributed sans source.

The difference is more like 'are you shipping an application or a library?'

[nathanl]

So is the difference a question of what files need to be generated?

[nathanl]

I just ran it both ways. With --bin, the new project's /src contains main.rs with

fn main() {
    println!("Hello, world!");
}

Without --bin, the new project's src/ contains lib.rs with

#[test]
fn it_works() {
}

Maybe it's silly to explain why at this point in the guide, I just found the flag confusing. --bin made me think "binary", which made me think "compiled", so I thought, "without that, we're going to skip compiling something?"

I'm only bugging you in the hopes that I'm a representatively confused newbie. 😄 Feel free to close / ignore if you think this isn't useful.

[huonw]

r? @steveklabnik

[steveklabnik]

No, I think it's worth explaining, since 'binary' is overloaded here, but we want to use it to explain why it's --bin. I'm still not sure what the right way to re-word it is.

[steveklabnik]

@nathanl any thoughts here?

[nathanl]

The difference is more like 'are you shipping an application or a library?'

If that's the distinction, I don't think there's a good way to say "--bin actually means 'application'" - it's the flag itself that's confusing. The real fix would be for cargo to deprecate --bin in favor of --app.

Short of that, maybe the docs should just acknowledge "this flag is confusingly-named, but you use --bin when you want to make a standalone application as opposed to a library." And possibly, "It will be compiled to a binary in the end either way."

[steveklabnik]

I mean, calling compiled programs 'binaries' has a loooong history. It's just a word that's overloaded due to context.

[richo]

Maybe referencing bin/ and lib/ in the posixfs layout?

On Monday, May 18, 2015, Steve Klabnik notifications@github.com wrote:

I mean, calling compiled programs 'binaries' has a loooong history. It's
just a word that's overloaded due to context.

—
Reply to this email directly or view it on GitHub
#24495 (comment).

[nathanl]

I mean, calling compiled programs 'binaries' has a loooong history. It's just a word that's overloaded due to context.

Yep, you're right, and so is @richo. How about saying something like "We're passing --bin because our goal is to get straight to making an executable application, as opposed to a library. Executables are often called "binaries" (as in /usr/bin, if you're on a Unix system)."

[steveklabnik]

@nathanl that sounds good to me. Are you interested in updating this PR? Sorry that it got lost in the shuffle :(

[nathanl]

@steveklabnik Yep, updated. 😄

[steveklabnik]

Awesome! This looks great, with a few smallll details: single quotes should be used for emphasis in this way, not double quotes. And, they should be curly quotes, and the period should move. :) I know these quotes can be weird, so here's the text, if you don't want to figure out how to type them: https://gist.github.com/steveklabnik/0ab6e31bb638263c196b

After that, let's get this merged! Sorry it's been so nitpicky :(

[nathanl]

No problem. I've made the tweaks and would like to squash my commits down to one, but so far I've just done edits straight from the Github interface and have to clone the project to do the squash. 41k commits take a while to clone... 😄

[nathanl]

@steveklabnik Squashed and ready to merge!

[steveklabnik]

@bors: r+ rollup

[bors]

📌 Commit a47d7a7 has been approved by steveklabnik

[steveklabnik]

Thanks so much!

[bors]

⌛ Testing commit a47d7a7 with merge 8d24f83...

[bors]

💔 Test failed - auto-linux-32-opt

[alexcrichton]

@bors: retry

On Thu, Jun 11, 2015 at 9:38 PM, bors notifications@github.com wrote:

[image: 💔] Test failed - auto-linux-32-opt
http://buildbot.rust-lang.org/builders/auto-linux-32-opt/builds/5327

—
Reply to this email directly or view it on GitHub
#24495 (comment).

[bors]

⌛ Testing commit a47d7a7 with merge b3a2a1c...

[bors]

⛄ The build was interrupted to prioritize another pull request.