User manual
This brief user manual describes how you can install VisuFlow and gives a short introduction into the different functions and how to use them.
Embed or mention video here?
Download your preferred Eclipse package from Eclipse Downloads, for example Eclipse IDE for Java Developers. Extract the .zip file and move the eclipse directory to your preferred location. Download the latest version of the VisuFlow plug-in. Select the latest version and download the .jar file, e.g. de.uni-paderborn.visuflow.plugin-1.0.0-SNAPSHOT.jar. Once the file is downloaded, move it to the dropins directory in the eclipse directory. VisuFlow is now installed and you can start Eclipse.
A prerequisite for VisuFlow is, that you already have a project (target project) to run your analysis on. This project has to be a project in the Eclipse workspace. So as a first step, import the target project, if it is not already part of your Eclipse workspace.
If you want to create a new analysis project, you can use the wizard VisuFlow provides. Select
File → New → Other.... In the appearing dialog scroll down to Other and select New Analysis Project. Enter the names for your project, package and main class. To choose
your target project, click on Browse and select your target project (see Prerequisites). On the
next page, you can choose the analysis framework i.e. Soot or Heros, the type of the new analysis,
the analysis direction. You can also define how the flow facts should look like by selecting the type of the
collection and the data type of the collection in the subsequent dropdowns. It is possbible to create
custom data types by selecting the Custom option. Select the soot version you intended to use in
the analysis. Once you are done, click Finish and the VisuFlow wizard will create a new project,
which already contains a project stub. This includes a main class to launch your analysis and
an analysis class, which implements the analysis type, you selected in the wizard. This class has
some errors, because it is just a stub and has to be implemented by you. When your analysis is
ready for a first run, continue with Executing your analysis.
Open the VisuFlow perspective by selecting the menu Window → Perspective → Open Perspective → Other....
In the appearing dialog select VisuFlow and click OK. Import both your
analysis and target project, if they are not already part of the Eclipse workspace. Click 
(Link Target Project) in the toolbar to link your analysis to your target project. This step is
necessary, because VisuFlow needs to know, which project is your analysis and which one is your
target project.
Once you build your analysis, VisuFlow runs its internal analysis and populates the CFG and the
Unit Inspection view. While your analysis is build, the target project is also compiled to Jimple.
The output can be found in the directory sootOutput in your analysis project. You can open the
files in this directory to have a look at the intermediate representation of your target project.
To execute your analysis, right-click on the analysis project and select Debug As → Java Application.
In the next dialog select the main class of your analysis and click OK. Another dialog
appears, which asks you to select the launcher. Select the VisuFlow Launcher, otherwise VisuFlow
is not able to extract the flow facts, while your analysis is executed.
Unit breakpoints can be set in the Jimple view or in an Java editor. To set breakpoints in the
Jimple view, open the Jimple file of the class you are interested in. All Jimple files can be found
in the sootOutput directory of your analysis project. You can now set breakpoints by double-clicking
on the ruler on the left side of the Jimple view. To remove a breakpoint, double-click it
again. You can also use the Breakpoints view from Eclipse to get an overview of all breakpoints and
remove breakpoints from here.
To set breakpoints in an Java editor, set a normal Java breakpoint in your analysis code.
Then right-click on the breakpoint indicator and select Unit Breakpoint Properties. In the
appearing dialog, you can choose between a breakpoint for a particular unit and a breakpoint for
a type of unit. If you want to set the breakpoint for a particular unit, select the class,
the method and then highlight the unit in the Jimple code.
You have the choice to navigate between the different views in VisuFlow by the right-click context menu available in each view. Upon selecting a node in the Graph view or a statement in the Jimple view/Target Java Source or a unit in the Unit Inspection view the navigation listed below is possible via the right-click context menu
| From | To |
|---|---|
| Graph View | Unit Inspection View Target Java Source Jimple View |
| Jimple view | Unit Inspection view Target Java Source Graph view |
| Unit Inspection view | Graph view Jimple view |
| Target Java Source | Graph view Jimple view |
To open up the CFG View, if it's not already open, click on Window → Show View → Other → VisuFlow → CFG View. Once the analyis and the target projects have been set up and the analysis
has been executed as described using the steps above, the CFG View gets populated with
the ICFG of the target code. You can get more information about each method by hovering the mouse
cursor over the method nodes. A tooltip is displayed with the information about the method such as
its name, method signature and a snippet of the method body. Sometimes the tooltip may not
appear on hovering over the node. In such cases, click anywhere in the CFG view in order to get
focus into it or double click on the CFG View tab in order to get the View to a full screen and
try again. You can click on any of the nodes in the ICFG in order to navigate to the CFG of that
particular method node. The title bar at the top of the view shows the method name of the
currently displayed CFG. You can also hover over any of the nodes of the CFG in order to get
more information about it. A tooltip is displayed with information such as the in- and out-sets of the
analysis, the unit and its type. Additionally, you can also navigate to any of the other views by using
the right-click options of any of the nodes in the CFG. You can also navigate back to the ICFG
of the target code using the ”Show ICFG” button in the toolbar of the Graph view.
The default call graph option is ”CHA”. In order to change this, when the CFG View is open and an ICFG is being displayed, right-click anywhere on the view in order to get a right-click menu ”Call Graph Option”. The sub menu of the ”Call Graph Option” contains two items ”CHA” and ”SPARK”. Click on any of these options to switch the call graph. Once the call graph option is selected, the analysis project rebuild is triggered. Once the rebuild is complete, the title bar at the top of the view, gets updated to display the current call graph option.
When an ICFG or CFG is being displayed, you can zoom in and out of the graph by using the mouse wheel. You can also use the ”+” and ”-” buttons on the toolbar of the view in order to zoom in and out of the graph.
You can pan the graph around by holding down the right mouse button and moving the mouse around. You can also use the panning buttons located after the ”Color Settings” button on the ”Settigns Bar” or even use the keyboard arrow keys to pan the graph. Additionally, if the graph is really huge, then you can also hold down the shift button and use the keyboard arrow keys to pan the graph by larger displacements.
You can search for nodes of the graph when the CFG of a method is being displayed by using the ”Search Box” located on the ”Settings Bar” of the view. Type in the search string and press ”Enter” in order to perform the search. All the nodes with names or the custom attributes containing the search string will be filtered.