10.3. Debugging

The user manual’s debugging section serves as a good starting point for development-side debugging as well—it’s often the same mechanisms that help understand why something’s not working as expected. In particular, looking at the generated HILTI & C++ code often shows quickly what’s going on.

That section describes only runtime debugging output. The Spicy toolchain also has a set of compile-time debug output streams that shine light on various parts of the compiler’s operation. To activate that output, both spicyc and spicy-driver (and hiltic as well) take a -D option accepting a comma-separated list of stream tags. The following choices are available:

ast-dump-iterations

The compiler internally rewrites ASTs in multiple rounds until they stabilize. Activating this stream will print the ASTs into files dbg.* on disk after each round. This is pretty noisy, and maybe most helpful as a last resort when it’s otherwise hard to understand some aspects of AST processing without seeing really all the changes.

ast-final

Prints out all the final ASTs, with all transformations, ID & operator resolving, etc fully applied (and just before final validation).

ast-orig

Prints out all the original ASTs, before any changes are applied.

ast-pre-transformed

Prints out ASTs just before the AST transformation passes kick in. Note that “transformation” here refers to a specific pass in the pipeline that’s primarily used for Spicy-to-HILTI AST rewriting.

ast-resolved

Prints out ASTs just after the pass that resolves IDs and operators has concluded. Note that this happens once per round, with progressively more nodes being resolved.

ast-scopes

Prints out ASTs just after scopes have been built for all nodes, with the output including the scopes. Note that this happens once per round, with progressively more nodes being resolved.

ast-transformed

Prints out ASTs just after the AST transformation passes kick in. Note that “transformation” here refers to a specific pass in the pipeline that’s primarily used for Spicy-to-HILTI AST rewriting.

ast-codegen

Prints out the ASTs used for C++ code generation. These are the final ASTs with possibly additional global optimizations applied to them.

compiler

Prints out a various progress updates about the compiler’s internal workings. Note that driver is often a better high-level starting point.

driver

Prints out the main high-level steps while going from source code to final compiler output. This stream provides a good high-level overview what’s going on, with others going into more detail on specific parts.

grammar

Prints out the parsing grammars that Spicy’s parser generator creates before code generation.

jit

Prints out details about the JIT process.

parser

Prints out details about flex/bison processing.

resolver

Prints out a detailed record of how, and why, IDs and operators are resolved (or not) during AST rewriting.