RFC: Procedural macros in same package as app

[ora-0]

See discussion on internals here.

I feel the need to clarify that this is not about crates, but packages. I had them confused the initial time I wrote the document.

Rendered

[ora-0]

I have wrote the first revision. Let me know if I missed anything in the feedbacks

A list of important things that have been changed:

1. Add example of a library that has both normal function and macros
2. Add specifications on the configs in cargo.toml
3. Imported via macros::*
4. Use src/macros.rs instead of a proc-macros directory. See the rationale and alternative section, and the example under the explanations section. I believe this is a better system than the original.
5. Clarify that it is built after build.rs, and before lib.rs.

[Jules-Bertholet]

This is missing a specification of the command-line interface. Can I do cargo build --macros?

[ora-0]

This is missing a specification of the command-line interface. Can I do cargo build --macros?

Yes, I'll add this to the rfc

[epage]

I have wrote the first revision. Let me know if I missed anything in the feedbacks

@ora-0 as a tip for RFCs,

• if you make each edit in its own commit, the commits can describe whats changed
• link to the commit from the relevant threads so people can easily find how you've responded to their feedback

[SOF3]

Is there any particular impact on rustdoc?

• Should docs of the proc macro crate be rendered on docs.rs
• What is the path of the proc macro crate under target/doc
• What happens if there are multiple packages with a proc macro crate

Unlike build crate, proc macro crates export items directly visible to downstream packages through reexporting, so documentation might be necessary, although it might just be inlined in the doc itself. But should it still be documented with --document-private-items?

[ora-0]

Should docs of the proc macro crate be rendered on docs.rs

Probably not, since we the api won't be publicly available unless reexported.

What is the path of the proc macro crate under target/doc

It would be whatever the name of the crate is. By default it would be "macros", but can be changed in cargo.toml.

What happens if there are multiple packages with a proc macro crate

hmm... Perhaps we should change the default name to be "crate-name-macros" to avoid collisions, or "crate-name-proc-macros" depending or which one we decide to go with. The latter does feel a bit too long for my taste tho.

And regarding the --document-private-items, I believe it should document it. I'll add a section that details the behaviours sometime.

[ora-0]

Do we have any ideas on what name the new target should be? Currently it's macros but it may cause name collisions with --document-private-items.

One way to solve this is to only display the macros crate of the current package, which isn't a bad option in my opinion, since it shouldn't really be exposed anyways, except through lib. Unfortunately we can't use proc_macro to stay consistent as it's already taken.

Or we could prefix it with the package name, something like "crate_name_macros". But libraries like Tokio are already doing something like this, with the tokio-macros crate, so it may cause collisions that way.

The final option is "crate_name_proc_macro", which would be consistent with what we have, but feels a bit too long for me, though it would solve the issue of the second option.

[programmerjake]

Do we have any ideas on what name the new target should be? Currently it's macros but it may cause name collisions with --document-private-items.

assuming you're talking about paths in the output of rustdoc, you could use some character that's illegal in crate identifiers but legal in file-system paths and URLs, e.g. serde.proc-macro, giving you a URL like https://docs.rs/serde/latest/serde.proc-macro/derive.Deserialize.html