document the difference between 'crate-type = ["proc-macro"]' and 'proc-macro = true'

[ExpHP]

...whatever it is.

All I can really see is that crate-type = ["proc-macro"] makes rustdoc die with proc-macro crate not dylib when used in a path dependency.

---

(er... now that I think about it, I wonder if that's a bug in rustdoc)
(...or even a bug in cargo)
(...or rustc even! On stable, it produces the same error, but as an ICE!)

[ExpHP]

soo.... just in case the aforementioned error is a bug in... whatever it is that is buggy, here's a repro:

git clone https://github.com/ExpHP/unbox-macro -b minimize-cargo-5310
cd unbox-macro
cargo doc

[ExpHP]

crate-type = ["proc-macro"] seen in the wild:

https://github.com/goffrie/plex/blob/d59296b7663d8ed3d9ebbc7266c859903663ca69/Cargo.toml

Everything appears to work fine on the crate author's end, but cargo test fails with a mysterious error in downstream crates. I'm beginning to feel this is less of a documentation bug, and more of an actual bug.

[ehuss]

Does anyone have ideas on how we can make this friction go away?

One way this comes up is when you don't set anything in Cargo.toml, you get this error message:

error: the #[proc_macro] attribute is only usable with crates of the proc-macro crate type

which might lead one to set the crate-type and lead to these mysterious problems.

One thought I had is to just automatically set proc-macro if the crate-type is set to proc-macro. I can't think of any immediate harm that might cause. Unfortunately this wouldn't work if you set the crate type with an attribute.

I'm not sure if adding more documentation will help, since the documentation already directs people towards proc-macro = true. Perhaps the error message could contain some cargo-specific hints, but there isn't much precedent for doing that and seems a little out of place.

[ExpHP]

Hmm, so the troublesome error message comes from rustc, I gather?

The current impression I get is that it is more or less a bug that cargo even allows crate-type = ["proc-macro"]. If this is the case, I think it should be forbidden on cargo's end (read: deprecated, with a warning that points you in the right direction).

Edit: Hmm. Okay, I see what you mean with setting it via attribute. Maybe that could be deprecated as well in rustc, although tbh it doesn't bother me so much that cargo doc is broken if you do this.

[alexcrichton]

@ehuss could we perhaps both update the rustc error message as well as simply interpret crate-type = ["proc-macro"] as a proc-macro = true? (perhaps with a warning to prefer the latter)