How to debug Julia macros?

Question

Note: This question refers to Julia v1.6. Of course, at any time the answers should ideally also answer the question for the most recent version.

There seem to be a lot of questions and confusion about macro hygiene in Julia. While I read the manual pages in question, I still really struggle to write macros while using things like interpolation ($name), quote and other quoting syntax, the differences in behavior between macros and functions acting on expressions, esc, etc.

What are the tools Julia provides for finding bugs in macros and how to use them effectively?

This is certainly a broad question, which I think very much deserves a dedicated manual page, rather than the current afterthought in an overview of meta-programing. Nevertheless, I think it can be answered effectively (i.e., in a way that teaches me and others a lot about the main, general question) by considering and debugging a concrete example. Hence, I will discuss a simple

toy-example macro:

(Note that the macro Base.@locals "Construct[s] a dictionary of the names (as symbols) and values of all local variables defined as of the call site" [from the docstring].)

# Julia 1.5
module MyModule

foo = "MyModule's foo"

macro mac(print_local=true)
    println("Dump of argument:{")
    dump(print_local)
    println("}\n\n")

    local_inmacro = "local in the macro"

    return quote
        println(repeat("-", 30)) # better readability of output

        # intention: use variable local to the macro to make a temporary variable in the user's scope
        # (can you think of a reason why one might want to do this?)
        var_inquote = $local_inmacro * "_modified"

        # intention: evaluate `print_local` in user scope 
        # (THIS CONTAINS AN ERROR ON PURPOSE!
        # One should write `if $(esc(print_local))` to achieve intention.)
        if $print_local
            # intention: get local variables in caller scope
            println("Local in caller scope: ", Base.@locals)
        else
            # intention: local to macro or module AA.
            println($foo)
            println($local_inmacro)
            println(var_inquote)
        end
    end
end

end  # module MyModule

Some code to test this

function testmacro()
    foo = "caller's foo"

    MyModule.@mac  # prints `Dict` containing "caller's foo"

    MyModule.@mac true # (Exactly the same)

    MyModule.@mac false # prints stuff local to `@mac` and `MyModule`

    # If a variable name is passed instead of `true` or `false`, 
    # it doesn't work. This is because of macro hygiene,
    # which renames and rescopes interpolated variables.
    # (Intended behaviour is achieved by proper escaping the variable in the macro)
    var_false = false
    MyModule.@mac var_false  # gives `UndefVarError`
end

testmacro()

Pretend that you don't understand why the error happens. How do we find out what's going on?

Debugging techniques (that I'm aware of) include:

• @macroexpand (expr) : expand all macros inside (expr)
• @macroexpand1 (expr) : expand only the outer-most macro in (expr), usually just the macro you are debugging. Useful, e.g., if the macro you're debugging returns expressions with @warn inside, which you don't want to see expanded.
• macroexpand(m::Module, x; recursive=true) : combines the above two and allows to specify the "caller"-module
• dump(arg) : can be used inside a macro to inspect its argument arg.
• eval(expr) : to evaluate expressions (should almost never be used inside a macro body).

Please help add useful things to this list.

Using dump reveals that the argument print_local during the problematic (i.e. last) macro call is a Symbol, to be exact, it has the value :var_false.

Let's look at the expression that the macro returns. This can be done, e.g., by replacing the last macro call (MyModule.@mac var_false) by return (@macroexpand1 MyModule.@mac var_false). Result:

quote
    #= <CENSORED PATH>.jl:14 =#
    Main.MyModule.println(Main.MyModule.repeat("-", 30))
    #= <CENSORED PATH>.jl:18 =#
    var"#5#var_inquote" = "local in the macro" * "_modified"
    #= <CENSORED PATH>.jl:23 =#
    if Main.MyModule.var_false
        #= <CENSORED PATH>.jl:25 =#
        Main.MyModule.println("Local in caller scope: ", #= <CENSORED PATH>.jl:25 =# Base.@locals())
    else
        #= <CENSORED PATH>.jl:28 =#
        Main.MyModule.println("MyModule's foo")
        #= <CENSORED PATH>.jl:29 =#
        Main.MyModule.println("local in the macro")
        #= <CENSORED PATH>.jl:30 =#
        Main.MyModule.println(var"#5#var_inquote")
    end
end

We could manually remove the annoying comments (surely there is a built-in way to do that?).

In this simplistic example, the debugging tools listed here are enough to see the problem. We notice that the if statement in the macro's return expression "rescopes" the interpolated symbol to the macro's parent module: it looks at Main.MyModule.var_false. We intended for it to be Main.var_false in the caller scope.

One can solve this problem by replacing if $print_local by if $(esc(print_local)). In that case, macro hygiene will leave the contents of the print_local variable alone. I am still a bit confused as to the order and placement of esc and $ for interpolation into expressions.

Suppose that we mess up and write if $esc(print_local) instead, thus interpolating the esc function into the expression, rather than escaping anything (similar mistakes have cost me quite a bit of headache). This results in the returned expression (obtained via @macroexpand1) being impossible to execute via eval, since the esc function is weird outside of a macro, returning in stuff like:($(Expr(:escape, <somthing>))). In fact, I am generally confused as to when Expressions obtained via @macroexpand are actually executable (to the same effect as the macro call) and how to execute them (eval doesn't always do the trick). Any thoughts on this?