Suggestion: clarify meaning of .compile("cxx-demo") in tutorial

[rodrigodesalvobraz]

In the cxx_build example in the tutorial, the role of the last line .compile("cxx-demo") confused me for quite a while because I was not sure what string to provide it with an argument.

The example makes it look like it should be the crate name, but that would not work if you are compiling multiple C++ files.

After some experimentation it looks like this can be a fairly arbitrary name that becomes the name of the object file for the particular source file (I found that out but using some other string and finding a file with a name containing it in the target directory).

I believe the best approach is to use the name of the source file itself, and would suggest changing the last line in this example to .compile("blobstore"). This would make the purpose of the name a lot clearer.

[adetaylor]

Thanks, I agree! Maybe with a comment too.

It would be great if you could raise a pull request to make this change :)

[rodrigodesalvobraz]

Alright, just did that. Please check https://github.com/dtolnay/cxx/pull/1012.

[adetaylor]

Hey @dtolnay @rodrigodesalvobraz sorry, I messed up here! I thought this was a concern about autocxx which is why I responded and said I thought this was a good idea. @dtolnay owns cxx so it was none of my business. Sorry about that!

(That said I always think more docs/comments on unclear stuff in demos are good, and I'll plan to make an equivalent change for the autocxx demo...)

[rodrigodesalvobraz]

Sure, no problem, I hope the PR is useful anyway.

[dtolnay]

I don't agree with using the user's source file's name in the compile call. In general there are going to be zero or more user-specified source files being compiled (in addition to the cxx-generated sources). I can see how a source file name may be appropriate if there is exactly one user-specified source file but that guidance does not make sense for 0 or 2+ source files.

Regardless of what the exact recommendation ends up being, I don't think it's going to be cxx-specific, so I would prefer for it to go in the cc::Build::compile docs and we can consider linking to that from the tutorial.

[rodrigodesalvobraz]

After learning some more I agree the source file's name is not the best option. I had assumed we would have one build per source file, but I see now that's only one for the entire crate.

However, I think that referring to cc::Building::compile is too generic (I had looked in there and it did not help me much). A recommendation for what this name should be at the cxx level would be more informative. I would recommend saying that this name is arbitrary but that the crate name is a good choice. In other words, making it clear the crate name is not mandatory but works.