The Little Book of Rust Macros

announcements
1

The Little Book of Rust Macros.

Because writing books about Rust is the kewl thing to do these days (and because I don't have the personality or ethic for a blog), it's a big brain-dump of a fair part of what I know about writing macros in Rust.

This is intended to be kind of like the Rustonomicon, but for macros: it goes through how they work, the gotchas, the weird minutiae, and contains various patterns and examples.

It is not finished, in the sense that a major part of it is meant to collect patterns, building blocks, and annotated examples. The two introductions (one methodical, one practical) should be more or less done. If you feel anything is missing from them, please let me know.

If you want to contribute, there's a few things that will help:

  • If there's anything in there that doesn't make sense, particularly in the introductions, let me know.
  • Noticed a useful parsing or expansion pattern? Also let me know.
  • Have a useful bit of macro code that can be factored into a stand-alone macro? See above. (Actually, if the "Building Blocks" chapter gets significantly larger, I'll be tempted to have a matching cargo crate so that they're all immediately usable).
  • Is there a big, complicated macro that you'd like to see explained (or better yet: you have an annotated version of a big, complicated macro)? You know the drill.
31 Likes
2

Wow! That's a lot of content for a "little" book.

Can I include this in my growing collection of Rust ebooks?

1 Like
3

Great work!

4

Don't see why not.

5

Look really cool.

Any chance to view it in a light theme?

6

None whatsoever. Do you know how long it took me to get that working? I had to write a custom build process to override what rustbook was doing.

I'd provide an alternate theme, but browsers dropped stylesheet switching years ago. Oh well. :stuck_out_tongue:

But seriously, I only get to pick one theme, and I like this one.

7

Nice! For some reason, the theme breaks keyboard scroll for me, though, and page flipping through arrow keys would be great thing :).

But that's really just details.

8

It's not the theme; at least, I can't find anything I've done to break it. As far as I know, rustbook is just crazy. Navigating back from footnotes has never worked for me, for example.

9

I wondered how did you get the syntax context rendered in the verbatim block. Then I checked the source code out.

Oh, well.

(Great book, by the way!)

1 Like
10

This is awesome! Loved the recursion trick, I once asked in IRC and nobody knew how to expand macros from the inside out.

11

You can't. That said, there's a proposal to add "eager expansion" which would let you do exactly that.

12

Did you consider using my crate instead of rustbook? (mdBook) :blush:

1 Like
13

I see. But the callback trick is a workaround to expand macros from the inside out, no? Also, Macronomicon would be cool name :stuck_out_tongue:

14

No, but I'll give it a shot and see how it does. It'll have to wait, though: my internet connection is shaped at the moment, so building Rust code is basically impossible until the quota resets.

15

Nice, let me know what you think about it :wink: I don't have a lot of feedback yet

16

I suppose it can do that to a degree, but it's mostly to work around not being able to expand to arbitrary token sequences.

Nah, I think that'd take away from the Rustonomicon. Besides, I want this to sound approachable, not existentially terrifying.

17

@Azerupi I tried to build it with mdBook but it threw an error and didn't seem to copy over most of the theme files. Manually copying them over fixed it. Also, the main headers which rustbook used seem to use % header but mdbook uses # header so it probably just needs updating.

Seems to work well other than that.

[EDIT]

I did run into a build script error when running cargo build --release --features="regenerate-css" though it went away when I retried a second time. Not sure why.

18

Did you use the git version? I pushed a merge about 30 minutes ago introducing many bugs but I just reverted it now.

19

It was git but I'm not sure which version it was as I mangled the history. I'll retry with current master.

20

It should work with the current git version because the doc rendered ok