Oovaide User Guide

Created: June 8, 2009 Last update: Nov 18, 2015

Contents
Quick Start
Oovaide
Build System
OovEdit

Quick Start

To work with the examples, see examples.

Use File/New and create a new Oovaide project using an existing or new C++ project. There are example source projects in trunk/examples.

select a new directory for source files, or an existing directory that is the root directory of existing source files.
select an output project directory to store oov project files.

OR: Use File/Open and open the trunk/test/trunk-oovaide-win or trunk/test/trunk-oovaide-linux directory.
At this point, it may be possible to view diagrams if the include paths are set. They are already set if the oovaide project was opened. Select Analysis/Settings and select the C++ Settings tab to change the include paths and compile and link settings. Note that the include and library paths can both be set using the External Project Packages button, or recursive searches using "-ER". See the Build System section for more information.
Build a project. These steps are not required for viewing diagrams. Building Oovaide requires CLang and GTK to be downloaded and to match the paths in the Analysis/Settings/C++ Settings.

Select Build/Settings and set the component type for each component. For the Oovaide project, the oovCommon and oovGuiCommon components are static libraries, and all other oov... components are executables.
Select Build/Build Debug to build a debug version of the project.

Oovaide

The Oovaide program performs many types of analysis on a selected set of source code. Setting up a new project requires selecting the root directory that contains the source code. Then Oovaide scans the directories for include and source files. There are many types of diagrams to allow viewing different levels of code.

View	Diagram Type Name	Description
Many Classes	Zone	Zone diagrams show all classes in a project and their relations. Each class can be shown as a dot so that thousands of classes can be viewed on a single diagram. Filtering can be applied to view smaller subsets of classes.
Directories	Component	Component diagrams show the relations between components. Examples of components are libraries or executables. Component diagrams requires that certain directories have a component type defined for them.
Few Classes	Class	Class diagrams show a few classes since the interface of each class is displayed.
Class Parts	Portion	Portion diagrams show member data, and relations between functions and the member data.
Class Methods	Sequence or Operation	Sequence diagrams show conditionals (if or loop constructs) and calls to other class methods.
Include Files	Include	Include dependency diagrams show which include files are used by other include files.

The Oovaide program also allows collecting analysis information from a project.

Analysis Tool	Description
Code Coverage	This displays how often each block of code was executed, and the percentage of code executed in each module.
Code Complexity	This displays both McCabe and Oovaide complexity.
Duplicate Code	All code is compared to find the number of lines that are similar to other places in the code.
Project Statistics	This displays the number of files, classes, operations, etc.
Line Counting	The number of code lines and comment lines are counted for each module.
Member Usage	The usage of each class member is displayed.

Setting Up C++ Analysis Projects

Anlyzing projects allows viewing zone, class and sequence diagrams. It is also the first step towards building projects and running code coverage.

Start the "oovaide" program
Use File/New to create a new project
The Project Settings dialog will appear that allows choosing the source root of the source files to analyze. The location can be specified for saving all of the project files for Oovaide. Files can be excluded from analysis. This can also be changed later.
Select the Analysis/Settings menu item. Choose the "C++ Settings" tab to change the include paths and other compiler settings. Errors during compilation are stored in the project directory. If there are errors, change the compiler settings and restart analysis.See the Build section for more examples.

To open a previously saved project, select File/Open and specify the previously saved Oovaide project directory. The build user guide is at Oovaide Build Help

Setting Up Java Analysis Projects

A JDK must be installed. The JAVA_HOME environment variable must point to the JDK root. For example, JAVA_HOME="C:\Program Files\Java\jdk1.8.0_51".

To analyze java source code, follow the steps for analyzing C++, but don't set up any analysis settings.

Some current limitations are:

Analysis limitations:

Missing constructors in diagrams.
Classes with the same name in Java and C++ are combined except when within a package.
Template class relations are not all displayed.
Method variable references are duplicated for parameters. (Affects complexity)
Line statistics are not supported
No duplicate code detection

Only analysis is performed. A build will be performed.
No editor highlighting or debugging.
Code coverage is not supported

Component Diagrams

Component diagrams are similar to UML (Unified Modelling Language) component diagrams. A component diagram displays components such as static or shared libraries and executables. When the Comp tab is clicked, the component diagram for a project is generated automatically.

Any component that has the Component Type defined in the Build Settings dialog will be displayed. In addition, the components that are defined in the Analysis/Settings C++ Settings dialog using the External Project Packages will be displayed. The analysis will figure out the dependencies and the dependency arrows will also be generated automatically.

The components for a project are displayed in the left pane in the "Comp" tab. The components list is a list of the source files for the project.
After the Component Types have been specified in the Build/Settings dialog, and the analysis has been run, then clicking on any component in the components list will update the diagram and show the dependencies between the run-time components.
The components can be moved by clicking and dragging the components.
Right clicking on a component allows:

Remove Component - Removes the component from the diagram
Show Implicit Relations - Shows relations between all components
Relayout - Repositions the components
Restart - Adds all removed components.

Zone Diagrams

A zone diagram displays all classes in the project in a circle diagram where all classes are layed out on the circumference of the circle. Any two classes that are related will have a line drawn between them.

The zone diagram component (directory) list/tree allows selecting which components are displayed on the diagram.
Right clicking on the component list allows:

Hide All, Show All - Hiding or showing all components
Hide Children, Show Children - Hiding or showing all components that are children of the selected component
Map Path - This allows combining directories into a single directory for the graph. For example, mapping /usr/include to /inc-lib and /usr/lib to /inc-lib, will combine both directories into one component in the graph. Child components with unique names are listed separately.

Right clicking on the graph allows:

Go To Class - Displays the class diagram for the selected class
View Source - Displays the source code for the selected class
Show All Classes - Showing all classes or just showing components
Show Function Relations - Shows classes as related if a class has a member function that uses another class.
Show Dependencies - Displays an arrow at the end of a relationship. The arrow end is the end that is the supplier and the non-arrow end is the consumer.
Zoom In/Out - Zoom the diagram

For more zone diagram information, see Zone Diagrams.

Class Diagrams

Class diagrams are similar to UML (Unified Modelling Language) class diagrams. They display the members of the classes and relations between classes.

The classes for a project are displayed in the left pane in the Class tab. Left click on a class to display a diagram of related classes with standard relations.
Right clicking on a class in the class list will display a popup menu that adds the selected class with standard relations. Adding a single class will not relayout the diagram.
Left click on a class in the diagram and drag the cursor to the desired location to move a class.

Right clicking on a class in the diagram allows

Go To Class - Shows the class diagram for the selected class
View Source - Views the source code
Preferences - Alter amount of data shown for the selected class
Add Selected - Adds the selected classes to the diagram with or without relayout
Add Standard Relations - Adds classes that have relations where the classes are related either through aggregation or inheritance
Add All Relations - Adds classes that have standard relations plus relations where member functions are related to the other classes
Zoom - Zooms the diagram
Removing class - Removes the selected class
Remove All Classes - Removes all classes
Restart - Adds the classes with standard relations

Class Diagram Symbols

So what are circles and V shapes doing on the drawings? Don't worry, they can be turned off if desired. These extra Oov symbols are used to provide quick visibility into other relations that are not displayed on standard UML diagrams. The goal is to find and show as many relationships as possible on the diagram for quick understandability and verification of the code.

(See the screenshots to see examples.) The enhanced symbols are:

the nested circles indicate the private, public, protected scope relations. Fully empty means public, and fully filled means private, otherwise it is protected.
the V shape indicates read only (const)
the circle standing alone means a relationship with a function variable
a small circle next to a circle is a function parameter relationship.

The other symbols are standard UML symbols.

Class Diagram Display Options

Select the Analysis/Settings menu item.
Choose the "Draw Options" tab and check or uncheck the various options. These options do not change how classes are added to the diagrams.

Portion Diagrams

Portion diagrams show the data members of a class, and show the operations that are related to each data member. These diagrams make it easy to visualize a class's composition to allow for refactoring or for understandability.

For more portion diagram information, see Portion Diagrams.

Sequence Diagrams

Sequence or operation diagrams are similar to UML (Unified Modelling Language) sequence diagrams. They display the member functions of the classes, and some detail of the members and relations to members in other classes.

Sequence diagrams are only slightly modified from standard UML diagrams. The guard conditions are not shown on each arrow, but are instead shown on the lifeline blocks. This prevents duplication of the condition for each operation call, and is still very easy to read for someone that is used to UML.

Selecting a class in the class list will change the operations in the Operations (Oper tab) list. Clicking on an operation will display the sequence diagram for the operation.
Selecting an operation from the operation list will display the contents of the operation.
Right clicking on the sequence diagram depends on whether a class or operation is clicked on. Right clicking allows:

Go To Operation - Displays a new diagram for the different operation.
Add Calls - Expands the selected call to show the child calls
Add Callers - Shows the operations that call the selected operation.

Include Diagrams

Include diagrams show the relationships between the include files.

Editing SVG diagrams

Use File/Export Drawing As to save an SVG file. An SVG file is a vector graph that most web browsers can display. Whichever drawing is displayed will be saved.
Download Inkscape from inkscape.org

When using File/Export Drawing As, the file's default location will be to save to the project directory.

Complexity Analysis

Code complexity is a measure of complexity for each function. The purpose of the measure is to help to determine the amount of testing required for various functions. Higher numbers indicate that more testing must be performed.

After the analysis has been performed, select Analysis/Complexity to update the complexity information for each source file.

For more complexity information, see C++ Complexity.

Member Usage Analysis

After the analysis has been performed, select Analysis/Member Usage to save usage information about members. This shows the number of member functions of a class that use each class member attribute.

Duplicate Code Analysis

Turn on duplicate code analysis by adding -dups to the Analysis/Settings/C++ Settings/Analyze/Extra Build Arguments
Delete any existing analysis directories in the Oovaide project using the clean menu item so that a complete analysis is run.
Run Analysis/Analyze
Run Analysis/Duplicates

For more information, see Duplicate Code.

Code Test Coverage System

Running Coverage/Instrument will create an "oov-cov" directory that contains a copy of all source files and modifies them so that they include coverage counting software. It copies the oovaide build files so if the project was built previously, the new project files will automatically build the coverage project when the Coverage/Build menu is run.
Running Coverage/Build will build the coverage project.
Running the coverage project components will update coverage counts.
Running Coverage/Statistics will output a coverage percentage file.

For more coverage information, see Test Coverage.

Build System

The build system is not required to view diagrams.

There must be a set of installed build tools such as clang or GNU. The oovBuilder manages the project source, and is an executable that can be run from the command line. It can be run from the build menu in the oovaide program.

Build Features

Provides a very simple setup for building projects
Eliminates reasons for "clean". Rarely any out of date dependencies
Source directories are not cluttered up with build files.
Fast builds using multitasking. Multitasking is used to analyze and build multiple object, library, executables files
Component names are derived from the directory names of directories that contain C++ source files.
Directories are scanned to find header files, and generate include paths.
Directories are scanned to find libraries, and library symbols are parsed to determine library link order, and to determine which static libraries are required for executables and shared libraries.
Source files are parsed using CLang to find include dependencies. Include dependencies are used to determine which files need to be built. Rebuilding will only compile files that need to be rebuilt based on dependencies.
External packages can be specified by selecting the package, or the root path of external projects can be specified for locations of header and library files. On Linux, the pkg-config system is used to find available packages. Exclusion criteria can be used to select only one of many types of library or header files.
Build tools are determined from paths and installed tools, but can be specified manually.
Project information is scanned and stored for different sets of build arguments. Debug and release configurations will not conflict.

Build Quick Start

The examples are a quick way to understand some basic principles. See Examples.
The build user guide is at Oovaide Build Help
The build details are described in Oovaide Build Design.
Note that the Oovaide binary packages do not include a compiler for building.

The following steps can be followed:

Run Oovaide and either create a new project, or open an existing project. Either the gnu or clang compilers should be installed in the system. In Windows, Oovaide searches the path and if LLVM is present, then clang++ is used as the compiler. In Linux, the clang++ compiler is searched for in the /usr/bin directory, and if found clang++ is used as the compiler.
Add some references to external project packages. These are specified under Analysis/Settings/C++ Settings.

Use the External Project Packages button to specify a package on the system. In Linux, this uses pkg-confg, and will define all includes, flags and libraries. In Windows, there are a few predefined packages that are defined in a file in the bin directory.
If the required external packages do not exist, either custom packages can be created, or add some external project root references.
An external directory can be specified, and may look like "-ERC:\ExternalPackage". The full syntax allows excluding some subdirectories using an exclamation point as a not symbol. This is required for cases where external project references contain multiple libraries with the same symbols. For example, "-ER/home/dave/software/oovaide/2.0/clang+llvm-3.2!libclang_rt" will prevent using any path with libclang_rt in it.

Select Build/Settings and specify what type of output to produce for each component listed in the dialog. If the needed components are not listed, then Oovaide will not build your type of project. Either rearrange the directory structure, or contact the Oovaide developers.
Run Build/Build Debug or Build/Build Release.

The trunk/test/trunk-oovaide directorys show example files for building the oovaide project. This is a somewhat complex project since it uses both Gtk and Clang, and has multiple libraries and executables. Early versions of CLang on Windows required building CLang, and the complex library order for Clang was able to be determined by the build system.

Cross Compiling

The following example shows the use of Ubuntu for cross compiling to an ARM hard float platform. This requires that the gcc-arm-linux-gnueabihf package is installed using apt-get or synaptic:

Select Analysis/Settings
Select Debug under Build Configurations, and click the NewConfig button. Enter "Arm-Debug" as a new configuration.
Enter arm-linux-gnueabihf-g++ for the Compiler Path
Add to the Common Build Arguments:

-fPIC
-march=armv7-a
-mfloat-abi=hard

Add something like the fillowing to the Extra Build Arguments for the Arm-Debug configuration:

-lnk-L/target-sysroot/arm-linux-gnueabihf/usr/lib
-lnk-L/target-sysroot/arm-linux-gnueabihf/lib
-lnk-Wl,-rpath-link,/target-sysroot/arm-linux-gnueabihf/usr/lib
-lnk-Wl,-rpath-link,/target-sysroot/arm-linux-gnueabihf/lib

When compiling, the linker may say, "cannot find", and then list some library name. If the target files were copied from the device, the links may contain paths to the directories for the target machine. This files can be edited and the paths removed so that the local files are found.If shared libraries are created, there may be some cases where a static library can be hidden by being renamed to force the shared library to be used.

Resolving Include Problems During Analysis

The Oovaide analysis will often produce usable output even when include files cannot be found, although this may result in missing classes, or methods in sequence diagrams.

Oovaide uses the OovCppParser to perform the analysis, and the OovCppParser uses CLang. Clang has hard coded paths compiled into the analysis binary. Compilers will only search for a certain set of include paths. See the include problems below for more information.

Oovaide produces analysis directories for each set of build arguments. This is in case the classes may be different for debug or release, etc.

The analysis directories are not kept unique for the clang and GCC compilers. Build argument differences are used to make unique analysis directories. If they are using the same directory, and different include paths are needed, set an argument that is different so that different analysis directories are used.

Windows Include Problems

Things can be difficult especially on Windows since Oovaide by default uses CLang for analysis, and can use either CLang or the gnu compiler for builds. The gnu compiler is available from the MinGW, MinGW-builds or MinGW-W64 projects. The old MinGW-builds project has now been incorporated into MinGW-W64. MinGW-builds or MinGW-W64 is required to build Oovaide instead of mingw because it supports C++11 threading.

The gnu compiler will normally find include and library paths since the compiler searches paths relative to the g++ directory. The CLang compiler will find many mingw paths, but does not find paths for Mingw-W64.

Switching between the packages often requires nothing more than changing the path environment variable or setting the compiler name in the Oovaide Analysis/Settings/C++ Settings dialog.

CLang normally finds mingw by searching for default paths, but does not find mingw-w64. For this reason, mingw-w64 is defined as a package that can be included in the Analysis/Settings/ menu in the C++ Settings tab using the External Project Packages button.

So there are a few usage scenarios:

Perform Analysis with Oovaide using Mingw - Typically CLang will require include files to be in \MinGW
Perform Analysis with Oovaide using Mingw-W64 or Build Oovaide - Use MinGW-W64 by selecting the package in the project and ensuring the path is correct

If the compiler cannot find a standard library file, then it isn't finding the file in its include directories. To view the CLang or GCC compiler include paths, use the -v option in the Oovaide Analysis/Settings/C++ Settings.

The typical location for mingw is in the \MinGW directory. CLang supports the following MinGW installations on Windows.

CLang Version	MinGW Versions Supported
CLang 3.4	4.5.0, 4.5.1, 4.5.2, 4.5.4, 4.6.0, 4.6.1, 4.6.2, 4.6.3, 4.7.0, 4.8.1
CLang 3.5	4.7.0, 4.7.1, 4.7.2, 4.7.3, 4.8.0, 4.8.1, 4.8.2

Linux Example

This is an old Linux example. The best method currently is to load the required packages in the Analysis/Settings/C++ Settings tab.
For Linux, the following arguments work to build all Oovaide components with the CLang compiler. These arguments will build the complete oovaide project on Linux when the component types are set in the components tab. This is how the arguments may look in the Analysis/Settings/C++ Settings dialog.

	-c
	-std=c++0x
	-ER/usr/include/gtk-3.0
	-ER/usr/include/glib-2.0
	-I/usr/include/c++
	-ER/usr/include/cairo
	-ER/usr/include/pango-1.0
	-ER/usr/lib/x86_64-linux-gnu/glib-2.0
	-ER/usr/include/gdk-pixbuf-2.0
	-ER/usr/include/atk-1.0
	-ER/usr/lib/x86_64-linux-gnu!libmcheck!libieee
	-ER/home/dave/software/oovaide/2.0/clang+llvm-3.2!libclang_rt
	-lnk-static-libstdc++
	-lnk-Wl,-rpath=./
	-lnk-rdynamic

Windows MFC Example

This example may compile with errors, but allows much of the analysis to occur correctly. Note that _M_IX86 cannot be used with the CLang compiler since it does not handle inline assembly. Much of the analysis still works even though the target is incorrect.

Base Build Arguments

-c
-x
c++
-fms-extensions
-fmsc-version=1500
-ferror-limit=3000
-D_M_IA64=1
-D_WIN32_WINNT=0x0501
-D_MSC_VER=1200
-D"WIN32"=1
-D="_WINDOWS"
-D_ALLOCA_S_MARKER_SIZE=8
-IC:\Program Files\Microsoft Visual Studio 9.0\VC\include
-IC:\Program Files\Microsoft Visual Studio 9.0\VC\atlmfc\include
-IC:\Program Files\Microsoft SDKs\Windows\v6.0A\include

Windows GTK Example

This is an old Windows example. The best method currently is to load the required packages in the Analysis/Settings/C++ Settings tab. For Windows, the following arguments work to build all Oovaide components with the g++ compiler.

Base Build Arguments

-c
-ERC:/Program Files/GTK+-Bundle-3.6.4
    -IC:/Program Files/LLVM/include
-lnk-LC:/Program Files/LLVM/lib
    -lnk-lpthread
-lnk-lpsapi
-lnk-limagehlp
-lnk-mwindows
-lnk-llibclang

Extra Analysis Arguments

-x
c++
-std=c++11

Extra Debug Arguments

-O0
-g3
-std=c++0x

Extra Release Arguments

-O3
-g3
-std=c++0x

For Windows, the arguments may look something like this when compiling with clang++ 3.2. The only problem is that clang 3.2 does not export symbols in the object files, so the link with GTK fails.

	-c
	-std=c++0x
	-ERC:\Program Files\GTK+-Bundle-3.6.1
	-ERC:\Dave\Mine\software\oovaide\clang+llvm-3.2

Build Sequence

The detailed sequence of the build is:

The user specifies the source root directory and output oovaide project directory. The build system scans the source root directory for include and source files. Each directory with source files is considered a component. Each directory with include files is added to the initial include paths.
The program tries to determine the compiler and other build tools.
- On Windows, the path is searched for clang, otherwise the build tools default to the GNU tools. (g++, ar, etc.) The llvm-ar tool is not used on Windows since it does not work.
- On Linux, the path is checked for /usr/bin/clang++, and if not present, the build tools default to the GNU tools.
- Manually edit oovaide.txt to change build tools.
The user specifies additional external project packages or package roots for includes and libraries. If include files are found, the paths are added to the initial include paths. If libraries are found, the paths are added to the initial library paths. The user must specify the project packages in the correct order. Include paths are scanned in the order that packages and external references are specified. During the link, the libraries are scanned in opposite order. Project package order is determined by the builder.
The program parses the source files for include dependencies using the initial include paths. The include dependencies are optimized so only needed include paths are used to detect dependencies for each component.
The program generates a list of components that could be built.
The user specifies the type of component such as static library, shared library or program.
The user can start a build.
The dependencies of external project libraries are determined to create libraries in the correct order for the linker. The external project libraries are used in the opposite order that the external project roots were specified. The library dependencies are optimizes so only needed libraries are used for each component.
Only out of date targets are built.

Project Limitations

There are some limitations on projects. The basic rule is that a directory can be defined as a component and all source files that are contained in that directory or other child directories of that directory will be used to build the component. The include files can be in any child directory, and will be found automatically.

If multiple directories are used to build a component that are not under one directory, it is possible to create many static libraries. Oovaide will determine static library link order automatically.

The following directory structure will be used to describe projects that can be supported.

Some of the rules are:

A component at any level of the tree will be built using all source files in all subdirectories that are not defined as a component. In this diagram, the top nodes ("Dir Root", "Dir A", and "Dir B-2") are defined as components.
The groupings do not determine where header files can be found. They only determine which source files are compiled into the component. Header files can be anywhere and will be automatically found during analysis.
Component "Dir A" could be a library, which will be linked into other components automatically.

If "Dir A" is defined as a component type other than Undefined, then it will use all source in "Dir A" and its children to build the component. OovAide searches down the tree until it finds a component, and then does not include anything under the directory that is defined as a component. Some examples are listed here:

"Dir A", "Dir B-2", and "Dir Root" could all be defined as executable programs.
"Dir A" could be a static library, "Dir B-2" could be defined as a dynamic library, and "Dir Root" could be defined as an executable program. The executable program and dynamic library would link in "Dir A" if needed. It will also link in external project libraries if any were defined.
"Dir A" and "Dir B-2" could be defined as static libraries, and "Dir Root" could be defined as an executable program. The executable program would link in the libraries that are needed in the correct order.

There are also these limitations.

Only GNU, clang C++ or Java projects. CLang support for MSVC projects is improving, but unknown.
Analysis is performed for one set of compiler switches for all files int a project. Different sets can be used for debug/release. External packages will cause other switches to be added.
Building Java programs does not order the building of jars.
External project roots are expected that they will not be changed. In order to update library information, delete the OovAide output files using the clean menu item.
The component names will be created from the directory names.
Some duplicate filenames (includes) may cause problems for determining dependencies. Circular dependencies may cause problems. These may be able to be resolved:
- View oovaide-incdep.txt to see include directory dependencies found by compiler
Only C++ or Java is compiled. (No .C or .ASM) Other types of files can be included by building them externally and using external objects or libraries.

There are some problems using llvm/clang 3.2 on Windows or Linux. The build tool will attempt to use tools that are known to work. CLang 3.4 may not have these problems.

Symbols are not exported. This appears to be a compile time (clang++) problem.
The llvm-ar tool will cause a link error
The llvm-nm tool has no output on Linux, and gives a bad file error on Windows.

OovEdit

The OovEdit program is a simple text editor. It has the following features.

C++ syntax highlighting using CLang
Code completion using CLang
Debugging using GDB
Find/Replace
Find in files
Undo/Redo
Copy/Paste
Find forward or reverse, and case sensitive or insensitive

Contents