User manual - VisuFlow/visuflow-plugin GitHub Wiki

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?

Installation

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.

Prerequisites

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.

Creating a new analysis project

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.

Setting up an existing analysis project

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.

Building your analysis

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.

Executing your analysis

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.

Setting breakpoints

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.

Navigation between the different views

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 ViewTarget Java SourceJimple View
Jimple view	Unit Inspection view Target Java SourceGraph view
Unit Inspection view	Graph viewJimple view
Target Java Source	Graph viewJimple view

Navigation in graph 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.

Changing the call graph to CHA or SPARK

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.

Zooming the graph

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.

Panning 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.

Searching the graph

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.