Expand Procedural Macro Docs #412

Havvy · 2018-09-02T10:42:30Z

This merges my WIP stuff, @alexcrichton's mostly guide level stuff, and some new material into what I hope will be the final status for the procedural macro page.

I'm not super happy with the attribute resolution section personally, but I feel like we can fix that up later. I want procedural macros to be in the reference before the next stable release, since I feel people are going to have questions about it and the reference should be a good place to find answers.

Opening a new pull request instead of pushing to @alexcrichton's because so much has changed that conversation already there is entirely outdated.

In preparation for the 1.30 stabilization I figured I'd get started and help write some documentation!

petrochenkov · 2018-09-02T12:02:21Z

src/procedural-macros.md

+
+These macros cannot expand to syntax that defines new `macro_rule` style macros.
+
+### Derive mode macros


What's the point of "mode" in "derive mode"?
It's like a random unrelated word just inserted there.
I've seen the wording "derive mode" in a couple of compiler errors maybe, but that's all.

The phrasing "define new modes for the derive attribute" doesn't make sense to me.
Ok, I'm not a native speaker, let's look into a dictionary - "A way or manner" / "A fashion or style" - still doesn't make any sense.
In the first approximation, derive just applies arbitrary macros passed to it (#[derive(A, B, C)] ITEM -> #[A] #[B] #[C] ITEM), how are those macros "modes"?

</rant>

The main point, as I see it, is that it lets us talk about the A, B, C inside #[derive(A, B, C)] without needing to always call them macros. If we want to talk about A without caring that its a macro, and we just call them derive macros, then what do we call it? We could call it a "derive", but that does not jive well. "The derive attribute takes derives" is also weird. So we need some name to distinguish them. My original thought was to go with "deriver", but then I saw said compiler error that calls them a derive mode. And mode makes sense to me.

When I think of modes, I think of distinct ways of operating something. My oven has modes for "bake", "boil", some other one I never use, and "clean". Firefox has safe mode and private browsing mode. Businesses operate in stealth mode or growth mode or whatever fancy mode they want. That said, if you want to get it changed to "deriver" or something, file an issue against rust-lang/rust. I defer terminology to what it uses when I can.

I saw said compiler error that calls them a derive mode.

Yeah, I've seen those diagnostics too and always thought they were bad, and wanted to get rid of them.
That's why when I'd seen that terminology reused I immediately thought it wasn't a good idea.
_{^{(Please, excuse my past tenses if I got them all wrong.)}}

I suspect the terminology came from the time when only a limited set of built-in derives existed.
"Mode" kinda implies that you have several of them and need to choose one, i.e. something enum-like.

without needing to always call them macros

Why? They are macros.
If #[proc_macro_attribute] defines an "attribute macro", #[proc_macro_derive] defines a "derive macro", then we have a symmetry between language and docs.
"derive attribute takes derive macros as arguments" - sounds ok to me.

petrochenkov · 2018-09-02T12:10:29Z

src/attributes.md

+when compiling for tests and dynamic otherwise. Attribute macros are dynamic.
+All other attributes are inert. 
+
+## Attribute resolution


I'd prefer to avoid specifying any details here for now, the rules are not settled yet.
Macro modularization was stabilized, but there's still a number of incomplete items from rust-lang/rust#50911 (comment) that need to be done until beta, stable or maybe even later if crater allows.
(My suggestion would be to stash this section somewhere until 1.30 stable is released.)

petrochenkov · 2018-09-02T12:14:41Z

src/attributes.md

+attributes* remove themselves from the thing they are on while *inert attriutes*
+stay on.
+
+The `cfg` and `cfg_attr` attributes are dynamic. The `test` attribute is inert


The full list is cfg, cfg_attr, test, bench, derive currently, if I'm not missing anything.

test and bench are being migrated to macros right now though (rust-lang/rust#53410).
(Also, test/bench are always "dynamic", they tweak their target items in test mode as well - add pubs, reexports.)

Perhaps "active" would be better than "dynamic"?
Dynamic sounds like 1) something happening at runtime and 2) the attributes themselves are changing.
The difference with inert attributes is that "dynamic"/"active" attributes can transform their target items, i.e. change something else rather than themselves.

Perhaps we can even avoid "active built-in attributes" as a class and just call them "built-in attribute macros".

👍 on "active". I knew there was a better word. There always is when it comes to "dynamic". I just couldn't think of it.

I was going for "inert" as being attributes that remain on the item during macro resolution. bench isn't stable so we don't have to worry about it. derive seems to act as an inert attribute to me. It doesn't get removed from the item when running the derivers/derive modes. It doesn't actually modify the item its own but produce new one. Likewise, the test attribute stays on when compiling tests.

I'm not quite sure I want to call built-in attributes macro attributes as well.

michaelwu · 2018-09-04T03:06:52Z

src/procedural-macros.md

+also define derive mode helper attributes.
+
+Custom deriver modes are defined by a [public] [function] with the
+`proc_maco_derive` attribute and a signature of `(TokenStream) -> TokenStream`.


proc_macro_derive

michaelwu · 2018-09-04T03:07:13Z

src/procedural-macros.md

+
+Function-like procedural macros define new invokable macros.
+
+These macros are defined by a [public] [function] with the `proc_maco`


proc_macro

steveklabnik

one tiny whitespace nit

steveklabnik · 2018-09-05T14:25:59Z

src/linkage.md

@@ -205,3 +209,7 @@ a statically linked binary on MSVC you would execute:
 ```ignore,notrust
 RUSTFLAGS='-C target-feature=+crt-static' cargo build --target x86_64-pc-windows-msvc
 ```
+
+


Havvy · 2018-09-07T01:51:04Z

I would like to see this section in the reference before the deadline. People are going to want to look this up.

Havvy added New Content Missing features or aspects of language not currently documented. RFC Stabilization Docs Documentation required for stabilizing a feature labels Sep 2, 2018

alexcrichton and others added 19 commits September 2, 2018 03:51

Expand documentation on procedural macros

b6fa5e2

In preparation for the 1.30 stabilization I figured I'd get started and help write some documentation!

Remove 'in Rust' in proc macros

b3758ad

Notify cargo proc-macro crate info

50d8cf4

Clarify proc macros as crate type, not crate

36d6be1

First pass removal of guide-level material

ef6ca2b

Move proc-macro type sections to bottom

0dd95e8

Improve proc_macro crate type docs

6f694fc

Clean up language in linkage. Note about compiler specifiness

7f80970

Add 'proc_macro' to configuation options

6dbdc8c

Add proc_macro attributes to attributes page

9c0045f

Attribute resolution, types of attrs, inert/dynamic attrs

6851fea

Referencify proc_macro crate section

690bdee

More referenceifying proc macros

8bb6ca3

Derive mode macros

58c49c7

Attribute macros

caa8877

Runtime information of proc macros

f800c04

Function-like proc macros

19a988a

Cleanup proc macros after multi-day editing

0a57ca9

Add proc macro attrs to attrs on fns list

5b27fac

Havvy force-pushed the proc-macros-2 branch from 1e38a74 to 5b27fac Compare September 2, 2018 10:52

petrochenkov reviewed Sep 2, 2018

View reviewed changes

alexcrichton mentioned this pull request Sep 3, 2018

Expand documentation on procedural macros #405

Closed

Havvy added 2 commits September 3, 2018 12:31

Remove attribute resolution for now

f52d416

Active attributes, not dynamic

4dc54f2

michaelwu reviewed Sep 4, 2018

View reviewed changes

Havvy added 2 commits September 3, 2018 21:56

macos => macros

981a1c3

Proc macros: Fix tests, links, slight rewording, consistency

f466d18

steveklabnik suggested changes Sep 5, 2018

View reviewed changes

Whitespace: Extra newline in linkage.md

1975f82

steveklabnik approved these changes Sep 7, 2018

View reviewed changes

steveklabnik merged commit 17d009a into rust-lang:master Sep 7, 2018

petrochenkov mentioned this pull request Mar 1, 2019

Update attribute documentation. #528

Merged

ehuss mentioned this pull request Mar 2, 2019

Remove "mode" from derive macro terminology. #530

Merged

ehuss mentioned this pull request Mar 24, 2019

Macro documentation is sorely lacking #294

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Expand Procedural Macro Docs #412

Expand Procedural Macro Docs #412

Havvy commented Sep 2, 2018

petrochenkov Sep 2, 2018

Havvy Sep 2, 2018

petrochenkov Sep 2, 2018 •

edited

Loading

petrochenkov Sep 2, 2018

petrochenkov Sep 2, 2018

petrochenkov Sep 2, 2018

Havvy Sep 2, 2018

michaelwu Sep 4, 2018

michaelwu Sep 4, 2018

steveklabnik left a comment

steveklabnik Sep 5, 2018

Havvy commented Sep 7, 2018


		These macros cannot expand to syntax that defines new `macro_rule` style macros.

		### Derive mode macros


		Function-like procedural macros define new invokable macros.

		These macros are defined by a [public] [function] with the `proc_maco`

Expand Procedural Macro Docs #412

Expand Procedural Macro Docs #412

Conversation

Havvy commented Sep 2, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

petrochenkov Sep 2, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveklabnik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Havvy commented Sep 7, 2018

petrochenkov Sep 2, 2018 •

edited

Loading