Skip to content

Debugging templates can be rather hard

While working on !42 (merged) I found that with a buggy template the error messages from the compiler often point to items in the macro's input, ie the driver. This seems inevitable since we can't generally double up spans on the generated output and there's no structural mechanism for ensuring that the output implied by the template is syntactically correct. (This is a problem that macro_rules! macros also suffer from.)

I found it was often most convenient to debug the examples I was working on by enabling the debugging eprintlns in the implementation of derive_adhoc_expand. (Part of the problem is that the examples are buried inside macrotest and trybuild, so that running cargo expand is not possible.) This is not a strategy readily available to the user of derive-adhoc.

The most effective strategy for the user is probably to use cargo expand. Sadly this depends on having a Nightly toolchain available.

Things we could do to help the user might include:

  1. Write documentation on how to go about debugging a macro and recommending cargo expand. I haven't used cargo expand much but it seems the tool people generally use for this?
  2. Maybe have derive_adhoc_expand try to syntax-check its own output with syn, and print something to stderr directly if the output doesn't parse.
  3. Have derive-adhoc write the output it generates to files in target (but what woudld we call them and how would the user find them?)
  4. Have the eprintlns compiled in behind a cargo feature.

Items 2 and 3 would have to be an optional off-by-default feature too since they would be slow and maybe flaky. And both are rather exciting and might not work for some reason or another. Maybe there are other possible options.

Debugging a macro call (ie, if the problem is in the driver) is probably not so bad, since the compiler will syntax-check it and the spans usually point to the right place and derive-adhoc likes to duplicate its own errors - reporting them at both the relevant part of the template, and the relevant part of the driver.

I suggest that for now we hope that 1 (docs) will suffice.