View your “dark code” in Rust

And know what your code is really doing

“I can has dark code?” — Photo by Mikhail Vasilyev on Unsplash

Macros and Attributes abound in Rust, and it’s often useful (nay, important!) to know how they are morphing your source code. This knowledge is important to help you:

1. Gain a deeper understanding of what your code is doing.

2. Debug your source code more easily and effectively, when using a macro or attribute produces unexpected results.

cargo-expand is a useful cargo sub-command that can be installed and run to “expand” the macros and attributes (hereafter, collectively referred to as “code shortcuts”) in your source code, and show you the code being generated.

Let’s say you start with the following code, where we have a simple struct called PersonDetails, and we want this type to be printable.

The code looks like this:

<a href="https://medium.com/media/b208c68346a222b650025a7b227dbc76/href">https://medium.com/media/b208c68346a222b650025a7b227dbc76/href</a>

I’ve made PersonDetails printable by using the Derive attribute to derive from the fmt::Debug trait.

But how exactly is the use of this attribute with the fmt::Debug trait making the Struct printable?

As it turns out, you can expand the attribute and look at the generated code using the rust compiler.

Unfortunately:

1. The rustc command needed to expand code shortcuts requires you to first install and then switch manually to the rust nightly toolchain.

2. The generated code is printed to the terminal, with formatting that isn’t ideal, and without syntax highlighting.

3. You’ll need to switch back to the non-nightly version of the toolchain once you’re done.

At my project root, I need to run:

rustup override set nightly

then:

cargo rustc —-profile=check -- -Zunstable-options --pretty=expanded

producing the following result:

Expanded output using rustc with the right flags.

You’ll see that the formatting is janky in places, especially within the main function.

Let’s try the same thing with cargo-expand.

cargo install cargo-expand

cargo-expand will use the rustfmt tool if it is installed on your system to format / prettify the generated code.

You can run cargo expand even without rustfmt installed. To install rustfmt run:

rustup component add rustfmt

While cargo-expand also uses the nightly build of the rust behind the scenes, it doesn’t expect you to manually change the default toolchain of the project you’re working in.

Expanding the code shortcuts on the same example with cargo-expand produces:

Expanded code output using `cargo expand`

Observe that:

1. The output makes better use of whitespace when formatting. ✨

2. The output is syntax highlighted! 🎉

Go forth, explore, and try cargo expand on code containing other macros such as vec! or with some of these super-useful attributes.

References

cargo-expand: https://github.com/dtolnay/cargo-expand

rustup: https://rustup.rs/

rustfmt: https://github.com/rust-lang/rustfmt

Macros: https://doc.rust-lang.org/1.7.0/book/macros.html

Attributes: https://doc.rust-lang.org/reference/attributes.html

6 useful Rust macros that you may not have seen before: https://blog.usejournal.com/6-useful-rust-macros-that-you-might-not-have-seen-before-59d1386f7bc5