CheckDep User Manual

Version 1.0.0

Introduction

The objective of CheckDep is to provide feedback on the consequences of code changes
in terms of dependencies. A software developer can use CheckDep to inspect introduced
and removed dependencies before committing new versions, and other developers receive
summaries of the changed dependencies via e-mail. CheckDep's visualization enables the
tool to help navigating large dependency graphs, and allows the user to explore a
"meaningful" layout in which related artifacts are displayed closely together.


Installation Instructions

  1. Install Java 1.6 SDK or higher.
       http://java.sun.com/
  2. Install Eclipse 3.3 or higher.
       http://www.eclipse.org/
  3. Download the relevant CheckDep plugin (jar) file according to your operating system
    and copy the downloaded jar file into the "plugins" folder of your Eclipse copy.
  4. Run the Eclipse application, and find the "Show View" item within the
    "Window" menu in the main menu bar.
  5. Select "Other..." option from the "Show View" menu choices.
  6. Select "CheckDep View" under "CheckDep Category" and press ok.
  7. The "CheckDep" view appears in the IDE. Maximize the view to make all of
    its features visible.

Using CheckDep

    The CheckDep view consists of three tab folders dividing the view to three different
    sections: Input Tab, Display Tab and the Log Tab

    Input Tab    

        This tab folder is responsible for collecting information from the user. It is divided into
        four different sections, namely First Revision, Second Revision, General Settings and
        Dependency Log.

        First Revision and Second Revision sections contain the first project and second project
        information entries respectively. They could denote two different revisions of the same
        project, or two unrelated ones. The first section is meant to point to an old version of a
        java project and the second section reflects the newer version of the same project, but
        this is simply a convention assumed by the software in general, not a strict rule.

      Workspace. The software can access local projects or those hosted by a
       Subversion repository. Either way, user should provide a local address in the "workspace"
       field, where the local copy resides or the project files are to be checked out. By leaving
       the workspace field blank, CheckDep can be used as a regular fact extractor and only
       extracts the dependency structure of the other project section without performing a
       dependency comparison (because only one project is provided by the user).

       SVN URL. By checking/unchecking the checkbox in front of this field, the user
       specifies that the project files are accessible locally/remotely (through Subversion
       check-out).

       Password. Use this field to enter the password required to authenticate the
        provided Subversion URL.

       Explore Button. Use this button to get a list of the available revisions and the relative
       information such as the revisions' authors, commited dates and etc. for a given Subversion
       URL. The list can be explored using the combo box located in front of the "Target Revision"
       label.
       The explore button also fetches the revision number of a local working copy specified by
       the workspace field and shows it on the field located in front of the "Current Revision" label.
       If the working copy is not a valid Subversion folder, the term "exported" will be shown
       instead.
      
       Update Button. Press this button to check out the target revision indicated by the
       related combo box from the given URL in the specified workspace. If the address specified
       by the workspace is a valid Subversion working copy then an "svn update" takes place to
       update the working copy to the selected target revision.

       Compile Button. CheckDep uses a fact extractor that is based on
       Dependency Finder to retrieve relations between methods and fields. Dependency Finder
       operates on compiled java files, and thus CheckDep also requires compiled classes as
       input. Because in most cases compiled classes are not kept in the repository, CheckDep
       attempts to compile the checked-out source files by itself. The "Compile Button" can be used
       to compile the source files in the workspace, and to generate a complete set of compile result
       messages reported on the "Log Tab". The compiler uses the relative source path specified in
       the text box in front of the "Source Folder" label to confine its search for the java source files
       to the path which is a combination of the workspace and the relative source path.

       Classpath. If a project requires certain libraries to be compiled, then the user can specify the
       local paths where those library files exist in the "Classpath" field. If there are multiple
       classpaths, the user must separate them with a semicolon (';') within the Classpath field.

       Force Compile Checkbox. If the compile folder where the auto-generated compiled files
       reside already exists, then CheckDep does not re-compile the project source files unless this
       checkbox is checked, in which case the compile folder and all of its contents will be
       overwritten and the compilation will be done from scratch.
      
       Same Checkbox. This check box exists only in the "Second Revision" section. When it is
       checked, it signals to the application that the repository information (the URL, password, etc.
       should be imported from the "First Revision" section, meaning that both section use the same
       repository.

   GENERAL SETTINGS

        Dependency Type. User can specify the type of the dependency graph and the level at which
        the result will be displayed by choosing one of the available options in this section. If the user
        chooses "All", then a comprehensive graph containing all kind of dependencies will be generated.

        Exclude "java.*" Checkbox. Check this box to ignore the java classes and methods
        contained in java standard libraries when evaluating the dependencies. All those elements whose
        fully qualified name start with the prefix "java." ―such as "java.lang.Object", "java.util.List" and
        "java.util.List.add(Object o)"― will be excluded from the result.

        Extract Button. By pressing this button the application attempts to compile the existing source
        files in both workspaces (without reporting the compilation results to the "Log Tab"), and then
        extract software dependencies of both projects. After the extraction and possibly comparison
        jobs are finished, statistical information will be displayed in the "Dependency Log" section. If the
        user decides to change the dependency graph type, he/she can do so without pressing the
        extract button again. Then by pressing the "Get Status" button in the "Dependency Log" section
        located at the bottom of the "General Settings", the dependency log will be updated to show the
        result for the new settings.

        Visualize Button. Pressing this button causes the application to switch to the "Display Tab",
        where it present the result generated by pressing the "extract button" visually. A dialog box will
        pop up, allowing the control of the visual layout preferences. The user can change the the
        dependency graph type without pressing the extract button again. If the "visualize button" is
        pressed more than once without pressing the "extract button" in between, its label changes into
        "Re-visualize" stressing the fact that the extracted dependencies are untouched, and probably
        only the dependency settings have changed.

        Name Includes Textbox. This text field is used to filter the software artifacts and dependecies
        which are to be reflected in the grahpical and textual results. If this textbox is left blank, no filter
        will be applied. The user can enter multiple strings separated by semicolons (';'), each
        representing the "complete" name of a package, class or method which is to be included in the
        result. In order for a dependency (edge) to be included in the result, it is required that at least
        one of its incident vertices (i.e. software artifacts) be a method or belong to a class or a package
        whose name is specified in the filter text.

        RSF Output Folder. Specifies the physical address at which the textual result (RSF file) should
        be saved.

    Display Tab

        This tab contains the display window, where the graphicall result is shown. The vertices are
        drawn as circles that could be different in radius size, representing software artifacts (classes,
        methods, etc.). Edges are drawn as the directed lines connecting the circles and represent the
        dependencies. The label of each vertex denotes the name of the software artifact represnted by
        the vertex, and the label of an edge indicates the type of the dependency[ies] that edge
        represents.
        Grey colored vertices and black edges respectively represent the artifacts and the dependencies
        that are common in both projects (untouched). Red vertices and edges respectively stand for
        those artifacts and dependencies that are present in the second project, but do not exist in the
        first one. The blue vertices and edges respectively represent those artifacts and dependencies that
        exist in the first project, but not the second one. So if the first project is an early revision of a
        project and the second one is an older revision of the same project, red color means "added" and
        blue means "removed" and the grey (or black) stands for "common" or "untouched".

    Log Tab