Customizing `#[derive(Debug)]`

[clubby789]

Proposal

Problem statement

The current behaviour of the #[derive(Debug)] macro can be overly broad and not work for some use cases. Users with types that do not fit the derive are forced to either write verbose custom implementations (which they must remember to update when the type is updated), or a 3rd-party derive. These approaches both mean missing out on upstream optimizations to the macro.

Motivating examples or use cases

#[derive(Debug)]
struct FunctionBuilder<'cx> {
  cx: &'cx SomeVeryLargeContextType,  // Required for the struct, but unecessarily bloats debug output
  name: String,
  instructions: Vec<Instruction>,
}

#[derive(Debug)]
struct MyListForTraitImpls<T>(Vec<T>); // Should be displayed as a list of elements like `Vec`, but includes the `MyListForTraitImpls` type name

#[derive(Debug)]
struct CallbackRunner {
	f: Box<dyn Fn() -> usize>, // We don't want this displayed, but it will fail to compile as `dyn Fn() -> usize` is not `Debug`
	name: &'static str,
}

Solution sketch

Introducing a new #[debug(..)] attribute which can be applied to fields or types to customize the behavior of the derive.

skip

#[debug(skip)] on a field will cause it to not be emitted, and not require the type of that field to implement Debug.

Ideally,

#[derive(Debug)]
struct Xxx<T> {
	#[debug(skip)]
	something: T,
    /* other fields that don't use T */
}

should not place a : Debug bound on T.

transparent

Similarly to repr(transparent), #[debug(transparent)] may be placed on any type containing a single field to use the debug implementation of that field directly. The macro should expand to something like

/* ... */
Debug::fmt(self.0)
/* ... */

Other ideas

Other attributes that I am less commited to, but could be of use:

• #[debug(type)] - expands to the std::any::type_name of the field - useful for function pointers to see the source location
• #[debug(format_with = "path")] - a more general version of type, allowing a custom function to be used to format the field
• #[debug(rename = "identifier")] - changes the name of a field in the debug output

Alternatives

The main alternative is using a 3rd-party crate such as derivative. The reasoning against this is explained in the problem statement.

Links and related work

Derivative - One of the top 350 most downloaded crates on crates.io.

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

Internals thread

[joshtriplett]

Copying a suggestion from the internals thread:

If skip is added, it should probably be spelled #[skip(Debug)] and be applicable to Eq, Ord and other "field-wise derivable" traits as well.

[clubby789]

I went with #[debug] because of the precedent with #[default], but I think there's definitely a good case for that ordering if skip is extended to other derives.

[jhpratt]

Procedurally, is an ACP sufficient? This feels like a relatively large change.

[Veykril]

Copying a suggestion from the internals thread:

If skip is added, it should probably be spelled #[skip(Debug)] and be applicable to Eq, Ord and other "field-wise derivable" traits as well.

Note that the choice here has certain implications for the ecosystem. Going with a skip derive helper would imply that third-party derives should likely adopt this form as well over them using their own#[my_derive(skip)] helper.

[clubby789]

Procedurally, is an ACP sufficient? This feels like a relatively large change.

I've added a link to the Pre-RFC I made on IRLO; Josh suggested filing an ACP so it could be nominated for discussion.

[joshtriplett]

@jhpratt I think an ACP is sufficient; this seems like a small change, which would be a relatively small PR, and the primary challenge is deciding "should we do this", which is what we have ACPs for.

[scottmcm]

Copying from IRLO:

jdahlstrom: If skip is added, it should probably be spelled #[skip(Debug)]

TBH, I prefer this phrasing. It makes the proposal "add a common skip attribute" instead of "add a bunch of customization knobs".

Then #[skip(Hash)] works for fields not worth hashing, and the compiler can do things like deny if you derive(PartialEq, Hash) but have skip(PartialEq), since that means that the Hash implementation is just wrong.

---

But that direction would implicitly be a "also, ecosystem, maybe you should support skip like this too", at which point an RFC becomes more useful.

[dvdsk]

I like the idea of a common skip attribute.

I am not sure about transparent for Debug. I like the Debug fmt to show the 'ugly' truth. In the mentioned use case it saves two lines. It might also look cleaner, but for a clean look shouldn't we rely on Display?

A similar concern around skipping. That is easily resolved by still showing the name of the field.

[joshtriplett]

We discussed this in today's @rust-lang/libs-api meeting.

We'd like to go ahead and approve #[skip(...)] to skip a field for field-wise derives.

We also felt that there should be some syntax to skip a field for all field-wise derives, without having to repeat the whole list. #[skip] could do that.

Something, probably rustc, needs to lint against un-handled arguments for skip, such as skip(Degub).

And it would probably also make sense to have a lint for the cases scottmcm mentioned: skipping a field for a subset of derives that seems unlikely to make sense, such as deriving more than one of Hash/PartialOrd/PartialEq` but skipping a field for some-but-not-all of those.

[cuviper]

How do you know it's unhandled if a 3rd party derive might use it? Or is the assertion that #[skip(_)] is only going to be allowed for builtins?

[joshtriplett]

@cuviper If skip is going to be shared across derives, one potential way would be to assume that the only arguments skip takes are the names of traits, so if it has an argument that's not the name of a trait being derived, lint.

Making it a lint and not an error also makes it easy enough to disable.