Debugging

Debugging compilers can be challenging. Polyglot provides several tools that help developers understand what is going on during compilation.

Running Polyglot

Polyglot is ordinarily run by invoking the class polyglot.main.Main. By default, Polyglot supports many options that can be viewed by giving it the --help option:

  --help                   print this message
  --version                print version info
  -addbootcp path          prepend path to the bootclasspath
  -assert                  recognize the assert keyword
  -bootclasspath path      where to find runtime class files (default: JVM 
                           property: sun.boot.class.path (or all jars in 
                           java.home/lib))
  -c                       compile only to .java
  -classpath path          where to find user class files (default: JVM 
                           property: java.class.path)
  -commandlineonly         only compile files named on the command-line (may
                           also require -c)
  -D directory             output directory for .java files (default: same 
                           as -d)
  -d directory             output directory (default: current directory)
  -debugpositions          generate position information for 
                           compiler-generated code
  -disable pass            disable pass pass
  -dump pass               dump the ast after pass pass
  -errors num              set the maximum number of errors (default: 100)
  -fqcn                    output fully-qualified class names
  -g                       generate debugging info in class files
  -mergestrings            parse concatenated string literals as one single 
                           string literal
  -no-output-to-fs         keep .java files in memory if possible
  -nooutput                delete output files after compilation
  -noserial                disable class serialization
  -ox ext                  set output extension
  -postcompiler compiler   run javac-like compiler after translation
  -postopts options        options to pass to the compiler after translation
  -preferclassfiles        prefer class files to source files even if the 
                           source is newer
  -print pass              pretty-print the ast after pass pass
  -report topic=level      print verbose debugging information about topic 
                           at specified verbosity. Allowed topics: cfg, 
                           context, dataflow, errors, frontend, imports, 
                           loader, resolver, serialize, time, types, visit, 
                           verbose, debug, jl, qq
  -simpleoutput            use SimpleCodeWriter
  -sourcepath path         where to find source files (default: current 
                           directory)
  -stdout                  output to stdout
  -sx ext                    set source extension
  -v                       delete output files after compilation
  -w num                   set the maximum width of the .java output files 
                           (default: 80)

Several of these options do the same thing as the corresponding javac option. Others add new functionality.

One option that isn't on this list is the -ext option. This option causes Polyglot to load the named extension, which may also add additional options to the list. The provided Polyglot compiler scripts such as bin/jlc and /binjl5c simply invoke Polyglot with the appropriate -ext option.

Controlling compilation

It is not necessary to compile all the way to bytecode. The -c option can be used to output Java source files rather than running the Java compiler them. It is possible to selectively stop compiler passes from running, using the -disable option.

Reporting

Polyglot is instrumented to report on what is happening internally. Reporting is enabled using the -report option. Reporting is organized by topics and within each topic, by a level of verbosity. Selecting a topic and a level of verbosity will cause all reports on that topic of that level of verbosity or lower to occur. Extensions can define their own topics and add their own report instrumentation to new or existing topics. The reporting mechanism is not expensive, and it is recommended over more ad hoc techniques such as invoking System.out.println.

Printing intermediate representations

The -print option can be used to generate a pretty-printed version of the AST produced by the selected pass during compilation. For less attractive but still informative version of the same thing, the -dump option may be used instead.