Getting started with Klocwork Architect

From Insight-9.2

Contents

To analyze and redesign your software system architecture, you need to install the Architect component of the Klocwork User package. If you have not done so, see Installing Klocwork Insight and Insight Pro.

What is Klocwork Architect?

Klocwork Architect extracts an accurate graphical view of the design of your software directly from your existing source code (C, C++ and Java). This graphical view, called the System Model, provides a comprehensive understanding of your application’s structure and design, allowing you to assess interfaces, relationships, and logic flow.

How architecture analysis works

Architect mines data from your software system’s source files. Architect extracts the following types of data from your software system:

  • entities in the software system, including directories, files, classes, methods, functions, variables, and so on
  • relationships between software entities (for example, method or function calls, operating system calls, usages of global variables, and usage of types)

Architect then uses this information to display the entities and relationships. The graphical views show you:

  • the system's containment structure, including packaging and directories, as well as methods, functions and variables
  • relationships between entities at all levels within the system
  • models of your software system, allowing you to redesign your software system architecture. Architect recalculates all relationships based on the new model, so that you can immediately see the impact of your changes. Changes are made only to the model within the Architect client, not to your source code.
  • custom diagrams that can represent selected pieces of your system architecture as if they were at the same level. Changes are made only to the custom diagram within the Architect client, not to your source code.
  • flowcharts of the source code associated with a file, function, class or method within the system
  • your software source code

Starting Klocwork Architect

To start Architect:

  1. Do one of the following:
    • On Windows, double-click the Architect icon on your desktop or, from the Start menu, choose Programs > Klocwork > Klocwork Architect.
    • On Mac, choose Applications > Klocwork User 9.2 > kwinsight.
    • On Unix, run:
    kwinsight
    Note: If you see a dialog requesting you to log in, enter the credentials provided by your Klocwork administrator, or your LDAP or NIS user name and password.
    If you're starting Architect for the first time, or if the server you last accessed is unavailable, the Connect dialog appears.
  2. Enter the host name (or IP address) and port number of the Klocwork Server, or leave the default entries (localhost and 8080) if they are correct.
  3. Enable the Use secure Klocwork Server connection checkbox if a secure connection to the Klocwork Server has been set up.
  4. Click Connect.
    Troubleshooting
    Cannot connect to Klocwork Server at <host and port>.
    If you see the preceding error message, check with the IT team that the host and port number of the Klocwork Server are correct, and that the Klocwork Server is running. See Starting the Klocwork Servers for more information.
    A list of available integration projects is displayed. Note that only integration projects can be opened with Architect; you cannot open desktop projects.
    Architect projects dialog.png
    Note: If no projects appear in the list, it may be because no integration projects have been created on the Klocwork Server.
    Troubleshooting
    Cannot connect to Klocwork Server at <host and port>.
    If the preceding error message is displayed, contact your Klocwork administrator to validate the current host and port number. If they are correct, ask your Klocwork administrator to verify that the Klocwork servers are running.
  5. Expand a project to see the list of successfully completed analyses (builds) for that project.
  6. Click a build to select it, and click OK.
    Tip: If you select Remember my choice before clicking OK, this build will automatically be opened the next time you start Architect. If this build or project has been deleted, the Projects dialog will appear.
    The Architect main window appears.
    Architect initial screen.png
    The Tree view is populated with the System model of the project you selected, models you’ve created, and models that other Architect users have shared.
    Note: Once you have chosen a build from the projects list, the build name appears at the top of the Tree view to remind you that all views of the information belong to that build.

Viewing and creating models

By default, Architect creates the System model, which shows you the existing physical design of your system along with the relationships and interfaces between entities in the system. Exploring the System model can help you understand how your software system is organized.

Explore the System model by expanding it and double-clicking any entity. You can also double-click any entity in the right pane to go down a level in the hierarchy.

Architect system model.jpg

You can also create your own models, which allow you to experiment with the design of your system. Architect automatically recalculates the relationships between entities, allowing you to immediately see the impact of your changes.

Models are automatically propagated when the project on which they are based is reanalyzed.

Create a new model based on the System model by right-clicking the System model in the Tree view and clicking New.

Architect new model crop.jpg

How Klocwork Architect solves common software architecture problems

The following sections describe Architect solutions to common software architecture problems. Whether you are a software system architect, development manager, or software developer tasked with system maintenance, feature enhancement or new development, Architect can provide both the big picture and the low-level detailed information you need to do your work.

Assessing and improving the quality of your software system design

The physical design of your software system may bear little relationship to the high-level logical design. Architect helps you assess the quality of your physical software system and reestablish the desired logical design on the system.

Architect can help you:

  1. Understand the physical design of your software system by:
    • using the default System model to navigate through the system hierarchy and explore its containment structure. You can view the structure down to the level of functions and data members.
    • viewing interfaces to reveal a component’s dependencies on other components as well as which other components use that component. While viewing relationships in the Graphic view, right-click on the line between two entities.
    • viewing relationships between entities and the environment. By default, when you display relationships in the Graphic view, Architect displays relationships to the environment--that is, relationships to entities at levels of the hierarchy outside the Graphic view.
    • viewing the details of a function in a Flowchart. To view a flowchart, right-click an entity in the Project Tree view or Graphic view, and click Show > Show Flowchart.
  2. Uncover inconsistencies between the current implementation and the original design intent by:
    • finding cyclical dependencies between files, or clusters. Tight coupling in clusters creates problems with maintainability, testing, and separation of components for reuse. Open a Graphic view of a model and click Tools > Find Clusters.
    • discovering inappropriate relationships and dependencies.
    • finding errors duplicated in different levels of the software hierarchy.
  3. Recover the logical design, using the Architect modeling capabilities, by:
    • creating a model so that you can begin making changes to the architecture. Modeling changes are made only to the model within the Architect client, not to your source code. Right-click the System model in the Tree view and click New.
    • moving entities in order to correct improper relationships and dependencies between components.
    • grouping entities into logical components. For example, if files that belong together in a logical component reside in the same directory, you can simply group them. If the files reside in different directories, you can create a new architectural container to represent the logical component, and move the entities into this component. You can then check the component’s interfaces to ensure that there are no unwanted dependencies to or from the logical component. Select one or more entities on the same level of the hierarchy by Ctrl-clicking the entities, or by clicking and dragging the cursor over a region of the architecture diagram. Right-click and select Group.
    • finding and breaking cyclical dependencies, or clusters, in the code. Open a Graphic view of a model and click Tools > Find Clusters.
    • removing unused code.
    • using annotations to describe the logical design. Right-click any entity and click Show > Show Annotations, then click the Add Annotation button in the annotations toolbar: Architect add annotation button.jpg. Your team can also use Source Cross-Reference in Klocwork Review to view annotations.
  4. Publish the changes that are required to bring the current implementation in line with the design intent by:
    • creating an architecture report. You can use the report to share the new logical design with developers and the management team. Click a model in the Project Tree view and click Tools > Create report.
    • creating a list of differences between your new logical design and the physical system. Select a model in the Project Tree view and click Tools > Compare With. In the Generate Differences dialog, select the model that you want to compare and click OK.

These steps can be repeated many times over as you refine your physical system and continue to uncover issues that impact quality.

You can use Klocwork to prevent future erosion of your software system quality by:

  • generating reports in Klocwork Review and using them to understand your source code
  • integrating rules and thresholds into the development environment with Klocwork developer tools, to prevent issues from entering the build

Example: Discovering bypassed interfaces in C code

In C code, the proper way to access a module's functionality is through its interface, defined in the module's header file. Although C allows you to explicitly declare functionality in the module where you are using the functionality, the presence of declarations in the calling module results in hard-to-maintain code.

Architect helps you discover instances where the proper interface to an entity has been bypassed.

Architect allows you to detect these bypassed interfaces through the declared-by relationship. A declared-by relationship points from the definition to all reachable declarations. A declared-by relationship should always point from a C file to the corresponding .h file. When an interface has been bypassed, you will see declared-by relationships between modules.

By analyzing all declared-by relationships, you can easily find improper declarations.

To illustrate, consider the following C file and its corresponding header file:

File a.C

#include "a.h"

int x(int a){
return a+1;
}

File a.h

int x(int);

The following file properly accesses the functionality of file a.C through its interface file, a.h:

File b.C

#include "a.h"

void abc ( ){
int r;
r=x(5);
}

By contrast, the following file declares the functionality of the file a.C directly, bypassing the interface to a.C specified in file, a.h:

File d.C

int x(int);
void abc ( ){
int r;
r=x(5);
}

To find and correct bypassed interfaces in C code:

  1. Create a new model in Architect based on the System model. See Creating a model based on an existing model.
  2. Group each implementation file (.C) and its interface file (.h) into a module. Right-click the entities and select Group.
  3. Use the Relationship Profile Editor to turn off all relationships except the Declared by relationship type. See Managing how you view relationships.
  4. Examine the relationships between the modules. You should not see any declared by relationships between any of the modules.
    In our example, we found one improper declared by relationship:
    Architect module declared-by.jpg
    To view details on a relationship, right-click a relationship arrow and select a relationship direction from the Edge pop-up menu. See Displaying relationship details.
  5. If you do see declared by relationships between modules, you must correct them in the source code.
  6. When the interfaces have been corrected in the source code, your Klocwork administrator must re-analyze the project with the updated source files.
  7. The model you created in Step 1 will automatically be propagated to the next project build. Open the new build in Architect.
  8. Open the model you created in Step 1.
  9. View the declared by relationships between the modules. The changes you made to source code should ensure that there are now no declared by relationships between the modules in the model.

Isolating reusable components

Many software applications make use of parts of other applications. If you want to reuse a component, you need to minimize its dependencies on other parts of the software system. Architect can help you

  • ensure the component contains only entities that are related to the component’s functionality
  • remove unnecessary dependencies

To isolate a reusable component:

  1. Create a new model in the Architect client based on the System model.
    A Graphic view of the model is displayed.
  2. Using the Architect navigation capabilities, identify the entities that are part of the component.
  3. Organize these entities into a logical component. For example, if files that belong together in a logical component reside in the same directory, you can simply group them. If the files reside in different directories, you can create a new architectural container to represent the logical component, and move the entities into this component.
  4. Find and break any cyclical dependencies, or clusters, between your component and other components. If your component is part of a cluster, it is not reusable. To find clusters, open a Graphic view of a model and click Tools > Find Clusters.
  5. Check the component’s interfaces to ensure that there are no unwanted dependencies on the software system (since any application that uses these components will have the same dependencies). While viewing relationships in the Graphic view, right-click on the line between two entities. Dependencies on the environment are acceptable; they do not inhibit component reuse.
  6. Correct all unnecessary dependencies by editing the model.
  7. Publish the changes that are required to make the component reusable:
    • create an architecture report. You can use the report to share the new model with developers and the management team. Click a model in the Project Tree view and click Tools > Create report.
    • create a list of differences between your new model and the physical system. Select a model in the Project Tree view and click Tools > Compare With. In the Generate Differences dialog, select the model that you want to compare and click OK.
  8. Publish a list of the remaining interfaces of the component to help developers who will be reusing the components.

Porting to a new platform

Architect greatly reduces the challenges associated with the porting process. By extracting information directly from the source code, Architect provides you with an accurate understanding of the code and its design, enabling you to quickly determine the scope of your porting effort and the actions required.

When porting an application, you need to discover the application’s dependencies on the external environment.

To port to a new platform:

  1. Create a new model in the Architect client based on the System model.
  2. Look at the top-level architecture block in your system. It shows a single arrow indicating the number of dependencies on the external environment.
  3. Use the Relationship Viewer to display a detailed list of all of the relationships to the environment. Relationships to the environment are represented with a single arrow pointing to the top of the Graphic view. Right-click this arrow to view details for these relationships.
  4. Use the Interfaces icon Architect view interfaces icon.gif on the List view toolbar to display a list of only the unique interfaces. This reduces your list to a more manageable number of dependencies. Click the Relationships icon Architect view relationship details icon.gif to return to the default Relationships view.
  5. Analyze each of the dependencies in the list to determine which are portable to the new operating system API, and which are unique to the old operating system and must be ported.
  6. Create groups of entities to simplify the architecture and more clearly establish what must be ported. Select one or more entities on the same level of the hierarchy by Ctrl-clicking the entities, or by clicking and dragging the cursor over a region of the architecture diagram. Right-click and select Group.
  7. Use annotations to provide developers with the necessary porting instructions. Your annotations will also be visible in Klocwork Review’s Source Cross-Reference component. Right-click any entity and click Show > Show Annotations, then click the Add Annotation button in the annotations toolbar: Architect add annotation button.jpg.

You can use the same method to analyze couplings to third-party libraries. Examine the links between the core application and third-party libraries. If the new operating system requires different third-party libraries, this may affect what must be ported.

See also our blog post Porting gotchas.

Communicating the system architecture

Architect offers architects a variety of ways to communicate both the existing and the desired architecture to other individuals in your organization.

Sharing custom diagrams and models

You can share your Architect custom diagrams and models, so that other Architect users can view them. Right-click a model in the Project Tree view and click Share.

Annotations

You can annotate entities in any custom diagram or user model that you can see in the Architect client or Source Cross-Reference (even models that are read-only, like the System model and other users’ models). Annotations are also visible in the architecture reports.

Right-click any entity and click Show > Show Annotations, then click the Add Annotation button in the annotations toolbar: Architect add annotation button.jpg.

More about annotations

Communicating by means of the Web

Your team can view models and annotations in the Source Cross-Reference module of Klocwork Review. Source Cross-Reference allows users to view source code and examine the physical software system down to the lowest level of detail, in the context of a model created in the Architect client.

Architecture publishing

You can create detailed HTML and PDF reports on your existing system architecture or any of your remodeled architectures. You can create a graphical report on your entire software system, or a portion of it, in either HTML or PDF format. These reports provide complete details on relationships between entities in the system. You can create reports for any of the models available in the Project Tree view. You can further annotate the reports using an editor. The reports provide a high-level view of the system architecture to a wider audience.

Click a model in the Project Tree view and click Tools > Create report.

Model comparison

The model comparison tool allows users to compare architecture models. Users can generate a list of differences for two architecture models, or compare an architecture model with the generated System model of a software system. You can also compare two custom diagrams with each other.

Once you’ve edited a model, you can compare it with the System model or another model (including other users’ models). Architect will give you a list of the changes that must be carried out on the existing model to make it conform to the target model. You can use this list as a guide for what changes you need to make to the software to align it with the model.

Select a model in the Project Tree view and click Tools > Compare With. In the Generate Differences dialog, select the model that you want to compare and click OK.

What's next?

Now that you've tried your hand at software system redesign, you might want to check out other how-to's at Software system architecture redesign with Klocwork Architect.