Diagnostics and troubleshooting

Record the compiler version

Before investigating syntax behavior, record the exact installed compiler version.

wavec --version

Use wavec --help to confirm the command and option spelling accepted by that installation.

Check source without linking

To separate Wave source errors from linking or execution:

wavec build main.wave --emit=check

This checks Wave input without producing a normal executable.

JSON diagnostics

For IDEs, CI, and build tools that need structured diagnostics:

wavec --error-format=json build main.wave --emit=check

Keep the default human-readable format for terminal use and JSON for automated consumers.

Inspect compiler output

wavec --debug-wave=tokens build main.wave --emit=check
wavec --debug-wave=ast build main.wave --emit=check

--debug-wave prints selected representations such as tokens, the AST, or IR. For an ordinary source error, start with the first diagnostic and its source location; use debug output when investigating compiler behavior or building developer tools.

Separate common failure classes

1. Parsing/type errors also fail under --emit=check.
2. Import errors require checking std-path, --dep-root, --dep, and the actual filesystem layout.
3. Link errors require checking --link, -L, the target ABI, and symbol names.
4. Runtime errors occur after a successful build and should be separated by exit status and runtime environment.
5. FFI errors require rechecking widths, string representation, pointer lifetime, and calling convention against the native declaration.

A useful bug report

Include:

• wavec --version
• Host OS and target triple
• The complete command you ran
• A minimal .wave source that reproduces the issue
• Full diagnostic output
• Expected and actual behavior

Remove unrelated secrets, tokens, and private paths before posting logs publicly.