Contents

1. Contents
2. Quick Start
3. Oovcde
   1. Setting Up Analysis Projects
   2. Component Diagrams
   3. Zone Diagrams
   4. Class Diagrams
      1. Class Diagram Symbols
      2. Class Diagram Display Options
   5. Portion Diagrams
   6. Sequence Diagrams
   7. Include Diagrams
   8. Editing SVG diagrams
   9. Complexity Analysis
   10. Member Usage Analysis
   11. Duplicate Code Analysis
   12. Code Test Coverage System
4. Build System
   1. Build Features
   2. Build Quick Start
   3. Cross Compiling
   4. Resolving Include Problems During Analysis
      1. Windows Include Problems
   5. Linux Example
   6. Windows MFC Example
   7. Windows GTK Example
   8. Build Sequence
   9. Project Limitations
5. OovEdit

Quick Start

1. Use File/New and create a new Oovcde project using an existing or new C++ project. There are example source projects in trunk/examples.
   
1. select a new directory for source files, or an existing directory that is the root directory of existing source files.
2. select an output project directory to store oov project files.
2. OR: Use File/Open and open the trunk/test/trunk-oovcde-win or trunk/test/trunk-oovcde-linux directory.
   
3. At this point, it may be possible to view diagrams if the include paths are set. They are already set if the oovcde project was opened. Select Analysis/Settings and select the Cpp Arguments 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.
   
4. Build a project. These steps are not required for viewing diagrams. Building Oovcde requires CLang and GTK to be downloaded and to match the paths in the Analysis/Settings/Cpp Arguments settings.
   
1. Select Build/Settings and set the component type for each component. For the Oovcde project, the oovCommon and oovGuiCommon components are static libraries, and all other oov... components are executables.
   
2. Select Build/Build Debug to build a debug version of the project.
   

Oovcde

The Oovcde 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 Oovcde scans the directories for include and source files.  There are many types of diagrams to allow viewing different levels of code.

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

Setting Up Analysis Projects

1. Start the "oovcde" program
2. Use File/New to create a new project
3. 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 Oovcde. Files can be excluded from analysis. This can also be changed later.
4. Select the Analysis/Settings menu item. Choose the "Cpp Arguments" 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.

Component Diagrams

1. 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.
2. 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.
3. The components can be moved by clicking and dragging the components.
4. Right clicking on a component allows:
1. Remove Component - Removes the component from the diagram
2. Show Implicit Relations - Shows relations between all components
3. Relayout - Repositions the components
4. Restart - Adds all removed components.
   

Zone Diagrams

1. The zone diagram component (directory) list/tree allows selecting which components are displayed on the diagram.
2. Right clicking on the component list allows:
1. Hide All, Show All - Hiding or showing all components
2. Hide Children, Show Children - Hiding or showing all components that are children of the selected component
3. 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.
   
3. Right clicking on the graph allows:
1. Go To Class - Displays the class diagram for the selected class
2. View Source - Displays the source code for the selected class
3. Show All Classes - Showing all classes or just showing components
4. Show Function Relations - Shows classes as related if a class has a member function that uses another class.
5. 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.
6. Zoom In/Out - Zoom the diagram

For more zone diagram information, see Zone Diagrams.

Class Diagrams

1. 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 click adds the selected class with standard relations.
   
2. Right clicking on a class will display a popup menu that allows adding classes with various types of relationships.
3. Left click on a class and drag the cursor to the desired location to move a class.

• Go To Class - Shows the class diagram for the selected class
• View Source - Views the source code
• Add Standard Relations - Adds classes that have relations where the classes are related either through aggregation or inheritance.
• All 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

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

Class Diagram Display Options

1. Select the Analysis/Settings menu item.
2. 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

1. 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.
2. Selecting an operation from the operation list will display the contents of the operation.
3. Right clicking on the sequence diagram depends on whether a class or operation is clicked on. Right clicking allows:
1. Go To Operation - Displays a new diagram for the different operation.
2. Add Calls - Expands the selected call to show the child calls
3. Add Callers - Shows the operations that call the selected operation.
   

Include Diagrams

Editing SVG diagrams

1. 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.
2. Download Inkscape from inkscape.org

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.

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

Member Usage Analysis

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

1. Turn on duplicate code analysis by adding -dups to the Analysis/Settings/Build Arguments/Analyze/Extra Build Arguments
2. Delete any existing analysis directories in the Oovcde project directory so that a complete analysis is run.
3. Run Analysis/Analyze
4. Run Analysis/Duplicates

For more information, see Duplicate Code.

Code Test Coverage System

1. 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 oovcde 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.
2. Running Coverage/Build will build the coverage project.
3. Running the coverage project components will update coverage counts.
4. Running Coverage/Statistics will output a coverage percentage file.

Build System

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

• Run Oovcde 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, Oovcde 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/Build Arguments.
• 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/oovcde/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 Oovcde will not build your type of project. Either rearrange the directory structure, or contact the Oovcde developers.
  
• Run Build/Build Debug or Build/Build Release.
  

Cross Compiling

• 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

Oovcde 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

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 Oovcde Analysis/Settings/Build Arguments 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 Build Arguments tab using the External Project Packages button.

So there are a few usage scenarios:

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

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

Linux Example

	-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/oovcde/2.0/clang+llvm-3.2!libclang_rt
	-lnk-static-libstdc++
	-lnk-Wl,-rpath=./
	-lnk-rdynamic
	

Windows MFC Example

-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

-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

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

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

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

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

Build Sequence

• The user specifies the source root directory and output oovcde 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 oovcde.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

  Sub-directory1 - Component1
      *.cpp - All of these files are used for Component1
      *.h - These can be used by any component

  Sub-directory2
      *.h - These can be used by any component

  Sub-directory3
      Sub-directory4 - Component2
          *.cpp - These can only be used for Component2
          *.h - These can be used by any component

  Sub-directory5 - Component3
      Sub-directory6
          *.cpp - These can be used for Component3

  Sub-directory7
          *.cpp - These can be used for Component3

• Only GNU or clang projects. CLang support for MSVC projects is improving, but unknown.
  
• External project roots are expected that they will not be changed. In order to update library information, delete the out/sym files.
• 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 oovcde-incdep.txt to see include directory dependencies found by compiler
• Only C++ is compiled. (No .C or .ASM) Other types of files must be put into external objects or libraries.

• 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

1. C++ syntax highlighting using CLang
2. Code completion using CLang
3. Debugging using GDB
   
4. Find/Replace
5. Find in files
   
6. Undo/Redo
7. Copy/Paste
8. Find forward or reverse, and case sensitive or insensitive