README.md
1# Overview
2
3The Ideal Graph Visualizer is a tool developed to help examine the intermediate
4representation of C2 which is commonly referred to as the "ideal graph". It was
5developed in collaboration with the University of Linz in Austria and has been
6included as part of hotspot since that was the primary target of the tool. The
7tool itself is fairly general with only a few modules that contain C2 specific
8elements.
9
10The tool is built on top of the NetBeans 7 rich client infrastructure and so
11requires NetBeans to build. It currently requires at least Java 6 to run as it
12needs support for JavaScript for its filtering mechanism and assumes it's built
13into the platform. It should build out of the box with NetBeans 7.0 and Java 6
14or later.
15
16# Building and Running
17
18The build system used for IGV is ant. To download all required libraries and
19build IGV, issue `ant build`. To run IGV, use the `igv.sh` command; it will put
20all log messages generated by the run to the file `.igv.log`. To see all log
21messages generated during an IGV run, use `ant run`.
22
23# Usage
24
25The JVM support is controlled by the flag `-XX:PrintIdealGraphLevel=#` where `#`
26is:
27
28* 0: no output, the default
29* 1: dumps graph after parsing, before matching, and final code (also dumps
30 graphs for failed compilations, if available)
31* 2: more detail, including after loop opts
32* 3: even more detail
33* 4: prints graph after parsing every bytecode (very slow)
34
35By default the JVM expects that it will connect to a visualizer on the local
36host on port 4444. This can be configured using the options
37`-XX:PrintIdealGraphAddress=` and `-XX:PrintIdealGraphPort=`.
38`PrintIdealGraphAddress` can actually be a hostname.
39
40It is advisable to run the JVM with background compilation disabled (-Xbatch).
41Compilations going on in the background may be cancelled when the VM terminates,
42which can lead to incomplete dumps being sent to IGV.
43
44Alternatively the output can be sent to a file using
45`-XX:PrintIdealGraphFile=filename`. Each compiler thread will get it's own file
46with unique names being generated by adding a number onto the provided file
47name.
48
49More information about the tool is available at
50https://wiki.openjdk.java.net/display/HotSpot/IdealGraphVisualizer.
51